Use the Junos PyEZ Config Utility to Configure Junos Devices

After successfully connecting to a Junos device, 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 you use 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:

   • Call load() when loading a new complete configuration or modifying specific portions of the configuration

   • Call rollback() to revert to a previously committed configuration, as described in Roll Back the Configuration

   • Call rescue() to load the rescue configuration, as described in Load the Rescue Configuration

3. Commit the configuration using commit() , as described in Commit the Configuration and Use 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 Specify 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 CLI. For more information, see:

• Specify the Load Operation

• Specify the Format of the Configuration Data to Load

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

• Specify the Location of the Configuration Data

• Load Configuration Data from a Local or Remote File

• Load Configuration Data from a String

• Load Configuration Data Formatted as an XML Object

• Load Configuration Data Using Jinja2 Templates

By default, when you create a Config object and do not explicitly specify a configuration mode, Junos PyEZ updates the candidate global configuration. You can also specify a different 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:

You can use Junos PyEZ to 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 Junos devices. 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 Use Junos PyEZ to Configure Junos Devices.

Junos PyEZ supports loading configuration changes using using many of the same load operations that are supported in the Junos CLI. 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 use a different load operation, set the corresponding parameter to True in the load() method.

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

Load Operation	Argument	Description	First Supported Junos PyEZ Release
load merge	merge=True	Merge the loaded configuration with the existing configuration.	1.0
load override	overwrite=True	Replace the entire configuration with the loaded configuration.	1.0
load patch	patch=True	Load configuration data from a patch file.	2.4.0
load replace (Default)	–	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.	1.0
load update	update=True	Load a complete configuration and compare it 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.	2.1.0

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.

The Junos PyEZ Config utility enables you to configure Junos devices 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: Specify 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:

Devices running Junos OS Release 16.1R1 or later support loading configuration data in JSON format.

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 the configuration data or reference its location. 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 Junos device or at a remote URL that is reachable from the Junos 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.

Junos PyEZ enables you to load configuration data formatted as ASCII text, Junos XML elements, Junos OS set commands, or JSON from a local or remote 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:

You can also load configuration data from a file located on the Junos device or at a URL that is reachable from the Junos device. To load configuration data from a file on the Junos device, set the url parameter to the absolute or relative path of the file on the target device, and include any other parameters required for the load operation. For example:

To load configuration data from a file at a remote URL, set the url parameter to 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 Specify 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 Load Configuration Data Using Jinja2 Templates.

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. 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 Junos device.

• 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".

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:

Junos PyEZ supports using Jinja2 templates to render Junos 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 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 Junos device.

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

Junos devices 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 Junos device. 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.

For a more extensive example that includes error handling, see Example: Use Junos PyEZ to Roll Back the 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 Junos devices. 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 Use Junos PyEZ to Manage the Rescue Configuration on Junos Devices.

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 Use Junos PyEZ to Commit the Configuration.