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 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/quagga/Quagga.conf can both be configured with
net, in addition
to running show and clear commands related to ifupdown2 and Quagga.
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
netstatcounters, 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 220.127.116.11/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 18.104.22.168 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 show commit (history|<number>|<number-range>|last) net 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
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 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 22.214.171.124/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 126.96.36.199/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 188.8.131.52/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
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
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 privilieges.|
|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.