Opengear CLI Guide

The ogcli command line tool is used for getting and setting configuration, and for retrieving device state and information. The purpose of ogcli is perform a single operation and exit. Operations are performed on a single entity, a list of entities, or all entities. Entities in ogcli are collections of related information items that represent device state, information or configuration.

For a list of operations supported by ogcli, see the "ogcli Operations" section.

Note: ogcli is not an interactive shell, it runs a single command and exits.

Getting Started with ogcli

The best way to get started with ogcli is to use the help command. Refer to the table below to access help topics within ogcli.

For detailed information about ogcli and how it works, view the ogcli help topic by running this command:

ogcli help ogcli

Access ogcli Help and Usage Information

Help Command	Displays...
ogcli help	Basic ogcli help and usage information.
ogcli help <concept>	More detailed help about a specific ogcli concept.
ogcli help help	Detailed information about the help command.
ogcli help operations	The full list of operations and a brief description of each.
ogcli help entities	The full list of entities and a brief description of each.
ogcli help syntax	How to get information into and out of ogcli.
ogcli help ogcli	More detailed information about the ogcli tool.
ogcli help usage	Common ogcli usage examples.
ogcli help notation	A simple notation reference for ogcli.
ogcli help secrets	Detailed information about controlling the display of secrets in ogcli.
ogcli help <operation>	A description and example usage of a specific ogcli operation.
ogcli help <entity>	A description of a specific entity and the operations it supports.
ogcli help <entity> <operation>	An example of how to perform a specific operation on a specific entity.
ogcli help <entity> <field>	Additional information about an entity's field.

Basic Syntax

The ogcli tool is always called with an operation, with most operations also taking one or more arguments specifying an entity for the operation to act on.

ogcli <operation> [argument] [argument]

ogcli Operations

Operation	Shortcut	Description
create	c	Create an item.
export	e	Export the system configuration.
diff		Show additions, removals, changes and functional differences between the input and running configurations. See also `config diff`.
get	g	Retrieve a list or single item.
help	h	Display ogcli help.
import	i	Import system configuration, merging with current system configuration.
merge	m	Merge a provided list with existing config.
replace	r	Replace a list or single item.
restore		Import system configuration, replacing the current system configuration.
update	u	Update an item, supports partial edits.

Supplying Data To ogcli

For operations that modify an entity (e.g. 'update') the new information can be passed as inline positional arguments, but this quickly becomes cumbersome when setting a large number of fields. Information can instead be supplied through stdin by piping the contents of a file, or with Here Document (heredoc) style. The heredoc style is the most flexible format and is used extensively in ogcli examples.

Here Document

A here document (heredoc) is a form of input redirection that allows entering multiple lines of input to a command. The syntax of writing heredoc takes the following form:

ogcli [command] << 'DELIMITER'
HEREDOC
DELIMITER

The first line starts with the ogcli command, followed by the special redirection operator << and a delimiting identifier. Any word can be used as the delimiter, commonly 'EOF' or 'END'.
The HEREDOC block can contain multiple lines of strings, variables, commands or any other type of input. Each line can specify one field to update.
The last line ends with the delimiting identifier used above, indicating the end of input.

ogcli update user <username> << 'END'
description="operator"
enabled=false
END

Inline Arguments

Field data can be entered inline with the ogcli command as arguments, with each field separated by a space.

ogcli update user <username> enabled=false description=\"operator\"

Pipes and Standard Input

The data can also be entered via stdin by piping the data to the ogcli command.

echo 'enabled=true description="operator"' | ogcli update user <username>

Alternatively, you can provide a file via input redirection with <.

echo 'enabled=true description="operator"' > partial_record

ogcli update user <username> < partial_record

Quoting String Values

All string fields require the argument to be specified with double quotes ". The shell can consume double quotes, so care must be taken when specifying strings to ensure the quotes are passed to ogcli as input.

Double quotes in heredoc do not need to be escaped.

ogcli update physif <device-identifier> << 'END'
description="test network"
END
Double quotes within single quotes do not need to be escaped.

ogcli update physif user <username> 'description="test user"'
Double quotes not within single quotes need to be escaped.

ogcli update physif user <username> description=\"test user\"

Tab Completion

ogcli includes tab completion to assist with typing commands. When entering the start of a command, press the <tab> key to complete the phrase to the nearest match.

If there are multiple matches, all options will be displayed for your reference.

Displaying Secrets in ogcli

Fields containing sensitive information are called secrets, which are handled specially by ogcli to obfuscate their values when they are displayed or exported.

Passwords and private keys are examples of secret fields.

The obfuscation process provides protection against "casual observation" only and offers no cryptographic security. The obfusc tool can be used to obtain the clear text version of any obfuscated secret generated by any Console Manager.

For more information, view the secrets help topic by running:

ogcli help secrets

The default behavior is for secrets to be passed to ogcli in clear text, and exported or displayed in obfuscated form.

For example, setting the password:

ogcli update services/snmpd auth_password=\"my secret\"

Retrieving the password (note, the output is abridged):

# ogcli get services/snmpd
auth_password="TkcxJAAAABBSB3xoFWhPA6B7sDrzq3HwaTOAO/jsURqFa0qa7hc3TA=="

This behavior can be overridden to display sensitive fields in clear text, obfuscated form, or masked form using the --secrets option. The clear text and obfuscated forms are also accepted when supplying a sensitive field.

# ogcli --secrets=cleartext get snmpd
auth_password="my_secret"

# ogcli --secrets=obfuscate get snmpd
auth_password="my secret"

# ogcli --secrets=mask get snmpd
auth_password="********"

If an export is performed with the --secrets=mask option it is impossible to subsequently import the configuration, because the secrets have been removed.

Common Configuration Examples

These examples contain a variety of notations and usage patterns to help illustrate the flexibility of ogcli. The examples can be copied and pasted into the CLI.

Replace Message of the Day (MOTD) Displayed at login

ogcli replace banner banner=\"updated message\"

Retrieve User Record

ogcli get user <username>

Update Item with Field Where Value is a String

ogcli update user <username> description=\"operator\"

Update Item with Field Where Value is Not a String

For example, a numeric or boolean value

ogcli update user <username> enabled=true

Export System Configuration

ogcli export <file_path>

Import System Configuration

ogcli import <file_path>

Restore System Configuration

ogcli restore <file_path>

Compare Current Configuration with a Proposed Configuration

The updated ogcli diff tool enables Opengear users to compare a proposed configuration with an existing configuration so that they may understand any prospective changes to the config.

The diff function performs a comparison of active configuration and an input configuration file, which must be in the format an export file produced by either a config export <template-file> or an ogcli export <template-file> operation. Any manual changes to this export file must include config or ogcli commands in a multi-line format using the ‘END’ heredoc marker as produced by an export. One line config or ogcli commands will not be accepted.

Using the diff Tool

The diff tool can be used by any user with Administrator permission via the command line.

ogcli diff <input file>

or using config:

config diff <input file>

Note: config diff and ogcli diff, and can be used interchangeably using export files in either format.

If there are no differences between the active configuration and the input configuration file, the diff tool will not print any output, and the operation will have an exit code of 0.

root@om2248:~# ogcli export config_file
root@om2248:~# ogcli diff config_file
root@om2248:~# echo $?
0

The diff function will show any additions, removals and changes clearly in a streamlined format with only functional differences between the input and running configurations. Any additions that will be made to the active configuration are marked with a (+). For example, the new_user user does not exist in the active configuration, but is present in the input file supplied. If the input file was imported, this user would be added.

ogcli --secrets=obfuscate merge users <<'END'
+ users[1].enabled=true
+ users[1].groups[0]="admin"
+ users[1].no_password=false
+ users[1].ssh_password_enabled=true
+ users[1].username="new_user"
END

If the new_user user exists in the active configuration, but does not exist in the input file, this user will be removed if the input file was imported or restored. Removals will be marked with a (-) symbol.

ogcli --secrets=obfuscate merge users <<'END'
- users[1].enabled=true
- users[1].groups[0]="admin"
- users[1].no_password=false
- users[1].ssh_password_enabled=true
- users[1].username="new_user"
END

Changes in configuration between an item which exists in both the active configuration and the input file will also be displayed. The existing configuration will be marked with a (-) and the incoming change as a (+). In the example below, the new_user user belongs to the netgrp group on the device. However, if the input file is imported, it will belong only to the Admin group.

ogcli --secrets=obfuscate merge users <<'END'
- users[1].groups[0]="netgrp"
- users[1].groups[1]="admin"
+ users[1].groups[0]="admin"
END

If any differences are found, the operation will have an exit code of 1. If there are any errors, the diff tool will have an exit code of 2.

Comparison to Default Values

If the input configuration file is missing properties or sections of configuration, the diff function will instead consider the differences between active configuration and the default values for those properties. Missing sections or properties from the input file will only be displayed in the diff tool output if the active configuration is different from the default system values. If any property or configuration section is missing from input configuration, and the running configuration is identical to the system defaults, it is omitted from the diff output.

How Secrets are Handled

The --secrets flag can be used to control how sensitive fields are displayed in the diff output. By default, sensitive fields are obfuscated. If the proposed config file was exported with --secrets=cleartext or --secrets=mask then the same value must be used when running ogcli diff.

root@om2248:~# ogcli --secrets=cleartext export config_file
root@om2248:~# ogcli --secrets=cleartext diff config_file

If the input file contains a different --secrets parameter than is passed to ogcli diff or config diff, an error will be returned:

root@om2248:~# config --secrets=cleartext export config_file
oot@om2248:~# config --secrets=cleartext diff config_file
root@om2248:~# config --secrets=mask diff config_file
The secrets flag provided doesn't match the flag in the proposed config for physifs.
This error can be ignored with the --ignore-secrets-mismatch flag.
Type ogcli diff --help for more information.

This behaviour is the same for config:

The --ignore-secrets-mismatch flag can be used to ignore a difference in the --secrets parameter:

root@om2248:~# ogcli diff --ignore-secrets-mismatch config_file

Diff Tool Help

Basic help for ogcli diff can be accessed with ogcli diff -h. Similarly, help for config diff can be accessed with config diff -h. Detailed help for both diff tools can be accessed by ogcli help diff.

Limitations
JSON template files are no longer supported with config diff.
`ogcli diff` only supports input configurations generated by the same product SKU and software version.
Comments can be included between ogcli or config commands in the export file, but not within the commands or an error will be thrown. Comments must start with #. These will be ignored by the diff tool.

Enable Local Console Boot Messages

ogcli get managementports

ogcli update managementport mgmtPorts-1 kerneldebug=true

Create New User

ogcli create user << 'END'
description="superuser"
enabled=true
groups[0]="admin"
password=”test123"
username="superuser123"
END

Change Root Password

ogcli update user root password=\"oursecret\"

Create New Administrative User

ogcli create user << 'END'
username="adal"
description="Ada Lovelace"
enabled=true
no_password=false
groups[0]="groups-1"
password="oursecret"
END

Manually Set Date and Time

ogcli update system/timezone timezone=\"America/New_York\"

ogcli update system/time time=\"15:30 Mar 27, 2020\"

Enable NTP Service

ogcli update services/ntp << 'END'
enabled=true
servers[0].value="0.au.pool.ntp.org"
END

Update System Hostname

ogcli update hostname hostname=\"system-hostname\"

Adjust Session Timeouts

ogcli update system/cli_session_timeout timeout=180

ogcli update system/webui_session_timeout timeout=180

Setup Remote Authentication with TACACS+

ogcli update auth << 'END'
mode="tacacs"
tacacsAuthenticationServers[0].hostname="192.168.250.21"
tacacsMethod="pap"
tacacsPassword="tackey"
END

Setup Remote Authentication with Radius

ogcli update auth << 'END'
mode="radius"
radiusAuthenticationServers[0].hostname="192.168.250.21"
radiusAccountingServers[0].hostname="192.168.250.21"
radiusPassword="radkey"
END

Create User Group with Limited Access to Serial Ports

ogcli create group << 'END'
description="Console Operators"
groupname="operators"
role="ConsoleUser"
mode="scoped"
ports[0]="ports-10"
ports[1]="ports-11"
ports[2]="ports-12"
END

View and Configure Network Connections

ogcli get conns

ogcli get conn system_net_conns-1

ogcli update conn system_net_conns-1 ipv4_static_settings.address=\"192.168.0.3\"

ogcli create conn << 'END'
description="2nd IPv4 Static Address Example"
mode="static"
ipv4_static_settings.address="192.168.33.33"
ipv4_static_settings.netmask="255.255.255.0"
ipv4_static_settings.gateway="192.168.33.254"
physif="net1"
END

Configure a DNS

DNS settings such as Name Servers and Search Domains can be configured for each network interface, which will override the DHCP provided settings.

Name servers allow the system to resolve hostnames to IP addresses to communicate with remote systems. Search domains allow the system to resolve partially qualified domain names (PQDN) by appending entries from the listed search domains to form a fully qualified domain name (FQDN).

When adding an interface to a Bond or Bridge, it will use the DNS configuration of the aggregate interface.

Note: Interfaces must have at least one network connection to be able to perform DNS resolution.

Configure a DNS via the Command Line

Description	Command
Display configured DNS settings for an interface	ogcli get physif "net1"
Update DNS settings for an interface	ogcli update physif "net1" << END dns.nameservers[0]="1.1.1.1" dns.nameservers[1]="1.0.0.1" dns.search_domains[0]="example.net" dns.search_domains[1]="example.com" END
Check unbound service status	systemctl status unbound.service
List forward-zones in use	unbound-control list_forwards

Configure Serial Ports

ogcli get ports

ogcli get ports | grep label

ogcli get port ports-1

ogcli update port "port05" << 'END'
mode="consoleServer"
label="Router"
pinout="X2"
baudrate="9600"
databits="8"
parity="none"
stopbits="1"
escape_char="~"
ip_alias[0].ipaddress="192.168.33.35/24"
ip_alias[0].interface="net1"
logging_level="eventsOnly"
END

Enable Cellular Modem Interface

ogcli get physifs

ogcli update physif wwan0 << 'END'
enabled=true
physif.cellular_setting.apn="broadband"
physif.cellular_setting.iptype="IPv4v6"
END

Disable Cellular Modem Interface

ogcli update physif physif wwan0 enabled=false