juniper_junos_software

Install software on a Junos device

Synopsis

  • Install a Junos OS image, or other software package, on a Junos device. This action is generally equivalent to the request system software add operational-mode CLI command. It performs the following steps in order:
  1. Compare the currently installed Junos version to the desired version specified by the version option.
    • If the current and desired versions are the same, stop and return changed with a value of false.
    • If running in check mode, and the current and desired versions differ, stop and return changed with a value of true.
    • Otherwise, proceed.
  2. If the local_package option is specified, compute the MD5 checksum of the local_package file on the local Ansible control machine.
  3. Check if the file exists at the remote_package location on the target Junos device. If so, compute the MD5 checksum of the file on the target Junos device.
  4. If the cleanfs option is true, the default, then perform the equivalent of the request system storage cleanup CLI command.
  5. If the checksums computed in steps 2 and 3 differ, or if the remote_package file does not exist on the target Junos device, then copy the package from local_package on the local Ansible control machine to remote_package on the target Junos device.
  6. Install the software pacakge from the remote_package location on the target Junos device using the options specified.
  7. If the reboot option is true, the default, initiate a reboot of the target Junos device.

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
all_re
bool no True
  • yes
  • no
Whether or not to install the software on all Routing Engines of the target Junos device. If true, and the device has multiple Routing Engines, the software is installed on all Routing Engines. If false, the software is only installed on the current Routing Engine.
checksum
str no none
The pre-calculated checksum, using the checksum_algorithm of the file specified by the local_package option. Specifying this option is simply an optimization to avoid repeatedly computing the checksum of the local_package file once for each target Junos host.
checksum_algorithm
str no md5
The algorithm to use when calculating the checksum of the local and remote software packages.
checksum_timeout
int no 300 (5 minutes)
The number of seconds to wait for the calculation of the checksum to complete on the target Junos device.
cleanfs
bool no true (unless no_copy is true, then false)
  • yes
  • no
Whether or not to perform a request system storage cleanup prior to copying or installing the software.
cleanfs_timeout
int no 300 (5 minutes)
The number of seconds to wait for the request system storage cleanup to complete on the target Junos device.
force_host
bool no False
  • yes
  • no
Forces the upgrade of the Host Software package on QFX-series devices.
install_timeout
int no 1800 (30 minutes)
The number of seconds to wait for the software installation to complete on the target Junos device.
issu
bool no False
  • yes
  • no
Indicates if a unified in-service software upgrade (ISSU) should be attempted. ISSU enables the upgrade between two different Junos OS releases with no control plane disruption and minimal data plane traffic disruption.
In order for an ISSU to succeed, ISSU must be supported. This includes support for the current to desired Junos versions, the hardware of the target Junos device, and the current software configuration of the target Junos device.
The issu and nssu options are mutually exclusive.
kwargs
dict no none
Additional keyword arguments and values which are passed to the <request-package-add> RPC used to install the software package. The value of this option is a dictionary of keywords and values.

aliases: kwarg, args, arg
local_package
path no none
The path, on the local Ansible control machine, of a Junos software package. This Junos software package will be installed on the target Junos device.
If this option is specified, and a file with the same MD5 checksum doesn't already exist at the remote_package location on the target Junos device, then the file is copied from the local Ansible control machine to the target Junos device.
If this option is not specified, it is assumed that the software package already exists on the target Junos device. In this case, the remote_package option must be specified.

aliases: package
no_copy
bool no False
  • yes
  • no
Indicates if the file containing the software package should be copied from the local_package location on the local Ansible control machine to the remote_package location on the target Junos device.
If the value is true, or if the local_package option is not specified, then the copy is skipped and the file must already exist at the remote_package location on the target Junos device.
nssu
bool no False
  • yes
  • no
Indicates if a non-stop software upgrade (NSSU) should be attempted. NSSU enables the upgrade between two different Junos OS releases with minimal data plane traffic disruption.
NSSU is specific to EX-series Virtual Chassis systems or EX-series stand-alone systems with redundant Routing Engines.
In order for an NSSU to succeed, NSSU must be supported. This includes support for the current to desired Junos versions, the hardware of the target Junos device, and the current software configuration of the target Junos device.
The nssu and issu options are mutually exclusive.
pkg_set
list no False
install software on the members in a mixed Virtual Chassis. Currently we are not doing target package check this option is provided.
reboot
bool no True
  • yes
  • no
Indicates if the target Junos device should be rebooted after performing the software install.
reboot_pause
int no 10
The amount of time, in seconds, to wait after the reboot is issued before the module returns. This gives time for the reboot to begin. The default value of 10 seconds is designed to ensure the device is no longer reachable (because the reboot has begun) when the next task begins. The value must be an integer greater than or equal to 0.
remote_package
path no /var/tmp/ + filename portion of local_package
This option may take one of two formats.
The first format is a URL, from the perspective of the target Junos device, from which the device retrieves the software package to be installed. The acceptable formats for the URL value may be found here.
When using the URL format, the local_package and no_copy options must not be specified.
The second format is a file path, on the taget Junos device, to the software package.
If the local_package option is also specified, and the no_copy option is false, the software package will be copied from local_package to remote_package, if necessary.
If the no_copy option is true or the local_package option is not specified, then the file specified by this option must already exist on the target Junos device.
If this option is not specified, it is assumed that the software package will be copied into the /var/tmp directory on the target Junos device using the filename portion of the local_package option. In this case, the local_package option must be specified.
Specifying the remote_package option and not specifying the local_package option is equivalent to specifying the local_package option and the no_copy option. In this case, you no longer have to explicitly specify the no_copy option.
If the remote_package value is a directory (ends with /), then the filename portion of local_package will be appended to the remote_package value.
If the remote_package value is a file (does not end with /), then the filename portion of remote_package must be the same as the filename portion of local_package.
validate
bool no False
  • yes
  • no
Whether or not to have the target Junos device should validate the current configuration against the new software package.
version
str no Attempt to extract the version from the file name specified by the local_package or remote_package option values IF the package appears to be a Junos software package. Otherwise, none.
The version of software contained in the file specified by the local_package and/or remote_package options. This value should match the Junos version which will be reported by the device once the new software is installed. If the device is already running a version of software which matches the version option value, the software install is not necessary. In this case the module returns a changed value of false and an failed value of false and does not attempt to perform the software install.

aliases: target_version, new_version, desired_version
vmhost
bool no False
  • yes
  • no
Whether or not this is a vmhost software installation.

Examples

---
- name: Examples of juniper_junos_software
  hosts: junos-all
  connection: local
  gather_facts: no
  roles:
    - Juniper.junos

  tasks:
    - name: Execute a basic Junos software upgrade.
      juniper_junos_software:
        local_package: "./images/"
      register: response
    - name: Print the complete response.
      debug:
        var: response

###### OLD EXAMPLES ##########
    - junos_install_os:
        host={{ inventory_hostname }}
        version=12.1X46-D10.2
        package=/usr/local/junos/images/junos-vsrx-12.1X46-D10.2-domestic.tgz
        logfile=/usr/local/junos/log/software.log
###### OLD EXAMPLES ##########

Return Values

name description returned type sample
changed
Indicates if the device's state has changed, or if the state would have changed when executing in check mode. This value is set to true when the version of software currently running on the target Junos device does not match the desired version of software specified by the version option. If the current and desired software versions match, the value of this key is set to false.
success bool
check_mode
Indicates whether or not the module ran in check mode.
success bool
failed
Indicates if the task failed.
always bool
msg
A human-readable message indicating the result of the software installation.
always str


Notes

Note

  • This module does support connecting to the console of a Junos device, but does not support copying the software package from the local Ansible control machine to the target Junos device while connected via the console. In this situation, the remote_package option must be specified, and the specified software package must already exist on the target Junos device.
  • This module returns after installing the software and, optionally, initiating a reboot of the target Junos device. It does not wait for the reboot to complete, and it does not verify that the desired version of software specified by the version option is actually activated on the target Junos device. It is the user’s responsibility to confirm the software installation using additional follow on tasks in their playbook.
  • The NETCONF system service must be enabled on the target Junos device.

Author

  • Jeremy Schulman
  • 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.