.. _juniper_junos_software:

juniper_junos_software
++++++++++++++++++++++
Install software on a Junos device



.. contents::
   :local:
   :depth: 2


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:

#. 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.
#. If the *local_package* option is specified, compute the MD5 checksum
   of the *local_package* file on the local Ansible control machine.
#. 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.
#. If the *cleanfs* option is ``true``, the default, then perform the
   equivalent of the ``request system storage cleanup`` CLI command.
#. 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.
#. Install the software pacakge from the *remote_package* location on the
   target Junos device using the options specified.
#. 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:

* `junos-eznc <https://github.com/Juniper/py-junos-eznc>`_ >= 2.2.0
* Python >= 2.7



.. _module-specific-options-label:

Module-specific Options
-----------------------
The following options may be specified for this module:

.. raw:: html

    <table border=1 cellpadding=4>

    <tr>
    <th class="head">parameter</th>
    <th class="head">type</th>
    <th class="head">required</th>
    <th class="head">default</th>
    <th class="head">choices</th>
    <th class="head">comments</th>
    </tr>

    <tr>
    <td>all_re<br/><div style="font-size: small;"></div></td>
    <td>bool</td>
    <td>no</td>
    <td>True</td>
    <td><ul><li>yes</li><li>no</li></ul></td>
    <td>
        <div>Whether or not to install the software on all Routing Engines of the target Junos device. If <code>true</code>, and the device has multiple Routing Engines, the software is installed on all Routing Engines. If <code>false</code>, the software is only installed on the current Routing Engine.</div>
    </td>
    </tr>

    <tr>
    <td>checksum<br/><div style="font-size: small;"></div></td>
    <td>str</td>
    <td>no</td>
    <td>none</td>
    <td></td>
    <td>
        <div>The pre-calculated checksum, using the <em>checksum_algorithm</em> of the file specified by the <em>local_package</em> option. Specifying this option is simply an optimization to avoid repeatedly computing the checksum of the <em>local_package</em> file once for each target Junos host.</div>
    </td>
    </tr>

    <tr>
    <td>checksum_algorithm<br/><div style="font-size: small;"></div></td>
    <td>str</td>
    <td>no</td>
    <td>md5</td>
    <td></td>
    <td>
        <div>The algorithm to use when calculating the checksum of the local and remote software packages.</div>
    </td>
    </tr>

    <tr>
    <td>checksum_timeout<br/><div style="font-size: small;"></div></td>
    <td>int</td>
    <td>no</td>
    <td>300 (5 minutes)</td>
    <td></td>
    <td>
        <div>The number of seconds to wait for the calculation of the checksum to complete on the target Junos device.</div>
    </td>
    </tr>

    <tr>
    <td>cleanfs<br/><div style="font-size: small;"></div></td>
    <td>bool</td>
    <td>no</td>
    <td>true (unless <em>no_copy</em> is <code>true</code>, then <code>false</code>)</td>
    <td><ul><li>yes</li><li>no</li></ul></td>
    <td>
        <div>Whether or not to perform a <code>request system storage cleanup</code> prior to copying or installing the software.</div>
    </td>
    </tr>

    <tr>
    <td>cleanfs_timeout<br/><div style="font-size: small;"></div></td>
    <td>int</td>
    <td>no</td>
    <td>300 (5 minutes)</td>
    <td></td>
    <td>
        <div>The number of seconds to wait for the <code>request system storage cleanup</code> to complete on the target Junos device.</div>
    </td>
    </tr>

    <tr>
    <td>force_host<br/><div style="font-size: small;"></div></td>
    <td>bool</td>
    <td>no</td>
    <td>False</td>
    <td><ul><li>yes</li><li>no</li></ul></td>
    <td>
        <div>Forces the upgrade of the Host Software package on QFX-series devices.</div>
    </td>
    </tr>

    <tr>
    <td>install_timeout<br/><div style="font-size: small;"></div></td>
    <td>int</td>
    <td>no</td>
    <td>1800 (30 minutes)</td>
    <td></td>
    <td>
        <div>The number of seconds to wait for the software installation to complete on the target Junos device.</div>
    </td>
    </tr>

    <tr>
    <td>issu<br/><div style="font-size: small;"></div></td>
    <td>bool</td>
    <td>no</td>
    <td>False</td>
    <td><ul><li>yes</li><li>no</li></ul></td>
    <td>
        <div>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.</div>
        <div>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.</div>
        <div>The <em>issu</em> and <em>nssu</em> options are mutually exclusive.</div>
    </td>
    </tr>

    <tr>
    <td>kwargs<br/><div style="font-size: small;"></div></td>
    <td>dict</td>
    <td>no</td>
    <td>none</td>
    <td></td>
    <td>
        <div>Additional keyword arguments and values which are passed to the <code>&lt;request-package-add&gt;</code> RPC used to install the software package. The value of this option is a dictionary of keywords and values.</div>
        </br><div style="font-size: small;">aliases: kwarg, args, arg</div>
    </td>
    </tr>

    <tr>
    <td>local_package<br/><div style="font-size: small;"></div></td>
    <td>path</td>
    <td>no</td>
    <td>none</td>
    <td></td>
    <td>
        <div>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.</div>
        <div>If this option is specified, and a file with the same MD5 checksum doesn&#x27;t already exist at the <em>remote_package</em> location on the target Junos device, then the file is copied from the local Ansible control machine to the target Junos device.</div>
        <div>If this option is not specified, it is assumed that the software package already exists on the target Junos device. In this case, the <em>remote_package</em> option must be specified.</div>
        </br><div style="font-size: small;">aliases: package</div>
    </td>
    </tr>

    <tr>
    <td>no_copy<br/><div style="font-size: small;"></div></td>
    <td>bool</td>
    <td>no</td>
    <td>False</td>
    <td><ul><li>yes</li><li>no</li></ul></td>
    <td>
        <div>Indicates if the file containing the software package should be copied from the <em>local_package</em> location on the local Ansible control machine to the <em>remote_package</em> location on the target Junos device.</div>
        <div>If the value is <code>true</code>, or if the <em>local_package</em> option is not specified, then the copy is skipped and the file must already exist at the <em>remote_package</em> location on the target Junos device.</div>
    </td>
    </tr>

    <tr>
    <td>nssu<br/><div style="font-size: small;"></div></td>
    <td>bool</td>
    <td>no</td>
    <td>False</td>
    <td><ul><li>yes</li><li>no</li></ul></td>
    <td>
        <div>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.</div>
        <div>NSSU is specific to EX-series Virtual Chassis systems or EX-series stand-alone systems with redundant Routing Engines.</div>
        <div>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.</div>
        <div>The <em>nssu</em> and <em>issu</em> options are mutually exclusive.</div>
    </td>
    </tr>

    <tr>
    <td>pkg_set<br/><div style="font-size: small;"></div></td>
    <td>list</td>
    <td>no</td>
    <td>False</td>
    <td></td>
    <td>
        <div>install software on the members in a mixed Virtual Chassis. Currently we are not doing target package check this option is provided.</div>
    </td>
    </tr>

    <tr>
    <td>reboot<br/><div style="font-size: small;"></div></td>
    <td>bool</td>
    <td>no</td>
    <td>True</td>
    <td><ul><li>yes</li><li>no</li></ul></td>
    <td>
        <div>Indicates if the target Junos device should be rebooted after performing the software install.</div>
    </td>
    </tr>

    <tr>
    <td>reboot_pause<br/><div style="font-size: small;"></div></td>
    <td>int</td>
    <td>no</td>
    <td>10</td>
    <td></td>
    <td>
        <div>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.</div>
    </td>
    </tr>

    <tr>
    <td>remote_package<br/><div style="font-size: small;"></div></td>
    <td>path</td>
    <td>no</td>
    <td><code>/var/tmp/</code> + filename portion of <em>local_package</em></td>
    <td></td>
    <td>
        <div>This option may take one of two formats.</div>
        <div>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 <a href='https://www.juniper.net/documentation/en_US/junos/topics/concept/junos-software-formats-filenames-urls.html'>here</a>.</div>
        <div>When using the URL format, the <em>local_package</em> and <em>no_copy</em> options must not be specified.</div>
        <div>The second format is a file path, on the taget Junos device, to the software package.</div>
        <div>If the <em>local_package</em> option is also specified, and the <em>no_copy</em> option is <code>false</code>, the software package will be copied from <em>local_package</em> to <em>remote_package</em>, if necessary.</div>
        <div>If the <em>no_copy</em> option is <code>true</code> or the <em>local_package</em> option is not specified, then the file specified by this option must already exist on the target Junos device.</div>
        <div>If this option is not specified, it is assumed that the software package will be copied into the <code>/var/tmp</code> directory on the target Junos device using the filename portion of the <em>local_package</em> option. In this case, the <em>local_package</em> option must be specified.</div>
        <div>Specifying the <em>remote_package</em> option and not specifying the <em>local_package</em> option is equivalent to specifying the <em>local_package</em> option and the <em>no_copy</em> option. In this case, you no longer have to explicitly specify the <em>no_copy</em> option.</div>
        <div>If the <em>remote_package</em> value is a directory (ends with /), then the filename portion of <em>local_package</em> will be appended to the <em>remote_package</em> value.</div>
        <div>If the <em>remote_package</em> value is a file (does not end with /), then the filename portion of <em>remote_package</em> must be the same as the filename portion of <em>local_package</em>.</div>
    </td>
    </tr>

    <tr>
    <td>validate<br/><div style="font-size: small;"></div></td>
    <td>bool</td>
    <td>no</td>
    <td>False</td>
    <td><ul><li>yes</li><li>no</li></ul></td>
    <td>
        <div>Whether or not to have the target Junos device should validate the current configuration against the new software package.</div>
    </td>
    </tr>

    <tr>
    <td>version<br/><div style="font-size: small;"></div></td>
    <td>str</td>
    <td>no</td>
    <td>Attempt to extract the version from the file name specified by the <em>local_package</em> or <em>remote_package</em> option values IF the package appears to be a Junos software package. Otherwise, <code>none</code>.</td>
    <td></td>
    <td>
        <div>The version of software contained in the file specified by the <em>local_package</em> and/or <em>remote_package</em> 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 <em>version</em> option value, the software install is not necessary. In this case the module returns a <em>changed</em> value of <code>false</code> and an <em>failed</em> value of <code>false</code> and does not attempt to perform the software install.</div>
        </br><div style="font-size: small;">aliases: target_version, new_version, desired_version</div>
    </td>
    </tr>

    <tr>
    <td>vmhost<br/><div style="font-size: small;"></div></td>
    <td>bool</td>
    <td>no</td>
    <td>False</td>
    <td><ul><li>yes</li><li>no</li></ul></td>
    <td>
        <div>Whether or not this is a vmhost software installation.</div>
    </td>
    </tr>

    </table>
    </br>

Common Connection-related Options
---------------------------------
In addition to the :ref:`module-specific-options-label`, the following connection-related options are also supported by this module:

.. raw:: html

    <table border=1 cellpadding=4>

    <tr>
    <th class="head">parameter</th>
    <th class="head">type</th>
    <th class="head">required</th>
    <th class="head">default</th>
    <th class="head">choices</th>
    <th class="head">comments</th>
    </tr>

    <tr>
    <td>attempts<br/><div style="font-size: small;"></div></td>
    <td>int</td>
    <td>no</td>
    <td>10</td>
    <td></td>
    <td>
        <div>The number of times to try connecting and logging in to the Junos device. This option is only applicable when using <code>mode = &#x27;telnet&#x27;</code> or <code>mode = &#x27;serial&#x27;</code>. Mutually exclusive with the <em>console</em> option.</div>
    </td>
    </tr>

    <tr>
    <td>baud<br/><div style="font-size: small;"></div></td>
    <td>int</td>
    <td>no</td>
    <td>9600</td>
    <td></td>
    <td>
        <div>The serial baud rate, in bits per second, used to connect to the Junos device. This option is only applicable when using <code>mode = &#x27;serial&#x27;</code>. Mutually exclusive with the <em>console</em> option.</div>
    </td>
    </tr>

    <tr>
    <td>console<br/><div style="font-size: small;"></div></td>
    <td>str</td>
    <td>no</td>
    <td>none</td>
    <td></td>
    <td>
        <div>An alternate method of specifying a NETCONF over serial console connection to the Junos device using Telnet to a console server. The value of this option must be a string in the format <code>--telnet &lt;console_hostname&gt;,&lt;console_port_number&gt;</code>. This option is deprecated. It is present only for backwards compatibility. The string value of this option is exactly equivalent to specifying <em>host</em> with a value of <code>&lt;console_hostname&gt;</code>, <em>mode</em> with a value of <code>telnet</code>, and <em>port</em> with a value of <code>&lt;console_port_number&gt;</code>. Mutually exclusive with the <em>mode</em>, <em>port</em>, <em>baud</em>, and <em>attempts</em> options.</div>
    </td>
    </tr>

    <tr>
    <td>cs_passwd<br/><div style="font-size: small;"></div></td>
    <td>str</td>
    <td>no</td>
    <td></td>
    <td></td>
    <td>
        <div>The password used to authenticate with the console server over SSH. This option is only required if you want to connect to a device over console using SSH as transport. Mutually exclusive with the <em>console</em> option.</div>
        </br><div style="font-size: small;">aliases: console_password</div>
    </td>
    </tr>

    <tr>
    <td>cs_user<br/><div style="font-size: small;"></div></td>
    <td>str</td>
    <td>no</td>
    <td></td>
    <td></td>
    <td>
        <div>The username used to authenticate with the console server over SSH. This option is only required if you want to connect to a device over console using SSH as transport. Mutually exclusive with the <em>console</em> option.</div>
        </br><div style="font-size: small;">aliases: console_username</div>
    </td>
    </tr>

    <tr>
    <td>host<br/><div style="font-size: small;"></div></td>
    <td>str</td>
    <td>yes</td>
    <td><code>{{ inventory_hostname }}</code></td>
    <td></td>
    <td>
        <div>The hostname or IP address of the Junos device to which the connection should be established. This is normally the Junos device itself, but is the hostname or IP address of a console server when connecting to the console of the device by setting the <em>mode</em> option to the value <code>telnet</code>. This option is required, but does not have to be specified explicitly by the user because it defaults to <code>{{ inventory_hostname }}</code>.</div>
        </br><div style="font-size: small;">aliases: hostname, ip</div>
    </td>
    </tr>

    <tr>
    <td>mode<br/><div style="font-size: small;"></div></td>
    <td>str</td>
    <td>no</td>
    <td>none</td>
    <td><ul><li>none</li><li>telnet</li><li>serial</li></ul></td>
    <td>
        <div>The PyEZ mode used to establish a NETCONF connection to the Junos device. A value of <code>none</code> uses the default NETCONF over SSH mode. Depending on the values of the <em>host</em> and <em>port</em> options, a value of <code>telnet</code> results in either a direct NETCONF over Telnet connection to the Junos device, or a NETCONF over serial console connection to the Junos device using Telnet to a console server. A value of <code>serial</code> results in a NETCONF over serial console connection to the Junos device. Mutually exclusive with the <em>console</em> option.</div>
    </td>
    </tr>

    <tr>
    <td>passwd<br/><div style="font-size: small;"></div></td>
    <td>str</td>
    <td>no</td>
    <td>The first defined value from the following list 1) The <code>ANSIBLE_NET_PASSWORD</code> environment variable. (used by Ansible Tower) 2) The value specified using the <code>-k</code> or <code>--ask-pass</code> command line arguments to the <code>ansible</code> or <code>ansible-playbook</code> command. 3) none (An empty password/passphrase)</td>
    <td></td>
    <td>
        <div>The password, or ssh key&#x27;s passphrase, used to authenticate with the Junos device. If this option is not specified, authentication is attempted using an empty password, or ssh key passphrase.</div>
        </br><div style="font-size: small;">aliases: password</div>
    </td>
    </tr>

    <tr>
    <td>port<br/><div style="font-size: small;"></div></td>
    <td>int or str</td>
    <td>no</td>
    <td><code>830</code> if <code>mode = none</code>, <code>23</code> if <code>mode = &#x27;telnet&#x27;</code>, <code>&#x27;/dev/ttyUSB0&#x27;</code> if (mode = &#x27;serial&#x27;)</td>
    <td></td>
    <td>
        <div>The TCP port number or serial device port used to establish the connection. Mutually exclusive with the <em>console</em> option.</div>
    </td>
    </tr>

    <tr>
    <td rowspan="2">provider<br/><div style="font-size: small;"></div></td>
    <td>dict</td>
    <td>no</td>
    <td></td>
    <td></td>
    <td>
        <div>An alternative syntax for specifying the connection options. Rather than specifying each connection-related top-level option, the connection-related options may be specified as a dictionary of suboptions to the <em>provider</em> option. All connection-related options must either be specified as top-level options or as suboptions of the <em>provider</em> option. You can not combine the two methods of specifying connection-related options.</div>
    </tr>

    <tr>
    <td colspan="5">
        <table border=1 cellpadding=4>
        <caption><b>Dictionary object provider</b></caption>

        <tr>
        <th class="head">parameter</th>
        <th class="head">type</th>
        <th class="head">required</th>
        <th class="head">default</th>
        <th class="head">choices</th>
        <th class="head">comments</th>
        </tr>

        <tr>
        <td>attempts<br/><div style="font-size: small;"></div></td>
        <td>int</td>
        <td>no</td>
        <td>10</td>
        <td></td>
        <td>
            <div>The number of times to try connecting and logging in to the Junos device. This option is only applicable when using <code>mode = &#x27;telnet&#x27;</code> or <code>mode = &#x27;serial&#x27;</code>. Mutually exclusive with the <em>console</em> option.</div>
        </td>
        </tr>

        <tr>
        <td>baud<br/><div style="font-size: small;"></div></td>
        <td>int</td>
        <td>no</td>
        <td>9600</td>
        <td></td>
        <td>
            <div>The serial baud rate, in bits per second, used to connect to the Junos device. This option is only applicable when using <code>mode = &#x27;serial&#x27;</code>. Mutually exclusive with the <em>console</em> option.</div>
        </td>
        </tr>

        <tr>
        <td>console<br/><div style="font-size: small;"></div></td>
        <td>str</td>
        <td>no</td>
        <td>none</td>
        <td></td>
        <td>
            <div>An alternate method of specifying a NETCONF over serial console connection to the Junos device using Telnet to a console server. The value of this option must be a string in the format <code>--telnet &lt;console_hostname&gt;,&lt;console_port_number&gt;</code>. This option is deprecated. It is present only for backwards compatibility. The string value of this option is exactly equivalent to specifying <em>host</em> with a value of <code>&lt;console_hostname&gt;</code>, <em>mode</em> with a value of <code>telnet</code>, and <em>port</em> with a value of <code>&lt;console_port_number&gt;</code>. Mutually exclusive with the <em>mode</em>, <em>port</em>, <em>baud</em>, and <em>attempts</em> options.</div>
        </td>
        </tr>

        <tr>
        <td>host<br/><div style="font-size: small;"></div></td>
        <td>str</td>
        <td>yes</td>
        <td><code>{{ inventory_hostname }}</code></td>
        <td></td>
        <td>
            <div>The hostname or IP address of the Junos device to which the connection should be established. This is normally the Junos device itself, but is the hostname or IP address of a console server when connecting to the console of the device by setting the <em>mode</em> option to the value <code>telnet</code>. This option is required, but does not have to be specified explicitly by the user because it defaults to <code>{{ inventory_hostname }}</code>.</div>
        </td>
        </tr>

        <tr>
        <td>mode<br/><div style="font-size: small;"></div></td>
        <td>str</td>
        <td>no</td>
        <td>none</td>
        <td><ul><li>none</li><li>telnet</li><li>serial</li></ul></td>
        <td>
            <div>The PyEZ mode used to establish a NETCONF connection to the Junos device. A value of <code>none</code> uses the default NETCONF over SSH mode. Depending on the values of the <em>host</em> and <em>port</em> options, a value of <code>telnet</code> results in either a direct NETCONF over Telnet connection to the Junos device, or a NETCONF over serial console connection to the Junos device using Telnet to a console server. A value of <code>serial</code> results in a NETCONF over serial console connection to the Junos device. Mutually exclusive with the <em>console</em> option.</div>
        </td>
        </tr>

        <tr>
        <td>passwd<br/><div style="font-size: small;"></div></td>
        <td>str</td>
        <td>no</td>
        <td>The first defined value from the following list 1) The <code>ANSIBLE_NET_PASSWORD</code> environment variable. (used by Ansible Tower) 2) The value specified using the <code>-k</code> or <code>--ask-pass</code> command line arguments to the <code>ansible</code> or <code>ansible-playbook</code> command. 3) none (An empty password/passphrase)</td>
        <td></td>
        <td>
            <div>The password, or ssh key&#x27;s passphrase, used to authenticate with the Junos device. If this option is not specified, authentication is attempted using an empty password, or ssh key passphrase.</div>
        </td>
        </tr>

        <tr>
        <td>port<br/><div style="font-size: small;"></div></td>
        <td>int or str</td>
        <td>no</td>
        <td><code>830</code> if <code>mode = none</code>, <code>23</code> if <code>mode = &#x27;telnet&#x27;</code>, <code>&#x27;/dev/ttyUSB0&#x27;</code> if (mode = &#x27;serial&#x27;)</td>
        <td></td>
        <td>
            <div>The TCP port number or serial device port used to establish the connection. Mutually exclusive with the <em>console</em> option.</div>
        </td>
        </tr>

        <tr>
        <td>ssh_private_key_file<br/><div style="font-size: small;"></div></td>
        <td>path</td>
        <td>no</td>
        <td>The first defined value from the following list 1) The <code>ANSIBLE_NET_SSH_KEYFILE</code> environment variable. (used by Ansible Tower) 2) The value specified using the <code>--private-key</code> or <code>--key-file</code> command line arguments to the <code>ansible</code> or <code>ansible-playbook</code> command. 3) none (the file specified in the user&#x27;s SSH configuration, or the operating-system-specific default)</td>
        <td></td>
        <td>
            <div>The path to the SSH private key file used to authenticate with the Junos device. If this option is not specified, and no default value is found using the algorithm below, then the SSH private key file specified in the user&#x27;s SSH configuration, or the operating-system-specific default is used.</div>
            <div>This must be in the RSA PEM format, and not the newer OPENSSH format. To check if the private key is in the correct format, issue the command `head -n1 ~/.ssh/some_private_key` and ensure that it&#x27;s RSA and not OPENSSH. To create a key in the RSA PEM format, issue the command `ssh-keygen -m PEM -t rsa -b 4096`. To convert an OPENSSH key to an RSA key, issue the command `ssh-keygen -p -m PEM -f ~/.ssh/some_private_key`</div>
        </td>
        </tr>

        <tr>
        <td>ssh_config<br/><div style="font-size: small;"></div></td>
        <td>path</td>
        <td>no</td>
        <td></td>
        <td></td>
        <td>
            <div>The path to the SSH client configuration file. If this option is not specified, then the PyEZ Device instance by default queries file ~/.ssh/config.</div>
        </td>
        </tr>

        <tr>
        <td>timeout<br/><div style="font-size: small;"></div></td>
        <td>int</td>
        <td>no</td>
        <td>30</td>
        <td></td>
        <td>
            <div>The maximum number of seconds to wait for RPC responses from the Junos device. This option does NOT control the initial connection timeout value.</div>
        </td>
        </tr>

        <tr>
        <td>user<br/><div style="font-size: small;"></div></td>
        <td>str</td>
        <td>yes</td>
        <td>The first defined value from the following list 1) The <code>ANSIBLE_NET_USERNAME</code> environment variable. (used by Ansible Tower) 2) The <code>remote_user</code> as defined by Ansible. Ansible sets this value via several methods including a) <code>-u</code> or <code>--user</code> command line arguments to the <code>ansible</code> or <code>ansible-playbook</code> command. b) <code>ANSIBLE_REMOTE_USER</code> environment variable. c) <code>remote_user</code> configuration setting. See the Ansible documentation for the precedence used to set the <code>remote_user</code> value. 3) The <code>USER</code> environment variable.</td>
        <td></td>
        <td>
            <div>The username used to authenticate with the Junos device. This option is required, but does not have to be specified explicitly by the user due to the algorithm for determining the default value.</div>
        </td>
        </tr>

        <tr>
        <td>cs_user<br/><div style="font-size: small;"></div></td>
        <td>str</td>
        <td>no</td>
        <td></td>
        <td></td>
        <td>
            <div>The username used to authenticate with the console server over SSH. This option is only required if you want to connect to a device over console using SSH as transport. Mutually exclusive with the <em>console</em> option.</div>
        </td>
        </tr>

        <tr>
        <td>cs_passwd<br/><div style="font-size: small;"></div></td>
        <td>str</td>
        <td>no</td>
        <td></td>
        <td></td>
        <td>
            <div>The password used to authenticate with the console server over SSH. This option is only required if you want to connect to a device over console using SSH as transport. Mutually exclusive with the <em>console</em> option.</div>
        </td>
        </tr>

        </table>

    </td>
    </tr>
    </td>
    </tr>

    <tr>
    <td>ssh_config<br/><div style="font-size: small;"></div></td>
    <td>path</td>
    <td>no</td>
    <td></td>
    <td></td>
    <td>
        <div>The path to the SSH client configuration file. If this option is not specified, then the PyEZ Device instance by default queries file ~/.ssh/config.</div>
    </td>
    </tr>

    <tr>
    <td>ssh_private_key_file<br/><div style="font-size: small;"></div></td>
    <td>path</td>
    <td>no</td>
    <td>The first defined value from the following list 1) The <code>ANSIBLE_NET_SSH_KEYFILE</code> environment variable. (used by Ansible Tower) 2) The value specified using the <code>--private-key</code> or <code>--key-file</code> command line arguments to the <code>ansible</code> or <code>ansible-playbook</code> command. 3) none (the file specified in the user&#x27;s SSH configuration, or the operating-system-specific default)</td>
    <td></td>
    <td>
        <div>The path to the SSH private key file used to authenticate with the Junos device. If this option is not specified, and no default value is found using the algorithm below, then the SSH private key file specified in the user&#x27;s SSH configuration, or the operating-system-specific default is used.</div>
        <div>This must be in the RSA PEM format, and not the newer OPENSSH format. To check if the private key is in the correct format, issue the command `head -n1 ~/.ssh/some_private_key` and ensure that it&#x27;s RSA and not OPENSSH. To create a key in the RSA PEM format, issue the command `ssh-keygen -m PEM -t rsa -b 4096`. To convert an OPENSSH key to an RSA key, issue the command `ssh-keygen -p -m PEM -f ~/.ssh/some_private_key`</div>
        </br><div style="font-size: small;">aliases: ssh_keyfile</div>
    </td>
    </tr>

    <tr>
    <td>timeout<br/><div style="font-size: small;"></div></td>
    <td>int</td>
    <td>no</td>
    <td>30</td>
    <td></td>
    <td>
        <div>The maximum number of seconds to wait for RPC responses from the Junos device. This option does NOT control the initial connection timeout value.</div>
    </td>
    </tr>

    <tr>
    <td>user<br/><div style="font-size: small;"></div></td>
    <td>str</td>
    <td>yes</td>
    <td>The first defined value from the following list 1) The <code>ANSIBLE_NET_USERNAME</code> environment variable. (used by Ansible Tower) 2) The <code>remote_user</code> as defined by Ansible. Ansible sets this value via several methods including a) <code>-u</code> or <code>--user</code> command line arguments to the <code>ansible</code> or <code>ansible-playbook</code> command. b) <code>ANSIBLE_REMOTE_USER</code> environment variable. c) <code>remote_user</code> configuration setting. See the Ansible documentation for the precedence used to set the <code>remote_user</code> value. 3) The <code>USER</code> environment variable.</td>
    <td></td>
    <td>
        <div>The username used to authenticate with the Junos device. This option is required, but does not have to be specified explicitly by the user due to the algorithm for determining the default value.</div>
        </br><div style="font-size: small;">aliases: username</div>
    </td>
    </tr>

    </table>
    </br>

Common Logging-related Options
------------------------------
In addition to the :ref:`module-specific-options-label`, the following logging-related options are also supported by this module:

.. raw:: html

    <table border=1 cellpadding=4>

    <tr>
    <th class="head">parameter</th>
    <th class="head">type</th>
    <th class="head">required</th>
    <th class="head">default</th>
    <th class="head">choices</th>
    <th class="head">comments</th>
    </tr>

    <tr>
    <td>level<br/><div style="font-size: small;"></div></td>
    <td>str</td>
    <td>no</td>
    <td>WARNING</td>
    <td><ul><li>INFO</li><li>DEBUG</li></ul></td>
    <td>
        <div>The level of information to be logged can be modified using this option</div>
        <div>1) By default, messages at level <code>WARNING</code> or higher are logged.</div>
        <div>2) If the <code>-v</code> or <code>--verbose</code> command-line options to the <code>ansible-playbook</code> command are specified, messages at level <code>INFO</code> or higher are logged.</div>
        <div>3) If the <code>-vv</code> (or more verbose) command-line option to the <code>ansible-playbook</code> command is specified, or the <code>ANSIBLE_DEBUG</code> environment variable is set, then messages at level <code>DEBUG</code> or higher are logged.</div>
        <div>4) If <code>level</code> is mentioned then messages at level <code>level</code> or more are logged.</div>
    </td>
    </tr>

    <tr>
    <td>logdir<br/><div style="font-size: small;"></div></td>
    <td>path</td>
    <td>no</td>
    <td>none</td>
    <td></td>
    <td>
        <div>The path to a directory, on the Ansible control machine, where debugging information for the particular task is logged.</div>
        <div>If this option is specified, debugging information is logged to a file named <code>{{ inventory_hostname }}.log</code> in the directory specified by the <em>logdir</em> option.</div>
        <div>The log file must be writeable. If the file already exists, it is appended. It is the users responsibility to delete/rotate log files.</div>
        <div>The level of information logged in this file is controlled by Ansible&#x27;s verbosity, debug options and level option in task</div>
        <div>1) By default, messages at level <code>WARNING</code> or higher are logged.</div>
        <div>2) If the <code>-v</code> or <code>--verbose</code> command-line options to the <code>ansible-playbook</code> command are specified, messages at level <code>INFO</code> or higher are logged.</div>
        <div>3) If the <code>-vv</code> (or more verbose) command-line option to the <code>ansible-playbook</code> command is specified, or the <code>ANSIBLE_DEBUG</code> environment variable is set, then messages at level <code>DEBUG</code> or higher are logged.</div>
        <div>4) If <code>level</code> is mentioned then messages at level <code>level</code> or more are logged.</div>
        <div>The <em>logfile</em> and <em>logdir</em> options are mutually exclusive. The <em>logdir</em> option is recommended for all new playbooks.</div>
        </br><div style="font-size: small;">aliases: log_dir</div>
    </td>
    </tr>

    <tr>
    <td>logfile<br/><div style="font-size: small;"></div></td>
    <td>path</td>
    <td>no</td>
    <td>none</td>
    <td></td>
    <td>
        <div>The path to a file, on the Ansible control machine, where debugging information for the particular task is logged.</div>
        <div>The log file must be writeable. If the file already exists, it is appended. It is the users responsibility to delete/rotate log files.</div>
        <div>The level of information logged in this file is controlled by Ansible&#x27;s verbosity, debug options and level option in task</div>
        <div>1) By default, messages at level <code>WARNING</code> or higher are logged.</div>
        <div>2) If the <code>-v</code> or <code>--verbose</code> command-line options to the <code>ansible-playbook</code> command are specified, messages at level <code>INFO</code> or higher are logged.</div>
        <div>3) If the <code>-vv</code> (or more verbose) command-line option to the <code>ansible-playbook</code> command is specified, or the <code>ANSIBLE_DEBUG</code> environment variable is set, then messages at level <code>DEBUG</code> or higher are logged.</div>
        <div>4) If <code>level</code> is mentioned then messages at level <code>level</code> or more are logged.</div>
        <div>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 <a href='http://docs.ansible.com/ansible/latest/intro_configuration.html#forks'>forks</a> for details.) This means that the value of this option must be unique per target host. This is usually accomplished by including <code>{{ inventory_hostname }}</code> in the <em>logfile</em> value. It is the user&#x27;s responsibility to ensure this value is unique per target host.</div>
        <div>For this reason, this option is deprecated. It is maintained for backwards compatibility. Use the <em>logdir</em> option in new playbooks. The <em>logfile</em> and <em>logdir</em> options are mutually exclusive.</div>
        </br><div style="font-size: small;">aliases: log_file</div>
    </td>
    </tr>

    </table>
    </br>

.. _juniper_junos_software-examples-label:

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
-------------

.. raw:: html

    <table border=1 cellpadding=4>

    <tr>
    <th class="head">name</th>
    <th class="head">description</th>
    <th class="head">returned</th>
    <th class="head">type</th>
    <th class="head">sample</th>
    </tr>


    <tr>
    <td>changed</td>
    <td>
        <div>Indicates if the device&#x27;s state has changed, or if the state would have changed when executing in check mode. This value is set to <code>true</code> when the version of software currently running on the target Junos device does not match the desired version of software specified by the <em>version</em> option. If the current and desired software versions match, the value of this key is set to <code>false</code>.</div>
    </td>
    <td align=center>success</td>
    <td align=center>bool</td>
    <td align=center></td>
    </tr>

    <tr>
    <td>check_mode</td>
    <td>
        <div>Indicates whether or not the module ran in check mode.</div>
    </td>
    <td align=center>success</td>
    <td align=center>bool</td>
    <td align=center></td>
    </tr>

    <tr>
    <td>failed</td>
    <td>
        <div>Indicates if the task failed.</div>
    </td>
    <td align=center>always</td>
    <td align=center>bool</td>
    <td align=center></td>
    </tr>

    <tr>
    <td>msg</td>
    <td>
        <div>A human-readable message indicating the result of the software installation.</div>
    </td>
    <td align=center>always</td>
    <td align=center>str</td>
    <td align=center></td>
    </tr>

    </table>
    </br>
    </br>


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.