Umbrella Virtual Appliance Commands

Introduction

This document describes the commands for the Umbrella Virtual Appliacnes (VAs).

Overview

The Umbrella 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 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: 

• tunnel
• snmp
• anycast
• va
• ntp
• admap
• logexport
• localdns
• loadbalancer

5720351776404

1) The tunnel subcommand is used for enabling and configuring the support tunnels, similar to doing so via Ctrl+B from the VA console. 

360037483772

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.

360037482211

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. 

360055492572

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.

360055639691

4417123559060

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, with these options being available: 

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.

360055626811

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. 
360037483672

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.

4412434552084

For more information, please see:

https://docs.umbrella.com/deployment-umbrella/docs/appendix-e-other-configurations#syslog

The localdns subcommand is used to configure conditional forwarding of internal domains to specific internal DNS servers.  It is new to version 3.2.

4417131713684

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.

5720280448276

For more information, please run "config loadbalancer help" or see:

https://docs.umbrella.com/deployment-umbrella/docs/appendix-e-other-configurations#section-configure-load-balancing

date

The date command can be used to print the current system time/date in the VA. The time is returned in Coordinated Universal Time (UTC). The date, time, and timezone cannot be reconfigured.

4412412915604

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

360037483652

execute

The execute command is available in newer build - version 3.4.6  

Usage : execute <commands>
Commands have to be one of these:
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 are removed).

free

The free command displays 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

360037482111

help

help can be used to display all of the commands available to the user within the restricted shell environment. 

360055506372

Note: While help is supported, man is not, so you 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

360037482091

netstat

netstat prints 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

360037482051

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 this syntax causes 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 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

4412413950484

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 are 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.

4412427409044

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. 

360037482031Most 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. 

360055639751

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 are prompted to confirm the reboot (Y = yes) or cancel the reboot (N = no).

4412413584148

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.

4412426989332

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 provides information about each hop between them.
Most common usage would be as follows: 

traceroute <domain or IP>

4412413519508

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 provides 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.

4412413617172

For more information, see https://manpages.ubuntu.com/manpages/focal/en/man1/uptime.1.html

version

version prints the current version of the VA software to the screen. This information is also available from the VA console. 

360037481991