Help us improve your experience.

Let us know what you think.

Do you have time for a two-minute survey?

Displaying 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

In operational or configuration mode, you can get context-sensitive help when you type a question mark (?) anywhere in the Junos OS command-line interface (CLI). When you execute a command or configure a device, 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:

user@host> show host-status hostip ?
user@host> show host-status hostip 198?

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.

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:

user@host> show host-status hostip ?

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

user@host> show host-status hostip 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.

  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:

valueString defining a valid value for the given command option or configuration statement.
descriptionString 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 script first checks for the presence of symbol in the script’s command-line arguments, and if present, sets the symbol variable equal to the user’s input. The script then calculates the set of valid values for the parameter based on the user’s input, and calls the jcs.expand() function for each value to display in the CLI.

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.
    user@host> request system yang add package rpc-host-status module /var/tmp/rpc-host-status.yang action-script [/var/tmp/rpc-host-status.py /var/tmp/hostip-expand.py]
    Note

    To prevent CLI-related or configuration database errors, we recommend that you do not perform any CLI operations, change the configuration, or abort 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 of the YANG Module and Scripts

The YANG module presented in this section 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 the RPC is executed.

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, and displays the set of values that the user can enter for that command option.

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. The module containing the RPC and the action scripts are added to the device as part of a new YANG package named rpc-host-status.

YANG Module

The YANG module, rpc-host-status.yang, defines the RPC, the command used to execute the RPC in the CLI, and the name of the action script to invoke when the RPC is executed.

The corresponding action script is rpc-host-status.py.

Action Script

The action script that handles the logic to display the valid values of hostip in the CLI is hostip-expand.py.

CLI expansion script

Loading 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 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

  3. Add the YANG module and scripts to a new YANG package.
    user@host> request system yang add package rpc-host-status module /var/tmp/rpc-host-status.yang action-script [ /var/tmp/rpc-host-status.py /var/tmp/hostip-expand.py ]
  4. 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.

Enabling Execution of Python Scripts

To enable the device to execute unsigned Python scripts, configure the language python or language python3 statement as appropropriate.

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.

Verifying the Context-Sensitive Help

Purpose

Verify that the CLI expansion script is working 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 (?).

user@host> show host-status hostip ?

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

user@host> show host-status hostip 198?

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.