Junos OS Upgrade with request system software add

Upgrading Junos OS looks like a one-liner - request system software add ... reboot - but the details decide whether the upgrade is boring or a change-window disaster: the image must live in /var/tmp, the configuration should be validated against the new version first, and you need a rollback path if the new release misbehaves. This guide walks through a safe Junos OS upgrade from pre-flight checks and image download to verification, rollback and the failures that ruin upgrade windows.

Pre-Flight: What to Check Before You Start

Most failed upgrades are decided before the first command runs. Work through this list in the change window, not during it:

• Know your current release. show version gives the model, the Junos build and, on dual-RE systems, the release running on each Routing Engine. Write the numbers down - you will want them for the rollback plan.
• Confirm the target release is supported on your hardware. Check the Juniper EOL and supported-platform pages; loading a train that does not support an FPC or line card can leave the box booting into an unusable state.
• Check free space in /var/tmp. Images run from several hundred megabytes to well over a gigabyte. show system storage shows the partition layout, and request system storage cleanup frees space by removing old logs and core files.
• Back up the configuration. show configuration | save /var/tmp/backup-before-upgrade.conf, plus a copy off the box. Save a rescue configuration as well - the topic covered in our Junos rescue configuration guide - so a single command can restore a known-good state.
• Check alarms and redundancy. Resolve any outstanding hardware alarms first so you are not debugging an upgrade and a failing PSU at the same time.

Step 1: Download the Image to /var/tmp

Always download the software image to /var/tmp - on EX and QFX switches other directories are not supported, and /var/tmp is the recommended location on all platforms:

user@switch> request file copy ftp://10.10.10.5/junos-install-qfx-x86-64-22.4R1.15.tgz /var/tmp/
user@switch> file list /var/tmp

An internal FTP or SCP host is preferred over the public web, because a download that stalls halfway through a maintenance window is an avoidable problem. Verify the file size after transfer with file list detail /var/tmp and, where your process requires it, confirm the MD5 or SHA-1 signature published on the download page before installing. Malware or a truncated image fails signature verification at install time and wastes the window.

Step 2: Validate Before Installing

The validate option checks the candidate software against the current configuration for compatibility, without changing anything. Run it when upgrading between releases that support direct validation:

user@switch> request system software validate /var/tmp/junos-install-qfx-x86-64-22.4R1.15.tgz

If validation reports a configuration incompatibility, fix the config before proceeding. When direct validation is not supported between your current and target releases, choose one of the following modes instead:

The practical rule is simple: if validation works, never use no-validate. A five-minute validation step on a lab device routinely catches a deprecated statement that would otherwise leave the switch unable to commit its configuration after the reboot.

Step 3: Install and Reboot

Add the package with reboot in one command so the device installs and restarts automatically:

user@switch> request system software add /var/tmp/junos-install-qfx-x86-64-22.4R1.15.tgz reboot

The device verifies the package signature, installs it, and reboots. If you add the package without reboot, Junos continues running the old version until you issue request system reboot - and you can still cancel the pending install with request system software delete. That delay is useful when you want to stage the install and choose the exact reboot moment, but it also means an unattended device that is never rebooted quietly stays on the old release.

user@switch> request system software add /var/tmp/junos-install-qfx-x86-64-22.4R1.15.tgz no-copy no-validate
user@switch> request system reboot
user@switch> request system software delete junos-install-qfx-x86-64-22.4R1.15.tgz

Depending on platform, the add command also accepts package-type qualifiers, for example junos on some MX-style platforms where the image is split from other components. On fixed-configuration EX switches the single-install package is what you want, and mixing install and runtime packages from different releases is a reliable way to break the box.

Step 4: Verify the New Version

user@switch> show version
user@switch> show system uptime
user@switch> show chassis environment
user@switch> show chassis alarms
user@switch> show system boot-messages | match "error|fail"
user@switch> show interfaces terse

Confirm the new version is active, all FPCs/modules are online, and alarms are clear before moving on. Then verify the data plane rather than just the control plane: check that the interfaces you care about are up, that the routing protocol adjacencies came back, and that a few representative prefixes are present. On a switch, show ethernet-switching table should be repopulating normally. A reboot that brings the box up but leaves a module offline is still a failed upgrade.

Step 5: Roll Back If Needed

Junos keeps the previous software set so you can return to it if the new release has issues. Roll back and reboot to load the old version:

user@switch> request system software rollback
Reboot the system to complete the rollback? [yes,no] yes

After the reboot the device runs the previous release. You can also delete stored software packages you no longer need:

user@switch> request system software delete junos-install-qfx-x86-64-22.2R1.tgz
user@switch> show system software
user@switch> show system software detail

Keep the old package until the new release has run clean through at least one busy period. Deleting it immediately after a successful upgrade removes your fastest escape route and leaves you restoring from a remote image over a possibly degraded link.

Dual-RE and High-Availability Notes

• On dual-Routing Engine systems, direct (in-service) upgrades are possible by specifying the RE or using ISSU-capable flows; otherwise upgrade the backup RE first, switch over, then upgrade the other. Specifying the RE explicitly - show version | match re to confirm which is master - avoids the classic mistake of upgrading the box you are logged into and losing the session.
• Take a configuration snapshot before upgrading (the rescue configuration is a good baseline): request configuration rescue save.
• Schedule maintenance windows for non-ISSU upgrades on devices carrying production traffic, and always keep the old image until the new release has run stable for a few days.
• If your environment uses ISSU, budget for the impact checks: compatibility between the two releases, graceful restart support, and the protocol hold times that determine whether a switchover is truly hitless. The same discipline is described for NX-OS ISSU impact checks, and the mechanics of a staged install and commit are documented in the Cisco IOS XE install-mode upgrade guide.

Release Trains and Upgrade Paths

Junos releases are grouped into trains: the R1, R2, R3 and later maintenance releases within a major version, and successive major versions such as 21.4, 22.4 and 23.2. Two rules govern how you move between them. First, stay within a train for routine patching - jumping from 22.4R1 to 22.4R3 is a low-risk maintenance upgrade that rarely changes the configuration schema. Second, when you cross a major version boundary, plan for a schema change: features get deprecated, defaults shift, and a statement that committed cleanly yesterday may now generate a warning or be rejected outright.

The intermediate-hop question comes up constantly. Some platforms and release pairs support a direct upgrade from any older train straight to the target, while others require you to pass through a specific intermediate release first. Check the release notes for the target version before committing to a plan, and treat any advice that "you can just jump" as unverified until the notes confirm it for your exact platform and current build. When a direct path is not supported, the two options are the supported intermediate release or a no-validate install followed by repairing the configuration - which is precisely the scenario validate-on-host was designed to avoid.

Finally, align the upgrade with the vendor's recommendation for your deployment. For devices carrying production traffic, the general guidance is to run a mature release within a train rather than the first R1 of a new major version, unless the new train contains a fix you specifically need. The mature build has had the edge cases shaken out; the brand-new one has not.

Common Upgrade Failures and How to Avoid Them

• Insufficient disk space. The install aborts partway. Run request system storage cleanup and remove old images before starting.
• Wrong image for the platform. Installing a QFX image on an EX chassis, or a package built for a different architecture, fails signature or platform checks.
• Configuration that will not commit after the upgrade. Exactly what validate exists to prevent. Without it, a deprecated statement can leave the device running with a stale configuration file.
• Mixed software versions across a Virtual Chassis or MC-LAG pair. Upgrade members in a controlled order and confirm the cluster is healthy between steps.
• Forgotten reboot. The install reports success, the version never changes, and the change window ends with the old software still in place.
• No console access. If the management interface does not come back, the console is the only way in. Verify console access before, not during, the upgrade.

Post-Upgrade Checklist

• show version matches the intended release; show system uptime confirms the reboot happened when expected.
• No new alarms: show chassis alarms and show system alarms are both clean.
• Routing and switching adjacencies are up: show ospf neighbor, show bgp summary, show lacp interfaces.
• Monitoring and syslog reach the box, and the configuration archive recorded the new version string.
• Run request system snapshot so the running image and the backup on disk match, giving you a clean recovery point for the next change.
• Only after the device has been stable for several days, delete the previous image.

Related reading: Junos rescue configuration save and recovery and Junos commit confirmed and safe configuration rollback.

Original article: request system software add (Junos OS CLI Reference)