NVUE CLI

The NVUE CLI has a flat structure instead of a modal structure. Therefore, you can run all commands from the primary prompt instead of only in a specific mode.

Command Syntax

NVUE commands all begin with nv and fall into one of three syntax categories:

• Configuration (nv set and nv unset)
• Monitoring (nv show)
• Configuration management (nv config)
• Action commands (nv action)

Command Completion

As you enter commands, you can get help with the valid keywords or options using the tab key. For example, using tab completion with nv set displays the possible options for the command and returns you to the command prompt to complete the command.

cumulus@switch:~$ nv set <<press tab>>
acl        evpn       mlag       platform   router     system     
bridge     interface  nve        qos        service    vrf
cumulus@switch:~$ nv set

Command Question Mark

You can type a question mark (?) after a command to display required information quickly and concisely. When you type ?, NVUE specifies the value type, range, and options with a brief description of each; for example:

cumulus@switch:~$ nv set interface swp1 link state ?
    [Enter]               
    down                   The interface is not ready
    up                     The interface is ready
cumulus@switch:~$ nv set interface swp1 link mtu ?
    <arg>                  (integer:552 - 9216)
cumulus@switch:~$ nv set interface swp1 link speed ?
    <arg>                  (string | enum:10M, 100M, 1G, 10G, 25G, 40G, 50G, 100G,
                           200G, 400G, 800G, auto)

NVUE also indicates if you need to provide specific values for the command:

cumulus@switch:~$ nv set interface swp1 bridge domain ?
    <domain-id>            Domain (bridge-name)

Command Abbreviation

NVUE supports command abbreviation, where you can type a certain number of characters instead of a whole command to speed up CLI interaction. For example, instead of typing nv show interface, you can type nv sh int.

If the command you type is ambiguous, NVUE shows the reason for the ambiguity so that you can correct the shortcut. For example:

cumulus@switch:~$ nv s i 
Ambiguous Command: 
   set interface 
   show interface 

Command Help

As you enter commands, you can get help with command syntax by entering -h or --help at various points within a command entry. For example, to examine the options available for nv set interface, enter nv set interface -h or nv set interface --help.

cumulus@switch:~$ nv set interface -h
usage: 
  nv [options] set interface <interface-id>

Description:
  interface             Update all interfaces. Provide single interface or multiple interfaces using ranging (e.g. swp1-2,5-6 -> swp1,swp2,swp5,swp6).

Identifiers:
  <interface-id>        Interface (interface-name)

General Options:
  -h, --help            Show help.

Command List

You can list all the NVUE commands by running nv list-commands. See List All NVUE Commands below.

Command History

At the command prompt, press the Up Arrow and Down Arrow keys to move back and forth through the list of commands you entered previously. When you find the command you want to use, you can run the command by pressing Enter. You can also modify the command before you run it.

Command Categories

The NVUE CLI has a flat structure; however, the commands are in three functional categories:

• Configuration
• Monitoring
• Configuration Management
• Action

Configuration Commands

The NVUE configuration commands modify switch configuration. You can set and unset configuration options.

The nv set and nv unset commands are in the following categories. Each command group includes subcommands. Use command completion (press the tab key) to list the subcommands.

Monitoring Commands

The NVUE monitoring commands show various parts of the network configuration. For example, you can show the complete network configuration or only interface configuration. The monitoring commands are in the following categories. Each command group includes subcommands. Use command completion (press the tab key) to list the subcommands.

The following example shows the nv show router commands after pressing the tab key, then shows the output of the nv show router bgp command.

cumulus@leaf01:mgmt:~$ nv show router <<tab>>
adaptive-routing  igmp              ospf              pim               ptm               vrrp              
bgp               nexthop           pbr               policy            vrr               

cumulus@leaf01:mgmt:~$ nv show router bgp
                                operational  applied  pending
------------------------------  -----------  -------  -----------  ----------------------------------------------------------------------
                                applied      pending    
------------------------------  -----------  -----------
enable                          on           on         
autonomous-system               65101        65101      
router-id                       10.10.10.1   10.10.10.1 
policy-update-timer             5            5          
graceful-shutdown               off          off        
wait-for-install                off          off        
graceful-restart                                        
  mode                          helper-only  helper-only
  restart-time                  120          120        
  path-selection-deferral-time  360          360        
  stale-routes-time             360          360        
convergence-wait                                        
  time                          0            0          
  establish-wait-time           0            0          
queue-limit                                             
  input                         10000        10000      
  output                        10000        10000 

Additional options are available for certain nv show commands. For example, you can choose the configuration you want to show (pending, applied, startup, or operational). You can also turn on colored output, and paginate specific output.

The following example shows pending BGP graceful restart configuration:

cumulus@switch:~$ nv show router bgp graceful-restart --pending
                              Rev ID: 8                  
----------------------------  -----------------  
mode                          helper-only        
path-selection-deferral-time  360              
restart-time                  120              
stale-routes-time             360              

The following example shows the views available for the nv show interface command:

cumulus@switch:~$ nv show interface --view <<TAB>>
acl-statistics  carrier-stats   dot1x-counters  lldp-detail     physical        status          vrf
bond-members    counters        dot1x-summary   mac             port-security   svi             
bonds           description     down            mlag-cc         qos-profile     synce-counters  
brief           detail          lldp            neighbor        small           up

Configuration Management Commands

The NVUE configuration management commands manage and apply configurations.

You can use the NVUE configuration management commands to back up and restore configuration when you upgrade Cumulus Linux on the switch. Refer to Upgrading Cumulus Linux.

Action Commands

The NVUE action commands clear counters, and provide system reboot and TACACS user disconnect options.

List All NVUE Commands

To show the full list of NVUE commands, run nv list-commands. For example:

cumulus@switch:~$ nv list-commands
nv show platform
nv show platform inventory
nv show platform inventory <inventory-id>
nv show platform software
nv show platform software installed
nv show platform software installed <installed-id>
nv show platform firmware
nv show platform firmware <platform-component-id>
nv show platform environment
...

You can show the list of commands for a command grouping. For example, to show the list of interface commands:

cumulus@switch:~$ nv list-commands interface
nv show interface
nv show interface <interface-id>
nv show interface <interface-id> ip
nv show interface <interface-id> ip address
nv show interface <interface-id> ip address <ip-prefix-id>
nv show interface <interface-id> ip gateway
nv show interface <interface-id> ip gateway <ip-address-id>
...

To view the NVUE command reference for Cumulus Linux, which describes all the NVUE CLI commands and provides examples, go to the NVUE Command Reference.

NVUE Configuration File

When you save network configuration, NVUE writes the configuration to the /etc/nvue.d/startup.yaml file.

You can edit or replace the contents of the /etc/nvue.d/startup.yaml file. NVUE applies the configuration in the /etc/nvue.d/startup.yaml file during system boot only if the nvue-startup.service is running. If this service is not running, the switch reboots with the same configuration that is running before the reboot.

To start nvue-startup.service:

cumulus@switch:~$ sudo systemctl enable nvue-startup.service
cumulus@switch:~$ sudo systemctl start nvue-startup.service

When you apply a configuration with nv config apply, NVUE also writes to underlying Linux files such as /etc/network/interfaces and /etc/frr/frr.conf. You can view these configuration files; however, do not manually edit them while using NVUE. If you need to configure certain network settings manually or use automation such as Ansible to configure the switch, see Configure NVUE to Ignore Linux Files below.

Default Startup File

NVUE provides a default /etc/nvue.d/startup.yaml file that includes configuration such as the switch hostname, default firewall rules, and cumulus user account credentials. The file also enables the NVUE API. This file is the factory configuration file that you can restore at any time.

Encrypted Passwords

By default, NVUE encrypts passwords, such as the RADIUS secret, TACACS secret, BGP peer password, OSPF MD5 key, and SNMP strings in the startup.yaml file. You can disable password encryption with the nv set system security encryption db state disabled command:

cumulus@switch:~$ nv set system security encryption db state disabled
cumulus@switch:~$ nv config apply

To reenable password encryption, run the nv set system security encryption db state enabled command.

To show if password encryption is on, run the nv show system security encryption command:

cumulus@switch:~$ nv show system security encryption
         operational  applied
-------  -----------  -------
db                           
  state               enabled

Configuration Files that NVUE Manages

NVUE manages the following configuration files:

Search for a Specific Configuration

To search for a specific portion of the NVUE configuration, run the nv config find <search string> command. The search shows all items above and below the search string. For example, to search the entire NVUE object model configuration for any mention of ptm:

cumulus@switch:~$ nv config find bond1
- set:
    interface:
      bond1:
        bond:
          lacp-bypass: on
          member:
            swp1: {}
          mlag:
            enable: on
            id: 1
        bridge:
          domain:
            br_default:
              access: 10
        link:
          mtu: 9000
        type: bond

Configure NVUE to Ignore Linux Files

You can configure NVUE to ignore certain underlying Linux files when applying configuration changes. For example, if you push certain configuration to the switch using Ansible and Jinja2 file templates or you want to use custom configuration for a particular service such as PTP, you can ensure that NVUE never writes to those configuration files.

The following example configures NVUE to ignore the Linux /etc/ptp4l.conf file when applying configuration changes.

cumulus@switch:~$ nv set system config apply ignore /etc/ptp4l.conf
cumulus@switch:~$ nv config apply

Auto Save

By default, when you run the nv config apply command to apply a configuration setting, NVUE applies the pending configuration to become the applied configuration and automatically saves the changes to the startup configuration file (/etc/nvue.d/startup.yaml).

To disable auto save so that NVUE does not save applied configuration changes, run the nv set system config auto-save state disabled command:

cumulus@switch:~$ nv set system config auto-save state disabled
cumulus@switch:~$ nv config apply

When you disable auto save, you must run the nv config save command to save the applied configuration to the startup configuration so that the changes persist after a reboot.

To renable auto save, run the nv set system config auto-save state enabled command.

Show Switch Configuration

To show the applied configuration on the switch, run the nv config show command:

cumulus@switch:~$ nv config show
header:
    model: VX
    nvue-api-version: nvue_v1
    rev-id: 1.0
    version: Cumulus Linux 5.7.0
- set:
    bridge:
      domain:
        br_default:
          vlan:
            '10':
              vni:
                '10': {}
            '20':
              vni:
                '20': {}
            '30':
              vni:
                '30': {}
...

To show the configuration on the switch in YAML format and include all default options, run the nv config show --all command.

Add Configuration Apply Messages

When you run the nv config apply command, you can add a message that describes the configuration updates you make. You can see the message when you run the nv config history command.

To add a configuration apply message, run the nv config apply -m <message> command. If the message includes more than one word, enclose the message in quotes.

cumulus@switch:~$ nv config apply -m "this is my message"

Reset NVUE Configuration to Default Values

To reset the NVUE configuration on the switch back to the default values, run the following command:

cumulus@switch:~$ nv config replace /usr/lib/python3/dist-packages/cue_config_v1/initial.yaml
cumulus@switch:~$ nv config apply

Detach a Pending Configuration

The following example configures the IP address of the loopback interface, then detaches the configuration from the current pending configuration. Cumulus Linux saves the detached configuration to a file with a numerical value to distinguish it from other pending configurations.

cumulus@switch:~$ nv set interface lo ip address 10.10.10.1/32
cumulus@switch:~$ nv config detach

View Differences Between Configurations

To view differences between configurations, run the nv config diff command.

To view differences between two detached pending configurations, run the nv config diff «tab» command to list all the current detached pending configurations, then run the nv config diff command with the pending configurations you want to diff.

cumulus@switch:~$ nv config diff <<press tab>>
1        2        3        4        5        6        applied  empty    startup

cumulus@switch:~$ nv config diff 2 3
- unset:
    system:
      wjh:
        channel:
          forwarding:
            trigger:
              l2:

To view differences between the applied configuration and the startup configuration:

cumulus@switch:~$ nv config diff applied startup
- unset:
    interface:
    system:
      wjh:

Replace and Patch a Pending Configuration

The following example replaces the pending configuration with the contents of the YAML configuration file called nv-02/13/2021.yaml located in the /deps directory:

cumulus@switch:~$ nv config replace /deps/nv-02/13/2021.yaml

The following example patches the pending configuration (runs the set or unset commands from the configuration in the nv-02/13/2021.yaml file located in the /deps directory):

cumulus@switch:~$ nv config patch /deps/nv-02/13/2021.yaml

Translate a Configuration Revision or File

NVUE provides commands to translate an NVUE configuration revision or yaml file into NVUE commands. The revision ID must be either an integer or a named revision (such as startup, applied, pending). The configuration file must be located on the switch and must include the full path to the file containing the configuration you want to translate. The file must be in YAML format and must be accessible with proper read permissions.

To translate a specific NVUE configuration revision, run the nv config translate system config revision <revision-id> command. NVUE displays the translation on the console.

The following command translates the configuration in revision 1:

cumulus@switch:~$ nv config translate revision 10 

The following command translates the configuration in the applied revision:

cumulus@switch:~$ nv config translate revision applied 

To translate a configuration file, run the nv config translate system config input-file <file-path> command. The following example translates the backup.yaml file in the /home/cumulus directory. NVUE displays the translation on the console.

cumulus@switch:~$ nv config translate input-file /home/cumulus/backup.yaml

If the revision or yaml file is not readable, is in an invalid format, or includes invalid parameters, NVUE returns an error message and prompts you to correct the issue before proceeding.

Session-Based Authentication

NVUE uses sessions to authenticate and authorize requests. After authenticating the user with the first request, NVUE stores the session in the nvued cache. NVUE authenticates subsequent interactions within the session locally so that it does not have to keep checking with external authentication servers. This process enhances system performance and efficiency, making it ideal for high-traffic environments.

• If you make changes to a user group, password, RADIUS, TACACS, or LDAP server setting locally on the switch, NVUE clears the current session automatically.
• If you make changes directly on the RADIUS, TACACS, or LDAP server, you must clear the user session with the nv action clear system api session user <user> command or clear all sessions with the nv action clear system api session command.

The following example clears the admin user session:

cumulus@switch:~$ nv action clear system api session user admin

The following example clears all sessions:

cumulus@switch:~$ nv action clear system api session

Passwords and Special Characters

If you use certain special characters in a password, you must quote or escape (with a backslash) these characters so that the system understands that they are part of the password.

The following table shows if you need to quote or escape a special character.

• Normal Use indicates that you can use the special character without quotes or a backslash.
• Single Quotes and Double Quotes indicate that the entire password needs to be enclosed in quotes.

1. Requires escape (\) in addition to the double quotes ("").
2. You cannot use this character at the beginning of a word.
3. A word cannot consist entirely of white space, even inside double quotes.

The following example shows a password that includes a question mark (?):

cumulus@switch:~$ nv set system aaa user cumulus password “Hello?world123”

The following example shows a password that includes a dot (.):

cumulus@switch:~$ nv set system aaa user cumulus password “Hello.world.123”

The following example shows a password that includes a dot (.) and tilde (~):

cumulus@switch:~$ nv set system aaa user cumulus password “Hello.world\~123”

Filter nv show Command Output

Filters show command output on column data; for example, to show only the interfaces with MTU set to 1500:

cumulus@switch:~$ nv show interface --filter mtu=1500

To filter on multiple column outputs, enclose the entire filter in double quotes; for example, to show data for bridges with MTU 9216:

cumulus@switch:~$ nv show interface --filter "type=bridge&mtu=9216" 

You can use wildcards; for example, to show all IP addresses that start with 1 for swp1:

cumulus@switch:~$ nv show interface swp1 --filter "ip.address=1*"

You can filter on all revisions (operational, applied, and pending); for example, to show all IP addresses that start with 1 for swp1 in the applied revision:

cumulus@switch:~$ nv show interface --filter "ip.address=1*" --rev=applied

You can filter the FRR nv show vrf <vrf> router rib command output by protocol (gp, ospf, kernel, static, ospf6, sharp, or connected); for example, to show all BGP IPv4 routes in the routing table:

cumulus@switch:~$ nv show vrf default router rib ipv4 route --filter=protocol=bgp                                                                             
Flags - * - selected, q - queued, o - offloaded, i - installed, S - fib-        
selected, x - failed                                                            
                                                                                
Route            Protocol  Distance  Uptime                NHGId  Metric  Flags
---------------  --------  --------  --------------------  -----  ------  -----
10.0.1.34/32     bgp       20        2024-12-17T10:24:14Z  127    0       *Si  
10.0.1.255/32    bgp       20        2024-12-17T10:24:10Z  127    0       *Si  
10.10.10.2/32    bgp       20        2024-12-17T10:24:10Z  62     0       *Si  
10.10.10.3/32    bgp       20        2024-12-17T10:24:17Z  127    0       *Si  
10.10.10.4/32    bgp       20        2024-12-17T10:24:10Z  127    0       *Si  
10.10.10.63/32   bgp       20        2024-12-17T10:24:10Z  127    0       *Si  
10.10.10.64/32   bgp       20        2024-12-17T10:24:17Z  127    0       *Si  
10.10.10.101/32  bgp       20        2024-12-17T10:24:10Z  102    0       *Si  
10.10.10.102/32  bgp       20        2024-12-17T10:24:10Z  115    0       *Si  
10.10.10.103/32  bgp       20        2024-12-17T10:24:10Z  121    0       *Si  
10.10.10.104/32  bgp       20        2024-12-17T10:24:10Z  113    0       *Si  

You can filter the FRR nv show vrf <vrf> router bgp neighbor command output by state (established or non-established); for example, to show all BGP established neighbors:

cumulus@switch:~$ nv show vrf default router bgp neighbor --filter=state=established                                                                             
AS - Remote Autonomous System, PeerEstablishedTime - Peer established time in   
UTC format, UpTime - Uptime in milliseconds, Afi-Safi - Address family, PfxSent 
- Transmitted prefix counter, PfxRcvd - Recieved prefix counter                 
                                                                                
Neighbor       AS     State        PeerEstablishedTime   UpTime   MsgRcvd  MsgSent  Afi-Safi      PfxSent  PfxRcvd
-------------  -----  -----------  --------------------  -------  -------  -------  ------------  -------  -------
peerlink.4094  65102  established  2024-12-17T10:22:36Z  8998000  3145     3151     ipv4-unicast  13       12     
                                                                                    l2vpn-evpn    72       51     
swp51          65199  established  2024-12-17T10:22:41Z  8998000  3132     3149     ipv4-unicast  13       8      
                                                                                    l2vpn-evpn    72       51     
swp52          65199  established  2024-12-17T10:22:44Z  8998000  3125     3139     ipv4-unicast  13       8      
                                                                                    l2vpn-evpn    72       51     
swp53          65199  established  2024-12-17T10:22:44Z  8998000  3138     3139     ipv4-unicast  13       8      
                                                                                    l2vpn-evpn    72       51     
swp54          65199  established  2024-12-17T10:22:44Z  8998000  3143     3139     ipv4-unicast  13       8      
                                                                                    l2vpn-evpn    72       51  

To show all BGP non-established neighbors:

cumulus@switch:~$ nv show vrf default router bgp neighbor --filter=state!=established
No Data

NVUE and FRR Restart

NVUE restarts the FRR service when you:

• Change the /etc/frr/daemons file.
• Change the BGP ASN.
• Remove the default instance.
• Disable the SNMP server with agentx configured.

Restarting FRR restarts all the routing protocol daemons that you enable and that are running, which might impact traffic.