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
get	g	Retrieve a list or single item
replace	r	Replace a list or single item
update	u	Update an item, supports partial edits
merge	m	Merge a provided list with existing config
create	c	Create an item
help	h	Display ogcli help
export	e	Export the system configuration
import	i	Import system configuration, merging with current system configuration
restore		Import system configuration, replacing the current system configuration

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 behaviour 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>

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 serialports

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