This documentation is for an older version of the software. If you are using the current version of Cumulus Linux, this content may not be up to date. The current version of the documentation is available here. If you are redirected to the main page of the user guide, then this page may have been renamed; please search for it there.

Managing Cumulus RMP Disk Images

The Cumulus RMP operating system resides on a switch as a disk image. This section discusses how to manage them.

Cumulus RMP comes preinstalled on your switch. However there may be instances where you need to perform a full image installation. Before you install Cumulus RMP, the switch can be in two different states:

ONIE is an open source project, equivalent to PXE on servers, that allows installation of network operating systems (NOS) on bare metal switches.

Unlike Cumulus Linux, there is no license to install on a Cumulus RMP switch.

Understanding these Examples

The sections in this chapter are ordered from the most repeatable to the least repeatable methods. For instance, DHCP can scale to hundreds of switch installs with zero manual input, compared to something like USB installs. Installing via USB is fine for a single switch here and there but is not scalable.

You can name your Cumulus RMP installer binary using any of the ONIE naming schemes mentioned here.

Installing via a DHCP/Web Server Method with DHCP Options

Installing Cumulus RMP in this manner is as simple as setting up a DHCP/Web server on your laptop and connecting the eth0 management port of the switch to your laptop.

Once you connect the cable, the installation proceeds as follows:

  1. The bare metal switch boots up and asks for an address (DHCP request).

  2. The DHCP server acknowledges and responds with DHCP option 114 and the location of the installation image.

  3. ONIE downloads the Cumulus RMP binary, installs and reboots.

  4. Success! You are now running Cumulus RMP.

The most common method is for you to send DHCP option 114 with the entire URL to the Web server (this could be the same system). However, there are many other ways to use DHCP even if you don’t have full control over DHCP. See the ONIE user guide for help.

Here’s an example DHCP configuration with an ISC DHCP server:

subnet 172.0.24.0 netmask 255.255.255.0 {
  range 172.0.24.20 172.0.24.200;
  option www-server = "http://172.0.24.14/onie-installer-[PLATFORM]";
}

Here’s an example DHCP configuration with dnsmasq (static address assignment):

dhcp-host=sw4,192.168.100.14,6c:64:1a:00:03:ba,set:sw4
dhcp-option=tag:sw4,114,"http://roz.rtplab.test/onie-installer-[PLATFORM]"

Don’t have a Web server? There is a free Apache example you can utilize.

Installing via a DHCP/Web Server Method without DHCP Options

If you have a laptop on same network and the switch can pull DHCP from the corporate network, but you cannot modify DHCP options (maybe it’s controlled by another team), do the following:

  1. Place the Cumulus RMP binary in a directory on the Web server.

  2. Run the onie-nos-install command manually, since DHCP options can’t be modified:

    ONIE:/ #onie-nos-install http://10.0.1.251/path/to/cumulus-install-[PLATFORM].bin
    

Installing via a Web Server with no DHCP

Use the following method if your laptop is on the same network as the switch eth0 interface but no DHCP server is available.

One thing to note is ONIE is in discovery mode , so if you are setting a static IPv4 address for the eth0 management port, you need to disable discovery mode or else ONIE may get confused.

  1. To disable discovery mode, run:

    onie# onie-discovery-stop 
    

    or, on older ONIE versions if that command isn’t supported:

    onie# /etc/init.d/discover.sh stop 
    
  2. Assign a static address to eth0 via ONIE (using ip addr add):

    ONIE:/ #ip addr add 10.0.1.252/24 dev eth0
    
  3. Place the Cumulus RMP installer image in a directory on your Web server.

  4. Run the onie-nos-install command manually since there are no DHCP options:

    ONIE:/ #onie-nos-install http://10.0.1.251/path/to/cumulus-install-[PLATFORM].bin
    

Installing via FTP or TFTP without a Web Server

  1. Set up DHCP or static addressing for eth0, as in the examples above.

  2. If you are utilizing static addressing, disable ONIE discovery mode.

  3. Place the Cumulus RMP installer image into a TFTP or FTP directory.

  4. If you are not utilizing DHCP options, run one of the following commands (tftp for TFTP or ftp for FTP):

    ONIE# onie-nos-install ftp://local-ftp-server/cumulus-install-[PLATFORM].bin
        
    ONIE# onie-nos-install tftp://local-tftp-server/cumulus-install-[PLATFORM].bin
    

Installing via a Local File

  1. Set up DHCP or static addressing for eth0, as in the examples above.

  2. If you are utilizing static addressing, disable ONIE discovery mode.

  3. Use scp to copy the Cumulus RMP binary to the switch.
    Note: Windows users can use WinScp.

  4. Run the following command:

    ONIE# onie-nos-install /path/to/local/file/cumulus-install-[PLATFORM].bin
    

Installing via USB

Follow the steps below to conduct a full installation of Cumulus RMP. This wipes out all pre-existing configuration files that may be present on the switch.

Make sure to back up any important configuration files that you may need to restore the configuration of your switch after the installation finishes.

Preparing for USB Installation

  1. Download the Cumulus RMP image from the Cumulus Downloads page.

  2. Prepare your flash drive by formatting in one of the supported formats: FAT32, vFAT or EXT2.

    Optional: Preparing a USB Drive inside Cumulus RMP

    It is possible that you could severely damage your system with the following utilities, so please use caution when performing the actions below!

    1. Insert your flash drive into the USB port on the switch running Cumulus RMP and log in to the switch.

    2. Determine and note which device your flash drive can be found at using output from cat /proc/partitions and sudo fdisk -l [device]. For example, sudo fdisk -l /dev/sdb. These instructions assume your USB drive is the /dev/sdb device, which is typical. Make sure to modify the commands below to use the proper device for your USB drive.

    3. Create a new partition table on the device:

      sudo parted /dev/sdb mklabel msdos

      The parted utility should already be installed. However, if it is not, install it with: sudo apt-get install parted

    4. Create a new partition on the device:

      sudo parted /dev/sdb -a optimal mkpart primary 0% 100%
    5. Format the partition to your filesystem of choice using ONE of the examples below:

      sudo mkfs.ext2 /dev/sdb1
       sudo mkfs.msdos -F 32 /dev/sdb1
       sudo mkfs.vfat /dev/sdb1

      To use mkfs.msdos or mkfs.vfat, you need to install the dosfstools package from the Debian software repositories (step 3 here shows you how to add repositories from Debian), as they are not included by default.

    6. To continue installing Cumulus RMP, mount the USB drive in order to move files to it.

      sudo mkdir /mnt/usb
       sudo mount /dev/sdb1 /mnt/usb
  3. Copy the image file over to the flash drive and rename the image file to onie-installer_x86-64.

    You can also use any of the ONIE naming schemes mentioned here.

    When using a Mac or Windows computer to rename the installation file the file extension may still be present. Make sure to remove the file extension otherwise ONIE will not be able to detect the file!

  4. Insert the USB stick into the switch, then prepare the switch for installation:

    • If the switch is offline, connect to the console and power on the switch.

    • If the switch is already online in Cumulus RMP, connect to the console and reboot the switch into the ONIE environment with the sudo onie-select -i command, followed by sudo reboot. Then skip to step 8 below.

    • If the switch is already online in ONIE, use the reboot command.

  5. SSH sessions to the switch get dropped after this step. To complete the remaining instructions, connect to the console of the switch. Cumulus RMP switches display their boot process to the console, so you need to monitor the console specifically to complete the next step.

  6. Monitor the console and select the ONIE option from the first GRUB screen.

  7. Cumulus RMP uses GRUB chainloading to present a second GRUB menu specific to the ONIE partition. No action is necessary in this menu to select the default option ONIE: Install OS.

  8. At this point, the USB drive should be automatically recognized and mounted. The image file should be located and automatic installation of Cumulus RMP should begin. Here is some sample output:

    ONIE: OS Install Mode  ...
         
    Version : penguin_arctica-2014.05.05-6919d98-201410171013
    Build  Date: 2014-10-17T10:13+0800
    Info: Mounting kernel filesystems...  done.
    Info: Mounting LABEL=ONIE-BOOT on /mnt/onie-boot  ...
    initializing eth0...
    scsi 6:0:0:0: Direct-Access  SanDisk Cruzer Facet 1.26 PQ: 0 ANSI: 6
    sd 6:0:0:0: [sdb] 31266816 512-byte logical blocks: (16.0 GB/14.9 GiB)
    sd 6:0:0:0: [sdb] Write Protect is off
    sd 6:0:0:0: [sdb] Write cache: disabled, read cache: enabled, doesn't support DPO or FUA
    sd 6:0:0:0: [sdb] Attached SCSI disk
         
    <...snip...>
         
    ONIE:  Executing installer: file://dev/sdb1/onie-installer-x86_64
    Verifying image checksum ... OK.
    Preparing image archive ... OK.
    Dumping image info...
    Control File Contents
    =====================
    Description: Cumulus  Linux
    OS-Release:  3.0.0-3b46bef-201509041633-build
    Architecture: amd64
    Date:  Fri, 04 Sep 2015 17:10:30 -0700
    Installer-Version:  1.2
    Platforms: accton_as5712_54x accton_as6712_32x  mlx_sx1400_i73612 dell_s6000_s1220 dell_s4000_c2338 dell_s3000_c2338  cel_redstone_xp cel_smallstone_xp cel_pebble quanta_panther  quanta_ly8_rangeley quanta_ly6_rangeley quanta_ly9_rangeley  
    Homepage: http://www.cumulusnetworks.com/
    
  9. After installation completes, the switch automatically reboots into the newly installed instance of Cumulus RMP.

  10. Determine and note at which device your flash drive can be found by using output from cat /proc/partitions and sudo fdisk -l [device]. For example, sudo fdisk -l /dev/sdb.

    These instructions assume your USB drive is the /dev/sdb device, which is typical if the USB stick was inserted after the machine was already booted. However, if the USB stick was plugged in during the boot process, it is possible the device could be /dev/sda. Make sure to modify the commands below to use the proper device for your USB drive!

  11. Create a mount point to mount the USB drive to:

     sudo mkdir /mnt/mountpoint
    
  12. Mount the USB drive to the newly created mount point:

     sudo mount /dev/sdb1 /mnt/mountpoint
    

Upgrading Cumulus RMP

If you already have Cumulus RMP installed on your switch and you are upgrading to an X.Y.Z release, like 2.5.7 from an earlier release in the same major and minor release family only (like 2.5.4 to 2.5.7), you can use apt-get to upgrade to the new version. (If are upgrading to a major (X.0) or minor (X.Y) release, you must do a full image install, as described above.)

To upgrade to a maintenance (X.Y.Z) release using apt-get:

  1. Run apt-get update.

  2. Run apt-get dist-upgrade.

  3. Reboot the switch.

Useful Links