CLI Command Reference

This reference page provides definitions for the most commonly used commands of the gateway CLI.

A note after each command indicates whether the command is supported in operational mode, configuration mode, or both modes.

?

Operational and configuration.

The "?" character provides different help strings depending upon when you enter this character.

Examples

Enter "?" on the command line as the sole entry to display the help strings for the possible commands at that level. In this regard, the "?" acts like the CLI Command Reference#help command.

BASH

% ?
Possible completions:
  commit   - Commit current configuration modifications to the datastore
  compare  - Compare current configuration to data in the datastore
  context  - Change to a different multi-tenant configuration context
  delete   - Delete a data element
  edit     - Edit a data element and set the configuration path
  exit     - Exit from configuration mode
  help     - Display help information
  insert   - Insert a new data element
  load     - Load configuration data from a file to the current configuration
  quit     - Exit from configuration mode
  rename   - Rename the instance (key) of an existing element
  revert   - Revert current configuration back to start of the transaction
  rollback - Roll back configuration to a previously committed version
  run      - Run a command in operational mode
  save     - Save the current configuration to a file
  set      - Set the value of a data element
  show     - Display the current configuration
  top      - Reset configuration path to the top level
  up       - Set configuration path up one level
  validate - Validate modifications to the current configuration

Enter a command followed by a space and "?" to show the subsequent level of help strings for the next possible command-line entries. In the following two examples, the "?" displays help strings at the subsequent level:

Example 1

BASH

% set ?
Possible completions:
  aaa
  addressing
  ports
  security
  system

Example 2

BASH

> set ?
Possible completions:
  history      - Set CLI history display size
  idle-timeout - Set the CLI session idle timeout
  paginate     - Set pagination mode for CLI command output

The "?" can also act like tab-completion. For example, if you type "a?" with no spaces, then the "?" displays all the possible choices which start with the letter "a" .

BASH

% set a
Possible completions:
  aaa
  addressing

command

Executes diagnostics actions on the gateway.

Operational only.

Use "command diagnostics ?" to show all the diagnostic actions you can perform on the gateway.

BASH

> command diagnostics 
Possible completions:
  collect
  remote
  web

This example performs a diagnostic action on a single element (checking the status of the remote server).

BASH

> command diagnostics remote status 
Status: Enabled

commit

Configuration only.

To configure data via the CLI, you must use a CLI Command Reference#set command followed by commit.

In configuration mode, the set command indicates that the operator is configuring data. Like other industry-standard CLIs, the gateway's set command lets you drill down to a specific element (or node). You can set the configurable data in one of the following ways: one at a time, all at once, or a few at a time. Also, you can set variables in any order.

Data is categorized logically based on the type of data. For example, data that is associated with a specific port includes data that is specific to that port. such as the admin status of the port, the IP address of the port, the subnet mask of the port, and so forth.

After issuing a set command, issue a commit command to commit the variables that have been set to the gateway's running configuration. Changes to the configurable data do not take effect until you issue a commit command. This command takes all outstanding set configuration requests and applies them to the gateway. On success, the running configuration of the gateway changes. It's often a good idea to issue commit commands immediately after each set request, so that if a set request fails, you can find out sooner.

Example:

To set and commit the user group for a CLI user:

BASH

% set aaa auth-provider local user bsmith group wheel
% commit
Commit succeeded.

compare

Configuration only.

The compare command is useful for viewing the diffs of your working non-committed configuration of the gateway and the current running configuration for the gateway. Non-committed configurations represent a "configuration in progress" for the purpose of checking what has changed before committing any of the changes. Viewing options are brief or full. Values that changed are marked with a minus (-) to indicate the previously committed change and plus (+) to indicate the current non-committed change.

Examples:

Showing the change in value for admin-state that is uncommitted.

BASH

% compare brief
configuration {
  context default {
    aaa {
      auth-provider {
        local {
          user bsmith {
            - group engineering;
            + group trainer;
          }
          + user jmontana {
            + group finance;
            + }
          }
        }
      }
    }
  }
% compare full
  context default {
    aaa {
      pki {
        certificate-revocation {
          crl {
            policy off;
            cache-size 5;
          }
        }
      }
      auth-group default {
        login-prompt "Please enter your login credentials.";
        dormant-session-timeout 30;
        certificate-enrollment {
          enabled false;
          email-pin false;
        }
        provider local {
        search-order 100;
        }
      }
      auth-provider {
        local {
          user admin {
            password $6$ySv5tll1$nyQbuLqlMSWJVmKY4CR1HrazReS5C3/ib6RgnmsmoKs2al0oyqRtSvdKlYDLNJI5.Q5VPLArV3CFSd4sHiL.6.;
            group default;
          }
          group wheel {
            administrator true;
            jailbreak-permitted false;
            tampered-apps-permitted false;
          }
...

delete

Configuration only.

The delete command deletes an entire element. Not all elements on the gateway can be deleted. This command is equivalent to the industry-standard commands of "no" or "clear configure".

Example:

Deleting user "joesmith".

BASH

% delete aaa auth-provider local user joesmith
% commit
Commit succeeded.
% show aaa auth-provider local user joesmith
No entries found

edit

Similar to a path command in that you can set a relative path to a specific level of the command hierarchy. However, unlike path, edit can insert or set values when they are appended at the end of the command.

Configuration only.

Example:

Setting the value of an element using edit

Note: This example shows the command prompt so you can see the level of the navigation tree that the user is in.

BASH

bcvac:default % edit aaa auth-provider local user bsmith
bcvac:bsmith % edit password abc123
bcvac:password % commit
Commit succeeded.

exit

In configure mode, the exit command instructs the CLI to leave configure mode, and go to operational mode.

In operational mode, the exit command instructs the CLI to terminate the CLI session. In other words, use exit to logout of the CLI.

Examples:

To exit configure mode:

Note: The example includes the command-line prompt on each line. The prompt shows that you are in operational mode after entering the exit command while in configuration mode.

BASH

% exit
>

To terminate the CLI session:

BASH

> exit
Terminating CLI Session
Connection to 192.168.8.24 closed.

Note: When you exit configuration mode, the ">" prompt replaces the "%" prompt, which means you are in operational mode.

help

Operational and configuration.

The help command displays the help-string for the requested command. Enter help followed by Return to show the help strings for all commands at that level of the CLI.

Examples:

Enter help at the top level of the command hierarchy to get a list of commands at the top level.

BASH

> help
  command   - Execute a custom command
  configure - Enter configuration mode
  clone     - Make a copy of a named datastore
  exit      - Exit the CLI session
  file      - Perform file operations
  help      - Display help information
  history   - Display CLI command history
  log       - Show or clear system log
  network   - Perform network operations
  path      - Set relative path for operational status
  quit      - Exit the CLI session
  remove    - Remove a named datastore
  request   - Make a device level request
  set       - Set CLI properties
  show      - Show information about the device
  source    - Execute commands from a file
  top       - Reset relative path to the top level
  up        - Set relative path up one level

Enter help with a specific command to display the help string for that command.

BASH

% help top 
  top       - Reset configuration path to the top level

insert

Configuration only.

The insert command allows you to create an element using a single command-line. An element is a leaf node and is similar to a row in a table. For example, when you insert a port, all configurable variables that do not have default values must be present.

Because set and commit can be used instead of insert, you can think of insert as an alternative (or optional) command.

Example

The following command creates ethernet port 1 with default values.

BASH

% insert ports ethernet1
% show ports ethernet1
ethernet1 {
  address     0.0.0.0;
  netmask     0.0.0.0;
  gateway     0.0.0.0;
  admin-state up;
  addr-type   static;
  mtu         1500;
  speed       1g;
  duplex      full;
  autoneg     enabled;
  security    private;
  management  false;
}

load

Configuration only.

Use this command to restore a previously saved configuration. You can merge a saved configuration with the current running configuration or override the current running configuration with the previously saved configuration. When upgrading to a new version, use load merge to restore the saved configuration.

Example:

To load a file that overrides a previously saved configuration:

BASH

% load merge myconfig.cfg
% commit
Commit succeeded.

network dns-lookup

Operational only.

The dns-lookup utility is useful to validate DNS configuration, locate the IP addresses associated with a domain name, and to check if that DNS (Domain Name System) resolution is working for the hosts. This helps you identify if the issue is with the client, a network DNS server, or network firewall rules.

To perform the dns-lookup, use the following command in operational mode:

BASH

> network dns-lookup hostname

Use the -x option for a reverse lookup, that is, starting with an IP address:

BASH

> network dns-lookup -x IP-address

For more examples, see Network testing and diagnostic procedures.

The dns-lookup command takes these options:

Option	Description
domain	The hostname to look up
-x dot_notation	Use reverse DNS lookup for IPv4 or IPv6 addresses.
dns-server	Optional. Specify a DNS server to use
-b source_address	Use this IPv4 source address for the query
-t record_type	Return the specified record type (only one per query): A: Default. IPv4 address record AAAA: IPv6 address record CNAME: canonical name for an alias record MX: mail exchange records associated with the domain NS: authoritative name server record PTR: domain name pointer record, or DNS reverse lookup SOA: start of authority record TXT: text record, that is, human readable notes about a domain

network ping

Operational only.

The ping command is a common method for troubleshooting the accessibility of network devices. It helps determine latency and packet loss, factors that tell you about the round-trip delay in communicating with the destination.

Examples:

To validate if the gateway can reach a network resource:

BASH

> network ping 8.8.8.8
Initiating ping (Ctrl-C to cancel)...
PING 8.8.8.8 (8.8.8.8) 56(84) bytes of data.
64 bytes from 8.8.8.8: icmp_seq=1 ttl=116 time=14.6 ms
64 bytes from 8.8.8.8: icmp_seq=2 ttl=116 time=14.3 ms
64 bytes from 8.8.8.8: icmp_seq=3 ttl=116 time=14.4 ms

For more examples, see Network testing and diagnostic procedures.

On the Blue Cedar Connect Gateway, the ping command takes these options:

Option	Description
`-c` count	The number of packets to transmit.
`-i` interval	Wait interval seconds between sending each packet.
`-I` source-IP-address	IP address for the source.
`-s` packetsize	Number of bytes in each packet to transmit. Default: 64
destination-IP-address	IP address for the destination.

network traceroute

Operational only.

Traceroute is a utility for troubleshooting network issues. Use traceroute to find the routes that the packets actually take when traveling to their destination. Traceroute shows what network devices are between one point and another, and some data about what those devices are doing. It can also help diagnose routing issues, especially when there is more than one network connection.

To check the routers along the path to the domain you are trying to reach:

BASH

> network traceroute 10.10.99.99
Initiating traceroute (Ctrl-C to cancel)...
traceroute to 10.10.99.99 (10.10.99.99), 30 hops max, 60 byte packets
send: Operation not permitted

The above error indicates that the packet is being routed out the public interface to an external server. Such routes are not allowed: traceroute is intended to find the route that a packet takes via the private interface.

To check routes from the mobile client to endpoints via the gateway, if the mobile client address-pool is configured on the gateway as static or dhcp addressing, you can choose a source address from the address pool and specify it with the -s option.

BASH

> network traceroute -s 192.168.50.3 8.8.8.8
Initiating traceroute (Ctrl-C to cancel)...
traceroute to 8.8.8.8 (8.8.8.8), 30 hops max, 60 byte packets
1 gateway (10.42.32.1) 0.835 ms 1.196 ms 1.340 ms
2 gi0-1-1-6.1288.agr22.bos01.atlas.cogentco.com (38.88.209.1) 6.708 ms 6.799 ms 6.848 ms
3 be3665.ccr32.bos01.atlas.cogentco.com (154.54.87.109) 7.154 ms 7.508 ms 7.560 ms
4 be3472.ccr42.jfk02.atlas.cogentco.com (154.54.46.34) 13.769 ms be3471.ccr41.jfk02.atlas.cogentco.com (154.54.40.154) 13.967 ms 13.972 ms
5 be3294.ccr31.jfk05.atlas.cogentco.com (154.54.47.218) 14.182 ms 14.503 ms 14.353 ms
6 tata.jfk05.atlas.cogentco.com (154.54.12.18) 14.663 ms 11.031 ms 10.846 ms
7 if-ae-12-2.tcore1.n75-newyork.as6453.net (66.110.96.5) 12.085 ms 12.054 ms 12.082 ms
8 72.14.195.232 (72.14.195.232) 12.671 ms 17.691 ms 12.868 ms
9 108.170.248.97 (108.170.248.97) 12.688 ms 12.689 ms 13.469 ms
10 216.239.62.147 (216.239.62.147) 13.546 ms 142.250.46.197 (142.250.46.197) 14.046 ms 172.253.70.7 (172.253.70.7) 15.424 ms
11 dns.google (8.8.8.8) 15.421 ms 15.034 ms 14.863 ms

For more examples, see Network testing and diagnostic procedures.

On the Blue Cedar Connect Gateway, the traceroute command takes these options:

Option	Description
-n	Do not try to map IP addresses to hostnames when displaying them
-r	Bypass the normal routing tables and send directly to a host on an attached network. This option can be used to ping a local host through an interface that has no route through it. Returns an error if the host is not on a directly attached network.
-w wait	Time in seconds to wait for a response to a probe.
-m max_ttl	Maximum number of hops (max time-to-live) traceroute will probe. Default: 30
-p port#	Specify the destination port base traceroute will use.
-q nqueries	Sets the number of probe packets per hop.
-t tos	Set the type of service and precedence value. Useful values are 16 (low delay) and 8 (high throughput).
-s source-IP-address	IP address for the source.
destination-IP-address	IP address for the destination.

path

Operational only.

The path command sets the relative path to the level of the command hierarchy that the administrative user wants. Useful for saving on inputting the entire path for commands. Acts like a “shortcut” to navigate to the desired command level that you have set.

To set a relative path in configuration mode, use the edit command.

If you set the relative path while in operational mode but later you want to return to the top-level of the CLI navigation tree, enter top at the command-line prompt. This returns you to the top level of the editing scope.

Examples:

Set the path to a lower level in the command hierarchy while in operational mode:

BASH

bcvac:/ > path configuration context default aaa
bcvac:aaa >

Set the path to a lower level in the command hierarchy while in configuration mode:

BASH

bcvac:default % edit aaa auth-provider
bcvac:auth-provider % show local
local {
 user admin {
   password       $6$ySv5tll1$nyQbuLqlMSWJVmKY4CR1HrazReS5C3/ib6RgnmsmoKs2al0oyqRtSvdKlYDLNJI5.Q5VPLArV3CFSd4sHiL.6.;
   group          wheel;
   email-address  jsmith@acme.com
 }
 group wheel {
   administrator       true;
   jailbreak-permitted false;
   tampered-apps-permitted false;
 }
 user jdoe {
   email-address  jdoe@acme.com;
   group          finance;
   password       $6$Huf/ZwpO$QHb.WRPcqECgqpQn/xbh.02gz7S6nbwSrb5OjEz7FG4.CBc1j1LXSKBVpy94BtZKcveRlzMqA0U4HyVC9h5ol1;
 }
 group finance {
   administrator           true;
   jailbreak-permitted     false;
   tampered-apps-permitted false;
 }
}

quit

Operational and configuration.

The quit command performs exactly the same operation as the exit command.

request

Operational only.

Use the request command to execute actions that the gateway should take. Most of the commands are related to upgrading the currently installed software, adding or removing an Active Directory server domain, or flushing dormant federation sessions on the gateway.

These are the request elements that the gateway currently supports:

BASH

Possible completions:
  active-directory-debug            - Enables or Disables debug for Active Directory services
  clear-active-directory-cache      - Clears the Active Directory cache
  clear-active-notification         - Clears an active notification with a given sequence number
  clear-sso-cache                   - Clears the SSO cache for the specified federation session
  cold-upgrade                      - Perform a cold upgrade (cluster restart)
  commit-release                    - Commit the active release
  copy-release                      - Create a new release from another
  deselect-image                    - Deselect image selected for upgrade
  deselect-releases                 - Deselect all releases selected as upgrade targets
  discover-releases                 - Perform release discovery
  dump-config-profile               - Dumps the contents of a config profile in JSON
  fips-mode                         - Enables/Disables FIPS mode
  flush-auth-lockout-table          - Clears the auth lockout table or a user in the table
  flush-dormant-federation-sessions - Clears dormant federation sessions
  flush-session                     - Clears a federation session
  get-data-model                    - Returns a json enoded object that describes the model associated with the active release
  install-image                     - Install an image
  install-release                   - Install a new software release candidate
  join-active-directory-domain      - Joins the gateway to a Microsoft Active Directory domain
  leave-active-directory-domain     - Leaves the Microsoft Active Directory domain to which the gateway was previously joined
  list-active-notifications         - list all currently active notifications
  list-images                       - List images from Docker registry
  list-releases                     - List all currently installed releases
  powerdown-system                  - Power down system
  reboot-system                     - Reboot system
  remove-release                    - Remove the specified release
  remove-ssh-known-hosts            - Removes one or all SSH known hosts used by the 'file copy' command.  If no 'pattern' is specified, removes all known hosts.
  restart-active-directory-services - Restarts the active directory services component
  select-image                      - Select an image as an upgrade target
  select-release                    - Select a release as an upgrade target
  set-console-password              - Sets the password for the 'console' user used to log into the Atlas through the serial interface
  set-current-datetime              - Set the /system-operational/clock/current-datetime leaf to the specified value.  If the system is using NTP (i.e., /system/ntp/enable is set to 'true'), then this operation will fail with error-tag 'operation-failed',
  snmp-verbose-debug                - Enables or Disables SNMP verbose debugging
  soft-restart                      - Perform a soft restart of system
  test-enrollment-email             - Diagnostic command to test delivery of Atlas Enrollment PIN independent of client connection
  test-web-request                  - Request a web resource to make sure it is responsive and (if https) trusted by Atlas.
  upgrade-image                     - Upgrade to selected image
  verify-release                    - Verify the specified release

Example:

To perform a soft-restart of the gateway:

BASH

> request soft-restart
message "Cluster is being restarted";
Connection to 192.168.3.24 closed.

request test-web-request

Operational only.

The test-web-request utility is a tool to diagnose potential connectivity issues. Use this command to determine if the gateway can reach a specified URL, and for HTTPS requests, determine if the gateway can trust the identity certificate of that resource.

Use test-web-request to validate that the gateway can reach HTTP(S) endpoints (https://www.trusted-resource.com in this example). HTTP(S) requests can be used to test web servers, SCEP servers, or LDAP server reachability. If your mobile client address pool is set to NAT addressing, then using test-web-request to validate in this manner is a valid test for both gateway traffic and mobile client traffic: both traffic sources are sourced from the gateway's private interface IP address.

BASH

> request test-web-request url https://www.trusted-resource.com

For more examples, see Network testing and diagnostic procedures.

The test-web-request command takes these options:

Option	Description
src-ip-address address	Source IP address to send the request from
url destination	A URL to request connection to
username user	HTTP basic auth username
password password	HTTP basic auth password
post-body string	HTTP Post basic body
verbose boolean	True: Use verbose logging False (default): Do not use verbose logging

revert

Configuration only.

The revert command essentially removes the data that has been set but not yet committed.

save

Configuration only.

When you have a working configuration of the gateway, you can save it to be retrieved later. To save a configuration, the CLI must be in configure mode.

Example:

These commands save a new configuration file and then check that it has been saved (using the file list command in operational mode).

BASH

% save 04-09-20_configuration.cfg
% exit
> file list
04-09-20_configuration.cfg
file.mbconf
file.text

set and commit (required)

Configuration only.

The commands CLI Command Reference#set followed by CLI Command Reference#commit are the required commands for configuring data via the CLI.

In configuration mode, the set command indicates that the operator is configuring data. Like other industry-standard CLIs, the gateway's set command lets you drill down to a specific element (or node). You can set the configurable data in one of the following ways: one at a time, all at once, or a few at a time. Also, you can set variables in any order.

Data is categorized logically based on the type of data. For example, data that is associated with a specific port includes data that is specific to that port. such as the admin status of the port, the IP address of the port, the subnet mask of the port, and so forth.

After you issue a set command, you need to issue a "commit" command to commit the variables that have been "set" to the gateway's running configuration.

Example:

Setting and committing the user group for a CLI user:

BASH

% set aaa auth-provider local user bsmith group wheel
% commit
Commit succeeded.

show

Operational and configuration.

The show command is used to display data, which appears within an element using curly braces { } as delimiters.

Examples:

In configuration mode, use show to display the settings for a specified component:

BASH

% show security
security {
  ike default {
    admin-state            down;
    dpd                    10;
    fragment-enable        on;
    dh-group               14;
    cipher                 aes256;
    hash                   sha2_256;
    life-secs-max          86400;
    security-parameter-set default;
    mode                   proprietary;
[...]

BASH

% show ports ethernet1 
ports ethernet1 {
  description "Public interface";
  addr-type   dhcp;
  address     0.0.0.0;
  netmask     0.0.0.0;
  gateway     0.0.0.0;
  admin-state up;
  security    public;
  management  false;
  mtu         0;
}

In operational mode at the top level, show all displays all of the data for the current implementation:

BASH

> show all
configuration {
  session {
    params {
      idle-timeout 1200;
    }
    users {
      user root {
        authorization-id root;
      }
      user mbuser {
        authorization-id root;
      }
      user bcnuser {
        authorization-id root;
      }
      user snmp {
        authorization-id operator;
      }
    }
    access {
      entry root {
        full-access allow;
      }
      entry operator {
        session-access     allow;
        config-read-access allow;
        oper-read-access   allow;
      }
      entry read-only {
        session-access            allow;
        config-read-access        allow;
  context default {
    security {
      ike default {
        admin-state            down;
        dpd                    10;
        fragment-enable        on;
        dh-group               14;
        cipher                 aes256;
        hash                   sha2_256;
        life-secs-max          86400;
        security-parameter-set default;
        mode                   proprietary;
      }
      security-parameter-set default {
        cipher          aes256;
        hmac            sha2_256;
        life-secs-max   86400;
        life-kbytes-max 0;
        pfs             on;
      }
    }
   ...

top

Operational and configuration.

The top command instructs the CLI to set the relative path to the top of whichever mode the operator is currently in.

Example:

Use top to navigate to the top-level of the command hierarchy

Note: The example includes the command-line prompt on each line. The prompt shows that you are at the top of the navigation tree after entering the top command.

BASH

bcbcvac:/ > path configuration context default aaa pki identity-certificate
bcvac:identity-certificate > top
bcvac:/ >

up

Operational and configuration.

After a path or edit command has been issued, you can navigate up one level by using the up command.

Example:

To navigate up one level at a time to the top level:

Note: The example includes the command-line prompt on each line. It shows where you are in the navigation tree after entering each up command.

BASH

bcvac:/ > path configuration context default aaa pki identity-certificate
bcvac:identity-certificate > up
bcvac:pki > up
bcvac:aaa > up
bcvac:default > up
bcvac:context > up
bcvac:configuration > up
bcvac:/ > up
bcvac:/ >

validate

Configuration only.

The validate command validates the data that you have set but not yet committed. Additionally, you can use the validate command to show any outstanding configuration requests that have not yet been committed.