Using Salt to Install Software on Devices Running Junos OS

Juniper Networks provides support for using Salt to manage devices running Junos OS, and the Junos execution and state modules (for Salt) define functions that enable you to perform operational and configuration tasks on the managed devices. The salt.modules.junos.install_os execution function and the salt.states.junos.install_os state function enable you to install software on devices running Junos OS.

The following sections discuss how to use Salt to install a Junos OS image, including the supported deployment scenarios, the general installation process and options, and specialized upgrade scenarios such as a VM Host upgrade, a unified in-service software upgrade (unified ISSU), and a nonstop software upgrade (NSSU) on devices that support these features.

junos.install_os Function Overview

The junos.install_os function enables you to use Salt to update the software on a device running Junos OS in the following scenarios:

Standalone device with a single Routing Engine
Standalone device equipped with dual Routing Engines
EX Series Virtual Chassis in non-mixed-mode configurations
QFX Series Virtual Chassis in non-mixed-mode configurations
VM Host upgrade on Routing Engines with VM Host support
Deployment configuration that has some form of in-service feature enabled, such as unified ISSU or NSSU

The basic syntax for the junos.install_os execution and state functions is shown here. For a complete list of the available function parameters, see the API documentation for that function.

The salt.modules.junos.install_os execution function syntax is:

The salt.states.junos.install_os state function syntax is:

where:

no_copy=(False | True)—(Optional) Specify whether to copy the software image to the device running Junos OS. The default is False.
path—Path to the software image to install.
reboot=(False | True)—(Optional) Specify whether to reboot the system after installing the software. The default is False.
remote_path='remote-path'—(Optional) Directory on the target device from which the image is installed. The default is /var/tmp.

Table 1 outlines the parameter settings required for the different software package locations.

Table 1: junos.install_os Parameter Settings for Different Software Package Locations
Software Package Location	`no_copy` Parameter	`path` Parameter	`remote_path` Parameter
Salt master	Omitted or set to `False`	Path to the software package on the Salt master. The path must use the `salt://` notation.	(Optional) Directory on the target device to which the package is copied. Default is /var/tmp.
Proxy minion server	Omitted or set to `False`	Absolute path to the software package on the proxy minion server.	(Optional) Directory on the target device to which the package is copied. Default is /var/tmp.
Target device	Set to `True`	Software package filename.	(Optional) Directory on the target device where the installation package must already reside. Default is /var/tmp.
URL	–	URL from the perspective of the target device running Junos OS from which the software package is installed.	–

By default, the junos.install_os function copies the software image from the path on the Salt master or proxy minion server, which is specified in the path parameter, to the /var/tmp directory on the device running Junos OS (individual device or primary device in a non-mixed Virtual Chassis). To copy the image to a different directory, include the remote_path argument and specify the directory. To ensure that the device has enough storage space to accommodate the image, the junos.install_os function automatically performs a storage cleanup on the target device before copying the image, unless you set the cleanfs parameter to False.

If the software image already resides on the target device, set the no_copy argument to True, and set the path argument to the image filename. The image must reside either in the directory specified by the remote_path argument, or if remote_path is omitted, in the default /var/tmp directory.

To install the software image from a remote URL, set the path argument to a URL from the perspective of the target device running Junos OS. The image is copied over and installed from the specified URL, and the no-copy and remote_path arguments are ignored. For information about specifying the format of the URL, see Format for Specifying Filenames and URLs in Junos OS CLI Commands.

For a complete list of the execution and state function parameters, see:

The junos.install_os execution and state functions use the Junos PyEZ install() function to perform the installation. For more information about the operations executed as part of the installation, see the Installation Process Overview section in Using Junos PyEZ to Install Software on Devices Running Junos OS.

How to Use the junos.install_os Execution Function

The salt.modules.junos.install_os execution function enables you to install a software image on one or more devices running Junos OS. For example, the following command copies the specified image from the Salt master to the /var/tmp directory on the target device. The device installs the package and then reboots.

Because the installation can take a long time, the command includes the -t seconds option to increase the time that Salt waits for a reply from the minion. Otherwise, the command line client might time out before the minion returns a response.

How to Use the junos.install_os State Function

The salt.modules.junos.install_os state function enables you to specify the image that a managed device should run. You can apply the state to one or more targets as required or reference it within the state top file for the appropriate minions.

The following state file ensures that the target minion runs the specified image:

When the state is applied, Salt copies the local image, which in this case resides in the /srv/salt/images directory on the Salt master, to the /var/tmp directory on the target device. The device installs the image and then reboots.

How to Specify Timeout Values

The junos.install_os function performs operations over a NETCONF session. The default time for a NETCONF RPC to time out is 30 seconds. During the installation process, the function increases the RPC timeout interval to 1800 seconds (30 minutes) when copying and installing the package on the device and to 300 seconds (5 minutes) when computing the checksum. In some cases, the installation process or checksum calculation might exceed these time intervals.

To increase the timeout value for the installation process and the checksum calculation in the call to the junos.install_os function, include the dev_timeout and checksum_timeout parameters, respectively, and set them to appropriate values. For example:

When the no_copy parameter is omitted or set to False, the junos.install_os function automatically performs a storage cleanup on the target device before copying the software image. Doing this helps to ensure that there is sufficient space for the image. By default, the cleanup operation times out after 300 seconds. To change the default timeout value for this operation, set the cleanfs_timeout parameter to the number of seconds to wait for the operation to complete.

The default time that the Salt command line client waits for replies from a minion is 5 seconds. However, the installation process can take a considerable amount of time. As a result, the command line client might time out before the minion returns a response. For example:

If that happens, you can check the result of the installation later. However, if you want to display the results when you execute the command, you can increase the time that Salt waits for replies from the minion by including the -t seconds option in the command and increasing the timeout value as necessary.

How to Perform a VM Host Upgrade

On devices that have Routing Engines with VM Host support, Junos OS runs as a virtual machine (VM) over a Linux-based host (VM host). A VM Host upgrade, which upgrades the host OS and compatible Junos OS, requires a VM Host installation package (junos-vmhost-install-x.tgz) and is performed using the request vmhost software add operational mode command, which corresponds to the <request-vmhost-package-add> RPC.

The junos.install_os function supports the vmhost=True argument for performing a VM Host upgrade. When this argument is present, the function performs the installation using the <request-vmhost-package-add> RPC.

The following state declaration upgrades both the Junos OS and host OS on the device:

How to Perform a Unified ISSU or an NSSU

Salt for Junos OS provides support for performing a unified in-service software upgrade (unified ISSU) or a nonstop software upgrade (NSSU) on devices that support the feature and meet the necessary requirements. For more information about unified ISSU and NSSU, see the software documentation for your product.

The unified ISSU feature enables you to upgrade between two different Junos OS releases with no disruption on the control plane and with minimal disruption of traffic. To perform a unified in-service software upgrade on devices that support this feature, use the junos.install_os function, and set issu to True.

In the following state declaration, the junos.install_os function upgrades Junos OS on both Routing Engines and reboots the new primary Routing Engine (previously the old backup Routing Engine) as part of the installation process. If the installation is successful, the reboot: True and all_re: False arguments then instruct the device to reboot the connected Routing Engine, which is the new backup Routing Engine (previously the old primary Routing Engine).

The NSSU feature enables you to upgrade the Junos OS software running on a switch or Virtual Chassis with redundant Routing Engines with minimal disruption to network traffic. To perform a nonstop software upgrade on devices that support this feature, use the junos.install_os function, and set nssu to True. For example:

ON THIS PAGE