Define Junos PyEZ Operational Tables for Parsing Unstructured Output

The Table name is a user-defined identifier for the Table. The YAML file or string can contain one or more Tables. The start of the YAML document must be left justified. The following example defines a Table named ChassisFanTable:

A Junos PyEZ op Table for unstructured output extracts data from the text output of a CLI or vty command. You must include the command property in the Table definition to specify the CLI command to execute on a device or the vty command to execute on a given FPC. You can define the command as a simple string or a Jinja template.

For example, the following Table executes the show chassis fan command on the device.

The following Table executes the show cmerror module brief vty command on the target FPC.

When you define the command as a Jinja template, you must also supply the args parameter. The args parameter is a dictionary of key-value pairs that map the variables in the template to the values used when you render the template. For information about defining the command as a Jinja template, see Command Arguments (args).

You can define the CLI or vty command for the command parameter as a Jinja template that substitutes variables for the command arguments. When you use a Jinja template, you must also define the args parameter. The args parameter is a dictionary of key-value pairs that map the variable names in the Jinja template to the values used when you render the template. You can provide default values for the template variables in the Table definition, and you can also define the values in the Junos PyEZ application.

To define default values for the template variables, include the args parameter in the Table definition and map each template variable to its default value. The following Table defines a command using a Jinja template that has one variable, protocol. The args parameter defines the default value for protocol. The application uses the default value when you call the get() method in your script and do not provide an argument that overrides that default.

Additionally, you can define the args argument as a dictionary in the Table’s get() method to:

• Define a value for any template variable that does not have a default value defined in the Table

• Override the default value defined in the Table for one or more template variables

The following example executes the command in the previous Table using protocol 'bgp' instead of the default value of 'ospf'.

Junos PyEZ op Tables can execute vty commands on a specific FPC. When you use a vty command, the Table must include the target parameter to define the target FPC. You can set target to Null and force the user to specify the target FPC in the application. Alternatively, you can set target to a default FPC, and the user can optionally override this value in the application.

The following Table executes the show memory vty command, but sets target: Null. Thus, the user must specify the target FPC in the Junos PyEZ application:

The following Table executes the show memory vty command on FPC 1, unless the user overrides this value in the Junos PyEZ application.

In the Junos PyEZ application, you can define the target FPC or override the default FPC defined in the Table. To specify the FPC, set the target argument in the Table’s get() method to the required FPC, for example:

The optional Table item property is a string or regular expression that defines how to split the command output for parsing. If the output has similar, repeating sets of data, you can define item to match on and extract each iteration of the data. For example, show interfaces returns a similar set of data for many interfaces. Alternatively, you can define item: '*' when you need to extract the data as a single block of text.

Consider the following output for the show devices local vty command:

The following Table extracts each section of the output that starts with TSEC Ethernet Device Driver:. In this case, the value for key: name is derived from the capturing group in the regular expression defined in item.

You can also define item as an asterisk ('*') if you want to match against the entire section of output instead of matching each line. When you include item: '*', in most cases, you must also include the title parameter to specify the heading for the section of output to extract. Extracting the output using item: '*' is useful when you include the regex parameter in a View and want each expression to match against the entire text string. Otherwise, the regex expressions are combined and matched against each line.

The following Table extracts the text block under the heading Receive: and matches each regular expression against the entire text string:

The optional key property defines the output fields that are used to uniquely identify a Table item. You can identify a Table item using a single key or a list of keys. If the Table and View return iterative data, the key value must reference a variable or field name defined in the View.

Consider the following show chassis fan output:

The following Table defines the Table item key as fan-name, which maps to the value under the Item column in the output.

When you retrieve and print the data in the Junos PyEZ application, each item in the resulting dictionary uses this field’s value as its key.

You can also define key as a list to identify a Table item using a composite key. For example:

The key parameter defines the output fields that uniquely identify a Table item. When you include the key parameter in a Table, you can use the optional key_items parameter to only return data for certain key values. key_items defines the key or list of keys of the Table items for which to retrieve data. You can define the key_items parameter in the Table definition or in the Junos PyEZ application.

Consider the following show chassis fan output:

The following Table defines the Table item key as fan-name and only retrieves the data for the Table item with a key value equal to Fan 1.

In the Junos PyEZ application, you can define the key_items to return and you can override the key_items defined in the Table. Set the key_items argument in the Table’s get() method to a list or tuple of the desired items. For example:

Tables can include the optional title parameter to define the starting point for a section in the command output from which to extract and parse the data. When the Table defines item: '*', you must include title to specify the heading for the section of output to extract

For example, consider the following command output, which is enclosed within a larger set of output:

The following Table uses the title parameter to extract and parse data from the TSEC status counters section of the output. In this case, the Table defines item as '*', which considers the data as a single text string.

Some operational commands return output comprised of only key-value pairs. If you want to simply retrieve the entire set of data and extract each key-value pair, you can use the delimiter parameter instead of defining a separate View. The delimiter parameter defines how to split each data pair. Junos PyEZ uses the delimiter to split the data at the specified boundary and stores each key-value pair in a dictionary.

Consider the following output for the show link stats vty command.

The following Table defines the delimiter as the colon (:) character:

When you retrieve the data in the Junos PyEZ application, the Table splits each line of output at the delimiter and stores the key-value pairs in a dictionary.

You can use the optional eval parameter to add or modify key-value pairs in the final data returned by the Table and View. The eval parameter maps a key name to a string containing a mathematical expression. You can include the eval parameter in both Tables and Views, and eval can define and calculate multiple values.

When you use eval in a Table, it references the full data dictionary for the calculation. The key and calculated value are added as a single additional item to the dictionary. When you use eval in a View, the expression is calculated on each iteration of the data. The calculated value is added to the data for that iteration. If the eval key name matches a key defined in the View, eval replaces the value of that key with the calculated value. If the eval key name does not match a key defined in the View, eval adds the new key and calculated value to the data.

The eval expression can reference the data dictionary returned by the View. The expression must reference data using a Jinja template variable, so that Junos PyEZ can replace the variable with the dictionary when the expression is evaluated.

Starting with Junos PyEZ Release 2.8.1, expressions used in Table and View eval statements are evaluated using a restricted implementation to reduce code-execution security risks. Junos PyEZ parses and validates each expression against a supported set of Python syntax, functions, methods, and operations before evaluation. Expressions containing unsupported or unsafe elements are rejected with an UnsafeExpressionError error. Table 2 outlines the supported expressions.

+ - * / // % **

The following example uses eval in the Table definition to include a single additional entry in the data dictionary. The added item’s key is total_interrupts, and its value is the sum of the number of interrupts.

You can also define eval in the Table to calculate and add multiple key-values pairs, for example:

For information about using eval in a View, see Eval Expression (eval).

The view property associates the Table definition with a particular View. A View defines how the Table output should be parsed and maps your user-defined Python variable names to output fields in the selected Table items. You can customize the View to only select certain fields from the Table items.

If the output consists of only key-value pairs, you can use the Table’s delimiter parameter to extract the data and store the key-value pairs in a dictionary. In this case, you do not need to define a separate View.

Junos PyEZ Tables can reference a TextFSM template to parse command output from Juniper Networks devices or other vendors’ devices. You must install the ntc-templates library on your Junos PyEZ server or virtual environment in order to use TextFSM templates in your Tables.

To use a TextFSM template to parse the command output, include use_textfsm: True in the Table. You can use just the TextFSM template or you can use the template in conjunction with a Junos PyEZ View. Junos PyEZ uses the platform and command values to determine the template’s filename.

For example, the following Table uses the juniper_junos_show_arp_no-resolve.textfsm template to parse command output from a Juniper Networks Junos device:

For detailed information about using Junos PyEZ Tables with TextFSM templates, see Use Junos PyEZ Tables with TextFSM Templates.