Help us improve your experience.

Let us know what you think.

Do you have time for a two-minute survey?

 
 

Use Junos PyEZ to Install Software on Junos Devices

The Junos PyEZ jnpr.junos.utils.sw.SW utility enables you to install or upgrade the software image on Junos devices. 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 Junos device 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).

How to Specify the Software Image Location

When you use Junos PyEZ to install software on Junos devices, 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

Omit 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 Junos device from which the software package is installed.

The package argument is used to install software on a single Junos device 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 primary 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 primary 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 primary 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.

Junos PyEZ also 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 Junos device. 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 Junos device, a Junos PyEZ application connects to the individual device or to the primary 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 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.

Starting in Junos PyEZ Release 2.5.0, the install() method returns a tuple that contains the status of the installation and a message string. In earlier releases, the method returns only the status of the installation. The status is True if the installation is successful and False otherwise. The message string provides additional information about the success or failure of the installation and can include informational messages or error messages that are generated by Junos PyEZ or the device. For example:

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.

How to Specify 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:

How to Log 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. 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.

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.

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 a single Routing Engine device:

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

How to Perform 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 Junos devices.

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 primary 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 primary 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: Use Junos PyEZ to Install Software on a Junos Device

The Junos PyEZ library provides methods to perform operational and configuration tasks on Junos devices. This example outlines how to use the Junos PyEZ jnpr.junos.utils.sw.SW utility to install or upgrade the software image on a Junos device.

Requirements

This example uses the following hardware and software components:

  • Configuration management server running Python 3.5 or later and Junos PyEZ Release 2.5 or later

  • Junos device 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 Junos device

Overview

This example presents a Python application that uses the Junos PyEZ SW utility to upgrade Junos OS on the specified device. This example assumes that the software image resides on the local server.

The application imports the Junos PyEZ Device class, which handles the connection with the Junos device; 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 Junos devices. The application also imports the os, sys, and logging Python modules for verifying the existence of the software package and performing basic logging functions.

The application 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 application first verifies that the software package exists. If the file cannot be found, the application exits with an error message. If the file exists, the application creates the Device instance for the target device and calls the open() method to establish a connection and NETCONF session with the device.

The application 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 application:

  • Calculates the local MD5 checksum for the software image

  • Performs a storage cleanup on the target device

  • 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

  • Installs the package

If the installation is successful, the application then calls the reboot() method to reboot the device. After performing the installation, the application calls the close() method to terminate the NETCONF session and connection. The application includes code for handling any exceptions that might occur when connecting to the device or performing the installation.

Configuration

Create the Junos PyEZ Application

Step-by-Step Procedure

To create a Python application that uses Junos PyEZ to install a software image on a Junos device:

  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 application and by the install() method.

  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 application. If the application does not display the intended code, repeat the instructions in this example to correct the application.

Execute the Junos PyEZ Application

Execute the Application

  • On the configuration management server, execute the application.

Verification

Verify 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 application, for details about the installation. Sample log file output is shown here. Some output has been omitted for brevity.

Meaning

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

Troubleshooting

Troubleshoot Timeout Errors

Problem

The application 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 application. For example:

Release History Table
Release
Description
2.5.1
Starting in Junos PyEZ Release 2.5.0, the install() method returns a tuple that contains the status of the installation and a message string.
2.1.5
Starting in Release 2.1.5, Junos PyEZ, by default, upgrades all Routing Engines on individual devices and members in a Virtual Chassis.