config

Manipulate the configuration of a Junos device

Synopsis

  • Manipulate the configuration of a Junos device. This module allows a combination of loading or rolling back, checking, diffing, retrieving, and committing the configuration of a Junos device. It performs the following steps in order:

  1. Open a candidate configuration database.

    • If the config_mode option has a value of exclusive, the default, take a lock on the candidate configuration database. If the lock fails the module fails and reports an error.

    • If the config_mode option has a value of private, open a private candidate configuration database. If opening the private configuration database fails the module fails and reports an error.

  2. Load configuration data into the candidate configuration database.

    • Configuration data may be loaded using the load or rollback options. If either of these options are specified, new configuration data is loaded. If neither option is specified, this step is skipped.

    • If the rollback option is specified, replace the candidate configuration with the previous configuration specified by the value of the rollback option.

    • If the load option is specified, load new configuration data.

    • The value of the load option defines the type of load which is performed.

    • The source of the new configuration data is one of the following:

      • src - A file path on the local Ansible control machine.

      • lines - A list of strings containing the configuration data.

      • template - A file path to a Jinja2 template on the local Ansible control machine. This template is rendered with the variables specified by the vars option. If the template option is specified, the vars option must also be specified.

      • url - A URL reachable from the target Junos device.

    • If the format option is specified, the configuration file being loaded is in the specified format, rather than the format determined from the file name.

  3. Check the validity of the candidate configuration database.

    • If the check option is true, the default, check the validity of the configuration by performing a “commit check” operation.

    • This option may be specified with diff false and commit false to confirm a previous “commit confirmed <min>” operation without actually performing an additional commit.

    • If the configuration check fails, further processing stops, the module fails, and an error is reported.

  4. Determine differences between the candidate and committed configuration databases.

    • If step 2 was not skipped, and the diff option is true, the default, perform a diff between the candidate and committed configuration databases.

    • If the diffs_file or dest_dir option is specified, save the generated configuration differences.

    • If the return_output option is true, the default, include the generated configuration difference in the diff and diff_lines keys of the module’s response.

  5. Retrieve the configuration database from the Junos device.

    • If the retrieve option is specified, retrieve the configuration database specified by the retrieve value from the target Junos device to the local Ansible control machine.

    • The format in which the configuration is retrieved is specified by the value of the format option.

    • The optional filter controls which portions of the configuration are retrieved.

    • If options are specified, they control the content of the configuration retrieved.

    • If the dest or dest_dir option is specified, save the retrieved configuration to a file on the local Ansible control machine.

    • If the return_output option is true, the default, include the retrieved configuration in the config, config_lines, and config_parsed keys of the module’s response.

  6. Commit the configuration changes.

    • If the commit option is true, the default, commit the configuration changes.

    • This option may be specified with diff false and check false to confirm a previous “commit confirmed <min>” operation.

    • If the comment option is specified, add the comment to the commit.

    • If the confirmed option is specified, perform a commit confirmed min operation where min is the value of the confirmed option.

    • If the check option is true and the check_commit_wait option is specified, wait check_commit_wait seconds before performing the commit.

  7. Close the candidate configuration database.

    • Close and discard the candidate configuration database.

    • If the config_mode option has a value of exclusive, the default, unlock the candidate configuration database.

Requirements

The following software packages must be installed on hosts that execute this module:

Module-specific Options

The following options may be specified for this module:

parameter type required default choices comments
check
bool no true (false if retrieve is set and load and rollback are not set)
  • yes
  • no
Perform a commit check operation.

aliases: check_commit, commit_check
check_commit_wait
int no none
The number of seconds to wait between check and commit operations.
This option is only valid if check is true and commit is true.
This option should not normally be needed. It works around an issue in some versions of Junos.
comment
str no none
Provide a comment to be used with the commit operation.
This option is only valid if the commit option is true.
commit
bool no true (false if retrieve is set and load and rollback are not set)
  • yes
  • no
Perform a commit operation.
commit_empty_changes
bool no False
  • yes
  • no
Perform a commit operation, even if there are no changes between the candidate configuration and the committed configuration.
config_mode
str no exclusive
  • exclusive
  • private
The mode used to access the candidate configuration database.

aliases: config_access, edit_mode, edit_access
confirmed
int no none
Provide a confirmed timeout, in minutes, to be used with the commit operation.
This option is only valid if the commit option is true.
The value of this option is the number of minutes to wait for another commit operation before automatically rolling back the configuration change performed by this task. In other words, this option causes the module to perform a commit confirmed min where min is the value of the confirmed option. This option DOES NOT confirm a previous commit confirmed min operation. To confirm a previous commit operation, invoke this module with the check or commit option set to true.

aliases: confirm
dest
path no none
The path to a file, on the local Ansible control machine, where the configuration will be saved if the retrieve option is specified.
The file must be writeable. If the file already exists, it is overwritten.
This option is only valid if the retrieve option is not none.
When tasks are executed against more than one target host, one process is forked for each target host. (Up to the maximum specified by the forks configuration. See forks for details.) This means that the value of this option must be unique per target host. This is usually accomplished by including {{ inventory_hostname }} in the dest value. It is the user's responsibility to ensure this value is unique per target host.
For this reason, this option is deprecated. It is maintained for backwards compatibility. Use the dest_dir option in new playbooks. The dest and dest_dir options are mutually exclusive.

aliases: destination
dest_dir
path no none
The path to a directory, on the Ansible control machine. This is the directory where the configuration will be saved if the retrieve option is specified. It is also the directory where the configuration diff will be specified if the diff option is true.
This option is only valid if the retrieve option is not none or the diff option is true.
The retrieved configuration will be saved to a file named {{ inventory_hostname }}.format_extension in the dest_dir directory. Where format_extension is conf for text format, xml for XML format, json for JSON format, and set for set format.
If the diff option is true, the configuration diff will be saved to a file named {{ inventory_hostname }}.diff in the dest_dir directory.
The destination file must be writeable. If the file already exists, it is overwritten. It is the users responsibility to ensure a unique dest_dir value is provided for each execution of this module within a playbook.
The dest_dir and dest options are mutually exclusive. The dest_dir option is recommended for all new playbooks.
The dest_dir and diff_file options are mutually exclusive. The dest_dir option is recommended for all new playbooks.

aliases: destination_dir, destdir, savedir, save_dir
diff
bool no true (false if retrieve is set and load and rollback are not set)
  • yes
  • no
Perform a configuration compare (aka diff) operation.

aliases: compare, diffs
diffs_file
path no None
The path to a file, on the Ansible control machine, where the configuration differences will be saved if the diff option is specified.
The file must be writeable. If the file already exists, it is overwritten.
This option is only valid if the diff option is true.
When tasks are executed against more than one target host, one process is forked for each target host. (Up to the maximum specified by the forks configuration. See forks for details.) This means that the value of this option must be unique per target host. This is usually accomplished by including {{ inventory_hostname }} in the diffs_file value. It is the user's responsibility to ensure this value is unique per target host.
For this reason, this option is deprecated. It is maintained for backwards compatibility. Use the dest_dir option in new playbooks.
The diffs_file and dest_dir options are mutually exclusive.
filter
str no none
A string of XML, or '/'-separated configuration hierarchies, which specifies a filter used to restrict the portions of the configuration which are retrieved. See PyEZ's get_config method documentation for details on the value of this option.

aliases: filter_xml
format
str no none (auto-detect on load, text on retrieve)
  • xml
  • set
  • text
  • json
Specifies the format of the configuration retrieved, if retrieve is not none.
Specifies the format of the configuration to be loaded, if load is not none.
The specified format must be supported by the target Junos device.
ignore_warning
bool, str, or list of str no none
A boolean, string or list of strings. If the value is true, ignore all warnings regardless of the warning message. If the value is a string, it will ignore warning(s) if the message of each warning matches the string. If the value is a list of strings, ignore warning(s) if the message of each warning matches at least one of the strings in the list. The value of the ignore_warning option is applied to the load and commit operations performed by this module.
lines
list no none
Used with the load option. Specifies a list of list of configuration strings containing the configuration to be loaded.
The src, lines, template, and url options are mutually exclusive.
By default, the format of the configuration data is auto-dectected by the content of the first line in the lines list.
If the format option is specified, the format value overrides the format auto-detection.
load
str no none
  • none
  • set
  • merge
  • update
  • replace
  • override
  • overwrite
Specifies the type of load operation to be performed.
The load and rollback options are mutually exclusive.
The choices have the following meanings:
none - Do not perform a load operation.
merge - Combine the new configuration with the existing configuration. If statements in the new configuration conflict with statements in the existing configuration, the statements in the new configuration replace those in the existing configuration.
replace - This option is a superset of the merge option. It combines the new configuration with the existing configuration. If the new configuration is in text format and a hierarchy level in the new configuartion is prefixed with the string replace:, then the hierarchy level in the new configuration replaces the entire corresponding hierarchy level in the existing configuration, regardles of the existence or content of that hierarchy level in the existing configuration. If the configuration is in XML format, the XML attribute replace = "replace" is equivalent to the text format's replace: prefix. If a configuration hierarchy in the new configuration is not prefixed with replace:, then the merge behavior is used. Specifically, for any statements in the new configuration which conflict with statements in the existing configuration, the statements in the new configuration replace those in the existing configuration.
override - Discard the entire existing configuration and replace it with the new configuration. When the configuration is later committed, all system processes are notified and the entire new configuration is marked as 'changed' even if some statements previously existed in the configuration. The value overwrite is a synonym for override.
update - This option is similar to the override option. The new configuration completely replaces the existing configuration. The difference comes when the configuration is later committed. This option performs a 'diff' between the new candidate configuration and the existing committed configuration. It then only notifies system processes repsonsible for the changed portions of the configuration, and only marks the actual configuration changes as 'changed'.
set - This option is used when the new configuration data is in set format (a series of configuration mode commands). The new configuration data is loaded line by line and may contain any configuration mode commands, such as set, delete, edit, or deactivate. This value must be specified if the new configuration is in set format.
options
dict no None
Additional options, specified as a dictionary of key/value pairs, used when retrieving the configuration. See the <get-configuration> RPC documentation for information on available options.
retrieve
str no none
  • none
  • candidate
  • committed
The configuration database to be retrieved.
return_output
bool no True
  • yes
  • no
Indicates if the output of the diff and retreive options should be returned in the module's response. You might want to set this option to false, and set the dest_dir option, if the configuration or diff output is very large and you only need to save the output rather than using it's content in subsequent tasks/plays of your playbook.
rollback
int or str no none
  • 0-49
  • rescue
Populate the candidate configuration from a previously committed configuration. This value can be a configuration number between 0 and 49, or the keyword rescue to load the previously saved rescue configuration.
By default, some Junos platforms store fewer than 50 previous configurations. Specifying a value greater than the number of previous configurations available, or specifying rescue when no rescue configuration has been saved, will result in an error when the module attempts to perform the rollback.
The rollback and load options are mutually exclusive.
src
path no none
Used with the load option. Specifies the path to a file, on the local Ansible control machine, containing the configuration to be loaded.
The src, lines, template, and url options are mutually exclusive.
By default, the format of the configuration data is determined by the file extension of this path name. If the file has a .conf extension, the content is treated as text format. If the file has a .xml extension, the content is treated as XML format. If the file has a .set extension, the content is treated as Junos set commands.
If the format option is specified, the format value overrides the file-extension based format detection.

aliases: source, file
template
path no none
The path to a Jinja2 template file, on the local Ansible control machine. This template file, along with the vars option, is used to generate the configuration to be loaded on the target Junos device.
The src, lines, template, and url options are mutually exclusive.
The template and vars options are required together. If one is specified, the other must be specified.

aliases: template_path
url
str no none
A URL which specifies the configuration data to load on the target Junos device.
The Junos device uses this URL to load the configuration, therefore this URL must be reachable by the target Junos device.
The possible formats of this value are documented in the 'url' section of the <load-configuration> RPC documentation.
The src, lines, template, and url options are mutually exclusive.
vars
dict no none
A dictionary of keys and values used to render the Jinja2 template specified by the template option.
The template and vars options are required together. If one is specified, the other must be specified.

aliases: template_vars

Examples

---
- name: 'Explicit host argument'
  hosts: junos
  connection: local
  gather_facts: no
  collections:
    - juniper.device

  tasks:
    - name: Retrieve the committed configuration
      config:
        retrieve: 'committed'
        diff: false
        check: false
        commit: false
      register: response

    - name: Print the lines in the config.
      debug:
        var: response.config_lines

    - name: Append .foo to the hostname using private config mode.
      config:
        config_mode: 'private'
        load: 'merge'
        lines:
          - "set system host-name {{ inventory_hostname }}.foo"
      register: response

    - name: Print the config changes.
      debug:
        var: response.diff_lines

    - name: Rollback to the previous config.
      config:
        config_mode: 'private'
        rollback: 1
      register: response

    - name: Print the config changes.
      debug:
        var: response.diff_lines

    - name: Rollback to the rescue config.
      config:
        rollback: 'rescue'
      register: response
    - name: Print the complete response.
      debug:
        var: response

    - name: Load override from a file.
      config:
        load: 'override'
        src: "{{ inventory_hostname }}.conf"
      register: response

    - name: Print the complete response.
      debug:
        var: response

    - name: Load from a Jinja2 template.
      config:
        load: 'merge'
        format: 'xml'
        template: "{{ inventory_hostname }}.j2"
        vars:
          host: "{{ inventory_hostname }}"
      register: response
    - name: Print the complete response.
      debug:
        var: response

    - name: Load from a file on the Junos device.
      config:
        load: 'merge'
        url: "{{ inventory_hostname }}.conf"
      register: response
    - name: Print the complete response.
      debug:
        var: response

    - name: Load from a file on the Junos device, skip the commit check
      config:
        load: 'merge'
        url: "{{ inventory_hostname }}.conf"
        check: false
      register: response
    - name: Print the msg.
      debug:
        var: response.msg

    - name: Print diff between current and rollback 10. No check. No commit.
      config:
        rollback: 11
        diff: true
        check: false
        commit: false
      register: response

    - name: Print the msg.
      debug:
        var: response

    - name: Retrieve [edit system services] of current committed config.
      config:
        retrieve: 'committed'
        filter: 'system/services'
        diff: true
        check: false
        commit: false
      register: response

    - name: Print the resulting config lines.
      debug:
        var: response.config_lines

    - name: Enable NETCONF SSH and traceoptions, save config, and diffs.
      config:
        load: 'merge'
        lines:
          - 'set system services netconf ssh'
          - 'set system services netconf traceoptions flag all'
          - 'set system services netconf traceoptions file netconf.log'
        format: 'set'
        retrieve: 'candidate'
        filter: 'system/services'
        comment: 'Enable NETCONF with traceoptions'
        dest_dir: './output'
      register: response

    - name: Print the complete response
      debug:
        var: response

    - name: Load conf. Confirm within 5 min. Wait 3 secs between chk and commit
      config:
        load: 'merge'
        url: "{{ inventory_hostname }}.conf"
        confirm: 5
        check_commit_wait: 3
      register: response

    - name: Print the complete response
      debug:
        var: response

    - name: Confirm the previous commit with a commit check (but no commit)
      config:
        check: true
        diff: false
        commit: false
      register: response

    - name: Print the complete response
      debug:
        var: response

    - name: fetch config from the device with filter and login credentials
      config:
        host: "10.x.x.x"
        user: "user"
        passwd: "user123"
        port: "22"
        retrieve: 'committed'
        format: xml
        commit: no
        check: no
        diff: no
        dest_dir: "/tmp/"
        filter: <configuration><groups><name>re0</name></groups></configuration>
        return_output: True
      register: config_output

Return Values

name description returned type sample
changed
Indicates if the device's configuration has changed, or would have changed when in check mode.
success bool
config
The retrieved configuration. The value is a single multi-line string in the format specified by the format option.
when retrieved is not none and return_output is true. str
config_lines
The retrieved configuration. The value is a list of single-line strings in the format specified by the format option.
when retrieved is not none and return_output is true. list
config_parsed
The retrieved configuration parsed into a JSON datastructure. For XML replies, the response is parsed into JSON using the jxmlease library. For JSON the response is parsed using the Python json library.
When Ansible converts the jxmlease or native Python data structure into JSON, it does not guarantee that the order of dictionary/object keys are maintained.
when retrieved is not none, the format option is xml or json and return_output is true. dict
diff
The configuration differences between the previous and new configurations. The value is a dict that contains a single key named "prepared". Value associated with that key is a single multi-line string in "diff" format.
when load or rollback is specified, diff is true, and return_output is true. dict
diff_lines
The configuration differences between the previous and new configurations. The value is a list of single-line strings in "diff" format.
when load or rollback is specified, diff is true, and return_output is true. list
failed
Indicates if the task failed.
always bool
file
The value of the src option.
when load is not none and src is not none str
msg
A human-readable message indicating the result.
always str


Notes

Note

  • The NETCONF system service must be enabled on the target Junos device.

Author

  • Juniper Networks - Stacy Smith (@stacywsmith)

Status

This module is flagged as stableinterface which means that the maintainers for this module guarantee that no backward incompatible interface changes will be made.