Using the Junos PyEZ Config Utility to Configure Devices Running Junos OS

 

Junos PyEZ enables you to make structured and unstructured configuration changes on devices running Junos OS. This topic discuss how to use the jnpr.junos.utils.config.Config utility to make unstructured configuration changes, which consist of static or templatized configuration data that is formatted as ASCII text, Junos XML elements, Junos OS set commands, or JavaScript Object Notation (JSON). The Config utility also enables you to roll back to a previously committed configuration or revert to a rescue configuration.

Configuration Process Overview

After successfully connecting to a device running Junos OS, to configure the device using the Config utility, first create a Config object and associate it with the Device instance. For example:

By default, Junos PyEZ updates the candidate global configuration (also known as the shared configuration database). The basic process for making configuration changes is to lock the configuration database, load the configuration changes, commit the configuration to make it active, and then unlock the configuration database. When using the Junos PyEZ Config utility to make unstructured configuration changes in the shared configuration database, you can perform these actions by calling the appropriate instance methods outlined here:

  1. Lock the configuration using lock()

  2. Modify the configuration by performing one of the following actions:

  3. Commit the configuration using commit(), as described in Committing the Configuration and Using Junos PyEZ to Commit the Configuration

  4. Unlock the configuration using unlock()

You can also use a context manager (with ... as syntax) to create a Config object instance, and certain configuration modes require that you use one. For these modes, Junos PyEZ automatically locks and unlocks the configuration. For more information, see Specifying the Configuration Mode.

When you use the load() method to modify the configuration, in addition to specifying the configuration mode, you can also specify the type of load operation, the format of the configuration changes, and the source of the configuration data. The Config utility supports many of the same load operations and formats that are available in the Junos OS command-line interface (CLI). For more information, see:

You can specify the source of the configuration data as a file on the local server, a file on the client device, or a file at a URL that is reachable from the client device, or as a string, an XML object, or a Jinja2 template. For information about specifying the configuration data source, see the following sections:

Specifying the Configuration Mode

By default, when you create a Config object and do not explicitly specify a configuration mode, Junos PyEZ updates the candidate global configuration. Starting in Junos PyEZ Release 2.0, you can specify the configuration mode to use when modifying the configuration database. To specify a mode other than the default, you must create the Config object using a context manager and set the mode argument to the desired mode. Supported modes include private, exclusive, dynamic, batch, and ephemeral.

Note

Starting in Junos PyEZ Release 2.1.3, you can update the ephemeral configuration database on devices that support this database. The ephemeral database is an alternate configuration database that provides a fast programmatic interface for performing configuration updates on devices running Junos OS. It is an advanced feature which if used incorrectly can have a serious negative impact on the operation of the device. For more information, see Understanding the Ephemeral Configuration Database.

When you specify a mode other than the default, the context manager handles opening and locking and closing and unlocking the database. This ensures that you do not unintentionally leave the database in a locked state. In these cases, you only need to call the load() and commit() methods to configure the device.

For example, the following code makes configuration changes using the configure private mode, which opens a private copy of the candidate configuration:

For more information about the different configuration modes, see the CLI User Guide and Using Junos PyEZ to Configure Devices Running Junos OS.

Specifying the Load Operation

Junos PyEZ supports loading configuration changes using a load merge, load replace, load override, or load update operation. You specify the desired load operation by including or omitting the appropriate parameters in the Config load() method.

Table 1 outlines the supported load operations and the corresponding load() method argument. By default, Junos PyEZ performs a load replace operation. To perform a load merge, load override, or load update operation, set the merge, overwrite, or update parameter, respectively, to True in the load() method.

Table 1: Parameters for Specifying the Load Operation Type in the load() and set() Methods

Load Operation

Argument

First Supported Junos PyEZ Release

Description

load  merge

merge=True

1.0

Merge the loaded configuration with the existing configuration.

load  override

overwrite=True

1.0

Replace the entire configuration with the loaded configuration.

load  replace (Default)

1.0

Merge the loaded configuration with the existing configuration, but replace statements in the existing configuration with those that specify the replace: tag in the loaded configuration. If there is no statement in the existing configuration, the statement in the loaded configuration is added.

load  update

update=True

2.1.0

Compare the complete loaded configuration against the existing configuration. Each configuration element that is different in the loaded configuration replaces its corresponding element in the existing configuration. During the commit operation, only system processes that are affected by changed configuration elements parse the new configuration.

The following example performs a load override operation, which replaces the entire candidate configuration with the loaded configuration, and then commits the candidate configuration to make it active.

Specifying the Format of the Configuration Data to Load

The Junos PyEZ Config utility enables you to configure devices running Junos OS using one of the standard, supported formats. You can provide configuration data as strings, files, XML objects, or Jinja2 Template objects. Files can contain either configuration data snippets or Jinja2 templates. When providing configuration data within a string, file, or Jinja2 template, supported formats for the data include ASCII text, Junos XML elements, Junos OS set commands, and JSON. You can specify the format of the configuration data either by explicitly including the format parameter in the Config utility load() method or by adding the appropriate extension to the configuration data file. If you do not specify a format, the default is XML.

Note

Starting in Junos PyEZ Release 1.2, Junos PyEZ automatically detects the format when you supply the configuration data as a string.

Table 2 summarizes the supported formats for the configuration data and the corresponding value for the file extension and format parameter. When using Junos XML formatting for the configuration data, you must enclose the data in the top-level <configuration> tag.

Note

You do not need to enclose configuration data that is formatted as ASCII text, Junos OS set commands, or JSON in <configuration-text>, <configuration-set>, or <configuration-json> tags as required when configuring the device directly within a NETCONF session.

Table 2: Specifying the Format for Configuration Data

Configuration Data Format

File Extension

format Parameter

ASCII text

.conf, .text, .txt

text

JavaScript Object Notation (JSON)

.json

json

Junos OS set commands

.set

set

Junos XML elements

.xml

xml

Note

When the overwrite or update parameter is set to True, you cannot use the Junos OS set command format.

Note

Starting in Junos PyEZ Release 2.0, Junos PyEZ supports loading configuration data in JSON format on devices running Junos OS Release 16.1R1 and later releases.

Specifying the Location of the Configuration Data

Junos PyEZ enables you to load configuration data as strings, files, XML objects, or Jinja2 Template objects. Files can contain either configuration data snippets or Jinja2 templates.

Table 3 summarizes the load() method parameters that you use to pass in or reference the location of the configuration data. You must always specify the format of the data by including the format parameter in the method call except when using strings, XML objects, or files that have the format indicated by the file extension. When using Jinja2 templates, include the template_vars parameter to pass in the dictionary of required template variables.

Table 3: Referencing Configuration Data in the load() Method

Parameter

Configuration Data Source

Description

format Parameter Requirements

path

Local file

Path to a file on the local configuration management server containing configuration data formatted as ASCII text, Junos XML elements, Junos OS set commands, or JSON.

You must include the format parameter when the file extension does not indicate the format of the data.

template

Jinja2 Template object

Pre-loaded Jinja2 Template object.

Include the template_vars parameter in the load() method argument list to reference a dictionary containing any required Jinja2 template variables.

You must include the format parameter when the file extension does not indicate the format of the data.

template_path

Local Jinja2 template file

Path to a file on the local configuration management server containing a Jinja2 template formatted as ASCII text, Junos XML elements, Junos OS set commands, or JSON.

Include the template_vars parameter in the load() method argument list to reference a dictionary containing any required Jinja2 template variables.

You must include the format parameter when the file extension does not indicate the format of the data.

url

Remote file

Path to a file located on the client device running Junos OS or at a remote URL that is reachable from the client device using an FTP or Hypertext Transfer Protocol (HTTP) URL.

You must include the format parameter when the file extension does not indicate the format of the data.

vargs[0]

XML object

String

XML object or a string that contains configuration data formatted as ASCII text, Junos XML elements, Junos OS set commands, or JSON.

Junos PyEZ automatically detects the format of the configuration data in this case, and the format parameter is not required.

Loading Configuration Data from a Local or Remote File

Junos PyEZ enables you to load configuration data formatted as ASCII text, Junos XML elements, Junos OS set commands, or JSON from a file. To load configuration data from a local file on the configuration management server, set the load() method’s path parameter to the absolute or relative path of the file. For example:

Starting in Junos PyEZ Release 2.1.5, you can load configuration data from a file located on the client device running Junos OS or at a URL that is reachable from the client device. To load configuration data from a file on the device running Junos OS or at a remote URL, set the url parameter to the absolute or relative path of the file on the client device or the FTP location or Hypertext Transfer Protocol (HTTP) URL of a remote file, and include any other parameters required for the load operation. For example:

For detailed information about specifying the URL, see the url attribute for the Junos XML protocol <load-configuration> operation.

If the file does not indicate the format of the configuration data by using one of the accepted file extensions as listed in Specifying the Format of the Configuration Data to Load, then you must specify the format by including the format parameter in the load() method parameter list. For example:

For information about loading configuration data from Jinja2 templates or template files, see Loading Configuration Data Using Jinja2 Templates.

Loading Configuration Data from a String

To load configuration data that is formatted as ASCII text, Junos XML elements, Junos OS set commands, or JSON from a string, include the string as the first argument in the load() method argument list. Starting in Junos PyEZ Release 1.2, Junos PyEZ automatically detects the format of the configuration data in strings, so the format parameter is optional in this case.

The following code snippets present sample multiline strings containing configuration data in the different formats and the corresponding calls to the load() method. The optional format parameter is explicitly included in each example for clarity. In the examples, cu is an instance of the Config utility, which operates on the target device running Junos OS.

  • For configuration data formatted as ASCII text:

    Load the configuration data by supplying the string as the first argument in the list, and optionally specify format="text".

  • For configuration data formatted as Junos XML:

    Load the configuration data by supplying the string as the first argument in the list, and optionally specify format="xml".

  • For configuration data formatted as Junos OS set commands:

    Load the configuration data by supplying the string as the first argument in the list, and optionally specify format="set".

  • For configuration data formatted using JSON:

    Load the configuration data by supplying the string as the first argument in the list, and optionally specify format="json".

Loading Configuration Data Formatted as an XML Object

To load configuration data formatted as an XML object, include the object as the first argument in the load() method argument list, and supply any other required parameters. Because the default format for configuration data is XML, you do not need to explicitly include the format parameter in the method call.

The following code presents an XML object and the corresponding call to the load() method:

Loading Configuration Data Using Jinja2 Templates

Junos PyEZ supports using Jinja2 templates to render Junos OS configuration data. Jinja is a template engine for Python that enables you to generate documents from predefined templates. The templates, which are text files in the desired language, provide flexibility through the use of expressions and variables. You can create Junos OS configuration data using Jinja2 templates in one of the supported configuration formats, which includes ASCII text, Junos XML elements, Junos OS set commands, and JSON. Junos PyEZ uses the Jinja2 template and a supplied dictionary of variables to render the configuration data.

Jinja2 templates provide a powerful method to generate configuration data, particularly for similar configuration stanzas. For example, rather than manually adding the same configuration statements for each interface on a device, you can create a template that iterates over a list of interfaces and creates the required configuration statements for each one. In Jinja, blocks are delimited by '{%' and '%}' and variables are enclosed within '{{' and '}}'.

The following sample Jinja2 template generates configuration data that enables MPLS on logical unit 0 for each interface in a given list and also configures the interface under the MPLS and RSVP protocols.

In the Junos PyEZ code, the corresponding dictionary of Jinja2 template variables is:

To load the Jinja2 template in the Junos PyEZ code, set the template_path parameter to the path of the template file, and set the template_vars parameter to the dictionary of template variables. If you do not use one of the accepted file extensions to indicate the format of the configuration data, then you must include the format parameter in the load() method parameter list.

Note

If you are supplying a pre-loaded Jinja2 Template object, you must use the template parameter instead of the template_path parameter in the load() method argument list.

Junos PyEZ uses the Jinja2 template and dictionary of variables to render the following configuration data, which is then loaded into the candidate configuration and committed on the device:

The following video presents a short Python session that demonstrates how to use a Jinja2 template to configure a device running Junos OS.

 

For additional information about Jinja2, see the Jinja2 documentation at http://jinja.pocoo.org/docs/.

Rolling Back the Configuration

Devices running Junos OS store a copy of the most recently committed configuration and up to 49 previous configurations, depending on the platform. You can roll back to any of the stored configurations. This is useful when configuration changes cause undesirable results, and you want to revert back to a known working configuration. Rolling back the configuration is similar to the process for making configuration changes on the device, but instead of loading configuration data, you perform a rollback, which replaces the entire candidate configuration with a previously committed configuration.

The Junos PyEZ jnpr.junos.utils.config.Config class rollback() method enables you to roll back the configuration on a device running Junos OS. To roll back the configuration, call the rollback() method and and set the rb_id argument to the ID of the rollback configuration. Valid ID values are 0 (zero, for the most recently committed configuration) through one less than the number of stored previous configurations (maximum is 49). If you omit this parameter in the method call, it defaults to 0.

The following example prompts for the rollback ID of the configuration to restore, rolls back the configuration, prints the configuration differences, and then commits the configuration to make it the active configuration on the device.

user@server:~$ python junos-pyez-rollback.py

For a more extensive example that includes error handling, see Example: Using Junos PyEZ to Roll Back the Configuration.

Loading the Rescue Configuration

A rescue configuration allows you to define a known working configuration or a configuration with a known state that you can restore at any time. You use the rescue configuration when you need to revert to a known configuration or as a last resort if your router or switch configuration and the backup configuration files become damaged beyond repair. When you create a rescue configuration, the device saves the most recently committed configuration as the rescue configuration.

The Junos PyEZ jnpr.junos.utils.config.Config utility enables you to manage the rescue configuration on devices running Junos OS. After creating an instance of the Config class, you use the rescue() method to mange the rescue configuration. You specify the action to perform on the rescue configuration by setting the rescue() method action parameter to the desired operation.

To load the existing rescue configuration into the candidate configuration, specify action="reload". If no rescue configuration exists, the load operation returns False. After loading the rescue configuration, you must commit the configuration to make it the active configuration on the device.

The following example loads and commits the rescue configuration, if one exists:

For information about creating, retrieving, or deleting the rescue configuration and for additional examples, see Using Junos PyEZ to Manage the Rescue Configuration on Devices Running Junos OS.

Committing the Configuration

After modifying the configuration, you must commit the configuration to make it the active configuration on the device. When you use the Config utility to make unstructured configuration changes on a device, you commit the candidate configuration by calling the commit() method.

For more information about the commit operation and supported commit options in Junos PyEZ scripts, see Using Junos PyEZ to Commit the Configuration.

Release History Table
Release
Description
Starting in Junos PyEZ Release 1.2, Junos PyEZ automatically detects the format when you supply the configuration data as a string.