Define Junos PyEZ Configuration Tables
SUMMARY Create custom Tables that configure a specific resource on a Junos device or extract configuration data from the device.
You define Junos PyEZ configuration Tables to extract specific data from the selected configuration database of a Junos device or to create structured resources that can be used to programmatically configure a Junos device. 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 Parameter Name |
Table Parameter |
Table Type |
Description |
|---|---|---|---|
Table name |
– |
|
User-defined Table identifier. |
Configuration scope |
|
— |
XPath expression relative to the top-level Specify These objects become the reference for the associated View. |
Configuration resource key field |
|
|
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 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 |
|
|
(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 Users must include all required keys as arguments to the |
Table View |
|
|
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.
---
UserTable:
get: system/login/user
required_keys:
user: name
view: UserView
UserView:
fields:
username: name
userclass: class
uid: uid
UserConfigTable:
set: system/login/user
key-field:
username
required_keys:
user: name
view: UserConfigView
UserConfigView:
fields:
username: name
userclass: class
uid: uid
password: authentication/encrypted-password
fullname: full-name
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:
--- UserTable: # Table definition
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 Junos device. 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
<rpc-reply>
<configuration>
<system>
<login>
...
<user>
<name>user1</name>
<uid>2001</uid>
<class>super-user</class>
<authentication>
<encrypted-password>...</encrypted-password>
</authentication>
</user>
<user>
<name>readonly</name>
<uid>3001</uid>
<class>read-only</class>
<authentication>
<encrypted-password>...</encrypted-password>
</authentication>
</user>
</login>
</system>
</configuration>
</rpc-reply>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:
system/login/user
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.
get: system/login/user
To define a Table that can be used to configure user objects in addition to retrieving them, use set.
set: system/login/user
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:
table_object.get(options={'database':'committed'})
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.
UserConfigTable:
set: system/login/user
key-field:
username
required_keys:
user: name
view: UserConfigView
UserConfigView:
fields:
username: name
userclass: class
uid: uid
password: authentication/encrypted-password
fullname: full-name
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:
from jnpr.junos import Device from myTables.ConfigTables import UserConfigTable with Device(host='router1.example.com') as dev: users = UserConfigTable(dev) users.username = 'admin' users.userclass = 'super-user' ...
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 it retrieves the data:
UserTable:
get: system/login/user
required_keys:
user: name
view: UserView
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':
from jnpr.junos import Device from myTables.ConfigTables import UserTable with Device(host='router1.example.com') as dev: users = UserTable(dev) users.get(user='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:
get: interfaces/interface/unit
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:
required_keys:
interface: name
unit: name
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 Define Views for Junos PyEZ Configuration Tables.