Solace CLI

The Solace Command Line Interface (CLI) is a text-based interface for configuring and monitoring Solace event brokers. It allows a user to perform event broker administration, configuration and provisioning, and network troubleshooting tasks. The CLI automatically starts after the event broker powers up.

The CLI supports command completion, so you do not need to enter the entire name of a command or option. If you enter part of a command then press the Tab key, the CLI lists the options you can enter at that point in the command string. As long as you enter enough characters of the command or option name to avoid ambiguity with other commands or options, the CLI can understand what you are typing and complete it.

Reference guides to the Solace CLI can be found in these locations: Appliance CLI Commands and Software Event Broker CLI Commands.

Logging In to the CLI

The method for accessing the CLI is different for appliances and software brokers.

Accessing the CLI on an Appliance

On the appliance, you can log in to the CLI through either management console or Secure Shell (SSH) connections.

At initial login to the appliance without an IP address, you must set up a management console (see Connecting a Management Console), and connect it directly to the event broker appliance’s RS-232 serial console port located on the rear panel of the appliance using the provided cable.

Once an IP address is assigned, you can log in to the CLI through SSH. To log in through SSH, SSH version 2.0 client software must be installed on your host computer. Solace PubSub+ event brokers use Keyboard/Interactive authentication for SSHv2. Ensure that you enable Keyboard/Interactive authentication on the SSH client you are using with the Solace PubSub+ appliance.

Accessing the CLI on a Software Event Broker

To access the CLI on a container, either connect via ssh on port 2222 (assuming you are using the default ports) or run the cli command in the container. For example, run the following Docker command:

>docker exec -it <container_name> /usr/sw/loads/currentload/bin/cli -A

Authenticating to the CLI

When a user successfully logs in or logs out, or fails to authenticate for a CLI, SEMP, shell, scp, or sftp session to the event broker, an authentication event is written to the event log.

There is a limit of eight active and concurrent CLI user sessions per PubSub+ event broker, not including the always-available serial console port that is accessible at the rear of a PubSub+ appliance. This limit does not apply to File Transfer user accounts.

At initial login, general access to the Solace PubSub+ event broker is established when the following prompt appears on your computer screen:

login>

Enter a valid CLI user account name:

login as: <assigned_user_name>

When you are prompted for a password, enter the assigned password for the user account:

Password: <assigned_password>

Once CLI connectivity to the event broker is established, a CLI banner and prompt appears:

System Software. SolOS-TR Version <version number>
Copyright 2004-20<xx> Solace Corporation. All rights reserved.
solace>

At this prompt (>), you are at the User EXEC level of the CLI command structure.

If you are logging in to a newly deployed event broker, and CLI user accounts have not yet been provisioned, you can log in to the event broker using the default admin CLI user account name (admin) and password (admin). For security reasons, Solace recommends that a system administrator change the default password for the admin user account once the initial Solace PubSub+ software configuration is completed. For information on managing CLI user accounts, see Management & Shell Users.

Setting CLI Paging Output

By default, the CLI limits the number of lines that are displayed for show commands according to your current screen size.

To set a specific number of lines to use for paging output, enter the following User EXEC command:

solace> paging [size <size>]

Where:

size <size> specifies the number of lines to limit the output page size to. Valid values are 1 through 2147483647.

The no version of this command, no paging, disables paging.

Setting a CLI Inactivity Timeout

The CLI has an inactivity timer which, by default, automatically logs out inactive CLI users if no commands are entered for five minutes.

To change the inactivity timeout value for CLI user sessions on an event broker, enter the following commands:

solace> enable
solace# configure
solace(configure)# console timeout <idle-timeout>

Where:

<idle-timeout> is an integer value representing the inactivity timeout in minutes. The valid range is 0 to 43200. To disable the inactivity timer, enter 0.

Changing CLI Inactivity Timeout for Single Sessions

You can change the CLI inactivity timer just for the current CLI user session instead of globally. The per-session CLI inactivity timeout setting overrides the global timeout setting, but it is not persistent across all CLI user sessions on the event broker.

To change the CLI inactivity timeout setting for your current CLI user session on the Solace PubSub+ event broker, enter the following commands:

solace> enable
solace# session timeout <idle-timeout>

Where:

<idle-timeout> is the integer value representing the inactivity timeout value in minutes. The valid range is 0 to 43200. To disable the inactivity timer, enter 0.

Displaying CLI Inactivity Timeout Settings

To show the global inactivity timeout configuration for all CLI user sessions on the Solace PubSub+ event broker, enter the following User EXEC command:

solace> show console

To show the inactivity timeout configuration for all current CLI user sessions on the Solace PubSub+ event broker, enter the following User EXEC command:

solace> show session

Adding CLI Login Banner Text

An administrator can configure a custom text banner to be displayed when CLI users and File Transfer users log in to a Solace PubSub+ event broker through either serial management console or SSH connections. The login banner text will be displayed before the user is prompted for a password. By default, no login banner is used.

The configured login banner text is saved so that it will continue to be used if the Solace PubSub+ event broker's version is upgraded. If the Solace PubSub+ event broker is upgraded and the banner text is modified, then the Solace PubSub+ event broker is subsequently downgraded to the previous software version, and the banner text used for the older version is used.

When Solace PubSub+ event brokers are deployed as high-availability (HA) redundant pairs, the login banner text is automatically synchronized between mates when the Config‑Sync facility is enabled (see Config-Sync Configuration).

To configure a login banner text, enter the following commands:

solace> enable
solace# configure
solace(configure)# console
solace(configure/console)# login-banner [{text <banner-text>} | {file <file-name>}]

Where:

text <banner-text> directly specifies the banner text to display when a CLI or File Transfer user logs in. <banner-text> is the banner text (up to 2,048 characters in length) to display. Standard CLI escape characters are accepted (see Inputting Non-Printable Characters as CLI Parameters). Use "\n" to insert new lines on the CLI (for example, the following banner text would display on three separate lines in the CLI: "Warning!\nProperty of Company X.\nAny unauthorized access is strictly prohibited.").

file <file-name> specifies to use a file that provides the banner text to display. <file-name> is a string text (up to 255 characters in length) that provides the name of the file to load from the jail file system directory (for example, jail/corporateLoginBannerFile).

The no version of this command, no login-banner, clears the login banner.

Displaying the CLI Login Banner Text

To show any custom text banner that is displayed when CLI users and File Transfer users log in to a Solace PubSub+ event broker, enter the following User EXEC command:

solace> show console login-banner

Command Levels

The CLI uses the following types of commands:

• EXEC commands
• CONFIG commands

EXEC Commands

There are three levels of executive (EXEC) commands:

• User EXEC—Lets you view basic system information and perform simple tasks such as pings, Show commands, and verify connectivity. You cannot make any changes to the event broker configuration.

  User EXEC level commands are at the top of the CLI hierarchy. These are the first commands that you have access to when you connect to the device through the CLI.

  To make event broker configuration change, you must move to other levels of the CLI hierarchy. You can enter the User EXEC level command enable to go to the Privileged EXEC level, from which you can reach other more powerful configuration command levels. For more information, see Reaching Other CLI Command Levels.

• Privileged EXEC—Lets you use the same commands as those at the User EXEC level plus configuration commands that do not require saving the changes to the system-config file. The Privileged EXEC level commands primarily enable you to transfer and store software images and configuration files between the network and the event broker and to review the configuration.

  From the Privileged EXEC level, you can enter the admin command to reach the Admin EXEC level, or you can enter the configure command to reach the Global CONFIG level.

• Admin EXEC—Lets you use the same commands as those at the User EXEC and Privileged EXEC level plus commands that are service‑effecting for configured entities (for example, disconnecting clients or deleting spooled messages). Again, these commands do not require saving the changes to the system-config file.

For show commands, which are common User EXEC-level commands, you can also use wildcards in name of objects that you want to view information for instead of entering the objectʼs full name. For example:

• You can enter part of an objectʼs name with the wildcard character * to represent zero or more arbitrary characters of the name ( "show queue cx* message-vpn default" returns "queue cx134" and "cx142"). Entering only the wildcard character * for the name displays all Message VPNs.
• You can also enter the wildcard character ? to represent one arbitrary character of the name ( "show smrp subscriptions message-vpn default topic #M?AST/>" returns "#MCAST/>").

CONFIG Commands

Configuration (CONFIG) commands let you make configuration changes to the Solace PubSub+ event broker. Each configuration command takes effect immediately after it is entered and is saved to the system-config file maintained in the internal event broker database. This allows configuration changes to remain in effect after an event broker restart.

The Global CONFIG command level is the first level you enter into from the Privileged EXEC level. The Global CONFIG level allows you to globally apply or modify parameters on the event broker.

For example, within the Global CONFIG level you can:

• apply features globally to an event broker
• configure, enable, or disable a feature or function
• access all CONFIG modes

To reach the Global CONFIG level, enter configure at the privileged EXEC level.

Example:

solace# configure
solace(configure)#

The CLI is now at the Global CONFIG level. From this level, you can enter into one of many other CONFIG sub‑levels, depending on what it is you want to configure on a Solace PubSub+ event broker (for example, Interface CONFIG or Client Username CONFIG).

Identifying Command Context

Command levels set a context for the CLI, which can help you to:

• determine where you are in CONFIG command levels
• determine what you are configuring
• go to other CLI command levels

Each command level has its own distinct CLI command prompt to let you know which level you are in at any given point and prevent you from making configuration mistakes that could adversely affect the operation of Solace PubSub+ event brokers.

As shown in the following table, the CLI command prompt that follows the event broker hostname (solace for this example and most examples throughout the Solace customer documentation) changes at each level of the command structure to easily identify the current level.

Command Context

Command Level	CLI Prompt
User EXEC	solace>
Privileged EXEC	solace#
Admin EXEC Level	solace(admin)#
Global CONFIG	solace(configure)#

Reaching Other CLI Command Levels

To make changes to the event broker configuration, you must move from the User EXEC level of the CLI command structure (the level that you are at after establishing CLI connectivity) and go to other levels of the CLI hierarchy. The relationship of the primary CLI command levels is shown below.

CLI Command Level Relationship

To reach Privileged EXEC level commands from the User EXEC level, enter the following commands:

solace> enable
solace#

From the Privileged EXEC level, you can reach the Admin EXEC or Global CONFIG levels.

• To reach Admin EXEC level commands from the Privileged EXEC level, enter the following commands:

  solace# admin
  solace(admin)#

• To reach Global CONFIG level commands from the Privileged EXEC level, enter the following commands:

  solace# configure
  solace(configure)#

  From the Global CONFIG level, you can reach feature-specific levels of the CONFIG command structure.

  Example:

  solace(configure)# service
  solace(configure/service)#

  The CLI moves to the Service CONFIG level.

Moving Back Command Levels

To move back command levels, you can use the following commands:

• End—Lets you exit the current CONFIG command level of the CLI and return to the Privileged EXEC level.

  Example:

  solace(configure/message-spool)# end
  solace#

• Exit—Lets you exit the current command level of the CLI and return to the previous level. At the User EXEC level, the exit command will result in an exit from the CLI.

  Example:

  solace(configure/client-profile)# exit
  solace(configure)#

• Home—Lets you exit the current command level of the CLI and return to the User EXEC level.

  Example:

  solace(configure/routing)# home
  solace>

CLI Command Structure

Many CLI commands require textual or numeral input as part of the command. These fields may be required or optional, depending on how the information is bracketed. For clarity, a few CLI command examples are provided below.

Example 1

logging debug {<subsystemId> | all} [level <level>] [mask <mask>]

When an item is bracketed with < > symbols, the information requested is a variable and is required.

When an item is enclosed with [ ] symbols, the information requested is optional.

When an item is enclosed by { } symbols, the information requested is a variable of which only one is required.

When an item is not enclosed by < >, [ ], or { } symbols, the item is a required keyword.

When two or more options are separated by a | symbol, you must enter one of the options as part of the command.

To get a quick display of available options at a CLI level or for the next option in a command string, enter a single question mark (?) at the prompt, or press the Tab key.

Example 2

To view all available commands at the user EXEC level, enter a double question mark (??) at that level:

solace> ??

 Commands available in the current mode:
            enable - Use this command to enter the Privileged EXEC level of
                     the CLI to perform appliance configuration.
 
   Global commands available in any mode:
       [no] alarm-display          - Use this command to enable the display
                                     of 3200 Series appliance system alarms in
                                     the current CLI session on a
                                     session-by-session basis. The no version
                                     disables the displaying of appliance system
                                     alarms in the current CLI session.
            cd                     - Use this command to change the current
                                     working directory on the appliance.
   .  .  .
                                    
            tree                   - Use this command to show the CLI command
                                     tree, starting from the current mode.
 
   Complete help for a command can be displayed by entering:
         "<command> ?"
 
   Output of any command can be redirected to overwrite a file using '>':
         "show version > version.txt"
 
   Output of any command can be redirected to append to a file using '>>':
         "show version >> version.txt"

You also can enter a question mark (?) with an individual command, to see all available options or to check context.

Example 3

To view possible show command options, enter the following User EXEC command:

solace> show ?

   COMMAND:
       show [acl-profile ... | authentication ... | backup | bridge ... |
             cache-cluster ... | cache-instance ... | client ... |
             client-certificate-authority ... | client-profile ... |
             client-username ... | clock ... | cluster ... |
             compression | config-sync ... | console ... | cspf |
             current-config | debug ... | deferred-config |
             distributed-cache ... | domain-certificate-authority ... |
             environment | home-cache-cluster ... | hostname |
             interface ... | ip | jndi | kerberos ... | ldap-profile ... |
             log | logging | memory | message-spool ... | message-vpn ... |
             mqtt | oauth-profile ... | paging | process ... |
             product-key | queue ... | queue-template ... |
             radius-profile ... | redundancy ... | replay-log ... |
             replicated-topic ... | replication ... | router-name |
             routing | semp-session ... | sequenced-topic ... | service ... |
             session | smrp | ssl |
             standard-domain-certificate-authority ... | stats |
             storage-element ... | syslog ... | system ... |
             topic-endpoint ... | topic-endpoint-template ... |
             transaction ... | username ... | version | web-manager]

   DESCRIPTION:
       Use this command to display a variety of configuration and statistical
       information about the router.

   MINIMUM REQUIRED SCOPE/ACCESS LEVEL:
       global/none
---Press any key to continue, or `q' to quit---

CLI Command Line Prompts

Within the CLI, the command line prompt identifies both the hostname and the command mode. The hostname is the name of your event broker set through the setup (or using the hostname Global CONFIG command); the command mode indicates your location within the CLI command structure.

In most cases, Solace customer documentation uses solace as the name of the host. This is the default system hostname.

Example:

solace(configure)# create message-vpn <vpn-name>

When redundancy scenarios are discussed, solace1 is often used for one event broker and solace2 for its mate.

Example:

solace1(configure)# ip vrf msg-backbone
solace2(configure)# ip vrf msg-backbone

For some actions, the CLI prompts you for a response. The acceptable default responses are the following:

• You can press <y> to agree with the prompt and continue.
• You can press <n> to disagree with the prompt and cancel the action.

CLI Keywords and Parameters

CLI commands are made up of two primary elements: keywords and parameters.

• Keywords

  Every command requires at least one keyword; however, a command can contain other optional keywords. Keywords must be typed into the CLI accurately for it to be recognized. These are examples of keywords:

  • reload
  • clear
  • configure
  • end
  • set

  Keywords identify the operation to be performed. You can abbreviate keywords; however, you must enter enough initial characters to unambiguously identify the command. For example, if the keyword you want to specify is source and you enter only s, an error appears. The error indicates that one or more possible keywords begin with s, thus making your entry ambiguous.

• Parameters

  Parameters are often required elements of a command; however, for some commands, parameters are not required. A parameter is most often a value that you specify after the keyword. There are different types of parameters, such as strings, integers, or IP addresses. The CLI indicates the type of parameter that you must enter. When you see a range of numbers or uppercase letters, it indicates that you must specify a value.

Keywords and Parameters Together

By combining keywords and parameters in the correct sequence, you can begin to use the CLI to configure and monitor your event broker. For example, you could specify the hostname Global Config command to change the name that your event broker was originally assigned on its initial setup (through the setup Privileged EXEC command).

The hostname Global Config command requires a hostname keyword and an associated parameter. In this case, the variable <name> parameter uses a string value of up to 64 characters for the name of the host.

router(configure)# hostname <name>

When you enter the hostname Global Config command, the new hostname appears in the command line prompt.

Example:

router(configure)# hostname solace
solace(configure)#

CLI Command Output Redirection

Rather than require the operator to copy and paste the CLI output from a command from the screen for editing or transferring to another event broker, you can use the CLI output redirection feature to redirect such output to a file in a specified subdirectory of the event broker root directory. This subdirectory must already exist on the event broker before you can specify it. In addition, the output can be redirected to either write a file using ">", or append to a file using ">>".

For example, the command below does the following:

• show the configuration of the message VPN named blue
• redirect the output to the to the blue.cli file in the cliscripts directory
• write the blue.cli file (that is, creates a new version and overwrites any previously existing version of the file)

solace> show current-config message-vpn blue > cliscripts/blue.cli

CLI paging is automatically disabled for the duration of a redirected CLI command, but confirmation prompts and error and warning messages are not; they remain displayed on the CLI console.

Partial Keyword <Tab>

At any point in the command line, you can press <Tab> to display the valid inputs onward.

When you cannot recall a complete command name or keyword, type in the first few letters, press <Tab>, and the system will complete your partial entry. However, you must type enough characters to provide a unique abbreviation. If your partially entered command is not unique, the CLI presents you with a list of valid options.

Examples:

solace> show message-v <Tab>
message-spool  message-vpn

solace> show message-s <Tab>
solace> show message-spool

A subsequent <Tab> will then display the valid parameters for the command / argument pair:

solace> show message-spool <Tab>
detail       message-vpn  rates        stats

* and ? as Input Wildcards

For some commands, the "*" and "?" characters are permitted as wildcards for information requested for command input.

• The "*" character may match 0 or more unknown characters.

  Examples:

  solace> show message-vpn r*d may display output for Message VPN red.

  solace> show message-vpn red* may display output for Message VPN red or redder.

  solace> show message-vpn * may display output for Message VPN red or redder.

  The "*" character can also be used as a wildcard for Solace Message Format (SMF) topic subscriptions. For information on its usage for SMF topic subscriptions, see Topic Support & Syntax.

• The "?" character may match only one unknown character.

  Example:

  solace> show message-vpn 1?3 may display output for Message VPN 123 or 13.

  The "?" character can also be used at the end of a command to display help for that command. For information on its usage for displaying help for commands, see Using Help.

Special Characters in Double Quotations

As described in previous sections, ? and > are characters with special meaning (? being a help request, and > and >> being redirect requests). If these characters are used in double quotations, they lose their special meaning and are treated as literals.

Examples:

Without double quotes, ? indicates a help request for the message-vpn command.

vmr-134-44(configure)# message-vpn ?

   COMMAND:
       message-vpn <vpn-name>
       create message-vpn <vpn-name>
       no message-vpn <vpn-name>

   DESCRIPTION:
       Create, modify, or delete a Message VPN.

       Message VPNs (Virtual Private Networks) allow for the segregation of
       topic space and clients. They also group clients connecting to a
       network of message brokers, such that messages published within a
       particular group are only visible to that group's clients.

   MINIMUM REQUIRED SCOPE/ACCESS LEVEL:
       vpn/read-write
       Notes/Exceptions:
        global/read-write is required to create or delete instances of this
        object.

   CONFIG-SYNC:
       HA: yes
       Replicated VPNs: no

   PARAMETERS:
       <vpn-name>               - [1..32 chars] The name of the Message VPN.

With double quotes, "?" is treated as a literal and the system tries to find a Message VPN called ?.

solace(configure)# message-vpn "?"

 Invalid command input
        message-vpn "?"
                    ^
         -> parameter parse error: Cannot contain the following characters: *?
 Expected one of the following:
      <vpn-name>               - [1..32 chars] The name of the Message VPN.

Using Help

The Solace CLI provides a variety of useful context-sensitive help features. An important thing to remember about using the help features is that the use of a space or the lack of a space before the "?" character gives different results. The following table summarizes the help system.

Help Commands

Command	Description
?, <Tab>, or tree	Lists commands or command options available in the current CLI level.
??, help, or tree all	Lists commands or command options available in both the current and global CLI levels.
tree global	Lists commands or command options available in the global CLI levels.
partial-command<Tab>	Completes the partial command you entered, if you have provided an unambiguous abbreviation. If ambiguous, the CLI lists the available command options.
command<space>?	Gives detailed help on the specific command and its available parameters in the current CLI level.

? Command

You can enter the question mark (?) key whenever you need additional information. When you enter ?, all available choices are displayed. When you enter ? on a line by itself, or when it is preceded by one or more spaces, a list of all next available choices is displayed. See ? Command Example 1.

Alternatively, the user can terminate a command with a ? to display the complete help on that command. This feature is useful when the command keyword is known but the list and format of parameters is not. Refer to ? Command Example 2.

? Command Example 1

From the prompt, you can enter ? to display the online help:

solace# ?

 Commands available in the current mode:
            admin       - Use this command to reach the Admin EXEC level.
            backup      - Use this command to immediately create a manual
                          local backup of your configuration database file on
                          the appliance.
            boot        - Use this command to upgrade or downgrade the appliance
                          software to a new or old SolOS software load and
                          activate it, or to revert to and run the previous
                          SolOS software version that was running before the
                          last upgrade.
            clear       - Use this command to clear various appliance
                          statistics.
 
. . .
 
            setup       - Use this command to quickly set the hostname,
                          interfaces, clock and time zone on the appliance.
            shell       - Use this command to acess the SolOS shell.
 
   Global commands (available in all modes) can be displayed by entering:
         "??"
 
   Complete help for a command can be displayed by entering:
         "<command> ?"
 
   Output of any command can be redirected to overwrite a file using '>':
         "show version > version.txt"
 
   Output of any command can be redirected to append to a file using '>>':
         "show version >> version.txt"
 
solace#

? Command Example 2

You can terminate a CLI command with a ? to display the complete help on the command:

solace(configure)# hardware ?

COMMAND:
    hardware [disk ... | message-spool | power-redundancy ... |
              topic-routing]
 
    DESCRIPTION:
        Use this commmand to configure routing modules and disks on the
        appliance.
 
    MINIMUM REQUIRED SCOPE/ACCESS LEVEL:
        global/read-write
 
    PARAMETERS:
        disk                  - Enable/disable hard disk
        [no] message-spool    - Configure message spool hardware options
        power-redundancy      - Configure power-redundancy
        [no] topic-routing    - Configure topic routing hardware options

Help Command

You can enter the help command to display a brief description of the context‑sensitive help system.

solace# help

Example:

solace# help

 Commands available in the current mode:
            admin       - Use this command to reach the Admin EXEC level.
            backup      - Use this command to immediately create a manual
                          local backup of your configuration database file on
                          the appliance.
            boot        - Use this command to upgrade or downgrade the appliance.
. . .
   Global commands available in any mode:
       [no] alarm-display          - Use this command to enable the display
                                     of 3200 Series appliance system alarms in
                                     the curren CLI session on a
                                     session-by-session basis. The no version
                                     disables the displaying of appliance
                                     alarms in the current CLI session.
            cd                     - Use this command to change the current
                                     working directory on the appliance.
            dir                    - Use this command to list the contents of
                                     a directory on the appliance.
            end                    - Use this command to exit the current
                                     CONFIG command level of the CLI and
                                     return to the Privileged EXEC level
 
. . .
 
   Complete help for a command can be displayed by entering:
         "<command> ?"
 
   Output of any command can be redirected to overwrite a file using '>':
         "show version > version.txt"
 
   Output of any command can be redirected to append to a file using '>>':
         "show version >> version.txt"

Tree Command

You can enter:

• tree to display a list of commands or command options available in just the current CLI level
• tree all to display a list of commands or command options available in both the current and global CLI levels
• tree global to display a list of commands or command options available in just the global CLI level

Example:

solace# tree global

GLOBAL COMMANDS - available in all modes:
     [no] alarm-display
     cd [<directory>]
     dir [<pattern>]
     end
     exit
     help
     home
     logout
     more <pattern>
     [no] paging [size <size>]
     ping <vrf-ip-addr-or-host> [ip-interface <ip-interface>]
     pwd
     session timeout <idle-timeout>
     show*
         acl-profile <name> [message-vpn <vpn-name>]
                     [detail[client-connect] [publish-topic]
                     [subscribe-topic] |users]
         alarm
         authentication [user-class cli-semp] [current-user
                        | access-level [{default |
                        ldap [group <group-name-pattern>]}]
                        [detail]]
         backup
 
. . .
 
     source script <script-name> [stop-on-error]
            [no-prompt]
     [no] strict-column-wrapping
     tree [all | global]
 
        * indicates a mode that can be "typed through"

Writing and Running Basic CLI Scripts

To simplify the loading of common or repetitive configuration setups, the CLI has a basic scripting facility that enables you to define and run scripts that run multiple CLI commands. Basic script files can be used to store more than one CLI command. Depending on your needs, you might want to store all of your CLI commands in one script file or group scripts by function.

To run a basic CLI script file, save the script as text, then transfer the script to the event broker using the copy Privileged EXEC command.

You can then run the basic CLI script file from within the CLI using the following User EXEC command:

solace> source script <script-name> [stop-on-error] [no-prompt]

Where:

<script-name> is the name of the CLI script file. The script file must be in a directory on the event broker.

stop-on-error specifies to stop running the script when encountering an error.

Ordinarily, when a CLI script is run, it is run to completion, even if errors are encountered. However, this can prove problematic if a command fails part way through a script and subsequent commands rely on it having run properly. To avoid this scenario, you can use the stop-on-error parameter.

no-prompt specifies to skip yes/no confirmation prompting. It is the equivalent to entering yes to all command prompts.

Certain CLI commands require a confirmation of the form "Do you want to continue (y/n)" when run. Use of the no-prompt parameter allows CLI scripts to run to completion without interruption.

Always observe these key points when writing or running CLI scripts:

• The commands in the script must be valid in the current operating mode.
• Nesting of scripts is allowed, up to a maximum nest level of five.
• If a command inside a script contains a syntax error, or fails for some other reason, the remainder of the commands in the file are still run (that is, script execution does not abort on failure), provided stop-on-error is not used.
• A script does not require an exit or logout command at the end. If present, these commands are run normally, such that if run in user mode the CLI session is exited.
• Comments can be included directly in the CLI script file itself and are identified with an exclamation mark (!) at the start of a line. This tells Solace PubSub+ event brokers that the information is a comment and should not be displayed or parsed. Comments do not require an end tag. If you decide to include comments, anyone who reads or edits your CLI script may read them. Any event broker or application that parses or validates your CLI script ignores commented information.

The current scripting facility does not include structures for control flow, environment variables, or other more sophisticated scripting features.

Inputting Non-Printable Characters as CLI Parameters

Non-printable characters can be inputted in a CLI argument as a 3-digit octal value preceded by a backslash escape character (for example, "\027"), a two digit hexadecimal value preceded by an escaped x: "\x", or a collection of standard escape sequences: "\a", "\b", "\f", "\n", "\r", "\t", "\\", and "\"". The CLI interprets these sequences as a single character whose value is representative of the escaped sequence.

To enter values with spaces, surround them with double quotes ("").

If you use pre-existing CLI command scripts that were written for a version of Solace PubSub+ software earlier than Version 6.1 (including the output of legacy show current-config User EXEC command commands) those scripts must be modified before they are executed if they contain octal escape sequences in them. To modify pre‑existing CLI command scripts, escape the escape character in scripts containing any of the documented escape sequences (for example, change the value "\027" to "\\027"). It is also suggested, but not required, that you escape all backslashes to allow for future expansion of the escape sequences.

Retrieving Entered CLI Commands for Reuse

All entered CLI commands are stored on the event broker in a history buffer. To retrieve these entered commands you can use the keyboard arrow keys to navigate the history buffer. You can then copy these retrieved commands and either reuse them as is, or edit them for reuse.

Displaying System Alarms

To enable the display of Solace PubSub+ event broker system alarms in the current CLI session, on a session-by-session basis, enter the following User EXEC command:

solace> alarm-display

The no version of this command, no alarm-display, disables the display of event broker system alarms in the current CLI session.

To show the current alarm status for the current CLI session, enter the following User EXEC command:

solace> show alarm