Network Command Line Utility - NCLU
The Network Command Line Utility, or NCLU, is a command line interface for Cumulus Networks products that simplifies 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 is capable of
configuring L2 and L3 features of the networking stack, installing ACLs
and VXLANs, rolling back and deleting snapshots, as well as providing
monitoring and troubleshooting functionality for these features.
/etc/frr/frr.conf can both be configured
net, in addition to running show and clear commands related to
ifupdown2 and FRRouting.
What’s New and Different in NCLU in Version 3.5?
A number of commands have been added, updated, or removed from NCLU in the new release. Read more about what’s changed in this knowledge base article.
If you upgraded Cumulus Linux from a version earlier than 3.2 instead of
performing a full binary install, you need to install the
on your switch:
cumulus@switch:~$ sudo -E apt-get update cumulus@switch:~$ sudo -E apt-get install nclu cumulus@switch:~$ sudo -E apt-get upgrade
nclu package installs a new bash completion script, and displays
the following message when it is manually installed:
Setting up nclu (1.0-cl3u3) ... To enable the newly installed bash completion for nclu in this shell, execute... source /etc/bash_completion
NCLU uses the following workflow for staging and committing changes to Cumulus Linux:
net delcommands to stage/remove configuration changes.
net pendingcommand to review staged changes.
net abortto commit/delete staged changes.
net commit applies the changes to the relevant configuration files,
/etc/network/interfaces, then runs necessary follow on
commands to enable the configuration, such as
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 historyand
net show bgpto view the complete network configuration, a history of commits using NCLU and BGP status, respectively.
net clear: A way to clear
net showcounters, BGP and OSPF neighbor content, and more.
net rollback: Provides a mechanism to revert back to an earlier configuration.
net commit confirm: Requires the user to press Enter in order to commit changes via NCLU. If you run
net commit confirmbut do not press Enter within 10 seconds, the commit is automatically reverted and nothing changes.
net commit permanent: Retains the snapshot taken when committing the change. Otherwise, the snapshots created from NCLU commands are cleaned up periodically via a snapper cron job.
net commit delete: Deletes one or more snapshots created when committing changes with NCLU.
net del all: Deletes all configurations and stops the IEEE 802.1X service.
This command does not remove management VRF configurations, as NCLU does not interact with eth0 interfaces and management VRF at all.
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 126.96.36.199/32 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 188.8.131.52 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
help to display
cumulus@switch:~$ net help Usage: # 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 rollback (<number>|last) net show commit (history|<number>|<number-range>|last) net show rollback (<number>|last) net show configuration [commands|files|acl|bgp|ospf|ospf6|interface <interface>] Options: # 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
Adding ? (Question Mark) Ability to NCLU
While tab completion is enabled by default, you can also configure NCLU to use the ? (question mark character) to look at available commands. To enable this feature for the cumulus user, open the following file:
cumulus@leaf01:~$ sudo nano ~/.inputrc
Uncomment the very last line in the
.inputrc file so that the file
changes from this:
# Uncomment to use ? as an alternative to # ?: complete
# Uncomment to use ? as an alternative to ?: complete
Save the file and reconnect to the switch. The ? (question mark) ability will work on all subsequent sessions on the switch.
cumulus@leaf01:~$ net abort : abandon changes in the commit buffer add : add/modify configuration clear : clear counters, BGP neighbors, etc commit : apply the commit buffer to the system del : remove configuration example : detailed examples of common workflows help : Show this screen and exit pending : show changes staged in the commit buffer rollback : revert to a previous configuration state show : show command output
When the question mark is typed, NCLU will autocomplete and show all available options, but the question mark won’t actually appear on the terminal. This is normal, expected behavior.
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 : A layer2 bridge clag : Multi-Chassis Link Aggregation dot1x : Configure, Enable, Delete or Show IEEE 802.1X EAPOL link-settings : Physical link parameters lnv : Lightweight Network Virtualization management-vrf : Management VRF mlag : Multi-Chassis Link Aggregation ospf : Open Shortest Path First (OSPFv2) vlan-interfaces : IP interfaces for VLANs cumulus@switch:~$ net example bridge Scenario ======== 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 10.0.0.1/24 to the SVI for vlan 10 - assign IP 184.108.40.206/24 to the SVI for vlan 20 - configure swp3 as a trunk for vlans 10, 11, 12 and 20 swp3 *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 10.0.0.1/24 to the SVI for vlan 10 - assign IP 220.127.116.11/24 to the SVI for vlan 20 switch1# net add vlan 10 ip address 10.0.0.1/24 switch1# net add vlan 20 ip address 18.104.22.168/24 - 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 Verification ============ switch1# net show interface switch1# net show bridge macs
Configuring User Accounts
You can configure user accounts in Cumulus Linux with read-only or edit permissions for NCLU:
You create user accounts with read-only permissions for NCLU by adding them to the
netshowgroup. A user in the
netshowgroup can run NCLU
net showcommands, such as
net show interfaceor
net show config, and certain general Linux commands, such as
man, but cannot run
You create user accounts with edit permissions for NCLU by adding them to the
neteditgroup. A user in the
neteditgroup can run NCLU configuration commands, such
net commitin addition to NCLU
The examples below demonstrate how to add a new user account or modify an existing user account called myuser.
To add a new user account with NCLU show permissions:
cumulus@switch:~$ sudo adduser --ingroup netshow myuser Adding user `myuser' ... Adding new user `myuser' (1001) with group `netshow' ...
To add NCLU show permissions to a user account that already exists:
cumulus@switch:~$ sudo addgroup myuser netshow Adding user `myuser' to group `netshow' ... Adding user myuser to group netshow Done
To add a new user account with NCLU edit permissions:
cumulus@switch:~$ sudo adduser --ingroup netedit myuser Adding user `myuser' ... Adding new user `myuser' (1001) with group `netedit' ...
To add NCLU edit permissions to a user account that already exists:
cumulus@switch:~$ sudo addgroup myuser netedit Adding user `myuser' to group `netedit' ... Adding user myuser to group netedit Done
You can use the
adduser command for local user accounts only. You can
addgroup command for both local and remote user accounts. For
a remote user account, you must use the mapping username, such as
radius_user, not the
If the user tries to run commands that are not allowed, the following error displays:
myuser@switch:~$ net add hostname host01 ERROR: User username does not have permission to make networking changes.
Editing the netd.conf File
Instead of using the NCLU commands described above, you can manually configure users and groups to be able to run NCLU commands.
/etc/netd.conf file to add users to the users_with_edit
and users_with_show lines in the file, then save the file.
For example, if you want the user netoperator to be able to run both
edit and show commands, add the user to the
users_with_show lines in the
cumulus@switch:~$ sudo nano /etc/netd.conf # Control which users/groups are allowed to run 'add', 'del', # 'clear', 'net abort', 'net commit' and restart services # to apply those changes users_with_edit = root, cumulus, netoperator groups_with_edit = root, cumulus # Control which users/groups are allowed to run 'show' commands users_with_show = root, cumulus, netoperator groups_with_show = root, cumulus
To configure a new user group to use NCLU, add that group to the
groups_with_show lines in the file.
Use caution giving groups edit permissions. For example, you don’t want to give edit permissions to the tacacs group.
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
Backing up the Configuration to a Single File
You can easily back up your NCLU configuration to a file by outputting
the results of
net show configuration commands to a file, then
retrieving the contents of the file using the
source command. You can
then view the configuration at any time or copy it to other switches and
source command to apply that configuration to those switches.
For example, to copy out the configuration of a leaf switch called leaf01, you would run something like the following:
cumulus@leaf01:~$ net show configuration commands >> leaf01.txt
With the commands all stored in a single file, you can now copy this file to another ToR switch in your network called leaf01 and apply the configuration by running:
cumulus@leaf01:~$ source leaf01.txt
NCLU needs no initial configuration; it’s ready to go in Cumulus Linux.
However, if you need to modify its configuration, you must manually
/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 Variable||Default Setting||Description|
|show_linux_command||False||When true, displays the Linux command running in the background.|
|users_with_edit||root, cumulus||Sets the Linux users with root edit privileges.|
|groups_with_edit||root, cumulus||Sets the Linux groups with root edit privileges.|
|users_with_show||root, cumulus||Controls which users are allowed to run |
|groups_with_show||root, cumulus||Controls which groups are allowed to run |
|ifupdown_blacklist||address-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-mcqv4src||Hides 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
output is directed. To only use
stdout, set the NCLU_TAB_STDOUT
environment variable to true. The value is not case sensitive.