SSH into your USG

When it comes to managing your UniFi Security Gateway (USG), the UniFi Controller is a powerful tool. But if you're looking to dig deeper, troubleshoot, or apply advanced configurations, SSH access is where the real magic happens.

Let's dive In!

🚨 Before we get to the SSH part, just a quick note: If you manage client networks on a self-hosted UniFi controller. Please stop. Sooner or later this will cause issues! It's fine for home users, but definitely not recommended for businesses. We've built UniFi hosting solution that is both secure and reliable. You can try it for free.

Why SSH into Your USG?
Final Thoughts

Why SSH into Your USG?

SSH (Secure Shell) is a secure way to access your USG's command-line interface (CLI). The CLI allows you to execute commands directly on the device, offering a level of control that's sometimes beyond what's available through the UniFi Controller.

Whether you're troubleshooting, configuring VLANs, or just curious about the logs, SSH gives you a window into your device's inner workings. It’s like having the keys to the kingdom—if you know what you’re doing, you can make your USG dance to your tune.

Step 1: Enabling SSH on Your USG

Before you can SSH into your USG, you need to enable it via the UniFi Controller.

Login to Your UniFi Controller: Open your UniFi Controller and log in with your credentials.
Go to Settings: Navigate to the "Settings" gear icon.
Network: In the left-hand menu, go to the "Networks" section.
Device Authentication: Scroll down to the "Device Authentication" section.
Enable SSH: Make sure the SSH checkbox is ticked. Set a strong username and password for SSH access. The default is usually "ubnt" for both the username and password, but it's highly recommended to change this for security reasons.

Pro tip: If you're using UniHosted to manage your UniFi Controller, enabling SSH is just as easy. We handle the rest so you can focus on managing your network without breaking a sweat.

Step 2: Logging into Your USG via SSH

Once SSH is enabled, you can access your USG from any terminal (Mac/Linux) or SSH client (Windows users might prefer PuTTY).

Open your terminal: On Mac or Linux, you can use the built-in Terminal app. On Windows, you can use an SSH client like PuTTY.
Enter the command:
```
ssh username@USG_IP_address
```
Replace "username" with the username you set in the UniFi Controller and "USG_IP_address" with the IP address of your USG.
Password prompt: You will be prompted for your password. Enter the password you set in the UniFi Controller.

Example:

ssh [email protected]

You should now be logged into your USG's command line! And that’s where the fun begins.

Step 3: Basic SSH Commands for USG

Now that you're logged in, here are some essential commands to get you started:

Check the USG's current configuration:
```
show configuration
```
This command displays the current configuration settings of your USG. It’s like peeking under the hood to see how everything is wired.
View real-time logs:
```
tail -f /var/log/messages
```
This shows the system log in real-time. It's handy for troubleshooting and seeing what's happening on your device as it happens.
Restart services:
```
sudo service unifi restart
```
If your USG is acting up, restarting the UniFi service can help clear out the cobwebs.
Reboot the USG:
```
sudo reboot
```
This will restart your USG. Make sure no one is actively using the network when you do this, or you might get some angry calls!
Backup the configuration:
```
show configuration | gzip > /tmp/usg-backup.gz
```
This command creates a backup of your current configuration. Always a good idea before making major changes.

Step 4: Advanced Configurations with SSH

SSH isn't just for basic commands; you can perform more advanced configurations that might not be accessible through the UniFi Controller. This is where the real power of SSH shines.

Editing Configuration Files:
You can directly edit configuration files using a text editor like "vi". This is useful for making changes that aren't possible through the UI.
```
sudo vi /etc/config/config.gateway.json
```
Warning: Be careful when editing configuration files directly. A typo or wrong setting can cause your USG to malfunction. Always backup before making changes.
Configuring VLANs:
You can set up VLANs (Virtual LANs) through SSH, giving you more granular control over your network traffic.
```
configure

set interfaces ethernet eth1 vif 10 address 192.168.10.1/24

commit

save
```
This example configures VLAN 10 on the "eth1" interface with the IP address "192.168.10.1". VLANs are crucial for segmenting your network traffic, especially in environments where security and traffic management are key.
Advanced Firewall Rules:
You can set up detailed firewall rules that aren't available through the UniFi Controller's interface.
```
configure

set firewall name WAN_LOCAL rule 10 action drop

set firewall name WAN_LOCAL rule 10 description "Drop traffic from specific IP"

set firewall name WAN_LOCAL rule 10 source address 192.0.2.1

commit

save
```
This example blocks traffic from the IP address "192.0.2.1" at the firewall level, providing an additional layer of security.

Step 5: Monitoring and Logs

Keeping an eye on what's happening with your USG is crucial for maintaining a healthy network. SSH gives you direct access to various logs and monitoring tools.

System Logs:
```
cat /var/log/messages
```
Reviewing the logs can give you insight into what’s happening on your network. Whether it’s failed login attempts, dropped packets, or just a detailed view of your USG’s activities.
Network Traffic:
```
sudo tcpdump -i eth0
```
This command captures live network traffic on the "eth0" interface. It's a powerful tool for diagnosing network issues, tracking down rogue devices, or just understanding your network’s behavior.
Check System Resource Usage:
```
top
```
This command gives you a real-time view of system resource usage, including CPU, memory, and process information. If your USG is acting sluggish, this is the first place to check.

Step 6: Security Best Practices

SSH access is powerful, but with great power comes great responsibility. Here are some security tips to keep in mind:

Change Default Credentials: Never keep the default "ubnt" credentials. Always set a strong, unique username and password.
Use Key-Based Authentication: Instead of relying on passwords, you can set up SSH key-based authentication, which is more secure.
Limit SSH Access: Restrict SSH access to certain IP addresses or networks to prevent unauthorized access.
Regular Updates: Ensure your USG and UniFi Controller are always updated to the latest firmware to protect against vulnerabilities.

Step 7: Troubleshooting Common Issues

SSH is not without its quirks. Here are a few common issues you might encounter and how to fix them:

Connection Refused:
If you see a "Connection Refused" message, SSH might not be enabled, or there could be a network issue. Double-check that SSH is enabled in the UniFi Controller and that you're using the correct IP address.
Incorrect Credentials:
If you're getting an "Access Denied" error, make sure you're using the correct username and password. Remember, the default is "ubnt", but this should be changed.
Network Timeout:
If your connection is timing out, the USG might be too busy to respond. Try again in a few minutes, or check your network for issues.

Final Thoughts

SSH is a powerful tool that gives you direct control over your USG. Whether you're performing basic checks, troubleshooting, or diving into advanced configurations, SSH access can significantly enhance your network management capabilities.

And remember, if you're hosting your UniFi Controller with us at UniHosted, we've got your back. From automated updates to daily backups, we make sure your network runs smoothly so you can focus on what really matters. Give SSH a try, and see how it can take your USG management to the next level!

If you would like me to personally walk you through UniHosted, you can schedule a call with me here.