Upgrading PICOS from Version 3.0 or Later Using Upgrade2
- Tracy Yang (Unlicensed)
Introduction
NOTE：
|
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:
- If PICOS has a license installed before the upgrade, the license will be copied and activated after the upgrade. Please check this section for the PICOS Licenses.
- If there is no license installed prior to upgrade, upgrade2 process can proceed but only the first four ports and the first two uplink ports (if exist) on the newly upgraded system can be used.
- If the license has expired, it is not allowed to upgrade a major release (e.g. 4.1 to 4.2). However, it will not affect upgrading to a minor release (e.g. 4.1.1 to 4.1.2).
- 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.
- An upgrage2.log file in /cftmp directory will be created which will contain all the logs related to the upgrade2 process.
- All X86 platforms share one installation and upgrade package with the name fixed as: onie-installer-picos-VERSION-x86.bin, where VERSION is the release version. X86 platform are listed below:
• Edgecore AS4630-54PE
• Edgecore AS5712-54X
• Edgecore AS5812-54T
• Edgecore AS5812-54X
• Edgecore AS7312-54X
• Edgecore AS7326-56X
• Edgecore AS7712-32X
• Edgecore AS7726-32X
• Edgecore AS7816-64X
• Edgecore AS5835-54X
• DELL N3248P-ON
• DELL N3248PXE-ON
• DELL N3224PX-ON
• DELL N3248X-ON
• DELL S4048-ON
• DELL S4148F-ON
• DELL S4148T-ON
• DELL S4128F-ON
• DELL S5224F-ON
• DELL S5296F-ON
• DELL S5212F-ON
• DELL S5248F-ON
• DELL Z9100-ON
• DELL Z9264F-ON
• DELL N3224T-ON
• DELL S4128T-ON
Usage of Upgrade2 Command
admin@Xorplus:~$ sudo upgrade2 USAGE Upgrade system with local new image SYNOPSIS upgrade2 [image_name] [factory-default] [use-prev-config] [backup-file=(*.lst)] DESCRIPTION image_name - Image with bin format file(*.bin) factory-default - Recovery configuration to factory default use-prev-config - Use previous config, and syslog trace backup-file=(*.lst) - Specify a user defined backup list |
For PICOS go2cli version, users can run the upgrade2 command under CLI operational mode or configuration mode:
admin@Xorplus> upgrade2 image-file xx.bin Possible completions: <[Enter]> Execute this command backup-file Specify a user defined backup list(*.lst) factory-default Recovery configuration to factory default use-prev-config Use previous configuration, and syslog trace admin@Xorplus# run upgrade2 image-file xx.bin Possible completions: <[Enter]> Execute this command backup-file Specify a user defined backup list(*.lst) factory-default Recovery configuration to factory default use-prev-config Use previous configuration, and syslog trace
PICOS upgrade is done via the command "upgrade2" in bash (launching a shell script named "upgrade2.sh"). This script will upgrade the image and backup configuration files automatically.
Image name is in the form of .bin, which should be copied to the /cftmp directory before running upgrade2 command.
The option factory-default is used to reset the configuration to factory default when performing upgrade, but it retains the license files from the previous version.
If you want to use the old configuration file in the new version, you can add the use-prev-config option when issuing upgrade2 command. The usage of option use-prev-config is described in the section Usage of Use-prev-config Option.
If you want to backup a file during upgrade, use backup-file=(*.lst) option to define your own backup file list. The usage of backup-file=(*.lst) option is described in the section Usage of Backup-file=(*.lst) Option.
Usage of use-prev-config Option
The main function of use-prev-config option is to decide whether to load the previous configuration file after a system reboot when performing upgrade2 or rollback to another version. If there is a command line in the old version configuration file that is not supported in the new system, with use-prev-config option that command will be skipped and continue loading the remaining configuration.
By default, upgrade2 or rollback is performed without use-prev-config option.
The following table describes the usage of use-prev-config option when performing upgrade2 or rollback.
upgrade2 (From old version to new version) | rollback (From current version to old version) | |
with use-prev-config | 1. Load the configuration file of old version after system reboot. 2. If there is a command line in the old version configuration file that is not supported in the new system, skip it and continue loading the remaining configuration. | 1. Load the configuration file of current version after system reboot. 2. If there is a command line in the current configuration file that is not supported in the old system, skip it and continue loading the remaining configuration. |
without use-prev-config | 1. Load the configuration file of old version after reboot. 2. If there is a command in the old version configuration file that is not supported in the new system, load default configuration file. | Load the old version configuration file after rebooting. |
Usage of Backup-file=(*.lst) Option
During the upgrade process, the switch can automatically back up the following files in the following directories from the previous PICOS system:
/etc/passwd /etc/shadow /etc/group /etc/gshadow /etc/resolv.conf ./etc/network/interfaces /etc/picos/picos_start.conf /etc/picos/switch-public.key /etc/picos/pica.lic /pica/config/pica_startup.boot /pica/config/pica.conf.01 /pica/config/pica.conf.02 /pica/config/pica.conf.03 /pica/config/pica.conf.04 /pica/config/pica.conf.05 /ovs/ovs-vswitchd.conf.db /ovs/function.conf.db /ovs/config/meters /ovs/config/groups /ovs/config/flows /ovs/var/lib/openvswitch/pki/ /var/log/report_diag.log /var/log/report_diag.log.1 /var/log/report_diag.log.2 /var/log/report_diag.log.3 /var/log/report_diag.log.4 /var/log/report_diag.log.5 /cftmp/upgrade.log /cftmp/upgrade2.log /cftmp/auto/ |
If you want to save user files that are not in the above default backup file list, you need to first create or specify a .lst file and then add all those files that need to be backed up to this .lst file. You can use the backup-file=(*.lst) option to achieve this, where (*.lst) is the user created file with .lst format or specify the file path to this file, for example:
admin@XorPlus:~$ sudo upgrade2 backup-file=/admin/back_files.lst onie-installer-picos-as7312_54x-4.0.1-cc8d268.bin
For example, if you want to backup /home/admin/a.txt file during the process, then add /home/admin/a.txt to back_files.lst. In this example, back_files.lst is a user created file. The user has already added the file to back_files.lst that needs to be saved in the event of power off.
admin@XorPlus:~$ sudo upgrade2 backup-file=/admin/back_files.lst onie-installer-picos-as7312_54x-4.0.1-cc8d268.bin
The above operations ensure that user can backup their important files with backup-file=(*.lst) option during the upgrade process.
Upgrade Procedure
The upgrading procedure in this document gives an example of upgrading from PICOS 4.0.0 to 4.0.1 using upgrade2 command on AS7312_54X switch.
Step1 Copy the upgrade package (in the form of .bin) and the MD5 file to /cftmp directory by either FTP, TFTP, HTTP or SCP according to the actual upgrade environment. The following example uses the SCP method.
admin@Xorplus:~$ sudo scp pica8@10.10.50.22:/tftp/build/4.0.1/as7312_54x/onie-installer-picos-as7312_54x-4.0.1-cc8d268.bin /cftmp admin@Xorplus:~$ sudo scp pica8@10.10.50.22:/tftp/build/4.0.1/as7312_54x/onie-installer-picos-as7312_54x-4.0.1-cc8d268.bin.md5 /cftmp
NOTE:
- If management VRF is enabled, and the FTP/TFTP/HTTP/SCP server is connected via the Eth0/1 port, you need to add the string sudo ip vrf exec mgmt-vrf before the SCP command when executing the scp operation. The format is as follows:
admin@Xorplus:~$ sudo ip vrf exec mgmt-vrf scp pica8@10.10.50.22:/tftp/build/4.0.1/as7312_54x/onie-installer-picos-as7312_54x-4.0.1-cc8d268.bin /cftmp
admin@Xorplus:~$sudo ip vrf exec mgmt-vrf scp pica8@10.10.50.22:/tftp/build/4.0.1/as7312_54x/onie-installer-picos-as7312_54x-4.0.1-cc8d268.bin.md5 /cftmp
If sudo ip vrf exec mgmt-vrf is not added, find the next hop routing information from the default VRF. For the usage of VRF, refer to the VRF Configuration Guide.
- For PICOS go2cli version, users can run the scp command under CLI operational mode or configuration mode:
Φ Download a file:
file scp get remote-file <remote-file-path> [local-file local-file-path] ip-address <ip-address>:<port> [vrf <mgmt-vrf | vrf-name>]
Φ Upload a file:
file scp put local-file <local-file-path> [remote-file <remote-file-path>] ip-address <ip-address>:<port> [vrf <mgmt-vrf | vrf-name>]
Step2 Execute the sync operation.
admin@Xorplus:~$ sync
Step3 Change directory to /cftmp.
admin@Xorplus:~$ cd /cftmp
Step4 Run upgrade2 command to begin upgrading.
admin@Xorplus:~$ sudo upgrade2 onie-installer-picos-as7312_54x-4.0.1-cc8d268.bin
After finishing upgrade, the switch will reboot automatically, the system will come up running the new network operating system.
NOTE：
|
Rollback Procedure
The 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.
NOTE： admin@Xorplus:~$ sudo nos-rollback USAGE Rollback to the previous system after next reboot SYNOPSIS nos-rollback [use-prev-config] DESCRIPTION use-prev-config - Use previous config, and syslog trace For details about the usage of use-prev-config, please refer to Usage of Use-prev-config Option. |
The rollback procedure is as follows:
Step1 Run nos-rollback command for manually rollback.
admin@Xorplus:~$ sudo nos-rollback
Step2 Reboot system manually to finish rollback.
admin@Xorplus:~$ sudo reboot
You need to manually run reboot command to reboot the system after you have issued "nos-rollback" command. After rebooting successfully, the system will come up running the previous version of network operating system.
Verifying Version after Upgrade
admin@Xorplus:~$ version Copyright (C) 2009-2021 Pica8, Inc. =================================== Hardware Model : as7312_54x Linux System Version/Revision : 4.0.1/cc8d268 Linux System Released Date : 5/18/2021 L2/L3 Version/Revision : 4.0.1/cc8d268 L2/L3 Released Date : 5/18/2021 OVS/OF Version/Revision : 4.0.1/cc8d268 OVS/OF Released Date : 5/18/2021
Appendix: Troubleshooting Installation/Upgrade Failure on AS7326-56X
Installation or upgrade failure (for example, the switches cannot boot up after install) may occur on the old AS7326-56X hardware models (revision is R01F and before). When booting PICOS on AS7326-56X and detect hardware rev R01F, the system will log a warning message to prompt the hardware revision R01F is a pre-production hardware reversion: "This hardware revision R01F is a pre-production hardware rev, PICOS has applied a work around to work with PICOS. Support will be provided on a best effort basis".
To work around the issue, first we need to check the “Label Revision”. If it is an old hardware model (revision is R01F or before), then, we can perform the following provided solution after installation/upgrade to solve the problem.
Check Label Revision
Under ONIE prompt, run “onie_syseeprom” to get the “Label Revision”.
ONIE:/ # onie-syseeprom TlvInfo Header: Id String: TlvInfo Version: 1 Total Length: 166 TLV Name Code Len Value -------------------- ---- --- ----- Manufacture Date 0x25 19 04/27/2019 02:10:06 Label Revision 0x27 4 R01B Platform Name 0x28 27 x86_64-accton_as7326_56x-r0 ONIE Version 0x29 13 2018.05.00.05 Manufacturer 0x2B 6 Accton Diag Version 0x2E 7 0.0.1.0 Base MAC Address 0x24 6 80:A2:35:81:D5:F0 Serial Number 0x23 14 732656X1916012 Country Code 0x2C 2 TW Part Number 0x22 13 FP4ZZ7656005A Product Name 0x21 15 7326-56X-O-AC-F MAC Addresses 0x2A 2 256 Vendor Name 0x2D 6 Accton CRC-32 0xFE 4 0xC3D3F2DE Checksum is valid. ONIE:/ #
Solution
You can follow the steps below after installation/upgrade, to fix the problem of installation and upgrade failure on the old AS7326-56X hardware model (revision R01F or before).
Step1 Power cycle the switch.
Step2 From the GRUB menu, choose “ONIE” to enter ONIE GRUB menu:
+----------------------------------------------------------------------------+
| PicOS |
|*ONIE |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
+----------------------------------------------------------------------------+
Use the ^ and v keys to select which entry is highlighted.
Press enter to boot the selected OS, `e' to edit the commands
before booting or `c' for a command-line.
Step3 From ONIE GRUB menu, choose “ONIE: Rescue” to launch ONIE in Rescue mode.
GNU GRUB version 2.02~beta2+e4a1fe391 +----------------------------------------------------------------------------+ | ONIE: Install OS | |*ONIE: Rescue | | ONIE: Uninstall OS | | ONIE: Update ONIE | | ONIE: Embed ONIE | | DIAG: Accton Diagnostic | | | | | | | | | | | | | +----------------------------------------------------------------------------+
Step4 Press Enter to display the ONIE prompt.
Step5 Mount PicOS partition with label is “PicOS”.
ONIE:/ # blkid /dev/sda7: LABEL="User-Data" UUID="be63cef8-4560-4c48-ab5a-8f7ced5a950b" /dev/sda6: LABEL="PicOS2" UUID="f589e53f-4cd1-44ba-8384-f339f4e2b2ac" /dev/sda5: LABEL="PicOS" UUID="8ca5f7ed-5a15-4a2a-944c-4d8872647bf5" /dev/sda4: LABEL="PICOS-GRUB" UUID="782a1372-4b66-4783-b920-dab1df8ec6e4" /dev/sda3: LABEL="ACCTON-DIAG" UUID="3e4117d0-1926-472a-9d9e-08883df83d40" /dev/sda2: LABEL="ONIE-BOOT" UUID="1a90abd8-f065-4f7a-90a0-af122b8805fa" ONIE:/ # ONIE:/ # mount /dev/sda5 /mnt
Step6 Execute the following command to modify the I2C access address.
ONIE:/ # sed -I "s/0x57/0x56/" /mnt/etc/rc_hw.sh ONIE:/ # sync
Step7 Unmount the PicOS partition.
ONIE:/ # unmount /dev/sda5
Step8 Reboot the switch.
ONIE:/ # reboot
Copyright © 2025 Pica8 Inc. All Rights Reserved.