UniConfig shell is a command-line interface for Uniconfig. Accessible over SSH, it allows users to interact with Uniconfig features including the following:
Read operational data of devices
Manipulate device configurations
Manipulate configuration templates
Manipulate data stored in Unistore
Invoke device or UniConfig operations
Manipulate global UniConfig settings
Uniconfig shell is model-driven, therefore its interface is mostly auto-generated from YANG schemas (e.g., tree structure of data-nodes or available RPC/action operations).
UniConfig shell is disabled by default. To enable it, set the configuration parameter cli-shell.ssh-server.enabled to true in the application.properties file.
All available settings and descriptions are listed below:
After starting UniConfig, the SSH server listens for connections on port 2022 and the loopback interface. UniConfig Shell has two connection timeouts:
Authorization timeout, after which the connection is closed if the other party has not been authenticated (in seconds). The default value is 120 seconds.
Idle timeout, after which the connection is closed if idle (in seconds). The default value is 600 seconds.
Every command line starts with a command prompt that ends with the > character. The identifier of the command prompt changes based on the current shell mode and the state of execution in this mode.
The exit and quit commands are available in all shell modes:
exit returns the state to the parent state
quit returns the state to the nearest parent mode (e.g., configuration mode, root mode, operational show mode). If the current state of the shell represents some mode, quit and exit have the same effect of returning to the parent mode.
Typed commands are sent to UniConfig using the ENTER key. UniConfig processes the command and may send a response to the console depending on the command. All commands are processed synchronously, meaning that multiple commands cannot be executed in parallel in the same SSH session.
CTRL-A and CTRL-E move the cursor to the beginning or end of the current line.
CTRL-L clears the shell screen.
Arrow keys UP/DOWN load previous commands in the command history.
CTRL-C cancels the current line and moves to a new blank line.
TAB loads suggestions in the current context. Hit TAB again to navigate through suggested commands using the arrow keys and select using ENTER. Leave the submode with suggestions using the shortcut CTRL-E. The text in brackets contains a description of the next command.
Loading available suggestions in 'uniconfig-topology-vnf21>' under 'show' command
If the output is longer than the length of the command line window, it is displayed with scrolling capability. Use ENTER to display the next line and SPACE to display the next page. Use the q key to leave scrolling mode. You can only scroll only in one direction, towards the end of the output.
uniconfig>
configuration-mode (opening configuration mode)exit
hide-get (Setting item to be hidden in get)
hide-set (Setting item to be hidden inset)
show (reading data from device)
show-history (show history[max number of commands])
unhide-get (Setting item to be unhidden in get)
unhide-set (Setting item to be unhidden inset)
The exit command is used to exit the UniConfig shell interface altogether (disconnecting SSH client).
Example - Exit UniConfig shell:
Leaving UniConfig shell
uniconfig>exit
Console closed. Press any key to exit!
Connection to 127.0.0.1 closed by remote host.
Connection to 127.0.0.1 closed.
Currently, only username/password single-user authentication is supported as configured in the application.properties file.
The following commands are used to unhide and hide attributes in application properties:
unhide-get is used to unhide an attribute hidden in application properties for read purposes (restconf.schema-filters.hidden-data-on-read-by-extensions).
unhide-set is used to unhide an attribute hidden in application properties for write purposes (restconf.schema-filters.ignored-data-on-write-by-extensions).
hide-get is used to hide attributes that were unhidden with unhide-get.
hide-set is used to hide attributes that were unhidden with unhide-set.
When unhide is set for a GET or SET operation, the request URL for the operation contains the unhide query parameter. In the following example, the unhide parameter is set to all:
This is also available for callbacks. Request and set operations for callbacks uses restconf.schema-filters.ignored-data-on-write-by-extensions and show operations uses restconf.schema-filters.hidden-data-on-read-by-extensions.
The command also gives confirmation that the attribute was added to or removed from the unhidden list.
When unhide-get or hide-get are called without parameters, the output contains a list of all unhidden parameters. The same applies to unhide-set and hide-set.
'unhide-get' and 'unhide-set' with parameters
uc>unhide-get deprecated
Attribute tailf:hidden deprecated was added to unhidden get list.
uc>unhide-set full
Attribute tailf:hidden full was added to unhidden set list.
'hide-get' and 'hide-set' with parameters
uc>hide-get deprecated
Attribute tailf:hidden deprecated was removed from unhidden get list.
uc>hide-set full
Attribute tailf:hidden full was removed from unhidden set list.
'unhide-get' and 'unhide-set' without parameters (same output for 'hide-get' and 'hide-set')
Example - Attempt to show hidden callbacks field details without unhide
Show hidden callbacks field details without unhide
uc>hide-get deprecated
Attribute tailf:hidden deprecated was removed from unhidden get list.
uc>configuration-mode
Transaction with id: fe30f909-82bd-4037-b262-a5e147034ab6 was successfully created
uc(config)#show callbacks vnms system details
Unknown arguments: details
uc(config)#
Example - Attempt to set hidden callbacks field reset-password with unhide
Set hidden callbacks field reset-password with unhide
uc>unhide-set full
Attribute tailf:hidden full was added to unhidden set list.
uc>configuration-mode
Transaction with id: fe30f909-82bd-4037-b262-a5e147034ab6 was successfully created
uc(config)#set callbacks vnms system reset-password
Failed to send request to remote server; Body is not specified!
uc(config)#
Example - Attempt to set hidden callbacks field reset-password without unhide
Set hidden callbacks field reset-password without unhide
uc>hide-set full
Attribute tailf:hidden full was removed from unhidden set list.
uc>configuration-mode
Transaction with id: fe30f909-82bd-4037-b262-a5e147034ab6 was successfully created
uc(config)#set callbacks vnms reset-password
Unknown arguments: reset-password
uc(config)#
Example - Attempt to request hidden callbacks field unlock-user with unhide
Request hidden callbacks field unlock-user with unhide
uc>unhide-set full
Attribute tailf:hidden full was added to unhidden set list.
uc>configuration-mode
Transaction with id: fe30f909-82bd-4037-b262-a5e147034ab6 was successfully created
uc(config)#request callbacks vnms system unlock-user
Request body is needed
uc(config)#
Example - Attempt to request hidden callbacks field unlock-user without unhide
Request hidden callbacks field unlock-user without unhide
uc>hide-set full
Attribute tailf:hidden full was removed from unhidden set list.
uc>configuration-mode
Transaction with id: fe30f909-82bd-4037-b262-a5e147034ab6 was successfully created
uc(config)#request callbacks vnms system unlock-user
Unknown arguments: unlock-user
uc(config)#
Configuration mode provides access to the following:
CRUD operations on top of persisted UniConfig, UniStore and template nodes
CRUD operations on top of persisted UniConfig settings
UniConfig RPC operations such as commit or calculate-diff
After opening configuration mode, a new UniConfig transaction is created. All operations invoked in configuration mode are executed in the scope of the created transaction. The transaction is automatically closed after leaving configuration mode (exit or quit command).
If commit or checked-commit are invoked, the transaction is automatically refreshed. The user stays in configuration mode with a newly created transaction.
Configuration mode overview
config>
others
callbacks (operations on callbacks)exit(return to parent mode)
quit (return to root mode)
request (execution of RPCs)
settings (operations on settings)
show-history (show history[max number of commands])
template-topology (operations on the template topology)
uniconfig-topology (operations on the uniconfig topology)
unistore-topology (operations on the unistore topology)
aliases
diff(alias for'request calculate-diff target-nodes/node *')
Commands like SET, SHOW and DELETE are now available only on a specific device and are not accessible in root configuration mode.
Set / show / delete commands overview
config>uniconfig-topology test-node-1
uniconfig-topology-test-node-1>
SNMP-NOTIFICATION-MIB nacm (Parameters for NETCONF Access Control Model.)
SNMP-TARGET-MIB ntp (NTP configuration)
SNMP-VIEW-BASED-ACM-MIB quit (return to root mode)
aaa (AAA management) redundancy (Redundancy Configuration)
alarms (Alarm configuration) service-node-groups (Service Node Gateway Services Configuration)alias(Create command alias.)set(set operation)
confdConfig (ConfD configuration.) show (show data in current path)
delete (delete operation) show-history (show history[max number of commands])
event (Event scripts) snmp (Simple Network Management Protocol (SNMP) configuration)exit(return to parent mode) system (System configuration and statistics)
interfaces (Interfaces configuration)
The show operation is used to display selected subtrees.
The subtree path can be constructed interactively with the help of shell suggestions/auto-completion mechanism. Construction of the path works the same way for SET, SHOW and DELETE operations.
Example - Display the configuration of a selected container:
First move into a specific topology on a specific device:
A JSON snippet can be written to a selected data-tree node by entering the json sub-mode. In this sub-mode, you can type multiple lines that represent a well-formed JSON document. At the end, confirm the set operation using the pattern w! + newline, or cancel the set operation with the pattern q! + newline.
Example - Replace configuration of an interface using a JSON snippet:
move to specified device
config>uniconfig-topology iosxr
Replace 'config' container under interface using the provided JSON snippet
The request command is used to execute UniConfig operations such as commit or calculate-diff in the UniConfig transaction:
The command is available in configuration mode
You can fill in input parameters and values interactively or via provided JSON snippet
Example - Execute UniConfig RPCs in the scope of the open UniConfig transaction:
Display available 'commit' RPC parameters
config>request commit
>(output to file)
do-rollback (Controls whether to roll back successfully configured devices incase of failu…)
do-validate (Option to enable/disable validation at commit. Default value is true - validate)
json (JSON input)
target-nodes/node
|(pipe)
Execute 'calculate-diff' RPC with one argument - target node
Display available 'sync-from-network' RPC parameters:
config>request sync-from-network
>(output to file)
check-timestamp (Perform timestamp comparison(last known to Uniconfig vs current timestamp …)
json (JSON input)
target-nodes/node
|(pipe)
Execute 'sync-from-network' RPC with two arguments (target node and 'check-timestamp' flag)
This command has been merged with request configuration mode and is now available only in configuration mode.
Request mode allows users to:
Invoke selected UniConfig requests that read or alter UniConfig settings.
Invoke RPCs or actions provided by network devices or other southbound mountpoints.
Input parameters and values can be filled in interactively or via a provided JSON snippet. The transaction is passed from configuration mode.
Example - Invoke RPC execute-and-read with typed input parameters:
Display available RPCs provided by device 'iosxr'
request>cli iosxr
operations
clear-journal
execute (Simple execution of single or multiple commands on remote terminal. Multiple comma…)
execute-and-expect (Form of the 'execute-and-read' RPC that can contain 'expect(..)' patter…)
execute-and-read (Execution of the sequence of commands specified in the input. These comma…)
execute-and-read-until
read-journal
Display available 'execute-and-read' RPC parameters
request>cli iosxr execute-and-read
>(output to file)command(Input configuration snippet (one or multiple commands separated by newline).)
json (JSON input)
wait-for-output-timer (If no output is received during this time, then execute next command…)|(pipe)
Execute 'execute-and-read' RPC with two arguments ('wait-for-output-timer' and 'command')
request>cli iosxr execute-and-read wait-for-output-timer 2command"show users"{"output":"Mon May 16 07:28:30.405 UTC
Line User Service Conns Idle Location
* vty0 cisco ssh 0 00:00:00 192.168.1.42"}[24.04.2023, 09:34:21]
Example - Execute the same RPC execute-and-read using input JSON:
Execute the 'execute-and-read' RPC with input JSON snippet:
request>cli iosxr execute-and-read json
{>"input":{>"command":"show users",
>"wait-for-output-timer":2>}>}
w!{"output":"Mon May 16 07:37:55.256 UTC
Line User Service Conns Idle Location
* vty0 cisco ssh 0 00:00:00 192.168.1.42"}[24.04.2023, 09:36:48]
UniConfig shell does not support interactive typing of input arguments for an RPC/action that contains the list YANG element. Such operations must be executed using input JSON.
UniConfig shell supports pipe operations similar to Unix shell/bash pipes. When a command is followed by the pipe sign (|), the output of the command is passed to the selected pipe operation.
You can define aliases in UniConfig shell. A json file named shell-aliases is included in the UniConfig distribution for this purpose. After unpacking the UniConfig distribution, the file can be found under Uniconfig/distribution/packaging/zip/target/uniconfig-x.x.x/config. The file contains some sample aliases.
shell-aliases.json with default samples
/*
Example: "alias": "command1 command2 * command3 *"
Alias name must be a simple word without spaces
Asterisk symbol is a placeholder. We can dynamically add an alias value
*/
{
"configuration-mode": {
"diff": "request calculate-diff target-nodes/node *"
},
"request": {
"shh": "show-history"
},
"show": {
"lbr": "logging-status broker restconf"
}
}
Callbacks include sending POST and GET requests to the remote server and invoking user scripts from the UniConfig shell.
The following is required to use callbacks:
Necessary YANG modules - YANG modules that are required by the callbacks.
Configuration - Enable callbacks in config/application.properties and set the remote server and access token.
Update repository - Add the necessary YANG modules from step 1 into at least one YANG repository in the cache directory, and either define remote endpoints and scripts in a YANG file or create a new one for callbacks. For a definition of remote endpoints, use the frinx-callpoint@2022-06-22.yang extension.
UniStore node - Create a UniStore node using the YANG repository containing the necessary YANG modules from step 1 and a YANG file with defined endpoints and scripts.
In UniConfig shell, step 4 is optional as UniConfig creates dummy UniStore nodes for all repositories that meet the conditions in step 3. In this case, the dummy UniStore node name is identical to the YANG repository name.
By default, callbacks are disabled and the host and port for the remote server are empty in config/application.properties.
To enable callbacks, set the configuration parameter callbacks/enabled to true. It is also necessary to set the host and port for the remote server and store an access token in the UniConfig database.
The host and port for the remote server can be set in three ways:
Before starting Uniconfig, in the config/application.properties file. The port number is optional:
First, create or update the YANG repository by using the frinx-callpoint@2022-06-22.yang extension displayed in the following snippet. There is only one extension, url, with the argument point.
The argument of the url extension is /data/from/remote, which is appended to the end of the remote server URI configured in config/application.properties. Thus the final address for the remote call-point is https://remote.server.io/data/from/remote.
The following snippet shows how to create an action in the frinx-test YANG file by using the frinx-callpoint@2022-06-22.yang extension. You must also import tailf-common.yang.
The action consists of:
The action name, defined by tailf:action.
The suffix for the remote endpoint, defined by fcal:url.
The input that contains body of the request. This part is optional.
The following snippet shows how to create a script in the frinx-test YANG file by using tailf-common.yang. It is not necessary to import the frinx-callpoint@2022-06-22.yang extension.
The script consists of:
The script name, defined by tailf:action.
The path to the script, defined by tailf:exec.
Arguments for the script, defined by tailf:exec.
Arguments can be dynamic (i.e., the user can pass values to them) or static (flags). Follow these conventions when creating arguments:
Each argument must contain a name (for example, -n, -j).
Dynamic arguments must be enclosed in $(...) (for example, $(name)).
Flags are simple words without whitespace (for example, VIP, UPPER, upper).
A UniStore node can be created by RestConf or UniConfig shell. If a repository is explicitly defined by the query parameter ?uniconfig-schema-repository=repository-name, this repository must contain all necessary YANG modules. If a repository name is not defined when the UniStore node is created, all necessary YANG modules must be in the latest schema repository.
