Using Salt to Configure Devices Running Junos OS

You can lock the candidate configuration before modifying it to prevent other users or applications from updating it until the lock is released. This is equivalent to the configure exclusive command in the CLI. We recommend locking the configuration before making changes, particularly on devices where multiple users are authorized to change the configuration, because a commit operation applies to all changes in the candidate configuration, not just those made by the user or application that requests the commit.

The junos.install_config function makes changes to the candidate configuration database using configure exclusive mode, which automatically locks the configuration database, loads and commits the changes, and unlocks the database. However if you need to execute the load and commit operations separately, for example, by using the junos.load and junos.commit functions, you can explicitly lock and unlock the database by using the junos.lock and junos.unlock execution or state functions.

To explicitly lock the configuration database before modifying it, use the junos.lock function. For example:

To unlock the database and discard any uncommitted changes, use the junos.unlock function. For example:

If the configuration database has been modified, or if another user already has an exclusive lock on it, the junos.lock function returns a LockError message, as shown in the following examples:

The junos.install_config function enables you to make changes in different configuration modes. By default, the function makes changes to the candidate configuration database using configure exclusive mode. The configure exclusive mode locks the candidate global configuration (also known as the shared configuration database) for as long as the function requires to make the requested changes to the configuration. Locking the database prevents other users from modifying or committing changes to the database until the lock is released.

To specify a different mode, set the mode parameter equal to the desired mode. Supported modes include batch, dynamic, ephemeral, exclusive, and private. For information about the different modes, see the CLI User Guide.

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

Similarly, you can include the argument in a Salt state file.

You can also use the junos.install_config function 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 devices running Junos OS. You must have Salt version 3001 and Junos PyEZ Release 2.1.3 or later to use this feature

To configure the default instance of the ephemeral configuration database, set the mode argument equal to ephemeral. For example:

To configure a user-defined instance of the ephemeral configuration database, set the mode argument equal to ephemeral, and set the ephemeral_instance argument equal to the name of the instance.

You can use the junos.load and junos.install_config functions to load 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 arguments for that function. If you do not specify a load operation, the default is load replace. Table 2 summarizes the arguments required for each type of load operation.

The following command replaces the entire configuration on the target device with the specified configuration and commits it. The RPC timeout is increased to provide sufficient time to load and commit the complete configuration.

The equivalent state file is:

The junos.load and junos.install_config functions enable you to configure devices running Junos OS using one of the standard, supported formats. You can load configuration data from a file containing a partial or complete configuration or a Jinja2 template. The data can be provided as text, Junos XML elements, Junos OS set commands, or JSON.

You must specify the format of the configuration data either by adding the appropriate extension to the configuration file or by explicitly including the format argument in the function call. Table 3 summarizes the supported formats for the configuration data and the corresponding value for the file extension and format parameter. If you include the format argument, it overrides the format indicated by the file extension.

The junos.load and junos.install_config functions enable you to load configuration data from a file that contains a partial or complete configuration or a Jinja2 template. The file can reside on the Salt master or the proxy minion server. The functions must use the salt:// notation to specify a path on the Salt master, and they must use an absolute path to specify a path on the proxy minion server. If the file does not use one of the accepted file extensions to indicate the format of the configuration data, then the function call must also include the format argument to specify the format of the data.

Table 4 describes the configuration data sources that you can use and lists the execution and state function arguments required to specify the location of the file. The execution functions can specify the path as a positional argument or by using the path keyword.

For example, the following file contains Junos OS set commands that configure two op scripts. The file’s extension indicates the format for the configuration data.

The following Salt command uses the junos.install_config execution function to load and commit the configuration on the target device. The path is provided as a positional argument.

The equivalent state file is:

The junos.install_config function automatically performs a diff between the candidate configuration and the requested configuration. The function only applies the configuration if there are changes. If you attempt to apply the same configuration a second time, the junos.install_config function returns a message that the configuration has already been applied and does not load and commit it again, as shown in the following example:

The junos.load and junos.install_config execution and state functions support using Jinja2 templates for 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. The functions use 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 '}}'.

To load a Jinja2 template, you must include the following parameters in the junos.load or junos.install_config function call:

• Template path—Specify the path to a template file on the Salt master or proxy minion server, as described in How to Load Configuration Data.

• Template format—Set the format argument to indicate the format of the configuration data if the template file does not use one of the accepted file extensions to specify the format. For information about specifying the format, see How to Specify the Format of the Configuration Data to Load.

• Template variables—The template can reference Salt internal variables like those defined in pillar or grain data. Any variables that are not already defined within the Salt system must be supplied in the template_vars argument. The template_vars value is a dictionary of keys and values that are required to render the Jinja2 template.

  Note:

  If your template only includes Salt internal variables like pillar data, grain data, and functions, the junos.install_config function might need to define template_vars: True in order to render the template.

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.

The following command uses the Jinja2 template and the variables defined in template_vars to render the configuration data, which is then loaded and committed on the target host:

The following state file loads the same configuration. The configuration differences are stored in the diffs_file file on the proxy minion server.

When you apply the state, Salt renders the configuration and loads and commits the configuration on the device.

The function generates the following configuration data, which is loaded into the candidate configuration on the device and committed:

After modifying the configuration, you must commit the configuration to make it the active configuration on the device. The junos.install_config, junos.rollback, and junos.set_hostname functions load the requested configuration changes and then automatically perform a commit check and commit operation. You can also use the individual junos.commit_check and junos.commit functions to perform a commit check and commit operation, for example, after using the junos.load function to update the configuration.

The Junos OS CLI provides options for the commit operation, such as adding a commit comment or synchronizing the configuration on multiple Routing Engines. Some of these options are supported by the Junos execution and state module functions. Table 5 outlines the commit options that are available and the functions that support them. Supported arguments are valid for both the execution function and the state function.

Commit Comment

When you commit the configuration, you can include a brief comment to describe the purpose of the committed changes. To log a comment describing the changes, include the comment argument and a message string. For example:

Similarly, in a state file:

The commit comment is included in the system log message for the commit as well as logged in the commit history.

Commit Confirmed

When you commit the candidate configuration, you can require an explicit confirmation for the commit to become permanent. If the commit is not confirmed within the specified amount of time, the device automatically loads and commits (rolls back to) the previously committed configuration. The confirmed commit operation is useful for verifying that a configuration change works correctly and does not prevent management access to the device. If the change prevents access or causes other errors, the automatic rollback to the previous configuration restores access to the device after the rollback deadline passes.

To require that a commit operation be confirmed within a specified amount of time after the initial commit, include the confirm=minutes argument. The allowed range is 1 through 65,535 minutes. You can also specify confirm=True to use the default time of 10 minutes.

The following command requires that the commit be confirmed within 15 minutes:

To confirm the commit operation, call either the junos.commit or junos.commit_check function.

Commit Detail

When you use the junos.commit function to commit the configuration, you can review the details of the entire commit operation by including the detail=True argument. When you include this argument, the function returns detailed information about the commit process.

Commit Synchronize

When you use the junos.commit function to commit the configuration, you can synchronize and commit the configuration on both Routing Engines in a dual Routing Engine system by including the sync=True argument. For example:

When you include the sync=True argument, the device copies the candidate configuration stored on the local Routing Engine to the other Routing Engine, verifies the candidate’s syntactic correctness, and commits it on both Routing Engines. To force the commit synchronize operation to succeed even if there are open configuration sessions or uncommitted configuration changes on the other Routing Engine, use the force_sync=True argument. Including this argument causes the device to terminate any configuration sessions on the other Routing Engine before synchronizing and committing the configuration.

Commit Timeout

The default time for an RPC to time out is 30 seconds. Large configuration changes might exceed this value causing the operation to time out before the configuration can be uploaded and committed. To accommodate configuration changes that might require a commit time that is longer than the default timeout interval, include the dev_timeout=seconds argument, and set the timeout interval to an appropriate value. For example:

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 salt.modules.junos.rollback execution function and the salt.states.junos.rollback state function enable you to roll back the configuration to a previously committed configuration on a device running Junos OS. To roll back the configuration and commit it, execute the function, and set the id argument to the ID of the desired 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 the id keyword, it defaults to 0.

For example, the following command rolls the configuration back to the previously committed configuration and commits it:

To roll back the configuration and log the configuration differences in a file for later reference, include the diffs_file argument, and set it to the path of the file on the proxy minion server to which the differences are written.

The differences are saved to the specified file on the proxy minion server.