How To SSH Into Your UniFi Dream Machine

UbiquitiNetworking
Written By Evan McCann

Originally Posted: May 15th, 2020
Last Edited: March 17th, 2021

How to SSH Into Your UniFi Dream Machine

Enable UDM SSH Access

  • If you don’t have remote access enabled, you will need to be connected locally to the UDM, and navigate to it’s IP address in a web browser.

  • If you have remote access enabled, you can navigate to unifi.ui.com and access the SSH setting there.

Enable SSH in the UDM Device settings:

  1. Click on the gear icon to access the UDM device settings

  2. Click on Advanced

  3. Enable SSH and set your SSH password

SSH into the UDM with the username of “root” and the password you just set

  • Open your terminal application of choice. There are many applications that you can use, but some quick recommendations based on your OS:

  • If your IP address is 192.168.1.1, you’d type ssh root@192.168.1.1 and hit enter. Replace the IP, but the username is always root.

  • If this is your first time accessing the device, accept the authenticity of the host key by typing yes and hit enter

  • Access the UniFi OS shell by typing unifi-os shell and hit enter

What You Can Do With SSH Access

If you’re not familar with SSH, Ubiquiti has a good help page which introduces what SSH is and how it works. The one sentence summary is that SSH allows for a safe way to read and write the configuration, access logs, and troubleshoot problems.

The “configuration” part doesn’t really apply to the UDM, though. With the UDM, you have to make your permanent configuration changes through the web UI. The UDM doesn’t have a configuration shell, you will only have direct Linux shell access. The Unifi service or a firmware update will overwrite most things you can change.

UbiOS/UniFi OS is based on Buildroot Linux, and is Ubiquiti’s custom implementation. You are not allowed to install packages or modify things like you might be used to on other Linux-based devices. With that said, there’s still a few things you can do.

Available commands

Typing “help” shows an incomplete list of the commands that are available:

Built-in commands available to root user:

. : [ [[ alias bg break cd chdir
command continue echo eval exec
exit export false fg getopts
hash help history jobs kill let
local printf pwd read readonly
return set shift source test times
trap true type ulimit umask
unalias unset wait

Standard Linux commands like ifconfig, tcpdump, netstat, whoami and cat are also available. There are also some commands and files that are unique to the UDM and not well documented by Ubiquiti. This reddit thread shows a good list of these unique commands, file locations, and what they are good for. Refer to the commands on the right side of the table

Retrieve Log Files

This is Ubiquiti's help article for how to retrieve log files. You can use view the specific logs you’re interested in by using the cat command, or view live logs with tail.

  • Show UniFi server logs with: cat /mnt/data/unifi-os/unifi/logs/server.log

  • Show UniFi system logs with: cat /mnt/data/unifi-os/unifi-core/logs/system.log

  • Refer to Ubiquiti’s help page and this Reddit thread for more examples.

Manual Firmware Upgrade

Custom firmware upgrade in the web interface.

One of the most common uses of SSH is firmware upgrades, especially for beta firmware. You can SSH into any of your UniFi devices, and run the ubnt-upgrade command with the proper file URL. This requires the device to be online and able to reach the internet.

ubnt-upgrade https://fw-download.ubnt.com/<insertfilepathhere>.bin

The best source to find the firmware URL is Ubiquiti’s community forums. Search for your device on this software releases page, and get the link to the firmware you want to install.

Another way to do this is by using the web interface. Under the devices tab, select your device, and click on the gear-shaped config icon. Paste the URL and hit the “custom upgrade” button. You don’t need the “ubnt-upgrade” command before the URL, that is only needed when you are using the command line.

Sources and Links

-Help article showing commands for retrieving log files.
-Ubiquiti’s SSH intro help article.
-Ubiquiti’s software releases page.
-Reddit thread with useful commands for the UDM and UDM-Pro.

I will continue to update this guide as I find more information about SSH access on the UDM and UDM-Pro. Until then, I have a lot of other posts where I talk about UniFi hardware and software:

Evan McCann

Nerd writing about Wi-Fi, Networking, Ubiquiti, and Apple.

Previous

Ubiquiti's First UniFi Wi-Fi 6 Access Points
Next

Link: How Apple Reinvented The Cursor For iPad