Configuring from the command line

After logging in via SSH or the local serial console, advanced users may configure the Opengear device from its Linux-based command line.  Configuration privileges are granted to root and admin group users.

Configuration system background

Most CLI configuration tasks are accomplished using Opengear's config command.  config stores and generates system configuration using the /etc/config/config.xml master configuration file.

Configuration settings are stored as ID, value pairs in a tree structure – e.g. the config ID config.ports.port1.label may have the value Cisco Switch.  The underlying data is stored in /etc/config/config.xml, where each dot-delimited field represents a sub-element in the XML tree structure, e.g.:

<config>
    <ports>
        <port1>
            <label>Cisco Switch</label>
            ...
        </port1>
        ...
    </ports>
...
</config>

Generally speaking, each config setting corresponds to a field in the web UI, however this isn't strictly the case.

The current system state is synced from stored configuration settings by running configurators – this is broadly equivalent to clicking Apply in the web UI.

In many cases the configurator name will match the URL "form" variable of the corresponding web UI page, e.g. serialconfig.  In this way, configurators can be selectively as they will automatically run any dependent configurators – e.g. running ipconfig to apply a new IP address will run services (and others) to restart network services.  You may also run all configurators for a full sync.

System configuration files are stored under /etc/config/ and can be edited, however many of these files are auto-generated by the configurators so any modifications will be overwritten.  To persist custom modifications, refer to this article.

config command examples

Warning: Manipulating configuration using arbitrary config commands may render your Opengear device unbootable.  Before proceeding, ensure you have taken a backup.

Display complete usage/help:

config -h

Display (get) the entire configuration (this does not display all possible IDs, only those that are set):

config -g config

Display a subsection of the configuration tree:

config -g config.ports.port1

Set a value for a configuration ID (validation is not enforced when using the CLI, take care to set appropriate values):

config -s config.ports.port1.label="Cisco Switch"

Delete an ID/value pair:

config -d config.ports.port1.label

Delete an entire subsection:

config -d config.ports.port1

Run a configurator to apply settings:

config -r serialconfig

Run all configurators to apply settings:

config -a

Hints & tips

– You can chain config commands, this can be significantly faster than running separate commands as config.xml is only read/written once:

config -s config.ports.port1.label="Cisco Switch" -s config.ports.port1.speed=9600 -r serialconfig

– The usual bash escaping caveats apply when operating at the CLI, so take care to appropriate escape special characters such as space and $ with single quotes, double quotes or backslashes.

– You will find examples of various configuration tasks throughout this knowledge base, e.g. network interface setup and serial port setup.  However, sometimes the simplest way to discover how to accomplish a configuration task via CLI is to try it through the web UI and see what changed:

• Save "before" config

config -g config > /tmp/config.old

• Set and apply changes via the web UI
• Save "after" config

config -g config > /tmp/config.new

• Compare before and after

diff /tmp/config.old /tmp/config.new

– You can queue all configurators to run next boot, by running:

touch /etc/config/.run_configurators
reboot

– You can "get" configuration transformed into properly escaped "set" format using the following command:

config -g config | awk '{ printf "config -s '\''%s", $1; $1=""; gsub(/'\''/, "'\''\\'\'''\''"); printf "=%s'\''\n", substr($0, 2); }'

– Some config subsections are lists that have a "total" item, that must be updated to reflect new or deleted items.  The "List Operations" are provided to automatically handle this:

prefix=$(config --list-base config.firewall.portrules --list-add)
config -s $prefix.name="New Firewall Rule" -s $prefix.action=accept # and so on

– Standard bash for and while loops come in handy to automate repetitive configuration tasks:

# Set serial ports 2, 5, 10, 11 and 23 to Console Server mode
for PORTNUM in 2 5 10 11 23; do config -s config.ports.port$PORTNUM.mode=portmanager; done
config -r serialconfig

# Set all serial ports to Console Server mode
TOTAL=$(cat /var/run/serial-ports | wc -l)
PORTNUM=0
while [[ $(( PORTNUM++ )) -lt $TOTAL ]]; do config -s config.ports.port$PORTNUM.mode=portmanager; done
config -r serialconfig