1 Introduction
2 Preparation before Upgrading
3 Upgrading Notes
4 Usage of Upgrade2 Command
- 4.1 Usage of use-prev-config Option
- 4.2 Usage of Backup-file=(*.lst) Option
5 Upgrade Procedure
6 Rollback Procedure
7 Verifying Version after Upgrade
8 Appendix: Troubleshooting Installation/Upgrade Failure on AS7326-56X
- 8.1 Check Label Revision
- 8.2 Solution

Introduction

NOTE：

This document only applies to PICOS upgrade from version 3.0 or later version using command upgrade2. If you want to upgrade PICOS from the version before 3.0, use ONIE installation process described in Installing PICOS on Bare Metal Switches.
You cannot do a standard upgrade from 3.x to 4.x. This is because 3.x config and 4.x config are not compatible, and PICOS 4.x will not be able to boot with 3.x config after the upgrade. In order to upgrade from 3.x to 4.x, you MUST convert the configuration to 4.x before upgrade, see section Converting Configuration to 4.x before Upgrade (when Upgrade from Version 3.x to 4.x) in this guide for details.

PICOS 4.0.0 and later versions have multiple system partitions including PicOS (partition size: 2G), PicOS2(partition size: 2G) and User-Data partitions. Among them, PicOS and PicOS2 are two independent system boot partitions. One of them is the active partition on which the running system resides, and the other is the inactive partition. The two-system-boot-partition feature allows the system to revert to a previous version of the installed software package when it fails to upgrade PICOS by using upgrade2 command.

User-Data partition is a reserved partition which is not affected by ONIE installer and upgrade unless user manually removes it. User-Data partition uses all the available space left on the disk. Users can use this partition to store files and data.

When running upgrade2, the new version PICOS image will be installed and boot onto the inactive partition automatically. Afterwards, the inactive partition will switch to active partition automatically when the switch boots up normally after the upgrading is finished, while the other partition where the old version resides will become the inactive partition.

Upgrade2 method supports system rollback function. The "nos-rollback" command can be used to revert to a previous version of the installed software package. Moreover, if it fails to upgrade, the system can automatically rollback to the old system. This can reduce the network interruption risk due to the failure of system upgrade process and ensure the systems’ continuous availability. You can refer to section Rollback Procedure in this page for details.

The system also supports the upgrade method for PICOS version upgrade, the usage is the same as before, you can refer to the document Upgrading PICOS from Version 4.0.0 or Later Using Upgrade Command for details of upgrade method. We recommend using upgrade2 method to upgrade the NOS as it includes system backup and rollback features.

Preparation before Upgrading

Table 1. Checklist before Upgrading

No.	Checking Items	Checking Standard	Results
1	Checking the Running PICOS Version	The currently running system software version is lower than the software version to be installed.
2	Building Upgrade Environment	Build an upgrade environment according to the need.
3	Getting the Required Upgrade Software	Obtain the required supported upgrade software.
4	Backing up Important Data	All the important data was backed up.
5	Converting Configuration to 4.x before Upgrade (when Upgrade from Version 3.x to 4.x)	4.x configuration is generated from 3.x configuration file.

Checking the Running PICOS Version

Use the version command to check the version of the running system software.

admin@Xorplus:~$ version
Copyright (C) 2009-2021 Pica8, Inc.
===================================
Hardware Model                : as7312_54x
Linux System Version/Revision : 4.0.0/4b5f523
Linux System Released Date    : 4/27/2021
L2/L3 Version/Revision        : 4.0.0/4b5f523
L2/L3 Released Date           : 4/27/2021
OVS/OF Version/Revision       : 4.0.0/4b5f523
OVS/OF Released Date          : 4/27/2021

Building Upgrade Environment

Please make sure that you have set up an HTTP, TFTP or FTP protocol upgrading environment, the basic requirements are as follows:

PC can log in to the device through serial or SSH.

The communication between the server and the device works well.

The upgrading file used by the device has already been stored on the server.

Getting the Required Upgrade Software

Please contact Pica8 technical support engineers at the following webpage for the latest version of upgrade software.

https://www.pica8.com/support/

Backing up Important Data

Before upgrading, save the important data, e.g. the configuration file, to the local PC through FTP or TFTP, and then upload it to the switch after the upgrade is completed if needed.

Converting Configuration to 4.x before Upgrade (when Upgrade from Version 3.x to 4.x)

NOTE:

When upgrade PICOS from version 3.x to 4.x:

When executing the upgrade2 command, no other option is supported except the option image_name.
Backup the configuration file before upgrading.
The OVS configuration for crossflow before the upgrade will be saved and restored automatically after the upgrade.

You cannot do a standard upgrade from 3.x to 4.x. This is because 3.x configuration and 4.x configuration are not compatible, and PICOS 4.x will not be able to boot with 3.x configuration after the upgrade.

In order to upgrade from 3.x to 4.x, follow the procedure below to prepare the 4.x configuration file before upgrade:

Create directory /pica/config-4.x/.
Contact Pica8 support to convert the 3.x configuration to 4.x configuration in configuration file pica_startup.boot.
Copy the 4.x configuration file (converted from 3.x configuration file in step 2) into the directory /pica/config-4.x just created. After upgrading from 3.x to 4.x and after rebooting, PICOS 4.x will look for the 4.x configuration in /pica/config-4.x.

After completing these steps, the 4.x configuration file is ready and you can continue with the upgrade process.

If these steps are not performed before upgrade, the system will load the default configuration file of 4.x and the 3.x configuration will not be loaded after upgrade. However, if this happens unexpectly, you can also remedy by loading the 4. x configuration file after upgrade, follow the steps below:

Copy the 4.x configuration file pica_startup.boot (already converted from 3.x configuration file) into the directory /pica/config/.
Run the load override command to load 4. x configuration.

admin@PICOS# load override /pica/config/pica_startup.boot
admin@PICOS# Loading config file...
Config file was loaded successfully.

Upgrading Notes

This upgrade2 guide only applies to PICOS upgrade from version 4.0.0 or the later versions.

When using upgrade2 to upgrade PICOS, you should make sure the “PicOS2” partition exists.

When using upgrade2 to upgrade PICOS, you should make sure the partition type is GPT.

When using upgrade2 to upgrade PICOS, you should make sure that ONIE is pre-loaded.

License check is performed for upgrade:

You can log in to a device through its console port or using SSH. After successful login, you can run commands on the command line interface (CLI) to upgrade the device.

When using FTP/TFTP to download the image, user should verify that the "binary" mode is being used. If the "binary" transfer mode is not being used, the image might be modified during download, and the upgrade will fail during the MD5 check.
The image is platform dependent, that is, the image should be consistent with the platform, otherwise the upgrade script will abort.

Upgrading PICOS from Version 3.0 or Later Using Upgrade2