UBNTMOD

UBNTMOD is a tool(Shell Script) that allows you to configure a vast amount of settings on Ubiquiti AirMax equipment from the Linux command line.  The script can be used for helping automate task like reboots and firmware updates, and/or be used to change settings like device name, ssid, enable or disable NTP, and Syslog.  For a complete list of functions look at the UBNTMOD HELP section.

The script has been tested and any known bugs should be listed at the bottom of this page, but use at your own risk.  This is a bash script so feel free to download, review, copy, add, tweak, and remove all or parts of the code.

Install Prerequisites

The only requirements outside of a Bash shell is having sshpass installed.

sudo apt install sshpass

Download script

Download the script here or with wget

wget http://incredigeek.com/home/downloads/ubntmod/ubntmod.sh

Make executable

chmod +x ./ubntmod.sh

Run script

./ubntmod.sh -h

 

Running script and basic usage

Basic syntax is

./ubntmod.sh -i {device ip} -o otheroptions

Example : Print firmware version

user:~$ ./ubntmod.sh -i 192.168.1.20 -U info
info
Printing firmware version
firmwareVersion=XM.ar7240.v6.0.3.30600.170329.1831
user:~$

A note about saving changes

If you make a change to a device like change the name, you’ll need to save and apply the changes to the radio.  Do this by using the -Z option, it writes the changes and reboots the device so the changes take effect.

./ubntmod.sh -i 192.168.1.20 -N "New Device" -Z

Tip : You can string a bunch of options together and then save them all at once,

Example : Change device name, username, and enable NTP.

./ubntmod.sh -i 192.168.1.20 -N "New Device" -u admin -n enable -Z

A note about usernames and passwords

In the script there are two variables “un” and “pw” which specify the username and password to use when connecting to the radios.  By default these are ubnt and ubnt.  you can change these in the script so the script uses some other default username and password, or you can specify the username and password with the “-y” option.

So in our first example, if the username and password are different then ubnt we use the -y option

./ubntmod.sh -i 192.168.1.20 -U info -y 'admin,password123'

All other needed information should be in the help part of the script, accessible with the -h argument.

 

UBNTMOD HELP

./ubntmod.sh -h
//////////////////////\\
\\ UBNTMOD tool 1.0.8  \\
 \\/___/___/___/___/___//

Help and Usage

Usage: ./ubntmod.sh -i TargetIP {OPTIONS}
Example: Add SSH Key to 192.168.1.20
./ubntmod.sh -i 192.168.1.20 -K id_rsa.pub -Z

Device to operate against
-i IPADDRESS,                           IP Address of the device.

Option usage
-a remove,                              Removes AirControl provisioning.  Works on AC1 and AC2
-D enable/disable,                      Enable or Disable DNS proxy
-e  ,                                   See if radio resolves DNS.  SSH's to the radio and pings a domain name to see if it can resolve
-N Device Name,                         Change name of the device.
-n enable/disable,                      Enable or Disable NTP server
-K SSH Key,                             Specifies to path to the Public SSH Key file i.e. id_rsa.pub
-l enable/disable,                      Enable or Disable Syslog.  Specify ip address if you want to enable remote syslog
echo "-p 'password',                            Change password for device.  You can use the -z option to save."
-P PSK key,                             Change wireless passkey
-r KEYTODEL,                            Replace KEYTODEL with key1(to delete the first SSH Key), key2(to delete the second Key), or allkeys(to delete all current SSH Keys on the device)
-S SSID,                                Change SSID.  Spaces are not supported in SSID field yet.
-s "community;contact;location"         Enable and set SNMP
-t enable/disable,                      Enable or Disable Traffic Shaping on device, note: you cannot set the speed limits from this program.
-c fromText,                            The c and C Options are for making custom changes to the /tmp/system.cfg file, put the text you want to change after the -c option
-C toText,                              The C and c Options are for making custom changes to the /tmp/system.cfg file, put the text you want the -c text to be changed to after the -C option.  See below example
-w Channel Width,                       Set Channel Width i.e.(-w 10) for 10mhz
-u username,                            Change default username for the device
-U firmware,                            Upgrade device firmware, can print current firmware version the option argument is version, info, or status

Device Operations
-B,                                    Backs up configuration of device.  Script automatically names and time stamps the backup
-b BACUPNAME,                           Restores a backup configuration from the specified file
-I,                                     Prints info about device
-d,                                     Run Discovery on device
-R,                                    Reboot Device.
-A,                                    Reboot devices connected to AP, then reboot the AP.  Needs jq installed.  You can reboot multiple AP's by putting the IP's in an ap.lst file (one ip per line).
-w Channel Width,                       Changes channel width to whatever is specified, just the number no need to add mhz to the end, supported channel widths are 5,8,10,20,40 mhz
-W,                                     WIFI Scan, runs a scan, same thing as site survey
-X COMMAND,                             Run a custom Command on device, like "ls", "grep ssid /tmp/system.cfg"  Make sure to put the command in ""
-y \'username,password\',               Specify username and password to use in script
-Y,                                     Update ubntmod script with the latest available
-z,                                       Saves changes without a reboot by executing /usr/etc/rc.d/rc.softrestart save
-Z,                                     Saves changes made and reboots device to apply changes



c and C Example

basic usage:
./ubntmod.sh -i IPADDRESS -c linetochange -C changetoline
./ubntmod.sh -i 192.168.1.20 -c snmp.status=enabled -C snmp.status=disable
The above line changes the "snmp.status=enabled" to "snmp.status=disabled"

Find more help and tutorials at http://incredigeek.com/home/UBNTMOD

 

 

Examples

Reboot

./ubntmod.sh -i 192.168.1.20 -R

Wireless Scan

./ubntmod.sh -i 192.168.1.20 -W

Discovery

user:~$ ./ubntmod.sh -i 192.168.1.20 -d
Hardware Address  IP            address Name
00:27:A8:BB:2A:CD 192.168.1.20  NanoStation M2 'UBNT'
00:27:A8:AB:32:4A 192.168.1.1   NanoStation M2 'AP'
Total: 2 devices.
user:~$

Upgrade

user:~$ ./ubntmod.sh -i 192.168.1.20 -U XM.v6.0.1.23382.160317.1806.bin

Backup Configuration

user:~$ ./ubntmod.sh -i 192.168.1.20 -B AccessPoint
backing up configuration file for 192.168.1.1 Saving to AccessPoint.cfg
user:~$

Restore Configuration

./ubntmod.sh -i 192.168.1.20 -b AccessPoint.cfg

Change SNMP settings

./ubntmod.sh -i 192.168.1.20 -s "public,netwatch@incredigeek.com,office" -z

Change Device name

./ubntmod.sh -i 192.168.1.20 -N "device name" -Z

Check if radio can resolve DNS

./ubntmod.sh -i 192.168.1.20 -e

Softrestart

The following options have been tested and work with the softrestart option

  • SNMP
  • SSID

Want a specific example or new features?  Leave a comment!

Future Changes
UNMS support for adding, disabling etc
Send changes to Slack or Teams channel
Support for multiple usernames and passwords
Support for soft restart, or where device doesn’t have to reboot to apply a change (implemented and testing)
support for testing a change before applying?

Latest Changes

### Version 1.0.8 (9/3/2022)
Added -A option to reboot devices connected to an access point.  The jq utility needs to be installed.  You can reboot multiple AP’s by putting the IP’s in an ap.lst file.
This release makes using ubntmod.sh much easier. It can now cycle through an infinite number of usernames/passwords.
Refactored the username password section.
By default, ubntmod.sh will try reading from ubntmod.conf for usernames and passwords.
Added function to create ubntmod.conf file if username/password is not specified and no config file exist.

### Version 1.0.7
Added ssh-rsa in the HostKeyAlgorithms as recent versions of SSH do not support it by default

### Version 1.0.6 (5/24/2019)
Enabled Remote syslog

### Version 1.0.5 Changes (8/9/2019)
Added -z softrestart option to save changes without rebooting.  May not work on all changes.

### Version 1.0.4 Changes (5/24/2019)
Added Password loop option to specify two different passwords
Changed the SNMP deliminating character from , to ;

### Version 1.0.3 Changes (9/5/2018)
Added support for testing if DNS resolves on device, -e option

### Version 1.0.2 Changes (10/31/2018)
Added AirControl provisioning removal, -a option

### Version 1.0.1 Changes (10/31/2018)
# SNMP, changed help info to be correct
# Backups, changed to automatically backup with device name and time stamp. There is a bug where if ubntmod.sh can’t access a radio to do a backup, it’ll create a empty file with the time stamp.