Help us improve your experience.

Let us know what you think.

Do you have time for a two-minute survey?

 
ON THIS PAGE
 

Upgrading and Downgrading to Junos with Upgraded FreeBSD

You can upgrade or downgrade Junos OS with upgraded FreeBSD. You can upgrade Junos OS with upgraded FreeBSD from Junos OS based on FreeBSD 6.1 and upgrade between different releases of Junos OS with upgraded FreeBSD. Before you stage an upgrade between different releases of Junos OS with upgraded FreeBSD, you should install the os-package software to help the upgrade go more smoothly.

Before You Upgrade, Install os-package

Before you stage an upgrade between different releases of Junos OS with upgraded FreeBSD, you should install the os-package software to help the upgrade go more smoothly. A vast majority of all upgrade problems are due to limitations or bugs in the already running software that is performing the installation, rather than the new software being installed. The os-package software contains the latest version of the package system and is installable on any BSDX version (FreeBSD 10 or later) of Junos OS Release 15.1 or later.

Benefits:

  • os-package facilitates the major FreeBSD upgrades (that is, version 10 to version 11 or version 11 to version 12).

  • The goal of the os-package is to be backward compatible with all prior BSDx releases of JUNOS.

  • os-package is architecture neutral.

You do not need to reboot the device after installing os-package. It takes only a few seconds to add and is immediately available for help with a planned upgrade. When added, the os-package checks the os-kernel for a feature toggle, which indicates that it is safe to reboot with the os-package in the active set. If the toggle is missing, the following warning will be issued:

Note:

The os-package is NOT bundled with Junos OS 22.2R1 and older. os-package is needed only when the shipped JUNOS package that is running on a device needs to be updated to facilitate an upgrade. You must install the latest package before every upgrade regardless of whether the os-package was installed previously on the device. Even when os-package is bundled with Junos OS (Release 22.3R1 and later), you should fetch and install the latest os-package before you upgrade to reduce the likelihood of issues impacting the upgrade.

Before you install os-package:

  • Determine which Junos OS releases have BSDx, by platform: Junos kernel upgrade to FreeBSD 10+.

  • Once you know which Junos OS BSDx release you have, find the correct os-package for it:

    • Junos OS Release 18.x and later: os-package. (For example, os-package-20221105.013526_builder_stable_12.tgz.)

    • Junos OS Release 17.x and earlier: os-package-sha1. (For example, os-package-sha1-20221105.013526_builder_stable_12.tgz.)

  1. Download the latest copy of os-package for your device and version of Junos OS and save it to the /var/tmp folder of the device.
    The original filename of os-package looks similar to this: os-package-20221105.013526_builder_stable_12.tgz. You may want to rename the file to have a simpler filename when you download it to the /var/tmp folder.
  2. Install os-package.

    In this example, the name given to the downloaded package was /var/tmp/os-package.tgz.

    Note:

    It only takes a few seconds to run and does not need a reboot.

    Do not add os-package when there is already a 'pending' set, else you will get no benefit from os-package. Thus, if you see the following notice after adding os-package, you'll need to rollback the software:
  3. If you had to rollback the software in the previous step due to a pending set, you need to repeat steps 1 and 2 to install os-package.

Once os-package has successfully installed, you can proceed to upgrade to a higher version of Junos OS. If the system reboots before you've had a chance to upgrade Junos OS, os-package deactivates itself, and you will have to install os-package again. If you ever want to delete os-package, you can use the request system software delete os-package CLI command.

Upgrading Junos OS with Upgraded FreeBSD

Note:

If you are upgrading or installing Junos OS on a VM host, see Installing, Upgrading, Backing Up, and Recovery of VM Host.

Starting in Junos OS Release 15.1, certain hardware platforms run an upgraded FreeBSD kernel (FreeBSD 10.x or later) instead of FreeBSD 6.1. The information in this section is about upgrading from Junos OS without upgraded FreeBSD (that is, based on FreeBSD 6.1) to Junos OS with upgraded FreeBSD. It does not address upgrading using ISSU. There are certain limitations to using ISSU when upgrading to Junos OS with upgraded FreeBSD. For more information on using ISSU, see Example: Performing a Unified ISSU.

When you are upgrading to a different release of Junos OS, you usually use the request system software add validate command. The validate option checks the candidate software against the current configuration of the device to ensure they are compatible. (Validate is the default behavior when the software package being added is a different release.) However, there are circumstances under which you cannot validate the running configuration in this way. One such circumstance is when you are upgrading to Junos OS with upgraded FreeBSD from Junos OS based on FreeBSD 6.1. Another such circumstance is when you are updating between different releases of Junos OS with upgraded FreeBSD, and the newest version of FreeBSD uses system calls that are not available in earlier versions of FreeBSD.

If you are upgrading between releases that cannot use direct validation, you need to specify one of the following on the request system software add operational mode command when you upgrade:

  • The no-validate option—this option does not validate the software package against the current configuration. Therefore, the current configuration might fail once you upgrade the system. Choose this option for the first time you upgrade to the newer version.

  • The validate-on-host option—this option validates the software package by comparing it to the running configuration on a remote Junos OS host. Be sure to choose a host that you have already upgraded to the newer version of software.

  • The validate-on-routing-engine option—(for systems with redundant REs) this option validates the software package by comparing it to the running configuration on a Routing Engine in the same chassis. Use this option when you have already upgraded the other Routing Engine to the newer version.

If you are upgrading between releases that cannot use direct validation, another approach would be to validate on a different host. It does not matter where that other host is, as long as you can reach it with NETCONF over SSH (see Establishing an SSH Connection for a NETCONF Session). The target system uses the network to contact the other host, run the validation and authentication, and return the result.

The following sections contain two procedures and one matrix. The procedures cover (1) upgrading to Junos OS with upgraded FreeBSD from Junos OS based on FreeBSD 6.1 and (2) upgrading between different releases of Junos OS with upgraded FreeBSD. To determine whether you are upgrading between releases that can use direct validation or not, see Upgrading Junos OS with Upgraded FreeBSD.

Note:

Before installing software on a device that has one or more custom YANG data models added to it, back up and remove the configuration data corresponding to the custom YANG data models from the active configuration. For more information see Managing YANG Packages and Configurations During a Software Upgrade or Downgrade.

Determine Which Package or Packages to Install

To determine which software package to install to upgrade to Junos OS with upgraded FreeBSD, you will need to consult the Feature Explorer and Table 1. In using Table 1, be aware of the following:

  • You can skip no more than two releases when upgrading (or downgrading). That means you can upgrade only to one of the three releases subsequent to your current release. If you want to upgrade across more releases than this, you need to perform multiple upgrades.

  • Notice that Table 1 separates its information between security devices and routing or switching devices. This is because security devices have been released on a different release sequence than routing and switching devices, and this in turn determines what constitutes skipping no more than two releases. Whereas routing and switching platforms have released software in each main release, security platforms have had only the following releases: 17.4, 17.3, 15.1X49, and 12.3X48. Therefore, for example, for a router to upgrade from Release 12.3 to the first release supporting Junos OS with upgraded FreeBSD (Release 15.1) would take multiple upgrades. But for a security device to upgrade from Release 12.3 to the first release supporting Junos OS with upgraded FreeBSD (Release 17.3) would take only one upgrade.

We recommend you upgrade to a 64-bit image of Junos OS with upgraded FreeBSD. In Junos OS releases earlier than 15.1, the partition swap pages are counted as part of the memory file system partition. Using this method leaves 4 GB of memory as the maximum that is theoretically accessible when you are using a 32-bit image. However, when Junos OS with upgraded FreeBSD is run, the system only counts the actual partition size, which leaves around 3.4 GB of available physical address space, or only 3 GB of usable RAM.

To determine which installation package and procedure you require:

  1. See the Junos kernel upgrade to FreeBSD 10+ entry in Feature Explorer.

    Click the link or go to https://pathfinder.juniper.net/feature-explorer/, type freebsd, and select Junos kernel upgrade to FreeBSD 10+.

    You will see a listing of platforms that run Junos OS with upgraded FreeBSD and the software release it was introduced in. Different platforms first support Junos OS with upgraded FreeBSD in different releases. Use this listing to find which release you need to install for your device to upgrade to Junos OS with FreeBSD.

  2. Consult Table 1 to determine the upgrade path to follow.

    • Determine which release your device is currently running.

      Look first at the release sequence and then at the second column and find the release running on your device.

    • Determine which release you need to install.

      The third column will give you the earliest release you need to install for your platform type to be running Junos OS with upgraded FreeBSD.

    Table 1: Upgrade Path to Junos OS with the Upgraded FreeBSD

    Release Sequence

    Current Router’s Junos OS Release

    Earliest Release Supporting Junos OS with Upgraded FreeBSD

    Upgrade Path

    Example

    Routing and Switching

    Earlier than Release 12.3

    15.1

    Upgrade in multiple steps, skipping no more than two releases in one upgrade.

    To upgrade from Release 12.1, upgrade first to Release 13.1, then to Release 14.1, then from there to either Release 15.1 or 16.1.

    12.3 to 13.2

    15.1

    Upgrade in two steps.

    To upgrade from Release 12.3, first upgrade to Release 13.3, then upgrade to Release 15.1.

    To upgrade from Release 13.2, first upgrade to Release 14.2, then upgrade to Release 15.1.

    13.3 to 14.2

    15.1

    Upgrade in a single step.

    To upgrade from Release 13.3, upgrade directly to Release 15.1.

    To upgrade from Release 14.2, upgrade directly to either Release 15.1 or 16.1.

    Security

    12.3 to 17.2

    17.3

    Upgrade in a single step.

    To upgrade from Release 12.3X48, upgrade directly to Release 17.3.

    15.1 to 17.2

    17.3

    Upgrade in a single step.

    To upgrade from Release 15.1X49, upgrade directly to Release 17.3.

    15.1 to 17.3

    17.4

    Upgrade in a single step.

    To upgrade from Release 15.1x49-D80, upgrade directly to Release 17.4.
    Note:

    You can also downgrade from Junos OS Release with upgraded FreeBSD to Junos OS based on FreeBSD 6.1 as long as the path complies with the Junos OS policy of skipping at most two earlier releases.

  3. Download the Junos OS with upgraded FreeBSD package.

    For a table listing the package prefixes, see Junos OS and Junos OS Evolved Installation Package Names. For more on the names of package name , see Changes in Package Names for Junos OS with Upgraded FreeBSD.

  4. Continue installing a software package on a device by using one of the following procedures:

Install Junos OS with Upgraded FreeBSD Over Junos OS

Upgrading to Junos OS with upgraded FreeBSD reformats the file system. Only specific files and directories are preserved unless precautions are taken. By default, the upgrade process preserves only the following directories:

  • /config

  • /etc/localtime

  • /var/db

  • /var/etc/master.passwd

  • /var/etc/inetd.conf

  • /var/etc/pam.conf

  • /var/etc/resolv.conf

  • /var/etc/syslog.conf

  • /var/etc/localtime

  • /var/etc/exports

  • /var/etc/extensions.allow

  • /var/preserve

  • /var/tmp/baseline-config.conf

  • /var/tmp/preinstall_boot_loader.conf

Note:

In /var/db/config, up to 10 rollback configurations will be saved, depending on the configuration file size.

Note:

On EX2300 and EX3400 switches, the following directories are not applicable:

  • /etc/localtime

  • /var/etc/localtime

  • /var/etc/exports

  • /var/preserve

  • /var/tmp/preinstall_boot_loader.conf

Before you begin, if you have important files in other directories that are not preserved, copy them from the router or switch to a secure location before upgrading the router or switch.

CAUTION:

If you do a media install (either USB or network), the system is wiped and re-partitioned completely. Before you begin, if you have important files, copy them from the device to a secure location before upgrading the device.

To install Junos OS with upgraded FreeBSD over plain Junos OS:

  1. Enter the request system software add install-package-name.tgz no-validate command from the operational mode in the CLI:
    Note:

    The no-copy option is enabled by default.

    Use the no-validate option with the request system software add command. If you leave out the no-validate option, the command uses the validate option by default, and direct validation of the running configuration does not work for upgrading to Junos OS with upgraded FreeBSD from Junos OS based on older versions of the FreeBSD kernel.

    Note:

    You can also use the reboot option along with the request system software add command, but it is not recommended to do this in a single step while upgrading from a FreeBSD 6.1 based Junos OS to Junos OS with upgraded FreeBSD.

    Note:

    To validate the current configuration on an upgrade to Junos OS with upgraded FreeBSD from Junos OS, use the request system software validate on (Junos OS with Upgraded FreeBSD) command.

    The new Junos OS image is installed on the device.

  2. Reboot the device to start the new software using the request system reboot command:
    Note:

    You must reboot the device to load the newly installed version of Junos OS on the device.

    To terminate the installation, do not reboot the device. Instead, finish the installation and then issue the request  system software delete install-package-name.tgz command. This is your last chance to stop the installation (not applicable on EX2300 and EX3400 platforms).

    The software is loaded when you reboot the system. Installation can take between 5 and 10 minutes. The device then reboots from the boot device on which the software was just installed. When the reboot is complete, the device displays the login prompt.

    While the software is being upgraded, the Routing Engine on which you are performing the installation does not route traffic.

  3. Log in and issue the show version command to verify the version of the software installed.
    Note:

    The output shows the OS kernel, OS runtime, and other packages installed on the device.

Install Junos OS with Upgraded FreeBSD Over Junos OS with Upgraded FreeBSD of a Different Release

CAUTION:

If you do a media install (either USB or network), the system is wiped and re-partitioned completely. Before you begin, if you have important files, copy them from the device to a secure location before upgrading the device.

To install Junos OS with upgraded FreeBSD over Junos OS with upgraded FreeBSD of a different release:

  1. Enter the request system software add package-name validate reboot command from the operational mode in the CLI:
    Note:

    Because Junos OS Release 21.2R1 runs on FreeBSD 12, which uses system calls not available on FreeBSD 10 or 11, you must include one of the following options instead of the validate option on the request system software add command when installing the package:

    • no-validate

    • validate-on-host

    • validate-on-routing-engine
    Note:

    The no-copy option is enabled by default.

    Use the validate and reboot options with the request system software add command. The command uses the validate option by default. We encourage users to validate using the validate option when upgrading from Junos OS to Junos OS or from Junos OS with upgraded FreeBSD to Junos OS with upgraded FreeBSD.

    If you leave out the reboot option, you can take care of that in a separate reboot step.

    The new Junos OS image is installed on the device.

  2. Verify the installation of Junos OS with upgraded FreeBSD.
    Note:

    The output shows the OS kernel, OS runtime, and other packages installed on the device.

See Also

Downgrading from Junos OS with Upgraded FreeBSD

Starting in Junos OS Release 15.1, certain hardware platforms run a Junos OS based on an upgraded FreeBSD kernel instead of older versions of FreeBSD. To find which platforms support Junos OS with upgraded FreeBSD, see Feature Explorer, enter freebsd, and select Junos kernel upgrade to FreeBSD 10+.

This topic discusses the different procedures for downgrading from a release of Junos OS with upgraded FreeBSD. One procedure describes how to downgrade to legacy Junos OS. The other procedures describe how to downgrade to an earlier release of Junos OS with upgraded FreeBSD.

The main difference between the procedures is whether to use the validate or no-validate option with the request system software add command. If you downgrade between two versions of legacy Junos OS, validate works. Similarly, if you downgrade from Junos OS with upgraded FreeBSD Release 18.1 or later to Release 17.4 or later, validate works. However, there is one set of circumstances in which the no-validate option must be used when downgrading between Junos OS with upgraded FreeBSD releases, and that is when you downgrade from a Junos OS with upgraded FreeBSD Release 17.4 or later to a release earlier than 17.4, that is, Junos OS releases 15.1 through 17.3.

Select and perform the procedure that matches your set of circumstances.

Downgrading from Junos OS with Upgraded FreeBSD to Legacy Junos OS

If you have previously upgraded to Junos OS with upgraded FreeBSD, you can downgrade to an earlier version of Junos OS (that is, legacy Junos OS) as long as the downgrade conforms to the Junos OS policy of skipping at most two earlier releases.

This example uses the package /var/tmp/jinstall-13.3R2.7-domestic-signed.tgz to install legacy Junos OS on the primary Routing Engine (re0).

To downgrade from Junos OS with upgraded FreeBSD to legacy Junos OS:

  1. Enter the request system software add package-name no-validate reboot command from the operational mode in the CLI.

    Use the no-validate and reboot options with the request system software add command. If you leave out the no-validate option, the command uses the validate option by default, and direct validation of running configuration does not work for downgrading to legacy Junos OS from Junos OS with upgraded FreeBSD.

    If you leave out the reboot option, you can take care of that in a separate reboot step.

    The following example uses the re0 option:

  2. Verify the downgrade of the software package.

    The output shows the OS kernel, OS runtime, and other packages installed on the device.

Downgrading from Junos OS with Upgraded FreeBSD Release 17.4 or Later to Release 15.1 Through 17.3

This procedure is applicable when downgrading from Junos OS with Upgraded FreeBSD Release 17.4 or later to an earlier release of Junos OS with Upgraded FreeBSD.

Note:

If you have important files in other directories, copy them from the router or switch to a secure location before upgrading the router or switch.

To downgrade from Junos OS with upgraded FreeBSD Release 17.4 or later to a Release 15.1 through 17.3:

  1. Enter the request system software add package-name no-validate reboot command from the operational mode in the CLI:

    Use the no-validate and reboot options with the request system software add command. If you leave out the no-validate option, the command uses the validate option by default, and direct validation of running configuration does not work for downgrading to an earlier release of Junos OS with upgraded FreeBSD from Junos OS with upgraded FreeBSD Release 17.4 or later.

    If you leave out the reboot option, you can take care of that in a separate reboot step.

    The new Junos OS image is installed on the device.

  2. Verify the installation of Junos OS with upgraded FreeBSD:

    The output shows the OS kernel, OS runtime, and other packages installed on the device.

Downgrading from Junos OS with Upgraded FreeBSD Release 17.3 or Earlier to Release 15.1 Through 17.2

This procedure is applicable when downgrading from Junos OS with Upgraded FreeBSD Releases 17.3 through 15.1 to an earlier release of Junos OS with Upgraded FreeBSD.

Note:

If you have important files in other directories, copy them from the router or switch to a secure location before upgrading the router or switch.

To downgrade from Junos OS with upgraded FreeBSD Release 17.3 or earlier to an earlier release of Junos OS with upgraded FreeBSD:

  1. Enter the request system software add package-name validate reboot command from the operational mode in the CLI:

    Use the validate and reboot options with the request system software add command. The command uses the validate option by default. If you leave out the reboot option, you can take care of that in a separate reboot step.

    The new Junos OS image is installed on the device.

  2. Verify the installation of Junos OS with upgraded FreeBSD:

    The output shows the OS kernel, OS runtime, and other packages installed on the device.

Downgrading from Junos OS with Upgraded FreeBSD Release 18.1 or Later to Release 17.4 or Later

This procedure is applicable when downgrading from Junos OS with Upgraded FreeBSD Releases 18.1 or later to a Junos OS with Upgraded FreeBSD Release 17.4 or later.

Note:

If you have important files in other directories, copy them from the router or switch to a secure location before upgrading the router or switch.

To downgrade from Junos OS with upgraded FreeBSD Release 18.1 or later to Junos OS with Upgraded FreeBSD Release 17.4 or later:

  1. Enter the request system software add package-name validate reboot command from the operational mode in the CLI:

    Use the validate and reboot options with the request system software add command. The command uses the validate option by default. If you leave out the reboot option, you can take care of that in a separate reboot step.

    The new Junos OS image is installed on the device.

  2. Verify the installation of Junos OS with upgraded FreeBSD:

    The output shows the OS kernel, OS runtime, and other packages installed on the device.

Related Documentation