Defining Junos PyEZ Configuration Tables

 

You define Junos PyEZ configuration Tables to extract specific data from the selected configuration database of a device running Junos OS or to create structured resources that can be used to programmatically configure a device running Junos OS. Thus, you can quickly retrieve or modify specific configuration objects on the device.

Junos PyEZ Tables are formatted using YAML. When you define a Junos PyEZ configuration Table, you must specify the configuration scope using either get or set. Tables that include the get property can only retrieve the specified configuration data from a device. Tables that include the set property define configuration resources that you can use to configure the device as well as to retrieve configuration data from the device. Thus, they are a superset and include all of the functionality of Tables that specify get.

Configuration Table definitions can include a number of required and optional parameters. Table 1 summarizes the parameters and specifies whether the parameter can be used in Tables that solely retrieve configuration data from the device (get) or in Tables that can also configure the device (set).

Table 1: Junos PyEZ Configuration Table Parameters

Table Parameter Name

Table Parameter

Table Type

Description

Table name

get or set

User-defined Table identifier.

Configuration scope

get or set

XPath expression relative to the top-level <configuration> element that identifies the configuration hierarchy level at which to select or configure objects, depending on the Table type.

Specify get to retrieve configuration objects or specify set to both configure and retrieve objects.

These objects become the reference for the associated View.

Configuration resource key field

key-field

set

String or list of strings that references any field names defined in the View that map to identifier elements and can be used to uniquely identify the configuration object. For example, you might specify the field name that corresponds to the <name> element for an object.

You must always define at least one key field in the Table, and users must declare values for all keys when configuring the resource in their application.

Required keys

required_keys

get or set

(Optional) Associative array, or dictionary, of key-value pairs that map a hierarchy level in the configuration scope to the element that uniquely identifies the object at that hierarchy level, for example, the <name> element.

Users must include all required keys as arguments to the get() method when retrieving the configuration data in their application.

Table View

view

get or set

View associated with the Table.

Consider the following Junos PyEZ configuration Tables and their associated Views. UserTable, which includes the get property, extracts configuration data for user accounts on the target device. UserConfigTable, which includes the set property, defines a structured configuration resource that can be used to configure user accounts on the target device as well as retrieve configuration data for user accounts.

The following sections discuss the different components of the Tables:

Table Name

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. For example:

Configuration Scope (get or set)

The configuration scope property, which is required in all configuration Table definitions, identifies the configuration hierarchy level at which to retrieve or configure objects, depending on the Table type. Junos PyEZ configuration Tables can be used to both retrieve and modify configuration data on a device running Junos OS. Configuration tables that specify the get property can only retrieve configuration data. Configuration Tables that specify the set property can both configure and retrieve data.

The value for get or set is an XPath expression relative to the top-level <configuration> element that identifies the hierarchy level at which to retrieve or set the configuration data. This data becomes the reference for the associated View.

Consider the following sample configuration hierarchy:

user@router> show configuration system login | display xml

To retrieve or configure the user elements at the [edit system login] hierarchy level, the value for the get or set property would use the following expression:

Note

Do not include a slash ( / ) at the end of the XPath expression, because the script will generate an error.

For example, to define a Table that can only be used to retrieve user objects, use get.

To define a Table that can be used to configure user objects in addition to retrieving them, use set.

By default, Junos PyEZ configuration Tables retrieve data from the candidate configuration database. When you call the get() method in the Python script to retrieve the Table data, you can specify that the method should instead return data from the committed configuration database by passing in the options argument and including the 'database':'committed' item in the options dictionary. For example:

Key Field (key-field)

In the Junos OS configuration, each instance of a configuration object, for example, an interface or a user account, must have a unique identifier. In many cases, the <name> element, which is explicitly displayed in the Junos XML output, uniquely identifies each instance of the object. However, in some cases, a different element or a combination of elements is used. For example, a logical interface is uniquely identified by the combination of the physical interface name and the logical unit number.

Configuration Tables that specify the set property to define a configuration resource must indicate which element or combination of elements uniquely identifies the resource. The key-field property, which is a string or list of strings, serves this function and is required for all set configuration Tables.

The View for a set Table must explicitly define fields for all identifier elements for the configuration resource. The key-field property must then reference all of the field names for the identifier elements in the Table definition. When using the Table to configure the resource, a Junos PyEZ application must supply values for all key fields.

For example, the following Table defines a structured resource that can be used to configure user accounts at the [edit system login] hierarchy level. The View explicitly defines the username field and maps it to the name element at the [edit system login user] hierarchy level. The key-field property references this field to indicate that the name element uniquely identifies instances of that object.

When the Junos PyEZ application configures instances of the UserConfigTable resource on the device, it must define a value for the username key for each instance. For example:

If the configuration Table defines fields for statements in multiple hierarchy levels that have identifiers at each level, the key-field property must include all of the identifiers. For example, if the Table configures a logical unit on an interface, the key-field property must include both the interface name and the logical unit number as keys.

Required Keys (required_keys)

You include the optional required_keys property in your configuration Table definition to require that the Table users provide values for one or more keys when they retrieve the data in their application. Each key must map a hierarchy level in the configuration scope defined by the get or set parameter to the <name> identifier at that level. You can only define one key per hierarchy level.

In the following example, UserTable requires that the Junos PyEZ application specify the value of a name element at the [edit system login user] hierarchy level when retrieving the data:

In the corresponding Junos PyEZ script, you must include the required keys in the get() method argument list. The following example requests the configuration data for the user named 'readonly':

You can only require keys at hierarchy levels in the configuration scope defined by the get or set parameter. Consider the following definition for get:

In this case, you can request that the user provide values for the interface name and the unit number as shown in the following sample code, but you cannot define a required key for the interface address, which is at a lower hierarchy level:

Table View (view)

The view property associates the Table definition with a particular View. A View maps your user-defined field names to elements in the selected Table items using XPath expressions. You can customize the View to only select certain elements to retrieve or configure, depending on the Table type and operation.

For more information about defining Views for configuration Tables, see Defining Junos PyEZ Views for Configuration Tables.