Chapter 1: Introduction

	cOS Stream 4.00.03 CLI Reference Guide	Next

	Note: This document is also available in other formats
A PDF version of this document along with all current and older documentation in PDF format can be found at https://my.clavister.com. It is also available as a single HTML page.

Note: This document is also available in other formats

A PDF version of this document along with all current and older documentation in PDF format can be found at https://my.clavister.com.

It is also available as a single HTML page.

This guide is a reference for all commands and configuration object types that are accessible through the Command Line Interface (CLI). This introduction gives a brief overview of the CLI help and autocompletion capabilities. CLI connection and usage is described in more depth in the separate Clavister firewall Administration Guide.

Case Sensitivity

The CLI is case-sensitive. However, the tab-completion feature of the CLI does not require the correct case to perform completion and will alter the typed case if it is required.

String Delimiters, the Escape Character and Special Characters

When entering CLI commands, literal strings can be enclosed in double quotation mark characters ("..."). For example:

add User my-user Password="pass word"

However, to include the double quotation mark itself in a string, it must be preceded by a backslash (\) which is the CLI escape character:

set User my-user Password="pass\"word"

Other special characters that might be needed are the following:

\r - The carriage return character.
\n - The new line character.
\t - The tab character.
\\ - The escape character \ itself.

For example:

set RemoteManagement RemoteMgmtSSH ssh Banner="Welcome!\r\n - Type \"help\"

Running a Command

The commands described in this guide can be run by typing the command along with any options followed by pressing the return key. Many commands require options to be set. If a mandatory option is missing, a brief syntax help will be displayed after the enter key is pressed.

CLI Function Keys

In addition to the return key there are a number of function keys that can be used with the CLI. These are listed below:

Backspace: Delete the character to the left of the cursor.
Tab: Complete current word.
Ctrl-A or Home: Move the cursor to the beginning of the line.
Ctrl-B or Left Arrow: Move the cursor one character to the left.
Ctrl-C: Clear line or cancel page view if more than one page of information is shown.
Ctrl-D or Delete: Delete the character to the right of the cursor.
Ctrl-E or End: Move the cursor to the end of the line.
Ctrl-F or Right Arrow: Move the cursor one character to the right.
Ctrl-K: Delete from the cursor to the end of the line.
Ctrl-N or Down Arrow: Show the next entry in the command history.
Ctrl-P or Up Arrow: Show the previous entry in the command history.
Ctrl-T: Transpose the current and the previous character.
Ctrl-U: Delete from the cursor to the beginning of line.
Ctrl-W: Delete word backwards.

The CLI History

Every time a command is run, the command line is added to a cached history of commands. The up and down arrow keys are used to access previous commands. The up arrow key displays the next oldest command in the history and the down arrow key returns to newer command lines.

The history command shows the entire contents of the history cache.

Example 1.1. CLI History

Using the command line history via the arrow keys:

Device:/> show Address
Device:/> (up arrow)
Device:/> show Address (the previous command is displayed)

CLI Help

There are two ways of getting help about a command. A brief help is displayed if the command name is typed followed by -?. This applies to all commands and is therefore not listed in the option list for each command in this guide.

In most cases it is possible to type the command help followed by the command name to get the detailed help for that command. To list all available commands, type help on its own and press return.

See Section 2.4.9, help for a more detailed description of the help command.

Example 1.2. CLI Help

Brief help for the activatecommand:

Device:/> activate -?

activate (ac). Activate changes.

Full help for activate:

Device:/> help activate

COMMAND
        activate (ac). Activate changes.

DESCRIPTION
        Activate the latest changes.

        This will issue a reconfiguration, using the new configuration.
        If the reconfiguration is successful a commit command must be
        issued within the configured timeout interval in order to save
        the changes to media. If not, the system will revert to using
        the previous version of the configuration.

USAGE
        activate

List all available commands:

Device:/> help

Available commands (type "help help" for more help):
		"
		"

Tab Completion

By using the tab function key in the CLI, the names of commands, options, objects and object properties can be automatically completed. If the text entered before pressing tab only matches one possible item, e.g. "activate" is the only match for "acti", and a command is expected, the name will be autocompleted.

Should there be more than one match, the part common to all matches will be completed. At this point the user can either enter more characters or press tab again, which will display a list of the possible completions. This can also be done without entering any characters, but the resulting list might be long if there are many possible completions, e.g. all commands.

Example 1.3. Tab Completion

An example of tab completion when using the add command:

Device:/> add Add (tab)
Device:/> add Address ("ress" was autocompleted)
Device:/> add Address i (tab)
Device:/> add Address IP ("IP" was autocompleted)
Device:/> add Address IPa (tab)
Device:/> add Address IPAddress ("IPAddress" was autocompleted)
Device:/> add Address IPAddress example_ip a (tab)
Device:/> add Address IPAddress example_ip Address= (autocompleted)
Device:/> add Address IPAddress example_ip Address=1.2.3.4

Mandatory Properties are Shown First

When using autocompletion, the optional object properties are not displayed until all mandatory properties have been assigned values.

For example, the Name parameter for an IP rule is optional. It will not be displayed by autocompletion until the such mandatory parameters as source/destination network/interface are emtered.

Inline Help

It is possible to also get help about available properties while a command line is being typed by typing tab. This will either result in a message to say what the next option is or show a list if there are several alternatives.

Example 1.4. Inline Help

Get inline help for all properties of an IPAddress:

Device:/> add Address IPAddress (tab)

 Enter a name for the new object.

Object Properties Help

It is possible to get information about the valid properties for an object through using the tab key:

Example 1.5. Option Properties Help

Option help for the Address= parameter of IPAddress:

Device:/> add Address IPAddress my_ip (tab)

<key-value pair>:

 Address  Comments  NoDefinedCredentials  UserAuthGroups

 Other valid options: -force, <enter>

Special Characters Used with Tab Completion

When entering the value of an object property, the tab character can be preceded by either of the following characters:

Entering the period "." (period) character before entering tab will insert the current value of the object property.

For example, assume that there is already an object in the address book called my_address and it has the IPv4 address value 203.0.113.10. Now enter the following command:
```
Device:/> set Address IPAddress my_address Address=.(tab)
```
This will cause the current IP address to be displayed:
```
Device:/> set Address IPAddress my_address Address=203.0.113.10
```
Entering the " * " (asterisk/star) character before entering tab will cause the default property value to be automatically filled in.

Entering the "?" (question mark) character before tab will provide information about the value that can be entered. For example:

Device:/> set RemoteManagement RemoteMgmtSSH RemoteMgmtSSH
			LogEnabled=?(tab)
         Type:  Boolean
  Description:  Enable logging.
      Default:  Yes
Current Value:  Yes

User Restrictions

Certain commands and options cannot be used unless the CLI user has administrator privileges. This is indicated in this guide by a note following the command stating Requires Administrator Privilege. Individual command options may be also be labelled Admin only.