Unifi SSH Commands

The Unifi controller by Ubiquiti Networks allows network administrators to manage their network devices like access points and switches through a web interface. However, for more advanced configurations, SSH access provides much more control and customization options. In this comprehensive guide, we will explore the full list of SSH commands available for Unifi devices.

What is SSH?

SSH, or Secure Shell, is a network protocol that allows admins to access devices remotely over an encrypted connection. This allows managing devices securely over the internet or local network. SSH uses public-key cryptography to authenticate the remote device and encrypt data connections.

Compared to the Unifi web UI, SSH provides unfettered access to the underlying Linux-based system that runs on Unifi devices. This allows administrators to tweak settings and customize configurations beyond what is available through the standard web interface.

Prerequisites for Using SSH with Unifi

Before you can start using SSH with your Unifi network, you need to fulfill a few requirements:

• Have SSH enabled on your Unifi devices like access points or switches. This is usually disabled by default.
• Know the IP address of the Unifi device you want to connect to.
• Have an SSH client like PuTTY to connect from your desktop.
• Have the username and password credentials for accessing the device over SSH.

Once you have enabled and configured SSH access, you can connect to your Unifi devices and start using the commands outlined in this guide.

Full List of Unifi SSH Commands

General Unifi SSH Commands

Unifi Log Files Commands

Unifi OS SSH Commands

Network Related SSH Commands

Here is an extensive list of the most useful Unifi SSH commands for managing your network devices:

General Commands

uci – Display all UCI configuration options

ubntbox – Display diagnostics summary

calc-neq – Calculate signal/noise ratio

restart – Restart the Unifi device

reboot – Reboot the Unifi device

help – Display available commands

? – Display available commands

Wireless Commands

wlanconfig ath0 list – List available wireless networks

wlanconfig ath0 delete – Delete a wireless network

wlanconfig ath1 down – Disable wireless radio

wlanconfig ath1 up – Enable wireless radio

iwlist ath0 scan – Scan for nearby wireless networks

iwlist ath0 freq – List frequencies in the wireless band

iwconfig ath0 channel – Set channel for wireless radio

iwconfig ath0 txpower – Set wireless transmit power

iwconfig ath0 rate – Set wireless rate in Mbps

iwpriv ath0 kickmac – Deauthenticate wireless client

Network Commands

ifconfig eth0 – Display eth0 IP address and statistics

ifconfig eth1 – Display eth1 IP address and statistics

ifconfig ath0 – Display ath0 IP address and statistics

iw dev ath0 link – Check wireless link status

ping – Ping host and display results

traceroute – Trace route to host

top – Display running processes and resource usage

netstat -an | grep ESTABLISHED – List established connections

brctl show – Show bridge interfaces

brctl delif eth0 – Remove eth0 from bridge

brctl addif eth0 – Add eth0 to bridge

Firmware Commands

cat /tmp/system.cfg – Display full system configuration

syswrapper.sh restore-default – Restore default firmware settings

fwupdate.sh -d /usr/share/fwupdate/data/stable.bin – Check firmware update

fwupdate.sh -i /usr/share/fwupdate/data/stable.bin – Install firmware update

fwupdate.sh -a /usr/share/fwupdate/data/stable.bin – Abort firmware update

Administration Commands

vim /etc/config/system – Edit system configuration in ViM

passwd – Change admin password

killall hostapd – Stop hostapd process

rm /tmp/hostapd.conf – Remove hostapd config file

ps – Display running processes

kill – Kill process with PID

vi /etc/crontab – Edit cron jobs

cat /etc/shadow – Display user passwords

These cover the most useful Unifi SSH commands for managing Ubiquiti access points and switches. Using SSH provides low-level access to tweak, customize, troubleshoot, and control your UniFi devices.

Common Uses for Unifi SSH Commands

Now that you know the main Unifi SSH commands, let’s look at some common use cases and examples for these commands.

Changing Wireless Settings

SSH makes it easy to modify wireless settings that may not be available through the web UI. For example:

iwconfig ath0 channel 36 

This will set the wireless channel on ath0 to channel 36.

iwconfig ath0 txpower 21

This boosts the transmit power to 21 dBm.

iwconfig ath0 rate 54M 

This limits the maximum wireless bitrate to 54 Mbps.

Managing Wireless Networks

You can add, modify, or delete wireless SSIDs using SSH:

wlanconfig ath0 create wlan0 ssid "My Network"

This creates a new SSID called “My Network” on ath0.

wlanconfig ath0 modify wlan0 ssid "New Name"

This renames the “My Network” SSID to “New Name”.

wlanconfig ath0 delete wlan0

This removes the wireless network entirely.

Monitoring Traffic and Connections

SSH gives you tools to monitor traffic flowing through the device:

nethogs

This displays bandwidth used per process.

iftop -i eth0

This monitors traffic on the eth0 interface.

tcpdump -i eth1 port 22

This captures SSH traffic on eth1.

netstat -an | grep ESTABLISHED

This lists all established connections on the system.

Advanced Wireless Controls

With SSH, you can use utility commands like iw and iwlist for advanced wireless controls:

iwlist ath0 scan

This scans for nearby WiFi networks.

iw dev ath0 link  

This checks the wireless link status.

iwpriv ath0 kickmac 00:11:22:33:44:55

This will deauthenticate a specific client.

Troubleshooting Device Issues

SSH gives you access to troubleshooting commands:

ping google.com

This tests connectivity by pinging Google.

traceroute 1.1.1.1

This traces the route to a destination IP.

top

This displays running processes and resource usage.

dmesg

This shows the kernel ring buffer for diagnosing boot issues.

Optimizing the Unifi Network with SSH

Now that you are familiar with the commands, let’s go over some ways to optimize and customize your Unifi network using SSH access.

Setting Custom Wireless Channels

Instead of using automatic channel selection, you can set custom channels based on a wireless site survey:

iwlist ath0 freq

First list available channels with this command.

iwconfig ath0 channel 6 

Then set an optimized channel like channel 6.

Adjusting Transmit Power

Increase transmit power to expand wireless coverage. But limit transmit power to reduce overlap:

iwconfig ath0 txpower 30

Boost power to 30 dBm.

iwconfig ath0 txpower 17

Reduce power to 17 dBm.

Changing WiFi Bandwidth

Set the wireless channel bandwidth for best performance:

iwconfig ath0 channel 36 HT20

Use a 20 MHz channel for range.

iwconfig ath0 channel 157 HT40+

Use a 40 MHz channel for throughput.

Utilizing Airtime Fairness

Airtime fairness can improve wireless performance for multiple devices:

uci set wireless.ath0.ath1_airtime_fairness=1

Enable airtime fairness.

wifi down
wifi up

Restart WiFi after making changes.

Setting Minimum Basic Rates

Set a minimum basic rate to improve compatibility with older wireless devices:

iwconfig ath0 rate 54M

Set to 54 Mbps minimum.

iwconfig ath0 rate 12M 

Or set to 12 Mbps minimum.

Optimizing WiFi Performance

Some other ways to optimize WiFi performance include:

• Disabling lower data rates
• Enabling TX beamforming
• Setting proper fragmentation threshold
• Adjusting RTS/CTS threshold
• Enabling hardware encryption

SSH provides the control for these advanced wireless tuning options.

Customizing the Wireless Environment

With full SSH access, you can customize the wireless environment including:

• Adding an enterprise security suite like WPA2
• Integrating seamless roaming for wireless clients
• Segmenting wireless traffic into VLANs
• Binding wireless interfaces into a bridge
• Blocking or deauthenticating clients
• Capturing wireless traffic remotely

SSH unlocks these advanced capabilities.

Potential Drawbacks of Unifi SSH Access

While SSH provides greater control and customization, there are some caveats to keep in mind:

Increased Security Risks

• SSH uses encrypted communications, but still increases attack surface.
• Default credentials are often left unchanged, allowing unauthorized access.
• Once compromised, SSH provides low-level access to device configuration.

Command Line Complexity

• Commands require precise syntax and knowledge of options.
• Misconfiguring settings via SSH could break functionality.
• Troubleshooting complex issues via CLI is difficult.

Beyond Web UI Capabilities

• Features like airtime fairness may require SSH access.
• Adjusting obscure OS parameters requires SSH access.
• Finding optimal wireless channels uses scanning utilities.

No GUI for Visualization

• Radio frequency analysis requires third party tools.
• Reporting traffic volumes is easier in web UI.
• Visualizing network topology requires diagramming tools.

While the CLI provides greater control, the web UI offers better visibility into some aspects of the network.

Conclusion

SSH access allows you to unlock the full potential of your Unifi network devices. The extensive set of commands provides low-level control over wireless settings, network monitoring, traffic management and advanced device configurations.

With great power comes great responsibility. Exercise caution when modifying device parameters over SSH, as misconfiguration could cause outages. Analyze your requirements and weigh the benefits of SSH against the convenience of the Unifi web management interface.

For advanced users and network engineers, SSH provides optimization capabilities that can take your Unifi network to the next level. Use this guide as a Unifi SSH cheat sheet to customize your network and tackled advanced wireless tuning.

Frequently Asked Questions

Q1: How do I enable SSH access on my Unifi device?

A1: Go to Settings > Services in the Unifi controller and check the “Enable SSH access” box. Each device will need SSH enabled individually.

Q2: What username and password do I use to connect over SSH?

A2: Use the same admin username and password that you use to login to your Unifi controller.

Q3: Is using SSH safe and secure?

A3: SSH encrypts the connection, so it is safe from sniffing. But you should use strong passwords or SSH keys, and restrict access to authorized users.

Q4: Can I damage my Unifi device using SSH commands?

A4: Yes, incorrect commands could misconfigure and break functionality. Make backups and test commands carefully.

Q5: Is there a reference guide for all Unifi SSH commands?

A5: Ubiquiti does not provide official CLI documentation. But you can find unofficial guides assembled by the Unifi community.

Q6: What are some common uses for SSH access?

A6: Customizing wireless settings, monitoring network traffic, troubleshooting issues, optimizing performance, advanced access controls.

Q7: Is SSH the only way to access the Linux shell?

A7: On UniFi OS devices you can also use the local console or UART serial access to get shell access.

Q8: Can I write scripts to automate Unifi configuration over SSH?

A8: Yes, SSH access allows you to write scripts in Bash, Python, Perl etc. to automate your network.

Q9: Is remote SSH access to Unifi devices secure?

A9: Enable SSH only on the LAN/mgmt port, disable remote login for admin users, and use SSH keys for authentication.

Q10: Are all the same SSH commands available on every Unifi device?

A10: There are some minor differences between CLI for access points, switches, gateways etc. But most core commands are the same.