browse
Overview
The Umbrella Virtual Appliances (VAs) run on the Ubuntu operating system, which is a Linux distribution based on Debian. Not all of the commands typically available in Linux are available to customers within the VA's "Configuration Mode" command line. Instead, the VAs utilize a restricted shell environment which provides a number of troubleshooting / diagnostic commands, as well as config commands to change relevant settings within the VAs.
For more information about configuring the VAs using the Configuration Mode, see https://docs.umbrella.com/deployment-umbrella/docs/5-configuring-the-vas
The commands in this article are all available as of VA software version 3.4.
Note:
The command descriptions above cover the supported syntax on the VAs. Links are provided for many of the commands to a third party resource for additional information about the commands themselves. Please note that not all Linux command options are supported on the VAs.
clear
The clear command clears the terminal screen. It is the equivalent of "cls" in the Windows command prompt.
Note:
This is not the command used to clear AD mappings
config
config is used to configure the virtual appliances. There are nine subcommands for config:
1) The tunnel subcommand is used for enabling and configuring the support tunnels, similar to doing so via Ctrl+B from the VA console.
Example commands:
config tunnel enable <optional time open, default is 72hrs, range is 7 to 240 hours>
config tunnel reenable <optional time open, default is 72hrs>
config tunnel disable
config tunnel status
For more information about configuring support tunnels, please see https://docs.umbrella.com/deployment-umbrella/docs/appendix-d-troubleshooting-the-va-using-a-restricted-shell#tunnel
2) The snmp subcommand is used for enabling and configuring SNMP support.
Example commands:
config snmp enable
config snmp configure -v2 -c <community string>
config snmp status
For more information about configuring SNMP, please see https://docs.umbrella.com/deployment-umbrella/docs/appendix-c-enable-snmp-monitoring
3) The anycast subcommand is used to configure AnyCast BGP.
Example commands:
config anycast enable <anycast ip> <ASN:ROUTER-IP:HOP-COUNT of BGP router>
config anycast status
config anycast disable
config anycast stats
config anycast add <ASN:ROUTER-IP:HOP-COUNT of BGP router>
config anycast delete <BGP router IP address>
For more information about configuring AnyCast, please see https://docs.umbrella.com/deployment-umbrella/docs/appendix-e-other-configurations#anycast
4) The va subcommand is used for all of the routine configurations on the VAs.
Example commands:
config va status
config va name <New name for the VA>
config va interface <interface name> <ip address> <subnet mask> <gateway>
config va interface6 <interface name> <IPv6 address/prefix> <IPv6 gateway>
config va show
config va ssh enable
config va dmz enable
config va dnssec enable
config va per-ip-rate-limit enable <packets/sec> <burst rate>
For more information about configuring rate-limiting, see https://docs.umbrella.com/deployment-umbrella/docs/appendix-e-other-configurations#section-configure-rate-limiting
For more information about configuring DNSSEC support, see https://docs.umbrella.com/deployment-umbrella/docs/appendix-e-other-configurations#section-configure-dnssec-support
It is also possible to configure the VAs to use specific resolvers using the resolvers subcommand. It is not possible to configure a custom resolver however, so you will be limited to the following options:
config va resolvers US (Uses 208.67.221.76 and 208.67.223.76)
config va resolvers US-v6 (Uses 2620:119:17::76 and 2620:119:76::76)
config va resolvers global (Uses 208.67.220.220 and 208.67.222.222)
config va resolvers global-v6 (Uses 2620:119:35::35 and 2620:119:53::53)
config va resolvers alternate (Uses 208.67.222.220 and 208.67.220.222)
For more information, see https://docs.umbrella.com/deployment-umbrella/docs/appendix-e-other-configurations#section-configure-umbrella-resolvers
5) The ntp subcommand can be used to define custom NTP servers on the VAs.
Example commands:
config ntp add <New NTP server>
config ntp show
For more information, see https://docs.umbrella.com/deployment-umbrella/docs/appendix-e-other-configurations#section-configure-ntp-servers
6) The admap subcommand is the command used to configure identity association timeouts as well as viewing or clearing the AD Mapping. As this time, it is possible only to clear clear out the mappings of an individual IP address. There is not currently a way to clear all AD mappings from the restricted shell.
Example commands:
config admap view <ip address>
config admap clear <ip address>
config admap set-user-timeout 28800 (This would set it for 8hrs)
config admap show-timeout
For more information, please see:
https://docs.umbrella.com/deployment-umbrella/docs/appendix-e-other-configurations#identity
Additional information can be found in these knowledge base articles:
Virtual Appliance: Manage/Delete Cached AD Users
Virtual Appliance: Tuning User Cache Settings
7) The logexport subcommand is used to export audit logs, health logs, and/or internal DNS request logs to a remote syslog server.
For more information, please see:
https://docs.umbrella.com/deployment-umbrella/docs/appendix-e-other-configurations#syslog
8) The localdns subcommand is used to configure conditional forwarding of internal domains to specific internal DNS servers. It is new to version 3.2.
For more information, please run "config localdns help" or see:
https://docs.umbrella.com/deployment-umbrella/docs/6-local-dns-forwarding
9) The loadbalancer subcommand is used for configuring a LoadBalancer that injects ECS. It is new to version 3.3.
For more information, please run "config loadbalancer help" or see:
date
The date command can be used to print the current system time/date in the VA. The time will be returned in Coordinated Universal Time (UTC). The date, time, and timezone cannot be reconfigured.
df
The df command can be used to display the current disk utilization of the VA.
For more information, see http://manpages.ubuntu.com/manpages/focal/en/man1/df.1.html
execute
The execute command is available in newer build - version 3.4.6
Usage : execute <commands>
commands have to be one of the following:
force_upgrade : Perform "disk_cleanup" > re-download new VA image > force VA upgrade immediately.
disk_cleanup : Remove VA images, upgrade error files and Azure extension (no logs will be removed).
free
The free command will display the amount of free and used memory in the system.
For more information, see http://manpages.ubuntu.com/manpages/focal/en/man1/free.1.html
help
help can be used to display all of the commands available to the user within the restricted shell environment.
Note:
While help is supported, man is not, so you will need to pull up any man pages you need elsewhere.
Links are included at the top of this article for each available command
iostat
iostat displays CPU statistics and input/output statistics for devices and partitions.
For more information, see http://manpages.ubuntu.com/manpages/focal/en/man1/iostat.1.html
netstat
netstat will print network connections, routing tables, interface statistics, masquerade connections, and multicast memberships.
For more information, see http://manpages.ubuntu.com/manpages/focal/en/man8/netstat.8.html
nslookup
nslookup is used to query Internet name servers interactively. The command structure matches that of Windows, Mac, and Linux.
nslookup <domain>
Running a lookup using the above syntax will cause the VA to send the query to our public resolvers rather than to itself. In order to successfully perform a lookup for an internal domain, you will need to specify your internal DNS server:
nslookup <Internal Domain> <Internal DNS Server IP>
To run an internal or external lookup from the VA against itself, you would run as follows:
nslookup <domain> 127.0.0.1
For more information, see http://manpages.ubuntu.com/manpages/focal/en/man1/nslookup.1.html
passwd
passwd is used to reset the VA password. The syntax is as follows:
passwd
You will then be prompted for the old password, then the new one (twice). Alternatively, you can reset the password to the default via the Umbrella dashboard as detailed here.
ping
The ping command is used to test connectivity, and the syntax again matches that found in Windows, Mac, and Linux. Available options are shown below.
Most common usage would generally be as follows:
ping -c 4 <Domain or IP>
For more information, see http://manpages.ubuntu.com/manpages/focal/en/man1/ping.1.html
ping6
The ping6 command is used to test connectivity to IPv6 endpoints, and the syntax again matches that found in Windows, Mac, and Linux. Available options are shown below.
Most common usage would be as follows:
ping6 -c 4 <Domain or IPv6 address>
For more information, see http://manpages.ubuntu.com/manpages/focal/en/man1/ping6.1.html
reboot
The reboot command reboots the VA. You will be prompted to confirm the reboot (Y = yes) or cancel the reboot (N = no).
tcptraceroute
tcptraceroute send functions much the same as the standard traceroute command, however, it uses TCP packets instead of the standard UDP or ICMP packets.
For more information, see: https://manpages.ubuntu.com/manpages/focal/man1/tcptraceroute.mt.1.html
traceroute
traceroute can be used to test UDP and ICMP connectivity between two endpoints on different networks and will provide information about each hop between them.
Most common usage would be as follows:
traceroute <domain or IP>
For more information, see https://manpages.ubuntu.com/manpages/focal/en/man1/traceroute.db.1.html
traceroute6
traceroute6 can be used to test UDP and ICMP connectivity between two IPv6 endpoints on different networks and will provide information about each hop between them.
For more information, see https://manpages.ubuntu.com/manpages/focal/man8/traceroute6.iputils.8.html
uptime
The uptime command shows the current time, how long the VA has been running, how many users are currently logged on, and the system load averages for the past 1, 5, and 15 minutes.
For more information, see https://manpages.ubuntu.com/manpages/focal/en/man1/uptime.1.html
version
version will print the current version of the VA software to the screen. This information is also available from the VA console.