This quick start guide provides an end-to-end setup process for installing and running Cumulus Linux, as well as a collection of example commands for getting started once installation is complete.
Prior intermediate Linux knowledge is assumed for this guide. You should be familiar with basic text editing, Unix file permissions, and process monitoring. A variety of text editors are pre-installed, including
You must have access to a Linux or UNIX shell. If you are running Windows, you should use a Linux environment like Cygwin as your command line tool for interacting with Cumulus Linux.
If you're a networking engineer but are unfamiliar with Linux concepts, refer to this reference guide for examples of the Cumulus Linux CLI and configuration options, and their equivalent Cisco Nexus 3000 NX-OS commands and settings for comparison. You can also watch a series of short videos introducing you to Linux in general and some Cumulus Linux-specific concepts in particular.
To install Cumulus Linux, you use ONIE (Open Network Install Environment), an extension to the traditional U-Boot software that allows for automatic discovery of a network installer image. This facilitates the ecosystem model of procuring switches, with a user's own choice of operating system loaded, such as Cumulus Linux.
The easiest way to install Cumulus Linux with ONIE is via local HTTP discovery:
If your host (like a laptop or server) is IPv6-enabled, make sure it is running a web server.
If the host is IPv4-enabled, make sure it is running DHCP as well as a web server.
- Download the Cumulus Linux installation file to the root directory of the web server. Rename this file
- Connect your host via Ethernet cable to the management Ethernet port of the switch.
- Power on the switch. The switch downloads the ONIE image installer and boots it. You can watch the progress of the install in your terminal. After the installation finishes, the Cumulus Linux login prompt appears in the terminal window.
These steps describe a flexible unattended installation method. You should not need a console cable. A fresh install via ONIE using a local web server should generally complete in less than 10 minutes.
You have more options for installing Cumulus Linux with ONIE. Read Installing a New Cumulus Linux Image to install Cumulus Linux using ONIE in the following ways:
- DHCP/web server with and without DHCP options
- Web server without DHCP
- FTP or TFTP without a web server
- Local file
ONIE supports many other discovery mechanisms using USB (copy the installer to the root of the drive), DHCPv6 and DHCPv4, and image copy methods including HTTP, FTP, and TFTP. For more information on these discovery methods, refer to the ONIE documentation.
After installing Cumulus Linux, you are ready to:
- Log in to Cumulus Linux on the switch.
- Install the Cumulus Linux license.
- Configure Cumulus Linux. This quick start guide provides instructions on configuring switch ports and a loopback interface.
Upgrade to the Latest Version
If you are running a Cumulus Linux version earlier than 3.0.0, you must perform a complete install, as described above. If you already have Cumulus Linux 3.0.0 or later installed on your switch, read Upgrading Cumulus Linux for considerations before start the process.
When bringing up Cumulus Linux for the first time, the management port makes a DHCPv4 request. To determine the IP address of the switch, you can cross reference the MAC address of the switch with your DHCP server. The MAC address should be located on the side of the switch or on the box in which the unit was shipped.
The default installation includes one system account, root, with full system privileges, and one user account, cumulus, with
sudo privileges. The root account password is set to null by default (which prohibits login), while the cumulus account is configured with this default password:
In this quick start guide, you will use the cumulus account to configure Cumulus Linux.
passwdcommand) before you configure Cumulus Linux on the switch.
All accounts except
root are permitted remote SSH login;
sudo may be used to grant a non-root account root-level access. Commands which change the system configuration require this elevated level of access.
For more information about sudo, read Using sudo to Delegate Privileges.
Serial Console Management
Users are encouraged to perform management and configuration over the network, either in band or out of band. Use of the serial console is fully supported; however, many customers prefer the convenience of network-based management.
Typically, switches ship from the manufacturer with a mating DB9 serial cable. Switches with ONIE are always set to a 115200 baud rate.
Wired Ethernet Management
Switches supported in Cumulus Linux always contain at least one dedicated Ethernet management port, which is named eth0. This interface is geared specifically for out-of-band management use. The management interface uses DHCPv4 for addressing by default. You can set a static IP address with the Network Command Line Utility (NCLU).
Example IP Configuration
Set the static IP address with the
interface address and
interface gateway NCLU commands:
These commands produce the following snippet in the /etc/network/interfaces file:
Configuring the Hostname and Timezone
To change the hostname, run
net add hostname, which modifies both the
/etc/hosts files with the desired hostname.
The command prompt in the terminal doesn't reflect the new hostname until you either log out of the switch or start a new shell.
When you use this NCLU command to set the hostname, DHCP does not override the hostname when you reboot the switch. However, if you disable the hostname setting with NCLU, DHCP does override the hostname the next time you reboot the switch.
To update the timezone, use the NTP interactive mode:
Run the following command in a terminal:
Follow the on screen menu options to select the geographic area and region.
Programs that are already running (including log files) and users currently logged in, will not see timezone changes made with interactive mode. To have the timezone set for all services and daemons, a reboot is required.
Verifying the System Time
Before you install the license, verify that the switch's date and time are correct. You must correct the time if it is wrong, as the wrong date may have other impacts on the switch like an inability to synchronize with Puppet or return errors like this one after you restart
Warning: Unit file of switchd.service changed on disk, 'systemctl daemon-reload' recommended.
Installing the License
Cumulus Linux is licensed on a per-instance basis. Each network system is fully operational, enabling any capability to be utilized on the switch with the exception of forwarding on switch panel ports. Only eth0 and console ports are activated on an unlicensed instance of Cumulus Linux. Enabling front panel ports requires a license.
You should have received a license key from Cumulus Networks or an authorized reseller. Here is a sample license key:
There are three ways to install the license onto the switch:
Copy it from a local server. Create a text file with the license and copy it to a server accessible from the switch. On the switch, use the following command to transfer the file directly on the switch, then install the license file:
Copy the file to an HTTP server (not HTTPS), then reference the URL when you run
Copy and paste the license key into the
You don't have to reboot the switch to activate the switch ports. Once you install the license, restart the
switchd service. All front panel ports become active and show up as swp1, swp2, and so forth.
If a license is not installed on a Cumulus Linux switch, the
switchd service does not start. Once you install the license, start
switchd as described above.
Configuring Breakout Ports with Splitter Cables
If you are using 4x10G DAC or AOC cables, or want to break out 100G or 40G switch ports, configure the breakout ports. For more details, see Layer 1 and Switch Port Attributes.
Testing Cable Connectivity
By default, all data plane ports (every Ethernet port except the management interface, eth0) are disabled.
To test cable connectivity, administratively enable a port:
To administratively enable all physical ports, run the following command, where swp1-52 represents a switch with switch ports numbered from swp1 to swp52:
To view link status, use
net show interface all. The following examples show the output of ports in "admin down", "down" and "up" modes:
Configuring Switch Ports
Layer 2 Port Configuration
Cumulus Linux does not put all ports into a bridge by default. To create a bridge and configure one or more front panel ports as members of the bridge, use the following examples as guides.
In the following configuration example, the front panel port swp1 is placed into a bridge called bridge. The NCLU commands are:
The commands above produce the following
A range of ports can be added in one command. For example, add swp1 through swp10, swp12, and swp14 through swp20 to bridge:
This creates the following
To view the changes in the kernel, use the
Layer 3 Port Configuration
The NCLU can also be used to configure a front panel port or bridge interface as a layer 3 port.
In the following configuration example, the front panel port swp1 is configured as a layer 3 access port:
This creates the following
To add an IP address to a bridge interface, it must be put into a VLAN interface:
This creates the following
To view the changes in the kernel use the
ip addr show command:
Configuring a Loopback Interface
Cumulus Linux has a loopback preconfigured in
/etc/network/interfaces. When the switch boots up, it has a loopback interface, called lo, which is up and assigned an IP address of 127.0.0.1.
The loopback interface lo must always be specified in
/etc/network/interfaces and must always be up.
To see the status of the loopback interface (lo), use the
net show interface lo command:
Note that the loopback is up and is assigned an IP address of 127.0.0.1.
To add an IP address to a loopback interface, configure the lo interface with NCLU:
Multiple loopback addresses can be configured by adding additional
This creates the following snippet in