The Cumulus Linux operating system resides on a switch as a disk image. Switches running Cumulus Linux can be configured with 2 separate disk images. This section discusses how to manage them including installation and upgrading.
Installing a New Cumulus Linux Image
For details, read the chapter, Installing a New Cumulus Linux Image.
Upgrading Cumulus Linux
There are two ways you can upgrade Cumulus Linux:
- Perform a binary (full image) install of the new version, running
cl-img-installon the switch
- Upgrade only the changed packages, using
The entire upgrade process is described in Upgrading Cumulus Linux.
Understanding Image Slots
Cumulus Linux uses the concept of image slots to manage two separate Cumulus Linux images. The important terminology for the slots is as follows:
- Active image slot: The currently running image slot.
- Primary image slot: The image slot that is selected for the next boot. Often this is the same as the active image slot.
- Alternate image slot: The inactive image slot, not selected for the next boot.
To identify which slot is active, which slot is the primary, and which slot is alternate use the
Slot 1 is the active slot, as indicated by the active. When the switch is rebooted, it will boot into slot 1, as indicated by primary. The alternate slot won't be booted into unless the user selects it.
cl-img-select displays the version of the software that was initially installed on the switch; if you've upgraded your switch,
cl-img-select won't display the most current version of Cumulus Linux installed. The above switch had Cumulus Linux 2.5.3 installed initially in slot 1, and Cumulus Linux 2.5.2 initially installed in slot 2.
To see the current version of Cumulus Linux running on the switch, use cat /etc/lsb-release.
PowerPC vs x86 vs ARM Switches
The characteristics of the image slots vary, based on whether your switch is on a PowerPC, ARM or x86 platform. You can easily determine which platform the switch is on by using the
uname -m command.
For example, on a PowerPC platform,
uname -m outputs ppc:
While on an x86 platform,
uname -m outputs x86_64:
While on an ARM platform,
uname -m outputs armv7l:
You can also visit the HCL (hardware compatibility list) to look at your hardware to determine the processor type.
PowerPC Image Slots
On the PowerPC platform, each image slot consists of a read-only Cumulus Linux base image overlaid with a read-write user area, as shown in the following diagram:
Files you edit and create reside in the read-write user overlay. This also includes any additional software you install on top of Cumulus Linux. After an install, the user overlay is empty.
PowerPC Image Slot Overlay Detailed Information
The root directory of an image slot on a PowerPC system is created using an overlayfs file system. The lower part of the overlay is a read-only squashfs file system containing the base Cumulus Linux image. The upper part of the overlay is a read-write directory containing all the user modifications.
The following table describes the mount points and directories used to create the overlay for image slots 1 and 2.
|Slot Number||R/O squashfs device||R/O mount point||R/W block device||R/W directory|
The following table describes all the interesting mount points.
|Mount Point||File System||Purpose|
|/mnt/root-ro||squashfs||Contains the read-only base Cumulus Linux image.|
|/mnt/root-rw||ext2||Contains the read-write user directories for the overlay.|
|/||overlayfs||The union of |
|/mnt/persist||ext2||Contains the persistent user configuration applied to each image slot.|
|/mnt/initramfs||tmpfs||Contains the |
x86 and ARM Image Slots
Unlike PowerPC-based switches, there is no overlay for an x86-based or ARM-based switch; instead each slot is a logical volume in the physical partition, which you can manage with LVM.
When you install Cumulus Linux on an x86 or ARM switch, the following entities are created on the disk:
- A disk partition using an ext4 file system that contains three logical volumes: two logical volumes named sysroot1 and sysroot2, and the
/mnt/persistlogical volume. The logical volumes represent the Cumulus Linux image slots, so sysroot1 is slot 1 and sysroot2 is slot 2.
/mnt/persistis where you store your persistent configuration.
- A boot partition, shared by the logical volumes. Each volume mounts this partition as
Managing Slot Sizes
As space in a slot is used, you may need to increase the size of the root filesystem by increasing the size of the corresponding logical volume. This section shows you how to check current utilization and expand the filesystem as needed.
Check utilization on the root filesystem with the
dfcommand. In the following example, filesystem utilization is 16%:
To increase available space in the root filesystem, first use the
vgscommand to check the available space in the volume group. In this example, there is 6.34 Gigabytes of free space available in the volume group CUMULUS:
Once you confirm the available space, determine the number of the currently active slot using
cl-img-selectindicates slot number 1 is active.
- Resize the slot with the
lvresizecommand. The following example increases slot size by 20 percent of total available space. Replace the "#" character in the example with the active slot number from the last step.
cumulus@switch$ sudo lvresize -l +20%FREE CUMULUS/SYSROOT# Extending logical volume SYSROOT# to 5.27 GiB Logical volume SYSROOT# successfully resizedThe use of + is very important with the
lvresizewithout the + results in the logical volume size being set directly to the specified size, rather than extended.
Once the slot has been extended, use the
resize2fscommand to expand the filesystem to fit the new space in the slot. Again, replace the "#" character in the example with the active slot number.
Accessing the Alternate Image Slot on x86 and ARM Platforms
It may be useful to access the content of the alternate slot to retrieve the configuration or logs.
cl-img-install fails while the alternate slot is mounted. It is important to unmount the alternate slot as shown in step 4 below when done.
Determine which slot is the alternate with
This output indicates slot 2 is the alternate slot.
Create a mount point for the alternate slot:
Mount the alternate slot to the mount point:
Where # is the number of the alternate slot.
The alternate slot is now accessible under
Unmount the mount point
Reverting an Image to its Original Configuration (PowerPC Only)
On PowerPC-based systems, you may want to clear out the read-write user overlay area. Perhaps something was misconfigured, or was deleted by mistake, or some unneeded software was installed.
You can purge the read-write overlay using the
cl-img-clear-overlay command, passing the slot number as an argument. For example, to purge the read-write overlay for image slot 2, run:
cumulus@switch:~$ sudo cl-img-clear-overlay 2 Success: Overlay configuration 2 will be re-initialized during the next reboot.
Reprovisioning the System (Restart Installer)
You can reprovision the system, wiping out the contents of both image slots and
To initiate the provisioning and installation process, use
If you change your mind, you can cancel a pending reinstall operation by using
cumulus@switch:~$ sudo cl-img-select -c Cancelling pending install at next reboot...done.
Uninstalling All Images and Removing the Configuration
To remove all installed images and configurations, returning the switch to its factory defaults, use
If you change your mind you can cancel a pending uninstall operation by using
cumulus@switch:~$ sudo cl-img-select -c Cancelling pending uninstall at next reboot...done.
Booting into Rescue Mode
If your system becomes broken is some way, you may be able to correct things by booting into ONIE rescue mode. In rescue mode, the file systems are unmounted and you can use various Cumulus Linux utilities to try and fix the problem.
To reboot the system into the ONIE rescue mode, use
If you change your mind you can cancel a pending rescue boot operation by using
cumulus@switch:~$ sudo cl-img-select -c Cancelling pending rescue at next reboot...done.
Inspecting Image File Contents
From a running system you can display the contents of a Cumulus Linux image file using
You can also extract the image files to the current directory with the