Introduction

PICOS supports upgrade2 method for system upgrade from version 2.11, it can be implemented when needing to upgrade the system from version 2.11 or the later versions.

The system will end up with three partitions, PICOS, PICOS-BAK and PICOS2 after it has finished upgrading with upgrade2 implemented. Among them, PICOS and PICOS2 are mutually the backup system partitions. The new version PICOS image will be installed and boot onto the inactive partition automatically. 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 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 for details.

The system still supports the upgrade method for PICOS version upgrade, the usage is the same as before. As this article only introduces upgrade2 method, you can refer to the document Upgrading PicOS from Release 2.1 or Later Using Upgrade for details of upgrade method. We recommend using upgrade2 method to upgrade the NOS as there are functions of system backup and rollback.

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 supporting upgrade software.
4	Backing up Important Data in Flash	All the important data in Flash is backed up.
5	Checking Total Disk Space	The total disk space should be more than 3700M.
6	Checking the Partition Type	The type of partition should be GPT.
7	Checking Whether ONIE is Pre-loaded	The ONIE should be pre-loaded.

Checking the Running PICOS Version

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

admin@Xorplus$version
Copyright (C) 2009-2018 Pica8, Inc.
===================================
Hardware Model                : ag6248c
Linux System Version/Revision    : 2.11.1/2d5c7f4
Linux System Released Date       : 05/29/2017
L2/L3 Version/Revision           : 2.11.1/2d5c7f4
L2/L3 Released Date             : 05/29/2017
OVS/OF Version/Revision        : 2.11.1/2d5c7f4
OVS/OF Released Date          : 05/29/2017

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 Telnet.

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 website for the latest version of upgrade software.

http://www.pica8.com/support/customer

Backing up Important Data in Flash

Before upgrading, save the important data in Flash to the local PC through FTP or TFTP, and then upload it to the switch after the upgrade is completed.

Checking Total Disk Space

Use the gdisk command to check the available flash space. When using upgrade2 to upgrade switch, you should make sure the total disk space is more than 3700M.

admin@Xorplus$sudo gdisk /dev/sda
GPT fdisk (gdisk) version 0.8.5

Partition table scan:
  MBR: MBR only
  BSD: not present
  APM: not present
  GPT: not present

Command (m for help): p

Disk /dev/sda: 4004 MB, 4004511744 bytes
124 heads, 62 sectors/track, 1017 cylinders, total 7821312 sectors
Units = sectors of 1 * 512 = 512 bytes
Sector size (logical/physical): 512 bytes / 512 bytes
I/O size (minimum/optimal): 512 bytes / 512 bytes
Disk identifier: 0x00000000

 Device Boot        Start         End      Blocks   Id  System
/dev/sda1              62     5973575     2986757   83  Linux
/dev/sda2         5973576     7611975      819200   83  Linux

Checking the Partition Type

Use the gdisk command to check the partition type. When using upgrade2 to upgrade the switch, you should make sure the type of partition is GPT.

admin@Xorplus$ sudo gdisk /dev/sda
GPT gdisk (fdisk) version 0.3.5

Partition table scan:
  MBR: protective
  BSD: not present
  APM: not present
  GPT: present

Checking Whether ONIE is Pre-loaded

On PowerPC & ARM platforms, we need to use the fw_printenv command to check whether the switch is pre-loaded with ONIE, which will be used to load PICOS on the switch. When using upgrade2 to upgrade the switch, you should make sure that ONIE is pre-loaded.

If the information displayed contains keywords like onie_initargs and onie_machine, the switch is pre-loaded with ONIE.

admin@Xorplus$ fw_printenv
active=image1
autoload=no
baudrate=115200
bootcmd=run check_boot_reason;run PicOS_bootcmd;run onie_bootcmd
bootdelay=10
check_boot_reason=if test -n $onie_boot_reason; then setenv onie_bootargs boot_reason=$onie_boot_reason; run onie_bootcmd; fi;
consoledev=ttyS0
dhcp_user-class=arm-agema_ag6248c-poe-r0_uboot
dhcp_vendor-class-identifier=arm-agema_ag6248c-poe-r0
......
onie_initargs=setenv bootargs quiet console=$consoledev,$baudrate
onie_machine=agema_ag6248c-poe
onie_machine_rev=0
onie_platform=arm-agema_ag6248c-poe-r0
onie_platformargs=setenv bootargs $bootargs serial_num=${serial#} ${platformargs} eth_addr=$ethaddr $onie_bootargs $onie_debugargs
onie_recovery=nand read ${loadaddr} onie2 ; nand erase.part onie ; nand write ${loadaddr} onie
onie_rescue=setenv onie_boot_reason rescue && boot
onie_start=onie
onie_sz.b=0x00c00000
onie_uninstall=setenv onie_boot_reason uninstall && boot
onie_update=setenv onie_boot_reason update && boot
onie_vendor_id=27658
onie_version=master-201603091701-dirty
PicOS_bootcmd=usb start;run platformargs;setenv bootargs root=/dev/sda1 rw noinitrd console=$consoledev,$baudrate rootdelay=10 $mtdparts;ext2load usb 0:1 $loadaddr boot/uImage;bootm $loadaddr
platform=agema_ag6248c-poe
platformargs=mtdparts=nand_iproc.0:1m(uboot),2m(shmoo),1m(nenv),12m(onie),3992m(open),12m(onie2),2m(vpd),6m(sys_eeprom),16m(diags),16m(diags2),32m(diags_fs)  maxcpus=2 mem=1024M
ramdiskaddr=0x3000000
serial#=A626P1DL174300014
serverip=192.168.0.10
stderr=serial
stdin=serial
stdout=serial
ubifscfg=ubi part nand0,4 0x0; ubifsmount fs
ver=U-Boot 2012.10-gcbef171 (Mar 09 2016 - 17:01:14) - ONIE master-201603091701-dirty
Environment size: 3992/65532 bytes

Upgrading Notes

This upgrade2 guide is only available for PICOS upgrade from version 2.11 and later.

When using upgrade2 to upgrade the switch, you should make sure the total disk space is more than 3700M.

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

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

From PICOS 2.4, a license check has been added.

- If PICOS has a license installed before the upgrade, the license will be copied and active after the upgrade. Please check this section for the license installation procedure.

- If there is no license installed before the upgrade, upgrade2 process can be implemented but only the first four ports on the system can be used after successfully upgrading.

- If the license has expired, it is not allowed to upgrade a major release (e.g. 2.11 to 2.12). However, it will not affect to upgrade a minor release (e.g. 2.11.1 to 2.11.2).

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

From PICOS 2.9, downgrade to an earlier version is NOT supported by upgrade. You can use ONIE installation when want to downgrade to an earlier version, please refer to Installing PicOS on Bare Metal Switches for details.

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 can be modified during download, and the upgrade will fail during the md5 check.

The image is platform dependent, that is, the image_name should be consistent with the platform, otherwise the upgrade script will abort.

It will create an upgrage2.log file in /cftmp directory after upgrading in which all processes of upgrade2 will be recorded.

Upgrade operation via upgrade or upgrade2 commands is not allowed on non-default system, you can upgrade PICOS only on default system. When there are more than one PICOS, the default system is the one automatically booted into after reboot.

Upgrade Procedure

Usage of Upgrade2 Command

NOTE：

admin@Xorplus$sudo upgrade2

USAGE

Upgrade system with local new image

SYNOPSIS

upgrade [image_name] [no-md5-check] [factory-default] [use-prev-config]

DESCRIPTION

image_name(*.bin/*.tar.gz) - Image should be saved in /cftmp

no-md5-check - Disable check of the image file for MD5

factory-default - recovery the configuration to factory default

use-prev-config - Use previous config, and syslog trace

backup-file=(*.lst) - Specify a user defined backup list

PICOS upgrade is done via the command "upgrade2" in bash (launching a shell script named "upgrade2.sh" in "/pica/bin/shell" directory). This script will upgrade the image and back up configuration files automatically.

Image name is in the form of .tar.gz, which should be copied to the /cftmp directory before running upgrade2 command.

By default, this script will check image integrity with MD5. It needs the MD5 file in the /cftmp directory. Otherwise, the script will abort. User can set the parameter of "no-md5-check" to disable MD5 checking.

When you want to restore factory settings after the upgrade, you can use the factory-default option when running upgrade2 command.

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. 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 it will not affect loading the remaining configuration, the system skips it and continues loading the remaining configuration.

The differences of upgrade2/rollback with or without use-prev-config option are described in the following table. By default, upgrade2 and rollback is performed without use-prev-config option.

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 rebooting.

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 rebooting.

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 or files in the following folders:

/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

/etc/picos/license.conf

/pica/config/pica_startup.boot

/ovs/ovs-vswitchd.conf.db

/ovs/function.conf.db

/ovs/var/lib/openvswitch/pki/

/ovs/portGroup.conf.db

/ovs/npb/htdocs/backend/web_api/dns_list.json

/ovs/npb/htdocs/backend/web_api/snmp_acl.json

/home

/root

/cftmp/

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 upgrade backup-file=/admin/back_files.lst

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.

root@Xorplus$ cat /admin/back_files.lst
/home/admin/a.txt

The above operations ensure that user can backup their important files with backup-file=(*.lst) option during the upgrade process.

Upgrade Procedure

The following upgrade procedure gives an example of upgrading on AG6248C from PICOS 2.11.1 to 2.11.2 using upgrade2 command.

Step1 Copy the upgrade package (in the form of .tar.gz) 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/daily/ag6248c/ rootfs.tar.gz  /cftmp
admin@XorPlus$sudo scp pica8@10.10.50.22:/tftp/build/daily/ag6248c/ rootfs.tar.gz.md5  /cftmp

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 rootfs.tar.gz

After finishing upgrade, the switch will reboot automatically, the system will come up running the new network operating system.

NOTE：

It will take 20 - 30 minutes to finish upgrading PICOS. During the upgrade process, please be patient and do not perform any operation until the upgrade is complete, otherwise, the upgrade may be interrupted.

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：
Usage of nos-rollback command:

admin@Xorplus$sudo nos-rollback

USAGE

Rollback to the previous system after next reboot

SYNOPSIS

nos-rollback [use-prev-config]

DESCRIPTION

iuse-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 reboot the system after issued "nos-rollback" command and the system switching takes effect. After rebooting successfully, the system will come up running the previous version of network operating system.

Verifying Version after Upgrading

admin@Xorplus$version
Copyright (C) 2009-2018 Pica8, Inc.
===================================
Hardware Model              : ag6248c
Linux System Version          : 2.11.2-93a66ac
Linux System Released Date    : 01/24/2018
L2/L3 Version                 : 2.11.2-93a66ac
L2/L3 Released Date           : 01/24/2018
OVS/OF Version/Revision       : 2.11.2-93a66ac
OVS/OF Released Date          : 01/24/2018

Page tree

Upgrading PicOS from Version 2.11 or Later Using Upgrade2

Introduction

Preparation before Upgrading

Checking the Running PICOS Version

Building Upgrade Environment

Getting the Required Upgrade Software

Backing up Important Data in Flash

Checking Total Disk Space

Checking the Partition Type

Checking Whether ONIE is Pre-loaded

Upgrading Notes

Upgrade Procedure

Usage of Upgrade2 Command

Usage of Use-prev-config Option

Usage of Backup-file=(*.lst) Option

Upgrade Procedure

Rollback Procedure

Verifying Version after Upgrading

**Usage of Backup-file=(*.lst) Option**