Programmable Internetworking & Communication Operating System Docs ... Click Spaces -> Space Directory to see docs for all releases ...
Page tree
Skip to end of metadata
Go to start of metadata

 

Introduction

NOTE

This document applies to upgrade from version 3.1.0 or the later version using the upgrade2 command. If you want to upgrade from 2.11.x (x indicates any version number of 2.11) to PICOS 3.1.0 or later versions, use upgrade command. For details, see Upgrading PICOS from Release 2.11.x Using Upgrade.

PICOS 3.1.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 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.11 or Later 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 in Flash

All the important data in Flash was backed up.


5

Checking if PicOS2 Partition Exist

The PicOS2 Partition exists.


6

Checking the Partition Type

The type of partition is GPT.


Checking the Running PICOS Version

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

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

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 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 if PicOS2 Partition Exists

Use the blkid command to check if the “PicOS2” partition exists. To use upgrade2 command to upgrade NOS, you should make sure there is a “PicOS2” partition.

admin@Xorplus:~$ sudo blkid
/dev/sdb2: LABEL="ONIE-BOOT" UUID="5c078d7e-03e8-49d7-a8ba-30107705c6b8" TYPE="ext4" PTTYPE="dos" PARTLABEL="ONIE-BOOT" PARTUUID="2be1af76-4ac4-43a6-ac60-6ac329772e74"
/dev/sdb3: LABEL="ACCTON-DIAG" UUID="d396322d-cfe9-4237-b21c-c1f12bc8cd1c" TYPE="ext4" PARTLABEL="ACCTON-DIAG" PARTUUID="57cb55ac-6f75-4732-aef0-867321a1c543"
/dev/sdb4: LABEL="PICOS-GRUB" UUID="680755b3-1847-47c0-85e8-20a11f230566" SEC_TYPE="ext2" TYPE="ext3" PARTLABEL="PICOS" PARTUUID="42ecb9ab-cbf9-49e1-b270-02f79670cb14"
/dev/sdb5: LABEL="PicOS" UUID="fae08336-9fa7-44ce-a5f4-ce546827ba11" TYPE="ext3" PARTLABEL="PICOS" PARTUUID="c9de9dac-4f8d-4517-8693-341431791009"
/dev/sdb6: LABEL="PicOS2" UUID="2e895a40-26c0-45d8-a343-e1154a63bdac" SEC_TYPE="ext2" TYPE="ext3" PARTLABEL="PICOS" PARTUUID="58731f03-936c-474e-bbcb-19448916f668"
/dev/sdb7: LABEL="User-Data" UUID="cf0db736-6bbd-464a-90f2-2cd1f7a4aa5e" TYPE="ext3" PARTLABEL="Linux filesystem" PARTUUID="73d48df0-9448-4dfe-b393-1369593fc686"
/dev/sdb1: PARTLABEL="GRUB-BOOT" PARTUUID="505671c7-6204-4c11-8c55-b5e3568ba4bf"

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


Upgrading Notes

  •    This upgrade2 guide only applies to PICOS upgrade from version 3.1.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.
  •    Since PICOS 2.4, a license check has been added.
    •    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 license installation procedure.
    •    If there is no license installed prior to upgrade, upgrade2 process can will proceed but only the first four ports on the newly upgraded system can be used.
    •    If the license has expired, it is not allowed to upgrade a major release (e.g. 3.1 to 3.2). However, it will not affect upgrading to a minor release (e.g. 3.1.1 to 3.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 no-md5-check option is removed from PICOS 3.1.0. If there is an MD5 file in the /cftmp directory, the upgrade script will check package integrity with MD5. Else if there is no MD5 file in the /cftmp directory, then skip the MD5 check step.

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-3.1.1-91bb175.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-3.1.1-91bb175.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 3.1.0 to 3.1.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/3.1.1/as7312_54x/onie-installer-picos-as7312_54x-3.1.1-91bb175.bin /cftmp
admin@Xorplus:~$ sudo scp pica8@10.10.50.22:/tftp/build/3.1.1/as7312_54x/onie-installer-picos-as7312_54x-3.1.1-91bb175.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/3.1.1/as7312_54x/onie-installer-picos-as7312_54x-3.1.1-91bb175.bin /cftmp

admin@Xorplus:~$sudo ip vrf exec mgmt-vrf scp pica8@10.10.50.22:/tftp/build/3.1.1/as7312_54x/onie-installer-picos-as7312_54x-3.1.1-91bb175.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-3.1.1-91bb175.bin

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

NOTE

  • For PICOS go2cli version, users can run the upgrade2 command under CLI operational mode or configuration mode.
  • 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 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 Upgrading

admin@Xorplus:~$ version
Copyright (C) 2009-2019 Pica8, Inc.
===================================
Hardware Model                : as7312_54x
Linux System Version/Revision    : 3.1.1/4b5f523
Linux System Released Date       : 12/27/2018
L2/L3 Version/Revision           : 3.1.1/4b5f523
L2/L3 Released Date             : 12/27/2018
OVS/OF Version/Revision         : 3.1.1/4b5f523
OVS/OF Released Date           : 12/27/2018
  • No labels