Using Junos PyEZ to Install Software on Devices Running Junos OS

 

The Junos PyEZ jnpr.junos.utils.sw.SW utility enables you to install or upgrade the software image on devices running Junos OS. The install() method installs the specified software package.

This topic discusses the supported deployment scenarios, how to specify the software image location, and the general installation process and options when using Junos PyEZ to upgrade a device. It also discusses how to use Junos PyEZ to perform more specialized upgrade scenarios such as a VM host upgrade, a unified in-service software upgrade (unified ISSU), or a nonstop software upgrade (NSSU) on devices that support these features.

Supported Deployment Scenarios

The Junos PyEZ jnpr.junos.utils.sw.SW utility enables you to install or upgrade the software image on an individual device running Junos OS or on the members in a mixed or non-mixed Virtual Chassis. The following scenarios are supported:

  • Standalone devices with a single Routing Engine

  • Standalone devices equipped with dual Routing Engines

  • EX Series Virtual Chassis in mixed and non-mixed-mode configurations

  • QFX Series Virtual Chassis in mixed and non-mixed-mode configurations

  • Mixed EX Series and QFX Series Virtual Chassis

  • VM host upgrades on Routing Engines with VM Host Support

  • Deployment configurations that have some form of in-service features enabled, such as unified ISSU or NSSU

Note

The jnpr.junos.utils.sw.SW utility does not support upgrading devices in an MX Series Virtual Chassis, an SRX Series chassis cluster, or a Virtual Chassis Fabric (VCF).

Specifying the Software Image Location

When you use Junos PyEZ to install software on devices running Junos OS, you can download the software image to the configuration management server, and the install() method, by default, copies it to the target device before performing the installation. You can also instruct the install() method to install an image that already resides on the target device or resides at a URL that is reachable from the target device.

Table 1 outlines the install() method parameters that you must set depending on the software package location. You must always include either the package or pkg_set parameter in the install() method invocation.

Table 1: install() Method Parameter Settings for Software Package Location

Software Package Location

no_copy Parameter

package or pkg_set Parameter

remote_path Parameter

Configuration management server

Omitted or set to False

File path including the filename of the software package or packages on the local server running Junos PyEZ.

(Optional) Path to the directory on the target device to which the package or packages will be copied. Default is /var/tmp.

Target device

Set to True

Filename of the software package or packages.

(Optional) Path to the directory on the target device where the package or packages 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.

The package argument is used to install software on a single device running Junos OS or on members in a non-mixed Virtual Chassis. The package argument is a string that specifies a single software image. For example:

The pkg_set argument is used to install software on the members in a mixed Virtual Chassis. It contains a list or tuple of strings that specify the necessary software images, in no particular order, for the various Virtual Chassis members. For example:

For packages residing on the local server running Junos PyEZ, when you omit the no_copy argument or set it to False, the server copies the specified software package to the device. Including the package argument causes the server to copy the package to the target device (individual device or master router or switch in a non-mixed Virtual Chassis), and including the pkg_set argument causes the server to copy all packages in the list to the master router or switch in a mixed Virtual Chassis. By default, software images are placed in the /var/tmp directory unless the remote_path argument specifies a different directory.

If you set the no_copy argument to True, the necessary software packages must already exist on the target device or Virtual Chassis master device before the installation begins. The packages must reside either in the directory specified by the remote_path argument, or if remote_path is omitted, in the default /var/tmp directory.

Starting in Release 2.1.5, Junos PyEZ supports installing software images from a URL. In this case, the package or pkg_set value must be a URL from the perspective of the target device running Junos OS. The package 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.

Installation Process Overview

To install a software image on a device running Junos OS, a Junos PyEZ application connects to the individual device or to the master device in a Virtual Chassis, creates an instance of the SW utility, and calls the install() method with any required or optional arguments. For example:

For the current list of install() method parameters, see http://junos-pyez.readthedocs.io/en/latest/jnpr.junos.utils.html#jnpr.junos.utils.sw.SW.install.

If the software package is located on the configuration management server, and the no_copy parameter is omitted or set to False, the install() method performs the following operations before installing the software:

  • Computes the checksum of the local software package or packages using the algorithm specified in the checksum_algorithm argument, if the checksum is not already provided through the checksum argument. Acceptable checksum_algorithm values are "md5", "sha1", and "sha256". The default is "md5".

  • Performs a storage cleanup on the target device to create space for the software package, unless cleanfs is set to False.

  • SCP or FTP copies the package to the remote_path directory, or if remote_path is not specified, to the /var/tmp directory, if a file with the same name and checksum does not already reside in the target location on the device.

  • Computes the checksum of the remote file and compares it to the value of the local file.

After the software package is on the target device, whether downloaded there initially, copied over from the configuration management server by the install() method, or copied from a URL by the target device, the install() method performs the following operations:

  • Validates the configuration against the new package if the validate parameter is set to True

  • Installs the package on all Routing Engines unless all_re is set to False

Note

Starting in Release 2.1.5, Junos PyEZ, by default, upgrades all Routing Engines on individual devices and members in a Virtual Chassis. In earlier releases, or if all_re=False, Junos PyEZ only upgrades the Routing Engine to which it is connected.

The install() method returns True if the installation is successful. The install() method does not automatically reboot the device. To reboot or shut down the device after the installation is complete, call the reboot() or shutdown() method, respectively.

The following video presents a short Python session that demonstrates how to use Junos PyEZ to install Junos OS.

 

Specifying Installation and Checksum Timeouts

Junos PyEZ performs operations over a NETCONF session. The default time for a NETCONF RPC to time out is 30 seconds. During the installation process, Junos PyEZ 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, include the timeout and checksum_timeout parameters, respectively, in the call to the install() method, and set them to appropriate values. For example:

Note

The checksum_timeout parameter is available starting in Junos PyEZ Release 2.1.4.

Logging the Installation Process

The Junos PyEZ install process enables you to display or log the progress of the installation by including the progress argument in the install() method call. The argument is set to a callback function, which must have a function prototype defined that includes the Device instance and report string arguments. Starting in Junos PyEZ Release 1.2.3, you can also set progress=True to use sw.progress() for basic reporting.

The following example prints the installation progress using the myprogress function.

The progress output is in the user-defined format.

user@server:~$ python junos-pyez-install.py

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

Starting in Junos PyEZ Release 2.1.6, the sw.install() method supports the vmhost=True argument for performing a VM host upgrade. When the vmhost=True argument is present, the sw.install() method performs the installation using the <request-vmhost-package-add> RPC instead of the <request-package-add> RPC.

The following example upgrades and reboots both the Junos OS and host OS on the device:

To reboot just the Junos OS software, call the sw.reboot() method instead.

Performing a Unified ISSU or NSSU

Junos PyEZ 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. Table 2 outlines the Junos PyEZ release in which the unified ISSU and NSSU features are first supported. For more information about unified ISSU and NSSU, see the software documentation for your product.

Table 2: Junos PyEZ Unified ISSU and NSSU Support

Junos PyEZ Release

Feature Support

2.1.0

Support for unified ISSU and NSSU on dual-Routing Engine devices running Junos OS.

2.1.6

Support for unified ISSU during a VM host upgrade for those devices with VM host support that use the request vmhost software in-service-upgrade command to perform a unified in-service software upgrade of the host OS and Junos OS.

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, include the issu=True argument in the install() method.

In the the following example, the install() method upgrades Junos OS on both Routing Engines and reboots the new master Routing Engine (previously the old backup Routing Engine) as part of the installation process. If the installation is successful, the reboot() method then reboots the connected Routing Engine, which is the new backup Routing Engine (previously the old master Routing Engine).

To perform a unified in-service software upgrade on a Routing Engine with VM host support that meets the necessary requirements and supports unified ISSU, include the vmhost=True and issu=True arguments in the install() method. The device upgrades from one host OS and Junos OS release to the requested release using the <request-vmhost-package-in-service-upgrade> RPC.

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, include the nssu=True argument in the install() method. For example:

Example: Using Junos PyEZ to Install Software on Devices Running Junos OS

Juniper Networks provides support for using Python to manage devices running Junos OS. The Junos PyEZ package provides simple yet powerful methods to perform certain operational and configuration tasks on devices running Junos OS. This example outlines how to use the Junos PyEZ jnpr.junos.utils.sw.SW utility to install or upgrade the software image on a device running Junos OS.

Requirements

This example uses the following hardware and software components:

  • Configuration management server running Python 2.7 or 3.4 and Junos PyEZ Release 2.0 or later release

  • Device running Junos OS with NETCONF enabled and a user account configured with appropriate permissions

  • SSH public/private key pair configured for the appropriate user on the Junos PyEZ server and device running Junos OS

Overview

This example presents a Python program that uses the Junos PyEZ SW utility to upgrade Junos OS on the specified device. This example assumes that the image has been downloaded to the local server.

The program imports the Junos PyEZ Device class, which handles the connection with the device running Junos OS; the SW class, which is used to perform the software installation operations on the target device; and required exceptions from the jnpr.junos.exception module, which contains exceptions encountered when managing devices running Junos OS. The program also imports the os, sys, and logging Python modules for verifying the existence of the software package and performing basic logging functions.

The program defines the update_progress() method, which is used by the install() method to report on the progress of the installation. By logging the installation process, you can more readily identify the point where any failures occur. In this example, progress messages are sent to standard output and also logged in a separate file.

Before connecting to the device and proceeding with the installation, the program first verifies that the software package exists. If the file cannot be found, the program exits with an error message. If the file exists, the program creates the Device instance for the target device and calls the open() method to establish a connection and NETCONF session with the device.

The program creates an instance of the SW utility and uses the install() method to install the Junos OS software image on the target device. The package variable defines the path on the local server to the new Junos OS image. Because the no_copy parameter defaults to False, the installation process copies the software image from the local server to the target device. The remote_path variable defines the path on the target device to which the software package is copied. The default is /var/tmp. Although not required, this example explicitly configures the parameter for clarity.

When the install() method is called, the program calculates the local MD5 checksum, performs a storage cleanup and copies the software image to the target device, computes the remote MD5 checksum and compares it to the local value, validates the configuration against the new image, and then installs the package. If the installation is successful, the program then calls the reboot() method to reboot the device.

After performing the installation, the NETCONF session and connection are terminated using the close() method. The program includes code for handling any exceptions that might occur when connecting to the device or performing the installation.

Configuration

Creating the Junos PyEZ Program

Step-by-Step Procedure

To create a Python program that uses Junos PyEZ to install a software image on a device running Junos OS:

  1. Import any required modules, classes, and objects.

  2. Include any required variables, which for this example includes the hostname of the managed device, the software package path, and the log file.

  3. Define the logging method used within the program and by the install() method.

    Note

    Starting in Junos PyEZ 1.2.3, you can set progress=True to use sw.progress() for basic reporting.

  4. Create a main() function definition and function call, and place the remaining statements within the definition.

  5. Initialize the logger instance.

  6. (Optional) Add code that verifies the existence of the software package.

  7. Create an instance of the Device class, and supply the hostname and any parameters required for that specific connection.

    Then open a connection and establish a NETCONF session with the device.

  8. Create an instance of the SW utility.

  9. Include code to install the software package and to reboot the device if the installation succeeds.

  10. End the NETCONF session and close the connection with the device.

Results

On the configuration management server, review the completed program. If the program does not display the intended code, repeat the instructions in this example to correct the program.

Executing the Junos PyEZ Code

Step-by-Step Procedure

To execute the Junos PyEZ code:

  • On the configuration management server, execute the program.

    user@server:~$ python junos-pyez-install.py

Verification

Verifying the Installation

Purpose

Verify that the software installation was successful.

Action

Review the progress messages, which are sent to both standard output and the log file that is defined in the program, for details about the installation. Sample log file output is shown here. Some output has been omitted for brevity.

user@server:~$ cat /var/log/junos-pyez/install.log

Meaning

The log file contents indicate that the image was successfully copied to and installed on the target device.

Troubleshooting

Troubleshooting Timeout Errors

Problem

The program generates an RpcTimeoutError message or a TimeoutExpiredError message and the installation fails.

Long operations might exceed the RPC timeout interval, particularly on slower devices, causing the RPC to time out before the operation can be completed. The default time for a NETCONF RPC to time out is 30 seconds. During the installation process, Junos PyEZ increases the RPC timeout interval to 300 seconds (5 minutes) when computing the checksum and to 1800 seconds (30 minutes) when copying and installing the package on the device.

Solution

To accommodate install or checksum operations that might require a longer time than the default installation and checksum timeout intervals, set the install method timeout and checksum_timeout parameters to appropriate values and re-run the program. For example:

Release History Table
Release
Description
Starting in Release 2.1.5, Junos PyEZ, by default, upgrades all Routing Engines on individual devices and members in a Virtual Chassis.