Updating Juniper MX With USB

Sometimes you have a Juniper MX router that may have firmware version from a number of years ago. Juniper usually can update at most 3 versions ahead. So for example you can potentially upgrade a device from Junos 21.3 to 23.3. However should your version be 20.1, you’re advised to upgrade to a version within the 3 max hops.

The alternative is to upgrade straight away using a USB key especially as it is a cleaner install and quicker all round. In my experence that is.

This post covers the process I use for MX204s jumping from 18.3 to 23.4R2-S5 — more than two hops, so a USB install is the way to go.

A few notes beforehand

• The USB install will wipe everything on the router. There will be no snapshots, no config etc.
• Take a full copy of your existing config. We use https://github.com/ytti/oxidized where I work for config backup. However during the upgrade you can take a copy of the set comands with show configuration | display set no-more
• Obtain a copy of any licence keys. There is a difference in licence between prior versions. Contact your account managers for this.

Why a USB install over an in-place jump

#

Because it’s more than 2 hops we go the USB route. It’s cleaner and generally quicker than chaining a series of intermediate upgrades together. The trade-off is that it’s a bare-metal install, so anything not backed up is gone: config, snapshots, the lot. Treat it as if you’re racking a fresh box.

Things to watch for between 18.3 and 23.4

#

Not a huge amount has changed between 18 and 24, but there are a couple of gotchas worth knowing before you start:

• ae interfaces - you may need to define gigether-options rather than ether-options on your aggregate links. If your existing config uses ether-options, expect it to either commit-fail or be silently accepted but ignored. Worth diffing your saved config against a known-good 23.x build before you paste it onto the freshly wiped box.
• Subscriber management has been significantly more streamlined in 20+. That said, we don’t think any of the config has been deprecated. Still worth a sanity check on your own subscriber profiles.
• Anything else that’s been quietly deprecated between releases. If you’ve got an obscure knob that’s been removed, the load set step is where it’ll tell you. Be ready to fix and reload.
• We suffered an odd kernel panic after our upgrades. This was due to a configuration of encapsulation ppp-over-ether on a vlan configured on a aggregate interface (ae0 in our case - example below). After removing that config, the MX no longer had and kernel panics.
  • Example:

interfaces {
    ae0 {
        unit 1234 {
            description "PPPoE testing";
            encapsulation ppp-over-ether;
            vlan-id 1234;
            pppoe-underlying-options {
                access-concentrator ac1.domain;
                duplicate-protection;
                dynamic-profile dyn-pppoe-profile;
            }
        }
    }
}

Licencing

#

Licencing is also removed by the wipe, so you’ll want one of the following two lined up before you start:

• A copy of the licence activation key.
• A case open with JTAC to get the key pre-emptively before the upgrade. Open the case ahead of time with the serial(s) and the target version so they’re ready to issue the key the moment you need it. Don’t wait until the box is down to raise this.

Pre-Installation Steps

#

Prepare the USB flash drive

#

• Ensure the USB meets the MX204 USB port spec: the MX Series router has a Type-A port on its front panel for removable media and manual Junos OS installation, supporting USB version 1.0 and later.
• Ensure the USB flash drive is empty and formatted as FAT-32. The capacity must be sufficient to hold the Junos OS package (the junos-install-media-* image for 23.4R2-S5)
• Copy the Junos OS image onto the root of the USB stick. The loader will scan the root for a valid package.

Upgrade Procedure

#

Installing Junos OS from a USB Flash Drive

#

These steps are the bare-metal loader-driven install:

1. Ensure that the router has been powered off.
2. Insert the USB flash drive into the USB port on the router.
3. Power on the router. This starts the loader script and checks for a Junos OS package on the USB flash drive.
4. When the install prompt appears, asking to install the image on both disks, enter Yes.
5. Reboot the router:

user@host> request system reboot

6. After the reboot has completed, log in and verify that the new version of the software has been properly installed:

user@host> show version

Hostname: host
Model: mx204
JUNOS Software Release [---] 23.4R2-S5

user@host> show version detail | match build
Build date: <YYYY-mm-DD HH:MM:SS UTC>

Ideally you’ll see the 23.4R2-S5 build string you just installed.

Post-Installation Steps

#

Restore the configuration from the USB

#

The quickest way to restore the backup is to load it directly from the USB stick. Mount it, then load set the file you saved back before the wipe.

root@host% mount -t msdos /dev/da0s1 /tmp/usb

Confirm the USB mounted and you can see your config file:

root@host% ls /tmp/usb/
filename_bla.config
junos-install-media-* ... .tgz

Now drop into the Junos cli and load set the file:

root@host% cli
user@host> configure
Entering configuration mode

[edit]
user@host# load set /tmp/usb/filename_bla.config
load complete

If load complete comes back without any warnings you can breathe easy. See the previous Things to watch for section for the kinds of knobs that may have changed meaning between 18.3 and 23.4.

Commit and we’re back in business:

[edit]
user@host# commit
commit complete

[edit]
user@host# quit
Exiting configuration mode

user@host> show interfaces terse ae0

Where relevant, expect to revisit your ae interface definitions and swap ether-options for gigether-options if they didn’t commit cleanly.

Restore the licence key

#

Copy license key to usb and load up onto the MX.

user@host> request system license add /tmp/usb/<licence-file>.lic
license file added successfully

Verify it took:

user@host> show system license
License usage:
                          Licenses     Licenses     Licences   Expiry
  Feature name              used      installed     needed
  ...

Troubleshooting and common pitfalls

#

• The loader doesn’t find the image. Check the format of the stick is genuinely FAT-32 (some tools default to exFAT or FAT-32+LBA, which the MX loader may not like), and confirm the image is in the root directory, not in a subfolder. If you’re unsure, reformat and re-copy.
• The box comes back up still on the old version. This usually means the loader booted from internal media instead of USB. Re-seat the stick, power-cycle, and watch the console. You should see the loader announce it’s found a package on removable media before it starts installing.
• load set fails partway with a commit error on ae interfaces. You hit the ether-options vs gigether-options change. Edit the relevant ae stanza and replace ether-options with gigether-options, then commit again.
• Licence key not applied / features don’t come up after restore. Confirm the licence key matches the serial of the box and is for the 23.4 release stream (Juniper licence keys are version-sensitive in some cases). If still no luck, chase the JTAC case.

All done. Happy upgrading.