Use the juniper.device.config Ansible Module to Manage the Junos OS Configuration

The juniper.device.config module enables you to perform the following operations on Junos devices:

• Load configuration data

• Commit the configuration

• Roll back the configuration

• Load the rescue configuration

The basic process for making configuration changes is to lock the configuration, load the configuration changes, commit the configuration to make it active, and then unlock the configuration. The user account that is used to make configuration changes must have permissions to change the relevant portions of the configuration on each device. To modify the configuration, the module’s argument list must include one of the following parameters:

• load—Load new configuration data.

• rollback—Revert to the rescue configuration or a previously committed configuration.

By default, the juniper.device.config module makes changes to the candidate configuration database using configure exclusive mode, which automatically locks and unlocks the candidate global configuration. You can also specify a different configuration mode. For example, you can make changes to a private copy of the candidate configuration or to the ephemeral configuration database. For more information about specifying the configuration mode, see How to Specify the Configuration Mode.

When loading new configuration data, in addition to specifying the configuration mode, you can also specify the load operation and the source and format of the changes.

• Load operation—The load operation determines how the configuration data is loaded into the selected configuration database. You can select from many of the same load operations that are available in the Junos OS CLI. For more information, see How to Specify the Load Action.

• Format—You can configure Junos devices using one of the standard, supported formats. You can provide configuration data or Jinja2 templates as text, Junos XML elements, Junos OS set commands, or JSON. For information about specifying the format of the configuration data, see How to Specify the Format of the Configuration Data to Load.

• Configuration data source—You can load configuration data from a list of strings, a file on the local Ansible control node, a Jinja2 template, or a URL reachable from the client device. For more information about specifying the source of the configuration data, see the following sections:

  • How to Load Configuration Data as Strings

  • How to Load Configuration Data from a Local or Remote File

  • How to Load Configuration Data Using a Jinja2 Template

The juniper.device.config module also enables you to load and commit the rescue configuration or roll the configuration back to a previously committed configuration. To load the rescue configuration or a previously committed configuration, you must include the rollback module argument. For more information, see the following sections:

• How to Load the Rescue Configuration

• How to Roll Back the Configuration

After modifying the configuration, you must commit the configuration to make it the active configuration on the device. By default, the juniper.device.config module commits the changes to the configuration. To alter this behavior or supply additional commit options, see How to Commit the Configuration.

By default, when the juniper.device.config module includes the load or rollback arguments, the module's response automatically returns the configuration changes in diff or patch format. The module returns the differences in the diff and diff_lines fields. To prevent the module from calculating and returning the differences, set the diff module argument to false.

You can specify the configuration mode to use when modifying the device configuration. To specify the configuration mode in your task, include the module's config_mode parameter. Supported configuration modes include:

• batch

• dynamic

• ephemeral

• exclusive

• private

By default, the juniper.device.config module makes changes to the candidate configuration database using configure exclusive mode. Configure exclusive mode locks the candidate global configuration (also known as the shared configuration database) for as long as the module requires to make the requested configuration changes. Locking the database prevents other users from modifying or committing changes to the database at the same time.

The following examples show how to configure a private copy of the candidate configuration and how to configure the ephemeral database.

• Example: config_mode: "private"
• Configure the Ephemeral Database

The juniper.device.config module supports loading configuration changes using many of the same load operations supported in the Junos OS CLI. You specify the load operation by setting the module's load argument to the value of the corresponding load operation. Table 2 summarizes the argument values for the different load operations.

Table 2: Parameters for Specifying the Load Operation

Load Operation	load Argument	Description
load merge	load: merge	Merge the loaded configuration with the existing configuration.
load override	load: override	Replace the entire configuration with the loaded configuration. All system processes parse the configuration.
load patch	load: patch	Load configuration data from a patch file.
load replace	load: replace	Merge the loaded configuration with the existing configuration, but replace statements in the existing configuration with statements in the loaded configuration that specify the replace: tag. If the statement is not in the existing configuration, the statement in the loaded configuration is added.
load set	load: set	Load configuration data that is in set format. The configuration data is loaded line by line and can contain configuration mode commands such as set, delete, and deactivate.
load update	load: update	Load a complete configuration and compare it against the existing configuration. Replace only those parts of the candidate configuration that have changed. During the commit operation, only affected system processes parse the new configuration.

The juniper.device.config module enables you to configure Junos devices using one of the standard supported formats. You can provide configuration data as strings or files. Files can contain either configuration data or Jinja2 templates. When providing configuration data within a string, file, or Jinja2 template, supported formats for the data include text, Junos XML elements, Junos OS set commands, and JSON.

The juniper.device.config module attempts to auto-detect the format of configuration data that you supply as strings within the lines argument. However, you can explicitly specify the format for strings by including the format argument. When you provide configuration data in a file or Jinja2 template, you must specify the format of the data. Add the appropriate extension to the file or include the format argument.

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 both the auto-detect format for strings and the format indicated by a file extension.

Table 3: Specifying the Format for Configuration Data

Configuration Data Format	File Extension	format Parameter
CLI configuration statements (text)	.conf	text
JavaScript Object Notation (JSON)	.json	json
Junos OS set commands	.set	set
Junos XML elements	.xml	xml

Note:

When you set the module’s load argument to override or update, you cannot use the Junos OS set command format.

The juniper.device.config module enables you to load configuration data from a list of strings. To load configuration data as strings, include the appropriate load argument and the lines argument. The lines argument takes a list of strings containing the configuration data to load.

The module attempts to auto-detect the format of the lines configuration data. However, you can explicitly specify the format by including the format argument. For information about specifying the format, see How to Specify the Format of the Configuration Data to Load. If you include the format argument, it overrides the auto-detected format.

The following playbook configures and commits two op scripts. In this case, the load argument has the value 'set' because the configuration data in lines uses Junos OS set statement format.

The following playbook configures the same statements using lines with configuration data in text format. In this case, the example uses load: "merge".

The juniper.device.config module enables you to load configuration data from a file. The file can reside in one of the following locations:

• Ansible control node

• Client device

• FTP or HTTP URL that is reachable from the client device

When you load configuration data from a file, you must indicate the location of the file and the format of the configuration data in the file. Supported configuration data formats include text, Junos XML elements, Junos OS set commands, and JSON. For information about loading files containing Jinja2 templates, see How to Load Configuration Data Using a Jinja2 Template.

To specify the format, include the module's format parameter or add the appropriate extension to the configuration data file. If you specify the format parameter, it overrides the format indicated by the file extension. For information about specifying the format, see How to Specify the Format of the Configuration Data to Load. When the configuration data uses Junos XML format, you must enclose the data in the top-level <configuration> tag.

Note:

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

Table 4 outlines the module parameters that you can include to specify the location of the file.

Table 4: Specifying the Location of the Configuration File

Module Parameter	Description
src	Absolute or relative path to a file on the Ansible control node. The default directory is the playbook directory.
url	Absolute or relative path to a file on the client device. The default directory on the client device is the current working directory, which defaults to the user’s home directory. FTP URL HTTP URL

To load configuration data from a local file on the Ansible control node, set the src argument to the absolute or relative path of the file containing the configuration data. For example:

To load configuration data from a file on the Junos device or from an FTP or HTTP URL, use the url parameter. Specify the path or URL of the file to load. For example:

The value for url can be an absolute or relative local file path, an FTP location, or an HTTP URL.

• The file path for a local file on the target device has one of the following forms:

  • /path/filename—File on a mounted file system, either on the local flash disk or on hard disk.

  • a:filename or a:path/filename—File on the local drive. The default path is / (the root-level directory). The removable media can be in MS-DOS or UNIX (UFS) format.

• The file path for a file on an FTP server has the following form:

• The file path for a file on an HTTP server has the following form:

In each case, the default value for the path variable is the home directory for the user. To specify an absolute path, the application starts the path with the characters %2F; for example, ftp://username:password@hostname/%2Fpath/filename.

The juniper.device.config module enables you to render configuration data from a Jinja2 template file on the Ansible control node and load and commit the configuration on a Junos device. 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 Ansible module uses the Jinja2 template and a supplied dictionary of variables to render the configuration data.

To load and commit configuration data using a Jinja2 template, include the template and vars parameters in the module’s argument list.

• template—Path of the Jinja2 template file

• vars—Dictionary of keys and values that are required to render the Jinja2 template

You must also include the format parameter when the template’s file extension does not indicate the format of the data. For information about specifying the format, see How to Specify the Format of the Configuration Data to Load.

For example, the interfaces-mpls.j2 file contains the following Jinja2 template:

To use the juniper.device.config module to load the Jinja2 template, set the template argument to the path of the template file. Define the variables required by the template in the vars dictionary.

The following playbook uses the Jinja2 template and the vars dictionary to render the configuration data. The format parameter indicates the format of the configuration data in the template file. The playbook loads and commits the configuration on the target host.

The module generates the following configuration data. The module loads the data into the candidate configuration on the device and commits it.

A rescue configuration enables 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 the device 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 juniper.device.config module enables you to revert to an existing rescue configuration on Junos devices. To load and commit the rescue configuration on a device, include the module’s rollback: rescue argument. For example:

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 feature is useful when configuration changes cause undesirable results and you want to revert to a known working configuration. Rolling back the configuration is similar to the process for making configuration changes on the device. However, instead of loading configuration data, you perform a rollback, which replaces the entire candidate configuration with a previously committed configuration.

The juniper.device.config module enables you to roll back to a previously committed configuration on Junos devices. To roll back the configuration and commit it, include the module’s rollback argument, and specify 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).

The following playbook first prompts for the rollback ID of the configuration to restore. The first task rolls back the configuration to the requested version and commits it. The second task prints the configuration differences to standard output.

By default, when you use the juniper.device.config module to modify the configuration, the module automatically performs a commit check and commits the changes. To prevent the module from performing a commit check or from committing the changes, set the check or commit argument to false, respectively.

You can also customize the commit operation with many of the same options that are available in the Junos OS CLI. Table 5 outlines the module arguments that you can use to specify different commit options.

Table 5: Commit Options

Module Argument	Description	Default value for load and rollback operations
check: boolean	Perform a commit check or confirm a previous confirmed commit operation.	true
check_commit_wait: seconds	Wait the specified number of seconds between the commit check and the commit operation.	–
comment: "string"	Log a comment for that commit operation in the system log file and in the device’s commit history.	–
commit: boolean	Commit the configuration changes or confirm a previous confirmed commit operation.	true
commit_empty_changes: boolean	Commit the configuration even if the candidate configuration has no changes.	false
commit_force_sync: boolean	Synchronize and commit the configuration on all Routing Engines, even if the other Routing Engine has open configuration sessions or uncommitted configuration changes.	false
commit_sync: boolean	Synchronize and commit the configuration on all Routing Engines.	false
confirmed: minutes	Require that a commit operation be confirmed within a specified amount of time after the initial commit. If you do not confirm the commit in the specified time, roll back to the previously committed configuration. Confirm the commit using either the commit: true option or the check: true option.	–
timeout: seconds	Wait for completion of the operation using the specified value as the timeout.	30 seconds

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: "comment string" argument with the message string.

Commit Check

By default, the juniper.device.config module executes both a commit check and a commit operation. The check_commit_wait argument defines the number of seconds to wait between the commit check and commit operations. Include this argument when you need to provide sufficient time for the device to complete the commit check operation and release the configuration lock before initiating the commit operation. If the device initiates the commit operation before the commit check operation releases its lock on the configuration, the commit operation fails and the module issues a CommitError.

Commit Empty Changes

By default, if the candidate configuration and the committed configuration have no differences, the module does not commit the changes. To force a commit operation even when no differences are present, include the commit_empty_changes: true argument.

Commit Synchronize

If the device has dual Routing Engines, you can synchronize and commit the configuration on both Routing Engines by including the commit_sync: true argument. To force the commit synchronize operation to succeed even if the other Routing Engine has open configuration sessions or uncommitted configuration changes, use the commit_force_sync: true argument. When you include the commit_force_sync: true option, the device terminates any configuration sessions on the other Routing Engine before synchronizing and committing the configuration.

Commit Confirm

To require that a commit operation be confirmed within a specified amount of time after the initial commit, include the confirmed: minutes argument. If you do not confirm the commit within the given time limit, the configuration automatically rolls back to the previously committed configuration. The allowed range is 1 through 65,535 minutes. 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 enables access to the device after the rollback deadline passes. To confirm the commit operation, invoke the juniper.device.config module with the check: true or commit: true argument.

In the following playbook, the first task modifies the configuration, waits 10 seconds between the commit check and the commit operation, and requires that the commit operation be confirmed within 5 minutes. It also logs a comment for the commit. The second task issues a commit check operation to confirm the commit. In a real-world scenario, you might perform validation tasks after the initial commit and only execute the commit confirmation if the tasks pass certain validation criteria.

The juniper.device.config module enables you to modify and commit the configuration on Junos devices. In some cases, the RPC reply might contain <rpc-error> elements with a severity level of warning or higher that cause the module to raise an RpcError exception. An RpcError exception can cause the load or commit operation to fail.

In certain cases, it might be necessary or desirable to suppress the RpcError exceptions that are raised in response to warnings for load and commit operations. You can instruct the juniper.device.config module to suppress RpcError exceptions that are raised for warnings by including the ignore_warning parameter in the module’s argument list. The ignore_warning argument takes a Boolean, a string, or a list of strings.

To instruct the module to ignore all warnings for load and commit operations performed by the module, include the ignore_warning: true argument. The following example ignores all warnings for load and commit operations.

If you include ignore_warning: true and all of the <rpc-error> elements have a severity level of warning, the application ignores all warnings and does not raise an RpcError exception. However, any <rpc-error> elements with higher severity levels will still raise exceptions.

To instruct the module to ignore specific warnings, set the ignore_warning argument to a string or a list of strings containing the warnings to ignore. The following example ignores two specific warnings:

The module suppresses RpcError exceptions if all of the <rpc-error> elements have a severity level of warning and each warning in the response matches one or more of the specified strings.