Network Command Line Utility
Early Access Feature
nclu is an early access
in Cumulus Linux 3.1. Before you can install
nclu, you must enable the
Early Access repository. For more information about the Cumulus Linux
repository, read this knowledge base
The Network Command Line Utility, or NCLU, is a command line interface for Cumulus Networks products, implemented in Cumulus Linux and VX 3.1 and later releases, with the goal of simplifying the networking configuration process for all users.
The NCLU wrapper utility is called
net. In 3.1 releases,
capable of configuring L2 and L3 features of the networking stack, as
well as providing monitoring and troubleshooting functionality for these
both be configured with
net, in addition to running show and clear
commands related to ifupdown2 and Quagga.
In later releases, additional features will be available for configuration, such as VXLANs and ACLs. However, they are not provided in Cumulus Linux 3.1.
The Cumulus Linux 3.1 release of NCLU supports ifupdown2 and quagga.
To install the
nclu package, follow the instructions in the Cumulus
Linux 3.1 release
Configuration of the
net utility is done in the
This file can be configured to allow different permission levels for
users to edit configurations and run show commands.
|Configuration Variable||Default Setting||Description|
|show_linux_command||False||When true, displays the linux command running in the background.|
|enable_ifupdown2||True||Enables net wrapping of ifupdown2|
|enable_quagga||True||Enables net wrapping of Quagga|
|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-mcqv4src, bridge-mcrouter, bridge-mcsqc, bridge-mcsqi, bridge-pathcosts, bridge-port-pvids, bridge-port-vids, bridge-portmcfl, bridge-portmcrouter, bridge-portprios, 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, pre-down, pre-up, preferred-lifetime, scope, vxlan-ageing, vxlan-learning, up, down||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.
NCLU uses the following workflow for staging and committing changes to Cumulus Linux 3.1:
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
/etc/network/interfaces, as well
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 18.104.22.168/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 22.214.171.124 cumulus@switch[~]# net add int swp10 mtu <TAB> <552-9216> : cumulus@switch[~]# net add int swp10 mtu 9300 ERROR: Command not found
NCLU has a comprehensive help system built in to assist usage.
help can be used to show available commands:
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", and "help" anytime while using net. # # Use 'man net' for a more comprehensive overview. net abort net commit [verbose] net help [verbose] net pending net show configuration [commands|files] Options: # Help commands help : context sensitive information; see section below example : detailed examples of common workflows # Configuration commands add : add/modify configuration (staged in commit buffer) del : remove configuration (staged in commit buffer) # Commit buffer commands commit : apply the commit buffer to the system pending : show changes staged in the commit buffer abort : abandon changes in the commit buffer # 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 debug bgp bestpath <ip/prefixlen> net del debug bgp bestpath [<ip/prefixlen>] net show [ip] bgp [ipv4|ipv6] [unicast|multicast] (<ip>|<ip/prefixlen>) [bestpath|multipath] [json]
Multiple interfaces can be configured at once:
net add int swp7-9,12,15-17,22 mtu 9216
The NCLU has a couple of built in examples to guide users through basic configuration setup:
cumulus@switch[~]# net example <TAB> bgp bond bridge clag ... ospf : Open Shortest Path First 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 126.96.36.199/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 188.8.131.52/24 to the SVI for vlan 20 switch1# net add vlan-interface vlan10 address 10.0.0.1/24 switch1# net add vlan-interface vlan20 address 184.108.40.206/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 bridge switch1# net show l2