The Network Command Line Utility (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 and provides consistent access to networking commands directly through bash, making configuration and troubleshooting simple and easy; no need to edit files or enter modes and sub-modes. NCLU provides these benefits:
- Embeds help, examples, and automatic command checking with suggestions in case you enter a typo.
- Runs directly from and integrates with bash, while being interoperable with the regular way of accessing underlying configuration files and automation.
- Configures dependent features automatically so that you don't have to.
The NCLU wrapper utility called
net is capable of configuring layer 2 and layer 3 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. You can configure both the
/etc/frr/frr.conf files with
net, in addition to running show and clear commands related to
ifupdown2 and FRRouting.
If you upgraded Cumulus Linux from a version earlier than 3.2 instead of performing a full disk image install, you need to install the
nclu package on your switch:
nclu package installs a new bash completion script and displays the following message:
Use the following workflow to stage and commit changes to Cumulus Linux with NCLU:
net delcommands to stage and remove configuration changes.
net pendingcommand to review staged changes.
net abortto commit and 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
If two different users try to commit a change at the same time, NCLU displays a warning but implements the change according to the first commit received. The second user will need to abort the commit.
When you have a running configuration, you can review and update the configuration with the following commands:
net showis a series of commands for viewing various parts of the network configuration. For example, use
net show configurationto view the complete network configuration,
net show commit history
net show bgpto view BGP status.
net clearprovides a way to clear
net showcounters, BGP and OSPF neighbor content, and more.
net rollbackprovides a mechanism to revert back to an earlier configuration.
net commit confirmrequires you to press Enter to commit changes using NCLU. If you run
net commit confirmbut do not press Enter within 10 seconds, the commit automatically reverts and no changes are made.
net commit description <description>enables you to provide a descriptive summary of the changes you are about to commit.
net commit permanentretains the snapshot taken when committing the change. Otherwise, the snapshots created from NCLU commands are cleaned up periodically with a snapper cron job.
net commit deletedeletes one or more snapshots created when committing changes with NCLU.
net del alldeletes all configurations and stops the IEEE 802.1X service.
net del allcommand does not remove management VRF configurations; NCLU does not interact with eth0 interfaces and management VRF.
Tab Completion, Verification, and Inline Help
In addition to tab completion and partial keyword command identification, NCLU includes verification checks to ensure correct syntax is used. The examples below show the output for incorrect commands:
NCLU has a comprehensive built in help system. In addition to the net man page, you can use
help to display available commands:
You can configure multiple interfaces at once:
Add ? (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:
Uncomment the very last line in the
.inputrc file so that the file changes from this:
Save the file and reconnect to the switch. The ? (question mark) ability will work on all subsequent sessions on the switch.
When the question mark is typed, NCLU autocompletes and shows all available options, but the question mark does not actually appear on the terminal. This is normal, expected behavior.
NCLU has a number of built in examples to guide users through basic configuration setup:
Configure 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:
To add NCLU show permissions to a user account that already exists:
To add a new user account with NCLU edit permissions:
To add NCLU edit permissions to a user account that already exists:
If the user tries to run commands that are not allowed, the following error displays:
Edit 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
To configure a new user group to use NCLU, add that group to the
groups_with_show lines in the file.
Use caution giving edit permissions to groups. For example, don't give edit permissions to the tacacs group.
Restart the netd Service
Whenever you modify
netd.conf, you must restart the
netd service for the changes to take effect:
Back 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 use the
source command to apply that configuration to those switches.
For example, to copy the configuration of a leaf switch called leaf01, run the following command:
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:
NCLU needs no initial configuration; however, if you need to modify its configuration, you must manually update the
/etc/netd.conf file. You can configure this file to allow different permission levels for users to edit configurations and run
show commands. The file also contains a blacklist that hides less frequently used terms from the tabbed autocomplete.
After you edit the
netd.conf file, restart the
netd service for the changes to take effect.
When true, displays the Linux command running in the background.
Sets the Linux users with root edit privileges.
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 |
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 to set 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.