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
|info||It Shows device information|
|set-default||Factory reset your Unifi device|
|set-inform http://192.168.1.1:8080/inform||Set the controller’s URL for adoption|
|upgrade https://<firmware-url>.bin||Upgrade The firmware|
|fwupdate –url https://<firmware-url>.bin||Update Your firmware|
|reboot||Reboot Your device|
|uptime||It displays device uptime|
Unifi Log Files Commands
|cat /var/log/messages||Output the error log|
|tail -f /var/log/messages||Monitor log file|
|cat /mnt/data/unifi-os/unifi-core/config/settings.yaml||Server settings|
|cat /mnt/data/unifi-os/unifi-core/logs/discovery.log||Discovery log file|
|cat /mnt/data/unifi-os/unifi-core/logs/system.log||System log file|
|cat /mnt/data/unifi-os/unifi/logs/server.log||Server log file|
|cat /mnt/data/unifi-os/unifi-core/logs/errors.log||HTTP errors|
Unifi OS SSH Commands
|ubnt-systool cputemp||Display CPU Temperature|
|ubnt-systool cpuload||Reveal CPU load|
|ubnt-systool portstatus||Show port status|
|ubnt-systool hostname <newname>||Set a new hostname|
|ubnt-systool reboot||Reboot your Unifi device|
|ubnt-systool reset2defaults||Factory reset|
|ubnt-device-info summary||Show system report|
|ubnt-tools ubnt-discover||Show Unifi devices in the network|
|cat /mnt/data/udapi-config/dnsmasq.lease||Display DHCP Leases|
|cat /mnt/data/udapi-config/unifi||Show setup|
|/etc/init.d/S95unifios restart||Restart Unifi OS Web interface|
Network Related SSH Commands
|ifconfig||Displays network interface data|
|ip address add 192.168.1.143/24 dev br0||Set static IP Address|
|ip route||It shows the existing gateway|
|ip route add default via 192.168.1.1||Set your default gateway|
|echo “nameserver 192.168.1.1” > /etc/resolv.conf||Set DNS Server|
|ping 220.127.116.11||Check network connection to the device|
|apr -a||Displays arp table|
|ip neigh||It shows IPv6 neighbors|
Here is an extensive list of the most useful Unifi SSH commands for managing your network devices:
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
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
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
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
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:
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
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:
This tests connectivity by pinging Google.
This traces the route to a destination IP.
This displays running processes and resource usage.
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.
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.