NCLU to NVUE Common Commands

Cumulus Linux version 4.4 introduces a new CLI called NVUE; a complete object model for Cumulus Linux. NVUE makes translating configurations from one vendor to another much more reliable the first time you use Cumulus Linux and across Cumulus Linux versions.

This KB article describes how to translate common NCLU configurations to NVUE commands and bring you up to speed using NVUE.

Where to Start?

To make the transition from NCLU to NVUE configuration easier, you can use this NVUE Migration Tool to convert your NCLU to NVUE configuration by uploading the cl-support file.

Hostname and System

NCLU Command NVUE Command Comments
net add hostname <hostname> nv set system hostname <hostname>
net add syslog host [ipv4|ipv6] <ip> port [tcp|udp] <port> nv set service syslog default server <ip> The value default is the VRF the server is in.
net add time ntp server <ip> nv set service ntp default server <ip>
net pending nv config diff empty pending NVUE can compare between configuration types.
When comparing configuration types to empty, it shows only the provided type.
net commit nv config apply In NCLU, the running-config equals the startup-config.
NVUE separates running and startup configs:
nv config apply - apply configuration as running (without saving as startup)
nv config save - save configuration as startup (without applying as running)
nv config save
net show configuration cat /etc/nvue.d/startup.yaml By using the net show configuration commands, you can view the configuration as actual NCLU commands.
You can view the NVUE single YAML-based configuration file using Linux cat command or using NVUE commands.
nv config diff empty startup
nv config diff empty applied

Interfaces

NCLU Command NVUE Command Comments
net add interface <interface> nv set interface <interface> type <interface-type> NVUE allows creating any interface-type under the interface object.
NCLU is not an object model, so this command only allows creating <swp> interface-type. For other interface-types, you need to use different commands.
net add interface <interface> [ipv4|ipv6] address <ip/mask> nv set interface <interface> ip address <ip/mask> In NVUE, you set IPv4 and IPv6 addresses with the same command.
To configure secondary IP address, use the same command.
To replace existing IP address, delete it first using:
NCLU - net del interface <interface> [ipv4|ipv6] address <ip/mask>
NVUE - nv unset interface <interface> ip address <ip/mask>
net add interface <interface> mtu <mtu> nv set interface <interface> link mtu <mtu> The default MTU in Cumulus Linux is 9216B.
net add interface <interface> link speed <speed> nv set interface <interface> link speed <speed>
net add interface <interface> link fec <fec-mode> nv set interface <interface> link fec <fec-mode>
net [add|del] interface <interface> link down <fec-mode> nv set interface <interface> link state [up|down] The default state for interfaces is UP.
net add loopback lo nv set interface lo The loopback interface in Cumulus Linux called `lo`.
net add interface <interface> breakout <breakout-option> nv set interface <interface> link breakout <breakout-option> Multiple breakout options exist. To view all options run:
NVUE - nv set interface <interface> link breakout -h
NCLU - net add interface <interface> breakout <press TAB>
net add interface <interface> alias <description-text> nv set interface <interface> alias <description-text>

Bonds and Port Channels

Linux uses the term bond to represent port-channels.

NCLU Command NVUE Command Comments
net add bond <bond-name> bond slaves <interfaces> nv set interface <bond-name> bond memeber <interfaces> In NCLU, create a bond by enslaving ports to it or setting bond mode. You create the bond and add members in a single command.
In NVUE, you create bond with or without adding members by using the type bond interface keywords. In addition, by starting an interface name with bond the type is automatically defined. For example, nv set interface bond1
NOTE: You define bonds with a name that must start with a letter.
nv set interface <bond-name> type bond
net add bond <bond-name> bond mode balance-xor nv set interface <bond-name> bond mode static The default bond mode in Cumulus LInux is lacp (802.3ad in NCLU).
net add bond <bond-name> bond lacp-rate slow nv set interface <bond-name> bond lacp-rate slow The default bond lacp-rate in Cumulus LInux is fast.

Layer 2 and VLANs

Cumulus Linux interfaces are layer 3 routed interfaces by default. To make an interface a layer 2 switchport, you must add the interface to the default bridge called bridge when using NCLU or br_default in NVUE:

cumulus@switch:~$ net add bridge bridge ports <interface>
cumulus@switch:~$ nv set interface <interface> bridge domain br_default
NCLU Command NVUE Command Comments
net add interface <interface> bridge access <vlan-id> nv set interface <interface> bridge domain br_default access <vlan-id>
net add bridge bridge ports <interface> nv set interface <interface> bridge domain br_default Ports you add to a bridge are trunk ports by default (all vlans allowed).
net add interface <interface> bridge trunk vlans <vlan-id|vlan-list> nv set interface <interface> bridge domain br_default vlan <vlan-id|vlan-list|all> To allow all vlans on the trunk port:
NCLU - net add interface <interface> bridge trunk
NVUE - nv set interface <interface> bridge domain br_default
net add interface <interface> stp portadminedge nv set interface <interface> bridge domain br_default stp admin-edge on
net add interface <interface> stp portnetwork nv set interface <interface> bridge domain br_default stp network on
net add interface <interface> stp bpduguard nv set interface <interface> bridge domain br_default stp bpdu-guard on
net add interface <interface> stp portbpdufilter nv set interface <interface> bridge domain br_default stp bpdu-filter on
net add bridge stp treeprio <stp-priority> nv set bridge domain br_default stp priority <stp-priority> Cumulus Linux only supports RSTP.

MLAG

In MLAG configuration, Cumulus Linux uses peer link (bond between peers) to sync the MLAG pair. In addition, to keep MLAG pairs in sync when a direct connection fails, Cumulus Linux uses mlag backup IP.

For more information about MLAG, refer to the Multi-Chassis Link Aggregation - MLAG page on the Cumulus Linux User Guide.

net add bond <bond-name> clag id <number> nv set interface <bond-name> bond mlag id <number|auto> You should create bond interfaces prior setting mlag id. The mlag id must match the bond interface on both MLAG peers connected to the same host. Using <auto> determines the ID based on the MAC address of the end host.
net add clag peer sys-mac <mac> interface <peerlink-members> [primary|secondary] backup-ip <ip> nv set mlag mac-address <mac|auto> NCLU MLAG configuration requires to set all parameters in a single command where the backup-ip <ip> is optional.
NVUE MLAG configuration consists of several commands, it allows easier changes to MLAG global parameters. It also supports <auto> MAC address generation.
Cumulus Linux requires a unique bond for the peerlink and an associated peer-ip definition.
nv set interface peerlink bond member <interfaces>
nv set mlag peer-ip linklocal
nv set mlag backup <ip>

Layer 3 Routing Protocols

Most NVUE BGP commands require including a VRF in the command. The examples below contain the default VRF name because it is pre-defined in the system, but you can use any VRF name. You can still configure some of the global BGP parameters (enable/disable BGP, set the ASN and the router ID, configure BGP graceful restart, and shutdown the router) without specifying a VRF. Then all VRFs inherit these settings automatically unless you set specific settings on the VRF.
In NCLU, by default, all configuration is global on the system’s default VRF (NCLU does not have a pre-defined VRF named default). Custom VRFs do not inherit the global BGP settings. Apply VRF specific configuration separately.

NCLU Command NVUE Command Comments
net add <interface> vrf <name> nv set interface <interface> ip vrf <name>
net add bgp [vrf <name>] autonomous-system <leaf|spine|ASN> nv set [vrf <default|name>] router bgp autonomous-system <leaf|spine|none|ASN> In NVUE, when a single AS is in use for all VRFs, the [vrf <name>] option is not required to create the instance. Its settings are automatically applied to all VRFs including the default VRF.
Set the ASN for every VRF when using the <none> ASN option.
For more information about the <leaf|spine> options, check out Auto BGP section in the Cumulus Linux User Guide.
net add bgp [vrf <name>] router-id <ipv4> nv set [vrf <default|name>] router bgp router-id <ipv4> In NVUE, when a single AS is in use for all VRFs, the <vrf <name> is not required in the command. It is globally applied to all VRFs including the default VRF.
net add bgp [vrf <name>] neighbor <ip|interface> remote-as <internal|external|ASN> set vrf <default|name> router bgp peer <ip|interface> remote-as <internal|external|ASN> NVUE requires you to specify a VRF when adding BGP peer. Cumulus Linux supports BGP Unnumbered peer configuration.
The ASN can be a number, or internal for a neighbor in the same AS or external for a neighbor in a different AS.
net add bgp [vrf <name>] neighbor <name> peer-group <attributes> nv set vrf <default|name> router bgp peer-group <name> <attributes> NCLU requires creating peer-groups with
net add bgp <vrf <name>> neighbor <name> peer-group prior configuring its attributes.
NVUE allows you to create peer-group and set its attributes in a single command.
net add bgp [vrf <name>] [ipv4|ipv6] unicast network <ipv4|ipv6/mask> nv set vrf <default|name> router bgp address-family <ipv4-unicast|ipv6-unicast> static-network <ipv4|ipv6/mask> In NCLU, the address-family is optional. The IP address advertised determines the address-family.
In NVUE, you must specify the address-family to advertise network into it.
net add bgp [vrf <name>] <ipv4|ipv6> unicast redistribute <connected|static|ospf|kernel> nv set vrf <default|name> router bgp address-family <ipv4-unicast|ipv6-unicast> redistribute <connected|static|ospf|kernel>
net add routing prefix-list <ipv4|ipv6> <name> seq <seq> <permit|deny> <ipv4|ipv6/lenght|any> nv set router policy prefix-list <name> rule <seq> action <permit|deny> NCLU allows configuring prefix-list match and actions in a single command.
NVUE does it in two commands. The default prefix-list type in NVUE is IPv4. But, you can set IPv6 prefix-list using the nv set router policy prefix-list <name> type ipv6 command.
nv set router policy prefix-list <name> rule <seq> match <prefix/length>
net add bgp [vrf <name>] [ipv4|ipv6] neighbor <ip|interface> prefix-list <name> <in|out> nv set vrf <default|name> router bgp peer <ip|interface> address-family <ipv4-unicast|ipv6-unicast> policy <inbound|outbound> prefix-list <name> In NCLU, the default address-family is IPv4-unicast.
net add routing route-map <name> <permit|deny> <seq> match ip address prefix-list <name> nv set router policy route-map <name> rule <seq> action <permit|deny> NCLU allows configuring route-map match and actions in a single command. NVUE does it with two commands.
nv set router policy route-map <name> rule <seq> match ip-prefix-list <name>
net add bgp [vrf <name>] [ipv4|ipv6|evpn] neighbor <ip|interface> route-map <name> <in|out> nv set vrf <default|name> router bgp peer <ip|interface> address-family <ipv4-unicast|ipv6-unicast|l2vpn-evpn> policy <inbound|outbound> route-map <name> In NCLU, the default address-family is IPv4-unicast.
net add routing route <ipv4|ipv6/mask> <next-hop|interface> [vrf <name>] nv set vrf <default|name> router static <route> via <next-hop>

VXLAN and EVPN

Cumulus Linux supports both single and traditional VXLAN devices. With a traditional VXLAN device, each VNI is a separate Linux device (for example, vni10, vni20, vni30). With the single VXLAN device feature, a set of VNIs represents a single Linux device. The single VXLAN device has a set of attributes that belong to the VXLAN construct.
Individual VNIs include a VLAN to VNI mapping, and you can specify which VLANs map to the associated VNIs. A single VXLAN device simplifies the configuration and reduces the overhead by replacing multiple traditional VXLAN devices with a single VXLAN device.

Using NCLU, you can configure only the traditional (multiple) VXLAN device. With NVUE, you can configure only a single VXLAN device. Some of the VXLAN commands look similar on both CLIs, but as the implementations are different, some of them are not.

Below are a few similar VXLAN and EVPN commands, for full configuration and more detailed information, read the Network Virtualization section in the Cumulus Linux User Guide.

NCLU Command NVUE Command Comments
net add loopback lo clag vxlan-anycast-ip <ip> nv set nve vxlan mlag shared-address <ip>
net add vxlan <name> vxlan id <number> nv set bridge domain br_default vlan <number> vni <number> Using NCLU, you have to create the VXLAN devices and assign them to VLAN in the bridge.
In NVUE, create a single VXLAN device by mapping the VLAN to VNI on the bridge.
net add vxlan <name> bridge access <vlan-id>
net add loopback lo vxlan local-tunnelip <ip> nv set nve vxlan source address <ip> In NCLU, it is possible to set local-tunnel IP separately per device using
net add vxlan <name> vxlan local-tunnelip <ip> command.
net add vlxan <name> bridge arp-nd-suppress on nv set nve vxlan arp-nd-suppress on In NCLU, configure VXLAN related settings on every device.
As NVUE has a single VXLAN device, the configuration is global for all VNIs.
net add vlxan <name> bridge bridge learning off nv set nve vxlan mac-learning off
net add vlxan <name> stp bpduguard nv set interface <interface> bridge domain br_default stp bpdu-guard on In NCLU, configure spanning-tree on each interface including the VXLAN devices.
in NVUE, configure spanning-tree on the bridge ports only.
net add vlxan <name> stp portbpdufilter nv set interface <interface> bridge domain br_default stp admin-edge on
net add bgp l2vpn evpn neighbor <ip-addr|interface|peer-group> activate nv set evpn enable on In NVUE, enable EVPN-AF globally and at the BGP proccess as well as the peer activation in BGP.
Unlike with NCLU, in NVUE you do not need to enable the BGP control plane for all VNIs with the advertise-all-vni option.
nv set vrf <default|name> router bgp address-family l2vpn-evpn enable on
net add bgp l2vpn evpn advertise-all-vni nv set vrf <default|name> router bgp peer <ip-addr|interface|peer-group> address-family l2vpn-evpn enable on
net add bgp vrf <name> l2vpn evpn advertise ipv4 unicast nv set vrf <name> router bgp address-family ipv4-unicast route-export to-evpn
net add vrf <name> vni <number> nv set vrf vrf <name> evpn vni <number>
net add vlan <number> vrf <name> In NVUE, the layer 3 VNI does not need a separate VLAN allocation.
net add vxlan <name> bridge access <vlan-id>
net add vrf <name> vni <number>
Active-Active VXLAN Symmetric Routing - NVUE Configuration Example
nv set interface lo ip address 10.10.10.1/32
nv set interface swp1-3,swp49-54
nv set interface bond1 bond member swp1
nv set interface bond2 bond member swp2
nv set interface bond3 bond member swp3
nv set interface bond1 bond mlag id 1
nv set interface bond2 bond mlag id 2
nv set interface bond3 bond mlag id 3
nv set interface bond1 bond lacp-bypass on
nv set interface bond2 bond lacp-bypass on
nv set interface bond3 bond lacp-bypass on
nv set interface bond1 link mtu 9000
nv set interface bond2 link mtu 9000
nv set interface bond3 link mtu 9000
nv set interface bond1-3 bridge domain br_default
nv set interface bond1 bridge domain br_default access 10
nv set interface bond2 bridge domain br_default access 20
nv set interface bond3 bridge domain br_default access 30
nv set bridge domain br_default vlan 10,20,30
nv set interface peerlink bond member swp49-50
nv set mlag mac-address 44:38:39:BE:EF:AA
nv set mlag backup 10.10.10.2
nv set mlag peer-ip linklocal
nv set mlag priority 1000
nv set mlag init-delay 10
nv set interface vlan10 ip address 10.1.10.2/24
nv set interface vlan10 ip vrr address 10.1.10.1/24
nv set interface vlan10 ip vrr mac-address 00:00:00:00:00:10
nv set interface vlan10 ip vrr state up
nv set interface vlan20 ip address 10.1.20.2/24
nv set interface vlan20 ip vrr address 10.1.20.1/24
nv set interface vlan20 ip vrr mac-address 00:00:00:00:00:20
nv set interface vlan20 ip vrr state up
nv set interface vlan30 ip address 10.1.30.2/24
nv set interface vlan30 ip vrr address 10.1.30.1/24
nv set interface vlan30 ip vrr mac-address 00:00:00:00:00:30
nv set interface vlan30 ip vrr state up
nv set vrf RED
nv set vrf BLUE
nv set bridge domain br_default vlan 10 vni 10
nv set bridge domain br_default vlan 20 vni 20
nv set bridge domain br_default vlan 30 vni 30
nv set interface vlan10 ip vrf RED
nv set interface vlan20 ip vrf RED
nv set interface vlan30 ip vrf BLUE
nv set nve vxlan mlag shared-address 10.0.1.12
nv set nve vxlan source address 10.10.10.1
nv set nve vxlan arp-nd-suppress on
nv set vrf RED evpn vni 4001
nv set vrf BLUE evpn vni 4002
nv set system global anycast-mac 44:38:39:BE:EF:AA
nv set evpn enable on
nv set router bgp autonomous-system 65101
nv set router bgp router-id 10.10.10.1
nv set vrf default router bgp peer-group underlay remote-as external
nv set vrf default router bgp peer swp51 peer-group underlay
nv set vrf default router bgp peer swp52 peer-group underlay
nv set vrf default router bgp peer swp53 peer-group underlay
nv set vrf default router bgp peer swp54 peer-group underlay
nv set vrf default router bgp peer-group underlay address-family l2vpn-evpn enable on
nv set vrf default router bgp peer peerlink.4094 peer-group underlay
nv set vrf default router bgp address-family ipv4-unicast redistribute connected enable on
nv set vrf RED router bgp autonomous-system 65101
nv set vrf RED router bgp router-id 10.10.10.1
nv set vrf RED router bgp address-family ipv4-unicast redistribute connected enable on
nv set vrf RED router bgp peer-group underlay address-family l2vpn-evpn enable on
nv set vrf RED router bgp address-family ipv4-unicast route-export to-evpn
nv set vrf BLUE router bgp autonomous-system 65101
nv set vrf BLUE router bgp router-id 10.10.10.1
nv set vrf BLUE router bgp address-family ipv4-unicast redistribute connected enable on
nv set vrf BLUE router bgp peer-group underlay address-family l2vpn-evpn enable on
nv set vrf BLUE router bgp address-family ipv4-unicast route-export to-evpn
nv config apply
Active-Active VXLAN Symmetric Routing - NCLU Configuration Example
net add loopback lo ip address 10.10.10.1/32
net add bond bond1 bond slaves swp1
net add bond bond2 bond slaves swp2
net add bond bond3 bond slaves swp3
net add interface swp1 alias bond member of bond1
net add interface swp2 alias bond member of bond2
net add interface swp3 alias bond member of bond3
net add interface swp51-54 alias to spine
net add bridge bridge vlan-aware
net add bond bond1 bridge access 10
net add bond bond1 clag id 1
net add bond bond1-3 bond lacp-bypass-allow
net add bond bond1-3 mtu 9000
net add bond bond1-3 stp bpduguard
net add bond bond1-3 stp portadminedge
net add bond bond2 bridge access 20
net add bond bond2 clag id 2
net add bond bond3 bridge access 30
net add bond bond3 clag id 3
net add bridge bridge ports bond1,bond2,bond3
net add bond peerlink bond slaves swp49,swp50
net add interface swp49-50 alias peerlink
net add bridge bridge ports peerlink
net add interface peerlink.4094 clag args --initDelay 10
net add interface peerlink.4094 clag backup-ip 10.10.10.2
net add interface peerlink.4094 clag peer-ip linklocal
net add interface peerlink.4094 clag priority 1000
net add interface peerlink.4094 clag sys-mac 44:38:39:BE:EF:AA
net add loopback lo clag vxlan-anycast-ip 10.0.1.12
net add vrf RED vni 4001
net add vrf BLUE vni 4002
net add vlan 10 ip address 10.1.10.2/24
net add vlan 10 ip address-virtual 00:00:00:00:00:10 10.1.10.1/24
net add vlan 10 vlan-id 10
net add vlan 10 vlan-raw-device bridge
net add vlan 10 vrf RED
net add vlan 20 ip address 10.1.20.2/24
net add vlan 20 ip address-virtual 00:00:00:00:00:20 10.1.20.1/24
net add vlan 20 vlan-id 20
net add vlan 20 vlan-raw-device bridge
net add vlan 20 vrf RED
net add vlan 30 ip address 10.1.30.2/24
net add vlan 30 ip address-virtual 00:00:00:00:00:30 10.1.30.1/24
net add vlan 30 vlan-id 30
net add vlan 30 vlan-raw-device bridge
net add vlan 30 vrf BLUE
net add vlan 4001 hwaddress 44:38:39:BE:EF:AA
net add vlan 4001 vlan-id 4001
net add vlan 4001 vlan-raw-device bridge
net add vlan 4001 vrf RED
net add vlan 4002 hwaddress 44:38:39:BE:EF:AA
net add vlan 4002 vlan-id 4002
net add vlan 4002 vlan-raw-device bridge
net add vlan 4002 vrf BLUE
net add vxlan vni10 vxlan id 10
net add vxlan vni20 vxlan id 20
net add vxlan vni30 vxlan id 30
net add vxlan vniBLUE vxlan id 4002
net add vxlan vniRED vxlan id 4001
net add vxlan vni10 bridge access 10
net add vxlan vni10,20,30,vniBLUE,vniRED bridge arp-nd-suppress on
net add vxlan vni10,20,30,vniBLUE,vniRED bridge learning off
net add vxlan vni10,20,30,vniBLUE,vniRED stp bpduguard
net add vxlan vni10,20,30,vniBLUE,vniRED stp portbpdufilter
net add vxlan vni20 bridge access 20
net add vxlan vni30 bridge access 30
net add vxlan vniBLUE bridge access 4002
net add vxlan vniRED bridge access 4001
net add bridge bridge ports vni10,vni20,vni30,vniRED,vniBLUE
net add bridge bridge vids 10,20,30,4001-4002
net add loopback lo vxlan local-tunnelip 10.10.10.1
net add bgp autonomous-system 65101
net add bgp router-id 10.10.10.1
net add bgp neighbor underlay peer-group
net add bgp neighbor underlay remote-as external
net add bgp neighbor peerlink.4094 interface peer-group underlay
net add bgp neighbor swp51 interface peer-group underlay
net add bgp neighbor swp52 interface peer-group underlay
net add bgp neighbor swp53 interface peer-group underlay
net add bgp neighbor swp54 interface peer-group underlay
net add bgp ipv4 unicast redistribute connected
net add bgp l2vpn evpn neighbor underlay activate
net add bgp l2vpn evpn advertise-all-vni
net add bgp vrf RED autonomous-system 65101
net add bgp vrf RED router-id 10.10.10.1
net add bgp vrf RED ipv4 unicast redistribute connected
net add bgp vrf RED l2vpn evpn advertise ipv4 unicast
net add bgp vrf BLUE autonomous-system 65101
net add bgp vrf BLUE router-id 10.10.10.1
net add bgp vrf BLUE ipv4 unicast redistribute connected
net add bgp vrf BLUE l2vpn evpn advertise ipv4 unicast
net commit

Access Control Lists (ACLs)

ACLs in Cumulus Linux are based on Linux iptables with the following default behaviors:

  • There is no implicit deny. ACLs must end in a match any and action deny rule to drop all unmatched traffic.
  • There is no support for wildcard masks. You must list subnets individually.

For more information, refer to the ACLs section of the Cumulus Linux User Guide.

In addition to NCLU commands, you can configure ACLs straight by setting ebtables and iptables rules. To ease ACL management on the system, you can use a tool called cl-acltool.

NCLU Command NVUE Command Comments
net add acl <ipv4|ipv6|mac> <name> <action> <attributes> [<value>] nv set acl <name> type <ipv4|ipv6|mac> NCLU allows ACL configuration in one line, but does not have sequance numbers. To change sequance numbers, you have to edit nclu_acl.conf file.
NVUE ACL configuration must be using separate commands and it links the source, destination, and actions with the <name> <seq> values.
nv set acl <name> rule <seq> match <ip|mac> <attributes> <value>
nv set acl <name> rule <seq> action <action> [<attributes>]
net add interface <interface> acl <ipv4|ipv6|mac> <name> <inbound|outboung> nv set interface <interface> acl <name> <inbound|outboung>