4. Installing software

This chapter describes software installation tasks. Software installation tasks include:

  1. Installation concepts
    Describes concepts to be familiar with prior to installing or upgrading.
  2. Installing the software manually on a 7250 IXR system
    Installs the SR Linux software on a 7250 IXR system for the first time.
  3. Installing the software manually on a 7220 IXR-D or 7220 IXR-H system
    Installs the SR Linux software on a 7220 IXR-D or a 7220 IXR-H system for the first time.
  4. Upgrading the software
    Upgrades previously installed SR Linux software to a later version.

4.1. Installation concepts

SR Linux can be installed on the 7250 IXR, 7220 IXR-D, and 7220 IXR-H series systems.

Installations can be completed using the CLI. To perform either an initial imaging, reinstallation, or an upgrade or downgrade of a system, the operation requires pushing the new image to the device, changing the boot configuration, and rebooting.

In the installation procedure examples, commands preceded by $ require root privilege. Commands preceded by # should be executed from a bash shell.

The basic installation actions performed on the system do not change, regardless of the method used to install the SR Linux (either using the CLI or manually), but the CLI method is dependent on having a working system whereas the manual method is not.

4.1.1. 7250 IXR installation concepts

On a 7250 IXR system, SR Linux boots from an internal SD card. No other boot device may be used with the system. The SD card contains:

  1. an MBR (containing the Grub2 boot loader)
  2. a partition used for SR Linux images
  3. two overlay partitions used for persistent storage

Installations can be performed manually without using the CLI. The process may also require partitioning an SD card external to the system, installing Grub into the MBR of the card, and copying the SR Linux image to the device. Use of the manual method requires advanced knowledge of Linux commands, including disk formatting, copying files, unpacking compressed images, and editing of text files. Basic knowledge of editing text files in Linux is mandatory. The manual method requires a Linux server, with an empty SD card mounted (or use of a USB-SD card adapter).

4.1.2. 7220 IXR-D and 7220 IXR-H installation concepts

On a 7220 IXR-D or 7220 IXR-H system, SR Linux boots from a the internal SSD. No other boot device may be used with the system. The internal SSD contains:

  1. an MBR (containing the Grub2 boot loader)
  2. a partition used for SR Linux images
  3. two overlay partitions used for persistent storage

SR Linux can boot from a USB device in recovery scenarios.

4.1.3. Software image

The software image is a set of files provided as part of an SR Linux distribution. The files contained in an image are:

  1. squashfs – Contains the SR Linux root file system, including any needed binaries for system operation.
  2. initramfs (or initrd) – Contains an initial file system that is used to make the hardware operational before unpacking the SR Linux squashfs into memory, then switching the root file system to it.
  3. kernel (or vmlinuz) – The Linux kernel is the initial program executed by the boot loader. The kernel handles all interactions between the OS and hardware.

To perform an installation, you must have an SR Linux image, which is a bin containing these files, along with some other files used for operations and maintenance (for example, YANG models and SNMP MIBs).

4.2. Installing the software manually on a 7250 IXR system

You can install the SR Linux software on a 7250 IXR system using the following methods.

4.2.1. Installation from a Linux machine

Installing the software manually requires a working Linux system, with access to an SD card (preferably 16 GB). A USB adapter may be used, as most servers do not have SD card slots. The SD card should be formatted and have no important data present on it. Any data on the card is wiped during the procedure. Installing the software manually requires downloading a script. In the following examples, /dev/sdb is used as the SD card device, and all steps should be completed as a user with root privileges.

Warning:

If used incorrectly, this procedure could be destructive and may render the system creating the SD card inoperable. Verify the correct drive is being used before completing the installation.

  1. Copy the SR Linux image and SR Linux rescue image to either an SD card or USB drive and insert it into the system. Alternatively, copy the images to the server being used to prepare the SD card. Use the following commands:
    # cp <path-to-srlinux-image.bin> <destination-directory>
    Example:
    # cp /mnt/removable/SRLinux-21.3.0-459.bin /tmp
  2. Wipe the SD card and ensure that you correctly identify the SD card, as this action is destructive.
  3. Download and install the following packages on the system.
    # sudo yum install e4fsprogs
    # sudo yum install grub2
    # sudo yum install grub2-efi-x64.x86_64
    # sudo yum install grub2-efi-x64-modules
  4. Upgrade mkfs.fat to version 4.1 or later.
    Example:
    # wget https://rpmfind.net/linux/fedora/linux/releases/29/Everything/x86_64/os/
    Packages/d/dosfstools-4.1-6.fc29.x86_64.rpm
    # sudo yum localinstall dosfstools-4.1-6.fc29.x86_64.rpm
  5. Download the sdcardflash.sh script.
  6. Run the script.
    Example:
    # /tmp/sdcardflash.sh -v -e 21.3.0-459 -i srlinux-21.3.0-459.bin -s /dev/sdb -g  "autoboot nosinstall"
  7. Physically remove the SD card from the system.
  8. Repeat steps 2 to 7 with another SD card for the standby control plane module (if applicable).
  9. Remove both control plane modules from the system (refer to the SR Linux 7250 Hardware Installation Guide for a procedure), then insert the SD cards into the internal SD slot for each module.
  10. Insert the control plane modules into the chassis, and power the chassis on.

4.2.2. Installation using a rescue image from an SD card

From a 7250 IXR system running SR Linux, you can create a bootable SD card which can then be transferred and used in another system.

  1. Log in to the system running SR Linux via a console connection.
  2. Reboot the system and select srlinux-rescue from the image boot menu.
  3. Copy the srlinux-xxx.bin file using scp.
    To allow this, one of the ports on the system in the rescue image should have management connectivity. If there is no IP assigned to any of the ports automatically, you can add an IP manually using the ifconfig command:
    ifconfig <port> <ip address> netmask <ip address>
    Example:
    ifconfig eth4 192.168.255.254 netmask 255.255.255.0
  4. Find the target SD card device.
    In this procedure example, the SD card device is detected as /dev/sdb.
  5. Find the current internal SD card device.
    In this procedure example, the SD card device is detected as /dev/sdc1.
  6. Run the following command to flash the SD card device with the srlinux-xxx.bin file:
    bash <srlinux-xxx.bin> -- --dev <target SD device> --no-onie --source-efi <internal SD device>
    Example:
    bash srlinux-21.3.0-459.bin -- --dev /dev/sdb --no-onie --source-efi /dev/sdc1
  7. Remove the SD card from the system. Insert it into the internal SD card slot on the control plane module of the system where the software image will be installed.
  8. Power on the system with the new image.

4.2.3. Installation using an image copied to an SD card

Using a Linux machine, you can copy an SR Linux image from one SD card to another SD card. You can then use this second SD card to install the SR Linux software image onto a 7250 IXR system.

  1. Insert an SD card containing an SR Linux image into any Linux machine with a supporting SD slot.
    In this procedure example, the SD card device is detected as /dev/sdb.
  2. When the SD card is detected, copy the SR Linux image to the Linux machine:
    sudo dd if=/dev/sdb of=sd.img
  3. Remove the SD card from the Linux machine.
  4. Insert the second SD card (to which the image will be copied) into the Linux machine.
  5. Copy the SR Linux image from the Linux machine to the second SD card:
    sudo dd if=sd.img of=/dev/sdb
  6. Remove the second SD card from the Linux machine.
    This SD card can now be inserted into the internal SD card slot of a 7250 IXR system’s control plane module. The system will power on with the image.

4.3. Installing the software manually on a 7220 IXR-D or 7220 IXR-H system

Installing the software manually on a 7220 IXR-D or 7220 IXR-H system requires a working Linux system and a USB device. Installation also requires the ONIE boot loader install environment.

If you do not host the SR Linux images from a ZTP server, you must perform a manual bootstrap procedure to complete the installation.

Warning:

Installing the ONIE from the USB wipes out all SSD partitions.

  1. Download the ONIE recovery .iso image for the respective 7220 IXR-D or 7220 IXR-H system from OLCS.
  2. Copy the ONIE recovery .iso image file to a USB using the following command:
    dd if=<machine>.iso of=/dev/sdX bs=10M
    where machine = the image name for the device and sdX = the USB device name.
  3. After the ONIE recovery .iso image is copied, unmount the USB device and remove it from the Linux machine.
  4. Insert the USB into the 7220 IXR-D or 7220 IXR-H system and power the system on.
  5. When the setup message comes up, press either the DEL or ESC key to enter the BIOS interface:
    Version 2.19.1266. Copyright (C) 2019 American Megatrends. Inc.
    BIOS Date: 11/01/2019 15:48:23 Ver: OACHI037 Minor_Ver: V1.03
    Press <DEL> or <ESC> to enter setup.
    Entering Setup...
  6. In the BIOS prompt, select Boot Device as USB, then Save & Exit.
  7. Install the ONIE from the USB. Select ONIE: Embed ONIE in the GNU Grub screen.
  8. After the ONIE installation is complete, remove the USB to boot the ONIE from the SSD.
  9. After the device boots the ONIE from the SSD, select ONIE: Install OS in the GNU Grub screen.
  10. Verify the platform, version, and build date of the installed ONIE image:
    GRUB loading.
    Welcome to GRUB!
     
    Platform  : x86_64-nokia_ixr7220_d3-r0
    Version   : 2019.02-onie_version-v1.5
    Build Date: 2020-02-13T15:05+08:00
     
    telnet>
  11. The device boots and enters the ONIE:/ # prompt.
    The ONIE service discovery automatically gets a device IP address from a ZTP server, and the SR Linux image is downloaded.
    Note:

    If you do not host the SR Linux images from a ZTP server, you must perform a manual bootstrap procedure to complete the installation. See the Manual bootstrapping procedure to continue.

  12. After the SR Linux software installation completes, the 7220 IXR-D or 7220 IXR-H reboots with the updated SR Linux image. The SR Linux services and applications are automatically started.

4.3.1. Manual bootstrapping

If you do not host the SR Linux images from a ZTP server, you must perform a manual bootstrapping to retrieve the image. Perform this procedure in addition to the steps in Installing the software manually on a 7220 IXR-D or 7220 IXR-H system to complete the installation.

  1. After the ONIE image boots, the service discovery starts automatically. To stop the service discovery, execute:
    ONIE:/ # onie-stop
  2. Configure the management IP address and the default route to copy the SR Linux image to the 7220 IXR-D or 7220 IXR-H:
    ONIE:/ #
    ONIE:/ # ifconfig eth0 135.227.251.182 netmask 255.255.255.0
    ONIE:/ # ip route add 0.0.0.0/0 via 135.227.248.1
    IP: RTNETLINK answers: Network is unreachable
    ONIE:/ #
  3. Using the SCP command, copy the SR Linux image <version>.bin to the root folder. The "root" user password field is blank.
  4. To install SR Linux, execute the following command:
    onie-nos-install <bin>
    Example:
    ONIE:/ # onie-nos-install /root/srlinux-20.6.1-21398.bin
    discover: installed mode detected.
    Stopping: discover... done.
    ONIE: Executing installer: /root/srlinux-20.6.1-21398.bin
    /dev/console
    Verifying archive integrity... 100%   MD5 checksums are OK. All good.
    Uncompressing srlinux-20.6.1-21398  100%
    Files used: srlinux-20.6.1-21398.squashfs, initramfs-4.18.39-2.x86_64-02.img, vmlinuz-4.19.39-2.x86_64
    Found ONIE-BOOT on /dev/sda2
    Will use /dev/sda as install dev
    Parts used: old_part_start[4], efi_part[4], nos_part[5], etc_part[6], opt_part[7], data_part[8]
    Remove existing partitions from /dev/sda
    /dev/sda4 is not mounted
    Warning: The kernel is still using the old partition table.
    The new table will be used at the next reboot.
    The operation has completed successfully.
  5. After the image is installed, the 7220 IXR-D or 7220 IXR-H reboots with the SR Linux image:
             Starting Wait for Plymouth Boot Screen to Quit...
             Starting Terminate Plymouth Boot Screen...
    [  OK  ] Started Login Service.
     
    SRLINUX 20.6.1-21463
    Kernel 4.19.39-2.x86_64 on an x86_64
     
    Localhost login: linuxadmin
    Password: 2020:06:21 19:52:54:54 | EVENT | Starting ZTP process
     
    [linuxadmin@localhost ~}$ system2020:06:21 19:52:58:64 | EVENT | Set link mgmt0 up
    ctl disable z2020:06:21 19:53:03:82 | EVENT | ZTP Perform DHCP_V4. attempt[1]
    t2020:06:21 19:53:04:14 | EVENT | Received dhcp lease on mgmt0 for 135.227.251.182/21
    2020:06:21 19:53:04:23 | EVENT | option 66 provided by dhcp: http://135.277.248.118
    2020:06:21 19:53:04:23 | EVENT | option 67 provided by dhcp: duts/SD-RD2-126/ztp-config.yml
  6. Enter the login credentials: linuxadmin
  7. Disable watchdog reboot using the following command:
    sr_wdc noreboot
  8. Permanently disable the ZTP service using the following command:
    systemctl disable ztp
  9. Enable SR Linux as a service with the systemctl command:
    systemctl enable /opt/srlinux/systemd/srlinux.service
  10. Configure the network IP address and enable network as service by performing the following steps.
    1. Enter sudo bash -c 'echo "NETWORKING=yes" >/etc/sysconfig/network'
    2. Enter sudo systemctl enable network
    3. Edit and include the sudo/etc/sysconfig/network-scripts/ifcfg-mgmt0 with the appropriate IP address, netmask, and gateway information:
      DEVICE=mgmt0
      IPADDR=<IP_ADDR>
      BOOTPROTO=static
      NETMASK=<NET_MASK>
      GATEWAY=<GATEWAY>
      ONBOOT=yes
      IPV6INIT=NO
      NM_CONTROLLED=no
  11. After a reboot, the networking and SR Linux service is started automatically.

4.4. Upgrading the software

The following procedures upgrade the software using the CLI. They require a working system, with SR Linux operational and the CLI available. If the system is not operational and CLI is not available, see either Installing the software manually on a 7250 IXR system or Installing the software manually on a 7220 IXR-D or 7220 IXR-H system to perform an initial installation.

There are two ways to upgrade the software. You can either use a tools command within the CLI, or upgrade from the bash shell.

4.4.1. Software upgrade using a tools command

You can upgrade and deploy a new software image using the tools system deploy-image command in the CLI. With this command, there are two methods you can use to deploy an image. You can choose to deploy using an HTTP/HTTPS link to the software, or you can copy the image bin file onto the system, then deploy it.

The tools system deploy-image command can be run with or without a reboot option. The reboot option deploys the image and reboots the system automatically to bring up the specified image. If the reboot option is not added, the image is only deployed. To then perform the upgrade, the system must be rebooted separately using the tools platform chassis reboot command.

Deploy a software image with the deploy-image command using either of the following methods:

  1. Method 1: HTTP/HTTPS link
    Deploy the image using an HTTP/HTTPS link to the software image. The download of the image is insecure by default, with cert verification disabled:
    tools system deploy-image <http link to bin file> reboot
    Example:
    In the following example, the reboot option is not used. After the image is deployed, the system must be rebooted separately.
    # tools system deploy-image https://username:password@example.com/repository/srlinux-os/21.3.0/srlinux-21.3.0-384.bin
    Downloading with the srbase-mgmt namespace. Connection timeout: 5 seconds
      % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                     Dload  Upload   Total   Spent    Left  Speed
    100  782M    0  782M    0     0  99.9M      0 --:--:--  0:00:07 --:--:--  101M
    Deploying SRL image version 21.3.0-384
    2021:03:15 21:51:46:10 | EVENT | Version of new image 21.3.0-384
    2021:03:15 21:51:46:10 | EVENT | Current version: 21.3.0-377, New version: 21.3.0-384
    2021:03:15 21:52:21:10 | EVENT | Invoked sync call. It may take few seconds to complete.
    2021:03:15 21:52:30:15 | EVENT | Syncing image with standby
    Successfully deployed SRL image version 21.3.0-384
  2. Method 2: Copy the image bin file
    Copy the image bin file onto the system, then use the deploy-image command after the bin file is uploaded:
    tools system deploy-image <absolute path to bin file> reboot
    Example:
    In the following example, the reboot option is used. After the image is deployed, the system reboots automatically to bring up the image.
    # tools system deploy-image /tmp/srlinux-21.3.0-382.bin reboot
    Deploying SRL image version 21.3.0-382
    2021:03:16 21:08:17:57 | EVENT | Version of new image 21.3.0-382
    2021:03:16 21:08:17:58 | EVENT | Current version: 21.3.0-388, New version: 21.3.0-382
    2021:03:16 21:08:53:77 | EVENT | Invoked sync call. It may take few seconds to complete.
    2021:03:16 21:09:01:73 | EVENT | Syncing image with standby
    Successfully deployed SRL image version 21.3.0-382
    --{ candidate shared default }--[  ]--
    # 2021:03:16 21:10:27:17 | EVENT | Linux sync call executing
    2021:03:16 21:10:27:21 | EVENT | Umount /dev/sdb1
    2021:03:16 21:10:27:23 | EVENT | Umount /dev/sdb2
    2021:03:16 21:10:27:26 | EVENT | sr_cli chassis reboot force requested.
    21-03-16 14:10:28.472 sr_device_mgr: Chassis reboot force requested - rebooting
    21-03-16 14:10:36.079 sr_device_mgr: Rebooting - chassis reboot requested

4.4.2. Software upgrade from the bash shell

This procedure upgrades the software from the bash shell using the CLI.

  1. Copy the SR Linux image to a location that the system being installed has access to, either to a USB or SD card, or somewhere on the network (assuming that the system being installed has access to the server). Enter:
    # cp <path-to-srlinux-image-bin> <destination-directory>
    Example:
    # cp SRLinux-21.3.0-459.bin /mnt/removable
  2. Log in to the system being upgraded:
    # ssh <user>@<address>
    Example:
    # ssh linuxadmin@192.168.0.1
  3. Enter the login credentials (when prompted by the system):
    1. username: linuxadmin
    2. password: linuxadmin
  4. Copy the image to the system. Do either of the following:
    1. If not using removable media (USB or SD card), copy the image to the system across the network:
      # sudo ns_exec srbase-mgmt bash
      # sudo scp <user>@<server-with-srlinux-image>:<path-to-srlinux-image-bin> <local-destination>
      Example:
      # sudo ns_exec srbase-mgmt bash
      # sudo scp serveruser@192.168.0.2:srlinux-21.3.0-459.bin /local-destination
    2. If using removable media (USB or SD card), insert either the USB or SD card into the system and mount it to a temporary directory:
      # sudo mkdir -p /mnt/removable
      # sudo mount <path-to-disk> /mnt/removable
      Example:
      # sudo mkdir -p /mnt/removable
      # sudo mount /dev/sdc1 /mnt/removable
  5. Unpack the SR Linux image to a location that the system being installed has access to, either across the network, or to a USB or SD card that may be inserted into the active control plane module:
    # sudo mkdir -p /mnt/nokiaos/<version>
    # sudo cp <local-destination>/<srlinux-image-file.bin>
    /tmp/<srlinux-image-file.bin>
    # sudo chmod +x /<tmp>/<srlinux-image-file.bin>
    # sudo /tmp/<srlinux-image-file.bin> --target /mnt/
    nokiaos/<version> --noexec
    Example:
    # sudo mkdir -p /mnt/nokiaos/21.3.0-459
    # sudo cp /mnt/removable/srlinux-21.3.0-459.bin /tmp/srlinux-21.3.0-459.bin
    # sudo chmod +x /tmp/srlinux-21.3.0-459.bin
    # sudo /tmp/srlinux-21.3.0-459.bin --target /mnt/nokiaos/21.3.0-459 --noexec
  6. Start an SR Linux CLI session, and retrieve the current version of the software. Multiple images can be shown.
    # info from state system boot image
    Example:
    # sr_cli
    # info from state system boot image
        system {
             boot {
                image [
                   21.3.0-449
                   20.6.1-10
                      ]
                  }
               }
  7. Update the boot image list by reordering the current version behind the new version:
    # tools system boot image [ <version> <old-version> ]
    Example:
    # tools system boot image [ 21.3.0-459 21.3.0-449 20.6.1-10 ]
    Boot order is updated with ['21.3.0-459', '21.3.0-449', '20.6.1-10']
  8. Reboot the chassis:
    # tools platform chassis reboot
  9. Wait ten minutes, then log in to the device via SSH or console, and confirm the new version.