Help us improve your experience.

Let us know what you think.

Do you have time for a two-minute survey?

 
 

Display Valid Command Option and Configuration Statement Values in the CLI for Custom YANG Modules

Certain devices running Junos OS enable you to load custom YANG modules on the device to add data models that are not natively supported by Junos OS. When you add custom YANG data models to a device, you must also supply an action or translation script that handles the translation logic between the YANG data model and Junos OS. Although the script logic can ensure that a user supplies valid values for a given command option or configuration statement, that logic is not always transparent to the user. Starting in Junos OS Release 19.2R1, the CLI displays the set of possible values for certain command options or configuration statements in a custom YANG data model when you include the action-expand extension statement in the option or statement definition and reference a script that handles the logic.

Understanding Context-Sensitive Help for Custom YANG Modules

The Junos OS CLI provides context-sensitive help whenever you type a question mark (?) in operational or configuration mode. When you execute a command or configure a statement, the CLI’s context-sensitive help displays the valid options and option values for a command or the valid configuration statements and leaf statement values in the configuration statement hierarchy. Additionally, context-sensitive help shows the possible completions for incomplete option names, statement names, and their values.

The CLI can also display the values that are valid for certain command options or configuration statements in a custom YANG data model. The CLI can display all possible values or a subset of values that match on partial input from the user. For example:

To display the set of valid values for a given command option or configuration statement in a custom YANG module:

  1. Define the action-expand and script extension statements under the appropriate input parameter or configuration statement in the YANG module as described in Defining the YANG Module.

  2. Create a Python script that checks for user input, calculates the possible values of the command option or configuration statement, and sends the appropriate output to the CLI, as described in Creating the CLI Expansion Script.

    Note:

    The CLI expansion script only displays the valid values in the CLI. The module’s translation script or action script must still include the logic that ensures that only valid values are accepted and processed.

  3. Load the YANG module, any translation or action scripts, and the CLI expansion script as part of a custom YANG package on the device as described in Loading the YANG Package.

    Note:

    Devices running Junos OS process CLI expansion scripts as another kind of action script, but we refer to CLI expansion script to avoid any confusion.

Defining the YANG Module

To define a custom YANG module that displays the set of valid values for a given command option or configuration statement when the user requests context-sensitive help in the CLI, your module must:

  1. Import the Junos OS DDL extensions module.
  2. Include the action-expand extension statement and script substatement in the corresponding command option or configuration statement definition.
    • You can include the action-expand statement within a leaf statement in modules that define custom RPCs and within a leaf or leaf-list statement in modules that define custom configuration hierarchies.

    • You can only define a single action-expand statement for a given node.

    • The script statement should reference the Python script that defines your custom logic.

For example, in the following module, the RPC defines the hostip input parameter, which calls the hostip-expand.py Python script when the user requests context-sensitive help for the hostip argument in the CLI. The script implements the custom logic that displays the valid values for that argument in the CLI.

Creating the CLI Expansion Script

When you define the action-expand statement and script substatement for a command option or configuration statement in a custom YANG module and you request context-sensitive help for that option or statement value in the CLI, the referenced Python script is invoked. The script must contain the custom logic that calculates and displays all possible values for that parameter or displays a subset of values that match on partial input from the user.

For example, the following command should display all valid values for the hostip argument:

And the following command should display all valid values that start with "198":

To display the valid values for a command option or configuration statement in the CLI, the Python script should perform the following functions:

  1. Import the jcs library along with any other required Python libraries.

  2. Retrieve and process any user input.

    If you specify partial input for an option or statement value in the CLI, the script’s command-line arguments include the symbol argument, which is a string containing the user input.

    Note:

    Starting in Junos OS Release 21.2R1 and Junos OS Evolved Release 21.2R1, the script's command-line arguments include the --symbol argument instead of the symbol argument.

  3. Define or calculate the valid values for the parameter.

  4. Call the jcs.expand() function for each value to display on the command line.

The script must call the jcs:expand() function for each option or statement value to display in the CLI. The syntax for the jcs:expand() function is:

Where:

value

String defining a valid value for the given command option or configuration statement.

description

String that describes the value.

units

(Optional) String that defines the units for the corresponding value.

range

(Optional) String that defines the range for the corresponding value.

For each call to the jcs.expand() function, the script emits the value, description, units, and range that are provided in the function arguments in the CLI. For example, given the following call to jcs.expand() in the script:

The corresponding CLI output is:

The following sample scripts check for the presence of symbol in the script’s command-line arguments, and if present, set the corresponding variable equal to the user’s input. The scripts then calculate the set of valid values for the parameter based on the user’s input and call the jcs.expand() function for each value to display in the CLI.

We provide two versions of the script, which appropriately handle the script's symbol argument for the different releases. The following sample script, which is valid on devices running Junos OS Release 21.2R1 and later, uses the argparse library to parse the --symbol argument.

Similarly, the following sample script, which is valid on devices running Junos OS Release 21.1 and earlier, checks for symbol in the sys.argv list.

The CLI expansion script only displays the valid values, units, and ranges for the command option or configuration statement in the CLI. The module’s translation script or action script must ensure that only valid values are accepted and processed.

Loading the YANG Package

When you load a YANG package on a device running Junos OS, include any CLI expansion scripts in the list of action scripts for that package. Junos OS automatically copies the script to the /var/db/scripts/action directory.

To load a new package and include custom CLI expansion scripts:

  1. Ensure that the Python scripts meet the following requirements:
    • File owner is either root or a user in the Junos OS super-user login class.

    • Only the file owner has write permission for the file.

    • Script includes an interpreter directive line:

      • On devices running Junos OS Release 20.2R1 or later, use #!/usr/bin/python3

      • On devices running Junos OS Release 20.1 or earlier, use #!/usr/bin/python

  2. In configuration mode, enable the device to execute unsigned Python scripts by configuring the language python or language python3 statement, as appropriate for the Junos OS release.
    Note:

    Starting in Junos OS Release 20.2R1, Junos OS uses Python 3 to execute YANG action and translation scripts. In earlier releases, Junos OS uses Python 2.7 to execute these scripts.

  3. In operational mode, load the YANG package, and include the CLI expansion script in the action-script list.
    Note:

    To prevent CLI-related or configuration database errors, we recommend that you do not perform any CLI operations, change the configuration, or terminate the operation while a device is in the process of adding, updating, or deleting a YANG package and modifying the schema.

  4. When the system prompts you to restart the Junos OS CLI, press Enter to accept the default value of yes.

Example: Displaying Context-Sensitive Help for a Command Option

This example presents a custom YANG module that uses the action-expand extension statement and a custom script to display the set of possible values for one of the command options when a user requests context-sensitive help in the CLI for that option.

Requirements

This example uses the following hardware and software components:

  • Device running Junos OS Release 19.2R1 or later that supports loading custom YANG data models.

Overview

The YANG module in this example defines a custom RPC to ping the specified host and return the result. The YANG module rpc-host-status is saved in the rpc-host-status.yang file. The module imports the Junos OS extension modules, which provide the extensions required to execute custom RPCs on the device and to customize the output and context-sensitive help in the CLI.

The module defines the get-host-status RPC. The junos:command statement defines the command that is used to execute the RPC in the CLI, which in this case is show host-status. The junos:action-execute and junos:script statements define the action script that is invoked when you execute the RPC.

The hostip input parameter includes the junos:action-expand and junos:script statements, which define the script that is invoked when the user requests context-sensitive help in the CLI for that input parameter.

The hostip-expand.py script processes the user’s input, which is passed to the script as the argument symbol or --symbol, depending on the release. The script then calculates and displays the set of values that the user can enter for that command option.

Note:

Starting in Junos OS Release 21.2R1 and Junos OS Evolved Release 21.2R1, when the device passes command-line arguments to a Python action script (including CLI expansion scripts), it prefixes a single hyphen (-) to single-character argument names and prefixes two hyphens (--) to multi-character argument names.

The expansion script displays the valid values for hostip in the CLI. The action script implements the logic that determines if the provided value is valid. This example adds the YANG module and the action scripts to the device as part of a new YANG package named rpc-host-status.

YANG Module and Action Scripts

YANG Module

The YANG module, rpc-host-status.yang, defines the RPC, the command used to execute the RPC in the CLI, the name of the action script to invoke when you execute the RPC, and the name of the CLI expansion script to invoke when the user requests context-sensitive help for the corresponding input parameter.

Action Script

The corresponding action script is rpc-host-status.py. This example provides two versions of the action script, which appropriately handle the script's command-line arguments for the different releases.

Action Script (Junos OS Release 21.2R1 and later)
Action Script (Junos OS Release 21.1 and earlier)

CLI Expansion Script

The action script that handles the logic to display the valid values for hostip in the CLI is hostip-expand.py. This example provides two versions of the script, which appropriately handle the script's arguments for the different releases.

CLI expansion script (Junos OS Release 21.2R1 and later)
CLI expansion script (Junos OS Release 21.1 and earlier)

Configuration

Enable Execution of Python Scripts

To enable the device to execute unsigned Python scripts:

  1. Configure the language python or language python3 statement, as appropriate for the Junos OS release.

    Note:

    Starting in Junos OS Release 20.2R1, Junos OS uses Python 3 to execute YANG action and translation scripts. In earlier releases, Junos OS uses Python 2.7 to execute these scripts.

  2. Commit the configuration.

Load the YANG Module and Scripts on the Device

To add the YANG module and scripts to the device running Junos OS:

  1. Download the YANG module and scripts to the device running Junos OS.

  2. Ensure that the Python scripts meet the following requirements:

    • File owner is either root or a user in the Junos OS super-user login class.

    • Only the file owner has write permission for the file.

    • Script includes the appropriate interpreter directive line:

      • On devices running Junos OS Release 20.2R1 or later, use #!/usr/bin/python3

      • On devices running Junos OS Release 20.1 or earlier, use #!/usr/bin/python

  3. (Optional) Validate the syntax for the YANG module and action scripts.

  4. Add the YANG module and scripts to a new YANG package.

  5. When the system prompts you to restart the Junos OS CLI, press Enter to accept the default value of yes, or type yes and press Enter.

Verifying the Context-Sensitive Help

Purpose

Verify that the CLI expansion script works as expected.

Action

From operational mode, request context-sensitive help in the CLI by issuing the command defined by the junos:command statement in the RPC definition, and include the hostip input argument and a question mark (?).

Perform the same operation with partial user input and verify that the displayed values correctly match the input.

Meaning

When context-sensitive help is requested for the hostip value, Junos OS invokes the hostip-expand.py script. The script processes the user’s input, if provided, and prints the valid completions in the CLI. If no user input is given, the script prints all possible values. When user input is provided, the script prints only matching values.

Release History Table
Release
Description
21.2R1 and 21.2R1-EVO
Starting in Junos OS Release 21.2R1 and Junos OS Evolved Release 21.2R1, when the device passes command-line arguments to a Python action script, it prefixes a single hyphen (-) to single-character argument names and prefixes two hyphens (--) to multi-character argument names.