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.

Network Command Line Utility

The Network Command Line Utility, or NCLU, is a command line interface for Cumulus Networks products, implemented in Cumulus RMP 3.1 and later releases, with the goal of simplifying the networking configuration process for all users.

NCLU resides in the Linux user space, as seen below. It provides consistent access to networking commands directly via bash, thereby making configuration and troubleshooting simple and easy - no need to edit files or enter modes and sub-modes. In addition, NCLU does more than traditional command line interfaces by:

  • Embedding help, examples and automatic command checking with suggestions in case you’ve entered a typo

  • Running directly from and integrating with bash, while being interoperable with the regular way of accessing underlying configuration files and automation

  • Automatically configuring dependent features so you don’t have to


The NCLU wrapper utility is called net. net is capable of configuring L2 and L3 features of the networking stack, rolling back and deleting snapshots, as well as providing monitoring and troubleshooting functionality for these features. /etc/network/interfaces and /etc/quagga/Quagga.conf can both be configured with net, in addition to running show and clear commands related to ifupdown2 and Quagga.

Getting Started

NCLU uses the following workflow for staging and committing changes to Cumulus Linux:

  1. Use the net add and net del commands to stage/remove configuration changes.

  2. Use the net pending command to review staged changes.

  3. Use net commit and net abort to commit/delete staged changes.

net commit applies the changes to the relevant configuration files, such as /etc/network/interfaces, then runs necessary follow on commands to enable the configuration, such as ifreload -a.

Once you have a running configuration, you can review and update it using:

  • net show: A series of commands for viewing various parts of the network configuration, such as net show configuration, net show commit history and net show bgp to view the complete network configuration, a history of commits using NCLU and BGP status, respectively.

  • net clear: A way to clear netstat counters, BGP and OSPF neighbor content, and more.

  • net rollback: Provides a mechanism to revert back to an earlier configuration.

Tab Completion, Verification and Inline Help

NCLU provides a number of features to assist users. In addition to tab completion and partial keyword commands identification, verification checks are set in place to ensure correct syntax is used. The examples below show the output for incorrect commands:

cumulus@switch:~$ net add bgp router-id
ERROR: Command not found
Did you mean one of the following?
    net add bgp router-id <ipv4>
        This command is looking for an IP address, not an IP/prefixlen
cumulus@switch:~$ net add bgp router-id
cumulus@switch:~$ net add int swp10 mtu <TAB>
    <552-9216> : 
cumulus@switch:~$ net add int swp10 mtu 9300
ERROR: Command not found
Did you mean one of the following?
    net add interface <interface> mtu <552-9216>

NCLU has a comprehensive help system built in to assist usage. In addition to the net man page, you can use ? and help to display available commands:

cumulus@switch:~$ net help
    # net <COMMAND> [<ARGS>] [help]
    # net is a command line utility for networking on Cumulus Linux switches.
    # COMMANDS are listed below and have context specific arguments which can
    # be explored by typing "<TAB>" or "help" anytime while using net.
    # Use 'man net' for a more comprehensive overview.
    net abort
    net commit [verbose] [confirm] [description <wildcard>]
    net commit delete (<number>|<number-range>)
    net help [verbose]
    net pending
    net show commit (history|<number>|<number-range>|last)
    net rollback (<number>|last)
    net show configuration [commands|files|acl|bgp|ospf|ospf6|interface <interface>]
    # Help commands
    help    : context sensitive information; see section below
    example : detailed examples of common workflows
    # Configuration commands
    add     : add/modify configuration
    del     : remove configuration
    # Commit buffer commands
    abort    : abandon changes in the commit buffer
    commit   : apply the commit buffer to the system
    pending  : show changes staged in the commit buffer
    rollback : revert to a previous configuration state
    # Status commands
    show    : show command output
    clear   : clear counters, BGP neighbors, etc
cumulus@switch:~$ net help bestpath
The following commands contain keyword(s) 'bestpath'
    net (add|del) bgp bestpath as-path multipath-relax [as-set|no-as-set]
    net (add|del) bgp bestpath compare-routerid
    net (add|del) bgp bestpath med missing-as-worst
    net (add|del) bgp vrf <text> bestpath as-path multipath-relax [as-set|no-as-set]
    net (add|del) bgp vrf <text> bestpath compare-routerid
    net (add|del) bgp vrf <text> bestpath med missing-as-worst
    net add bgp debug bestpath <ip/prefixlen>
    net del bgp debug bestpath [<ip/prefixlen>]
    net show bgp (<ipv4>|<ipv4/prefixlen>) [bestpath|multipath] [json]
    net show bgp (<ipv6>|<ipv6/prefixlen>) [bestpath|multipath] [json]
    net show bgp vrf <text> (<ipv4>|<ipv4/prefixlen>) [bestpath|multipath] [json]

Multiple interfaces can be configured at once:

cumulus@switch:~$ net add int swp7-9,12,15-17,22 mtu 9216

Built-In Examples

The NCLU has a number of built in examples to guide users through basic configuration setup:

cumulus@switch:~$ net example 
    acl              :  access-list
    bgp              :  Border Gateway Protocol
    bond             :  Bond, port-channel, etc
    bridge           :  interface
    clag             :  Multi-Chassis Link Aggregation
    link-settings    :  Physical link parameters
    lnv              :  Lightweight Network Virtualization
    management-vrf   :  Management VRF
    ospf             :  Open Shortest Path First (OSPFv2)
    vlan-interfaces  :  IP interfaces for VLANs
cumulus@switch:~$ net example bridge
We are configuring switch1 and would like to configure the following
- configure switch1 as an L2 switch for host-11 and host-12
- enable vlans 10-20
- place host-11 in vlan 10
- place host-12 in vlan 20
- create an SVI interface for vlan 10
- create an SVI interface for vlan 20
- assign IP to the SVI for vlan 10
- assign IP to the SVI for vlan 20
- configure swp3 as a trunk for vlans 10, 11, 12 and 20
     *switch1 --------- switch2
  swp1 /  \ swp2
      /    \
     /      \
 host-11   host-12
switch1 net commands
- enable vlans 10-20
switch1# net add vlan 10-20
- place host-11 in vlan 10
- place host-12 in vlan 20
switch1# net add int swp1 bridge access 10
switch1# net add int swp2 bridge access 20
- create an SVI interface for vlan 10
- create an SVI interface for vlan 20
- assign IP to the SVI for vlan 10
- assign IP to the SVI for vlan 20
switch1# net add vlan 10 ip address
switch1# net add vlan 20 ip address
- configure swp3 as a trunk for vlans 10, 11, 12 and 20
switch1# net add int swp3 bridge trunk vlans 10-12,20
# Review and commit changes
switch1# net pending
switch1# net commit
switch1# net show interface
switch1# net show bridge macs

Restarting the netd Service

Whenever you modify netd.conf, you must restart the netd service for the changes to take effect:

cumulus@switch:~$ sudo systemctl restart netd.service

Advanced Configuration

NCLU needs no initial configuration; it’s ready to go in Cumulus Linux. However, if you need to modify its configuration, you must manually update the /etc/netd.conf file. This file can be configured to allow different permission levels for users to edit configurations and run show commands. It also contains a blacklist that hides less frequently used terms from the tabbed autocomplete.

Configuration VariableDefault SettingDescription
show_linux_commandFalseWhen true, displays the Linux command running in the background
enable_ifupdown2TrueEnables net wrapping of ifupdown2 commands.
users_with_editroot, cumulusSets the Linux users with root edit privileges.
groups_with_editroot, cumulusSets the Linux groups with root edit privilieges.
ifupdown_blacklistaddress-purge, bond-ad-actor-sys-prio, bond-ad-actor-system, bond-mode, bond-num-grat-arp, bond-num-unsol-na, bond-use-carrier, bond-xmit-hash-policy, bridge-bridgeprio, bridge-fd, bridge-hashel, bridge-hashmax, bridge-hello, bridge-maxage, bridge-maxwait, bridge-mclmc, bridge-mclmi, bridge-mcmi, bridge-mcqi, bridge-mcqpi, bridge-mcqri, bridge-mcrouter, bridge-mcsqc, bridge-mcsqi, bridge-pathcosts, bridge-port-pvids, bridge-port-vids, bridge-portprios, bridge-stp, bridge-waitport, broadcast, hwaddress, link-type, mstpctl-ageing, mstpctl-fdelay, mstpctl-forcevers, mstpctl-hello, mstpctl-maxage, mstpctl-maxhops, mstpctl-portp2p, mstpctl-portpathcost, mstpctl-portrestrrole, mstpctl-portrestrtcn, mstpctl-treeportcost, mstpctl-treeportprio, mstpctl-txholdcount, netmask, preferred-lifetime, scope, vxlan-ageing, vxlan-learning, up, down, bridge-ageing, bridge-gcint, bridge-mcqifaddr, bridge-mcqv4srcHides corner case command options from tab complete, to simplify and streamline output.

Net Tab Complete Output

net provides an environment variable for setting where the net output is directed. To only use stdout, set the NCLU_TAB_STDOUT environment variable to true. The value is not case sensitive.