Release 2.0.0

Summary

This release is a major rewrite of the modules in this Juniper.junos role. This release offers several new features and bug fixes over previous releases, yet it still maintains backwards compatibility with playbooks written to previous releases of the Juniper.junos role. The following sections highlight some of the changes in this release.

Important Installation Note

The ansible-galaxy install command does not support a smooth upgrade from previous releases to this release. Therefore, you must first remove any previous versions of the Juniper.junos role by executing:

sudo ansible-galaxy remove Juniper.junos

Once previous versions have been removed, the current version of the Juniper.junos role may be installed with:

sudo ansible-galaxy install Juniper.junos

New Features

Modules renamed and re-organized.

Ansible added core modules for managing Junos devices in Ansible release 2.1. Since that time, there's been a lot of confusion between the Ansible-provided and supported modules in Ansible core and the Juniper-provided and supported modules in this Juniper.junos role. Part of this confusion was due to the similar names (and functionality) between the two sets of modules. Module renaming helps distinguish between the two sets of modules by:

1. The new names for modules in this Juniper.junos role name all start with the prefix juniper_junos_ to indicate that the module is part of the Juniper.junos role, and that the module is written and supported by Juniper.
2. Removes the direct naming conflict which existed with the junos_rpc module.
3. Removes verbs such as get and install from the module names in order to better follow Ansible best practices.
4. Removes the cli misnomer from the junos_cli module by renaming it to juniper_junos_command. The new name better indicates the module uses the NETCONF <command> RPC to execute the equivalent of a CLI command.
5. Consolidates multiple modules which deal with the same component (such as the configuration or system) into a single module per component.

NOTE

If a playbook worked with a prior version of the Juniper.junos role, it should continue to work on the current version without requiring modifications to the playbook. However, these older module and argument names are no longer present in the current documentation. You may reference previous module and argument names by referring directly to the 1.4.3 version of the Juniper.junos role documentation.

The following table provides a mapping between new and old module names:

New Module Name	Old Module Name	New Arguments/Values Required to Mimic Old Module Behavior
juniper_junos_command	junos_cli
juniper_junos_config	junos_commit	commit=True, diff=False, check=False
juniper_junos_config	junos_get_config	retrieve="candidate"
juniper_junos_config	junos_install_config	load="merge|update|replace|override"
juniper_junos_config	junos_rollback	rollback=<value>
juniper_junos_facts	junos_get_facts
juniper_junos_jsnapy	junos_jsnapy
juniper_junos_ping	junos_ping
juniper_junos_pmtud	junos_pmtud
juniper_junos_rpc	junos_rpc
juniper_junos_software	junos_install_os
juniper_junos_srx_cluster	junos_srx_cluster
juniper_junos_system	junos_shutdown	action="shutdown" or action="off" or action="reboot"
juniper_junos_system	junos_zeroize	state="zeroize"
juniper_junos_table	junos_get_table

Enhanced Connection-related Module Arguments (common for all modules)

• The host argument now defaults to {{ inventory_hostname }}. This means the host argument is no longer required unless connecting to a Junos device through a console server.
• Aliases have been added for several connection arguments to support compatibility with the argument names used by the core Ansible modules for Junos. Specifically:
  • The host argument may now be alternatively specified using the hostname or ip argument aliases.
  • The user argument may now be alternatively specified using the username argument alias.
  • The passwd argument may now be alternatively specified using the password argument alias.
  • The ssh_private_key_file argument may now be alternatively specified using the ssh_keyfile argument alias.
• The algorithm for selecting the default value of the user, passwd, and ssh_private_key_file arguments has been enhanced. In many cases, this means these parameters no longer need to be specified in each task. See the module documentation for details on the default values for these arguments.
• The algorithm for selecting the default value of the user, passwd, and ssh_private_key_file arguments is compatible with Ansible Tower.
• All connection-related arguments may now be, optionally, specified as sub-arguments of a provider argument. This allows connection-related parameters to be specified in the same format used by the core Ansible modules for Junos.
• All modules support a common set of connection-related arguments using a common library of code. This ensures the connection-related arguments behave consistently across all modules in the Juniper.junos role.

Enhanced Logging (common for all modules)

• All modules in the Juniper.junos role support a common set of logging arguments.
• When the logdir or logfile option is specified, the following messages are logged:
  1. By default, messages at level WARNING or higher are logged.
  2. If the -v or --verbose command-line options to the ansible-playbook command are specified, messages at level INFO or higher are logged.
  3. If the -vv (or more verbose) command-line option to the ansible-playbook command is specified, or the ANSIBLE_DEBUG environment variable is set, then messages at level DEBUG or higher are logged.

juniper_junos_command Module

• The output of the command is available in the module's return value. It does not have to be saved to a file.
• For xml and json format types, the output of the command is available as both an unparsed string and a parsed data structure.
• Supports a list of commands to execute, rather than just a single command.

juniper_junos_config Module

• Any combination of loading or rolling back, checking, diffing, retrieving, and committing the configuration of a Junos device can now be performed in a single task.
• Configurations may be loaded from local filesystem of a Junos device or a remote URL using the url argument.
• Configurations may be loaded directly from a rendered Jinja2 template using the template and vars arguments.
• Configurations may be loaded directly from a list of strings using the lines argument.
• Configurations may be loaded using exclusive mode (the default) or private mode.
• The candidate or committed configurations can be retrieved from the device.
• The retrieved configuration is available in the module's return value.
• Ability to ignore warnings.

juniper_junos_facts Module

• Acts as an official fact plugin so that facts are registered under the junos hostvar.
• Supports optionally retrieving the committed configuration as a fact.

juniper_junos_rpc Module

• The output of the RPC is available in the module's return value. It does not have to be saved to a file.
• For xml and json format types, the output of the RPC is available as both an unparsed string and a parsed data structure.
• Supports a list of RPCs to execute, rather than just a single RPC.

juniper_junos_software Module

• Support ISSU / NSSU.
• Support timeouts for the various stages of the software install process.
• Support the ability to disable cleanfs.

juniper_junos_system Module

• Support a rollback rescue equivalent.
• When performing a rollback, return config diffs in the response data structure.

Maintainability

Verified functionality with Ansible releases 2.1 to 2.4

Console connectivity to Junos devices is now provided by PyEZ rather than the Netconify library

• This ensures that all modules support connecting to the Junos device via console.
• The Netconify library is no longer a required package.

Better error handling of missing required libraries or unmet minimum versions.

Bugs Fixed

junos_shutdown - XMLSyntaxError' object has no attribute 'rsp #243

get_table - rpc timeout #242

'junos_install_os' fails without 'logfile' parameter #246

junos_install_os with NSSU get exceptions #244

junos_install_os fails to execute on a SRX320 #227

###"Uncaught exception - please report: Type 'str' cannot be serialized." #137

Release 1.4.3

Summary

This is primarily a maintenance release to provide compatibility with the latest Ansible 2.4.0 release.

New Features

Add the force_host argument to junos_install_os. #233/#234

• By default, the Host Software package on QFX-series platforms is not
  upgraded by the <request-package-add> RPC. Adding the <force-host/>
  argument to the RPC forces the Host Software package to also be upgraded.
  This PR adds the ability to pass the force_host argument to the
  junos_install_os module. This optional boolean argument defaults
  to False. When set to True, it passes the <force-host/> argument to
  the underlying <request-package-add> RPC.

Add new re_name and master_state facts to junos_get_facts. #239

• These new facts are based on the dev.re_name and dev.master
  PyEZ device properties.

ignore_warning support for junos_install_config. #248

• The new ignore_warning parameter can be used to ignore warnings generated
  when loading a configuration with junos_install_config
  • If ignore_warning=True then ALL warnings are ignored
  • If ignore_warning=<string_val> then all warnings matching <string_val> are ignored.
  • If ignore_warning=<list_of_string_vals> then all warnings matching any of the
    <string_vals> in the list are ignored.

Add do_not_fragment argument to junos_ping. #262

Add new junos_pmtud module. #263

check_commit option added added to junos_commit. #163

Add a parameter to only do a commit check. #109

Maintainability

Verified functionality with Ansible 2.4.0

Add text for ansible-galaxy installation from GitHub. #204

Bugs Fixed

junos_install_os used to fail without 'logfile' parameter. #247

version finding regex in case version is not provided. #249

Fix do_not_fragment argument to junos_ping module. #264

Test fixes for junos_pmtud fixes. #265

Fix junos_commit commit_check argument. #266

Fix doc string in junos_install_config and documentation generation on Ansible 2.4. #267

Release 1.4.2

Summary

This is primarily a maintenance release to provide compatibility with the latest Ansible 2.3.0 release.

New Features

Non-default SSH private key files with the ssh_private_key_file argument

• Priv ssh key #205
  Example:

   - name: gather facts
     junos_get_facts:
       host={{ inventory_hostname }}
       user='xxxx'
       passwd='Test123'
       ssh_private_key_file='/Users/nitinkr/.ssh/id_rsa_vmx'
     register: junos

   - name: Verify JUNOS version
     debug: msg="{{junos.facts.version}}"

where passwd='Test123' is the passphrase for the ssh private key file. (If passwd is ommitted, the key is tried with an empty passphrase.)

Support the update argument for configuration loading with junos_install_config

• "update" action for config load #218
  This feature is equivalent to a load update from the Junos CLI. When the update=True argument is specified for junos_install_config, the complete loaded configuration is compared against the candidate configuration. For each hierarchy level or configuration object that is different in the two configurations, the version in the loaded configuration replaces the version in the candidate configuration. When the configuration is later committed, only system processes that are affected by the changed configuration elements parse the new configuration. This action is supported from PyEZ 2.1.0.
  Example:

    - name: Install the config using load update
      junos_install_config:
        host: "{{ inventory_hostname }}"
        user: "{{ username }}"
        passwd: "{{ password }}"
        file: "{{ inventory_hostname }}.conf"
        diffs_file: "{{ inventory_hostname }}.diff"

ISSU/NSSU support for junos_install_os

• ISSU/NSSU support #219
  Support the ability to perform a unified in-service software upgrade from the junos_install_os module by adding the issu argument. For Juniper Networks EX Series devices which support the nonstop software upgrade feature, the nssu argument is added.
  Example:

    - name: Perform an ISSU of Junos
      junos_install_os:
        host: "{{ inventory_hostname }}"
        user: "{{ username }}"
        passwd: "{{ password }}"
        issu: True
        version: "16.1R4.7"
        package: "junos-install-mx-x86-64-16.1R4.7.tgz"

Maintainability

• Add Unitest for Ansible modules using Virtual Devices in the Cloud #187

Bugs Fixed

• junos_jsnapy: snap_pre was broken & snapcheck was expecting testfiles full path #171/#172
• setup.py: Fix missing interpreter: (on Rhel7) #176
• junos_jsnapy: Add Jsnapy library to Dockerfile for junos_jsnapy #184
• junos_jsnapy: Add more checks to callback_plugin to make sure info returned by modules is valid #186
• README.md: Update README.md #188
• Don't log password #183
• junos_cli: Add test before writing output to dest #193
• junos_rpc: To support kwargs as dict into junos_rpc #196
• junos_jsnapy: Clean up the inline documentation #197
• junos_cli: Fix for > global name 'dest' is not defined #198
• junos_get_facts: Modify junos_get_facts to be compatible with Juniper/py-junos-eznc#638. #210
• junos_get_config: options type defined for Ansible >=2.1 #211
• JSON dump of Junos facts requires native Python data types. #223/#224
• All: Compatibility with Ansible 2.3. Allow modules to import cleanly #215
• All: Fix docs for Ansible 2.3 #230

Release 1.4.0

New Features

Dockerfile for junos ansible modules

• New Dockerfile added to automatically build a docker container for junos ansible modules #165

Console connection support

• Modules to work with console connections too using PyEZ 2.0 #162. For example

  - name: Get configs
    junos_get_config:
      user: "{{ USERNAME }}"
      passwd: "{{ PASSWORD }}"
      port: 7011
      mode: "telnet"
      format: xml

junos_jsnapy

• Integrate JSNAPy to ansible which helps audit network devices

   - name: Test based on a test_file directly
     junos_jsnapy:
       host: "{{ junos_host }}"
       user: "{{ ansible_ssh_user }}"
       passwd: "{{ ansible_ssh_pass }}"
       test_files: tests/test_junos_interface.yaml
       action: snapcheck
     register: test1
   - name: Check JSNAPy tests results
     assert:
     that:
       - "test1.passPercentage == 100"

junos_ping

• Execute ping on junos devices

- name: "Execute ping peer"
      junos_ping:
        host={{ junos_host }}
        user={{ ansible_ssh_user }}
        passwd={{ ansible_ssh_pass }}
        dest_ip=8.8.8.8

junos_get_table

• Retrieve data from a Junos device using Tables/Views.

- name: "Get neighbour info using std lldp table"
      junos_get_table:
        host={{ junos_host }}
        user={{ ansible_ssh_user }}
        passwd={{ ansible_ssh_pass }}
        table=LLDPNeighborTable
        file=lldp.yml

Updates/Enhancement

• ImportError to show proper message #158. For example

$ ansible-playbook facts_gather.yml 

PLAY ***************************************************************************

TASK [gather facts] ************************************************************
fatal: [x.x.x.x]: FAILED! => {"changed": false, "failed": true, "msg": "ImportError: No module named lxml"}

• junos_shutdown to support delayed reboot and shutdown #150
• junos_install_config->check_commit_wait: Set number of seconds to wait between check and commit. #140
• Timeout option for junos_cli and junos_rpc #133
• timeout parameter to junos_rollback #131

Bugs Fixed

• junos_rpc: Fix regex to match xe/ge/et interfaces #153
• junos_get_table: Fix for nested tables #127
• junos_get_config: Fix for filter argument contains more than one level of configuration hierarchy #121
• Fix for Ansible 2.0 & 2.1 #119

Release 1.3.1

Bug Fix

junos_rpc was not working with anisble 2.0.1.0 #114

For junos >=14.2 json config can be register to rpc_reply

- name: Get Device Configuration
  hosts: all
  roles:
    - Juniper.junos
  connection: local
  gather_facts: no
  tasks:
    - name: Get interface information
      junos_rpc:
        host={{ inventory_hostname }}
        rpc=get-interface-information
        kwargs={interface_name:em0,media:True}
        format=json
        dest=get_interface_information.conf
      register: junos

    - name: Print configuration
      debug: msg="{{ junos.rpc_reply }}"

Release 1.3.0

New Features

Added junos_rpc

• To execute RPC on device and save output locally.

  Example

  - junos_rpc: 
  host={{ inventory_hostname }}
  rpc=get-interface-information
  dest=get_interface_information.conf
  
  - junos_rpc: 
  host={{ inventory_hostname }}
  rpc=get-interface-information
  kwargs="interface_name=em0"
  format=text
  dest=get_interface_information.conf

Added junos_cli

• To execute CLI on device and save output locally

  Example

  - junos_cli:
  host: "{{ inventory_hostname }}"
  cli: "show chassis hardware"
  logfile: cli.log
  dest: "{{ inventory_hostname }}.xml"
  format: xml

Updates/Enhancement

junos_get_config diff option #100

• junos_get_config now supports check_mode (as opposed to claiming that it did, but overwriting the dest file anyway).
  Properly reports 'changed' attribute for junos_get_config module.

  Fixed the requirement status for the dest argument in junos_get_config (docs claimed True, but set to False when module was called).

  If --diff on cmdline*, return diff diff with results.
  In junos_get_config, sets before and after attributes and lets Ansible do the diff.
  In junos_install_config, sets prepared with the output of commit check.

Add a timeout argument to the junos_commit module #97

• Add a timeout argument to the junos_commit module to support confirming a commit on a device which is slow and/or has a large config.

Bugs Fixed

Ansible 2.0 support #103

• junos_get_facts module was returning a junos.version_info object
  which caused this new feature to raise a TypeError.

Exception handling #101

• Fix exception handling line in junos_install_config

Proper log message for junos_srx_cluster #98

• Fixing log message and setting results variable when enabling cluster

shebang path changed, modules to work in virtualenv environment too #93 #77

• Update all the shebangs in library/ to use /usr/bin/env python instead of hardcoding to /usr/bin/python.

Release 1.2.0

New Features

Added junos_srx_cluster

• SRX devices can be joined or removed from a cluster

  Example

  -junos_srx_cluster:
  host={{ inventory_hostname }}
  console="--port={{ serial }}"
  cluster_enable=true
  logfile=cluster.log
  cluster_id={{ cluster_id }}
  node={{ node_id }}
  
  -junos_srx_cluster:
  host={{ inventory_hostname }}
  cluster_enable=false
  logfile=cluster.log

Added junos_get_config

• Configuration can be retrieved from a device and stored as a file. Supports text (default) and XML format. Configuration filter and options supported.

  Example

  - junos_get_config:
  host: "{{ inventory_hostname }}"
  logfile: get_config.log
  dest: "{{ inventory_hostname }}.xml"
  format: xml
  filter: "interfaces"
  options: {inherit: inherit, groups: groups}

Added junos_rollback

• Configuration will be rolled back and committed to Rollback Id provided. Module supports commit comments and confirm.

  Example

  - junos_rollback:
  host: "{{ inventory_hostname }}"
  logfile=rollback.log
  diffs_file=rollback.diff
  rollback=1
  comment="Rolled back by Ansible"
  confirm=5

Added junos_commit

• Execute a commit independently of loading a configuration.

  Example

  - junos_commit:
  host: "{{ inventory_hostname }}"
  logfile=changes.log
  comment="Non load commit"

Updated junos_install_config

• Now supports Load Replace

• Now supports Commit Confirmed

  Example

  - junos_install_config:
  host={{ inventory_hostname }}
  file=snmp.conf
  replace=yes
  confirm=5

Bugs Fixed

junos_install_config

• Underlying PyEZ exceptions were not being properly captured and logged. #56
• Warnings (RpcError) were not triggering rollback. Warning will now prevent a configuration from loading. (Per PyEZ functionality). #58

2015-07-29 17:12:48,505:CONFIG:pabst.englab.juniper.net:pushing file: /home/rsherman/workspace/warning.set
2015-07-29 17:12:48,505:CONFIG:pabst.englab.juniper.net:taking lock
2015-07-29 17:12:48,828:CONFIG:pabst.englab.juniper.net:loading config
2015-07-29 17:12:49,980:CONFIG:pabst.englab.juniper.net:doing a commit-check, please be patient
2015-07-29 17:12:51,467:CONFIG:pabst.englab.juniper.net:Unable to commit configuration: CommitError(edit_path: [edit security policies from-zone corp to-zone], bad_element: corp, message: mgd: Security zone must be defined)

Release 1.1.0

New Features

Add Ability to specify NETCONF Port

• User can specify port other than default 830

  Example

  junos_install_config:
    host={{ inventory_hostname }}
    user=user
    passwd=pass
    port=22
    file=load.conf

Commit comment junos_install_config

• Add ability to specify a comment with config commit

  Example

  - junos_install_config:
    host={{ inventory_hostname }}
    file=banner.conf
    comment="configured by ansible"

Check mode added to junos_install_config and junos_get_facts

• Allows use of --check when executing ansible-playbook
  • junos_get_facts will return facts as normal
  • junos_install_config will load config, commit check and automatically rollback on exit.

Write configuration diff to file junos_install_config

• Allows user to specify a file to write configuration diff to

  Example

  junos_install_config:
    host={{ inventory_hostname }}
    file=load.conf
    diffs_file=diff.log

Bugs Fixed

Rename facts 2RE to has_2RE

• Per Ansible convention all variables should start with a letter.

Console mode logging

• Underlying netconify errors were not captured

junos_install_config Exception Handling

• Capture and log PyEZ ConfigLoadError and CommitError

  2015-01-15 13:13:33,861:CONFIG:device:connecting to host: regress@device:22
  2015-01-15 13:13:40,657:CONFIG:device:pushing file: /home/rsherman/workspace/bad-script.conf
  2015-01-15 13:13:40,657:CONFIG:device:taking lock
  2015-01-15 13:13:40,878:CONFIG:device:loading config
  2015-01-15 13:13:41,101:CONFIG:device:unable to load config:error,op1,syntax error
  2015-01-15 13:13:41,101:CONFIG:device:Unable to make changes
  

Release 1.0.0

Production Release 1.0.0

Release Notes

Early Adopter Release 0.4.0

Bugfix:
Updates for junos_install_config to do merge by default via Netconf
Introduced version 1.6