LCFG network component

This documents the latest version of the LCFG network component (version 2) which is used on Ubuntu. Documentation for older platforms (e.g. SL7), which use version 1 of the component, is found at NetworkComponentLegacy.

On Ubuntu we manage the network configuration using netplan which has support for systemd-networkd and Networkmanager. Theoretically it all works with Networkmanager but only networkd has been tested, any reports of success/failure with Networkmanager would be much appreciated.

Currently (as of version 2.3.3) the component supports the following:

• Simple static and DHCP configurations
• Bonded interfaces
• VLAN devices
• Bridge devices

Patches for other features would be very welcome.

Standard configuration

By default the lcfg/defaults/network.h header creates a single interface with the name eth0 which has a static address. This assumes that the LCFG profile name is the hostname (e.g. the hostname is <%profile.node%>.<%profile.domain%>)

The relevant resources are:

!network.interfaces              mADD(eth0)
network.netmask_eth0             24
network.ipaddr_eth0              auto
network.hostname_eth0           <%profile.node%>
network.device_eth0             eno1

The netmask is expected to be in CIDR notation (unlike the old Redhat network scripts), for compatibility the old-style will be translated into CIDR by the component.

The ipaddr_eth0 resource is set to auto which tells the component on the client machine to lookup the address using the host name provided in the hostname_eth0 resource. To avoid that lookup the ipaddr_eth0 resource can alternatively be set to a list of one or more addresses. If an interface should not have any address then the value for the ipaddr resource may be set to none.

Note that the real name of the interface is expected to be eno1 in the default case. Some hardware headers (e.g. lcfg/hw/kvm.h) will override that as required. See below for details.

Depending on how routing is managed it be necessary to also specify a gateway for the interface, in the standard case that can be done using the gateway_eth0 resource, e.g.

!network.gateway_eth0        mSET(10.10.10.1)

DHCP

For sites which use DHCP to allocate IP addresses the lcfg/options/dhcp.h header should be included. The primary effect of including the header is that the value for the ipaddr_eth0 resource is changed to be DHCP. We recommend including the header rather than just simply mutating the resource in case further changes to resources are needed in the future.

Matching the correct network device

netplan supports matching network devices based on various information (e.g. device name, kernel module name, MAC address).

By default in LCFG the device name for the eth0 interface is expected to be eno1. That default will suit most hardware but there are exceptions such as virtual machines. If you know part of the device name but the complete string is not easily predicted then globs may be used, for example with KVM this is set to be ens*. Changing the device name can be done using the LCFG_NETWORK_SET_DEVICE macro like this:

LCFG_NETWORK_SET_DEVICE(eth0,ens*)

For other interfaces (e.g. eth1, eth2) the default value for the device resource is auto which instructs the component to use the tag name. Again, the simplest approach is to use the macro:

LCFG_NETWORK_SET_DEVICE(eth1,eno2)

It is also possible to match on the MAC address of the device, that is done using the relevant hwaddr resource. For example:

network.hwaddr_eth0         9c:7b:ef:24:c1:c1

If both the MAC address and the device name are specified then the component will only use the MAC address

Alternatively, to match on the kernel module name use the relevant driver resource. If the kernel module name is specified in combination with the device name or MAC address then the component will use both.

For example:

!network.interfaces          mADD(ev3dev)
network.driver_ev3dev        cdc_ether

Additional Addresses

Adding extra addresses to an interface is quite straightforward, they should be appended to the relevant ipaddr resource, for example:

!network.ipaddr_eth0        mADD(192.168.1.100)

VLAN interfaces

To add a VLAN interface you need to know the ID and the name of the interface to which it should be associated. The relevant resources are:

!network.interfaces         mADD(vlan202)
network.type_vlan202       vlan
network.physdev_vlan202    eth0

Which would create a VLAN interface named vlan202 on the interface named eth0. If the ID is not explicitly specified using the vlan resource then it is taken from the tag name (202 in this case) which matches with the behaviour of the Redhat network scripts. Those familiar with the previous version of the component will know that the vlan resource used to be treated as a boolean to indicate if the interface was a VLAN (or not), that is now controlled through the type resource instead. The vlan resource has been repurposed to hold the integer ID for the VLAN which allows the interfaces to have arbitrary names if desired.

It's also possible to do the same thing in a slightly simpler way using the LCFG_NETWORK_ADD_VLAN macro, e.g.:

LCFG_NETWORK_ADD_VLAN(202,eth0)

The interface usually needs an address, this works the same as with standard interfaces described above. Either set the ipaddr resource to an explicit resource or leave it as auto which is the default and set the hostname resource so that the component does a lookup, e.g.:

!network.hostname_vlan202   mSET(yair-at1)

Bridges

A network bridge with an address may be fully specified like this:

!network.interfaces              mADD(br0)
network.type_br0                 bridge
network.ipaddr_br0             192.168.9.87
network.netmask_br0          26
network.gateway_br0          192.168.9.126
network.delay_br0                0
network.stp_br0                    off

!network.bridge_eth0           mSET(br0)

It is important to note how the interface eth0 is associated with the bridge.

Bridges don't always need to have an address, the LCFG_NETWORK_ADD_BRIDGE macro makes adding them very simple, for example:

LCFG_NETWORK_ADD_BRIDGE(42)

This would create a bridge named br42 which can be then be associated with a VLAN like this:

LCFG_NETWORK_ADD_VLAN(42,eth0)

To give a vlan with ID 42 that is associated with the eth0 interface and the bridge br42.

For compatibility with the previous version of the component, it is possible to specify some parameters for bridges via resources:

• stp - A boolean that controls whether the bridge should use Spanning Tree Protocol (e.g. stp_br42).
• delay - the period of time the bridge will remain in "Listening and Learning" state before getting to the Forwarding state (e.g. delay_br42).

Further parameters may be specified using the params_$ tag list. For each tag there are param_key_$_$ and param_val_$_$ resources. The value resource must be specified, the key resource is optional, it only needs to be specified if the parameter name cannot be expressed as a LCFG tag (e.g. it contains hyphens). For example:

!network.params_br0 mADD(delay)
network.param_key_br0_delay forward-delay
network.param_val_br0_delay 5

network.params_br0 mADD(stp)
network.param_val_br0_stp false

Bonded Interfaces

The easiest way to configure bonded network interfaces is to use the lcfg/options/etherbond.h header, like this:

#define LCFG_HWADDR_NIC1 C8:1F:66:BE:0E:E5
#define LCFG_HWADDR_NIC2 C8:1F:66:BE:0E:E6
#define LCFG_HWADDR_NIC3 C8:1F:66:BE:0E:E7
#define LCFG_HWADDR_NIC4 C8:1F:66:BE:0E:E8

/* We'll bond across NIC 1 and NIC 3 */
#define LCFG_HWADDR_ETH0 LCFG_HWADDR_NIC1
#define LCFG_HWADDR_ETH1 LCFG_HWADDR_NIC3

#include <lcfg/options/etherbond.h> 

This header configures a bonded-interface named bond0

The primary interface may be specified by defining the LCFG_OPTIONS_ETHERBOND_PRIMARY macro as the lcfg tag name, before including the header, for example:

#define LCFG_OPTIONS_ETHERBOND_PRIMARY eth0

You may also specify the interface tag names to be used, the default is to use eth0 and eth1 which will usually be correct. For example:

#define LCFG_OPTIONS_ETHERBOND_FIRST eth0
#define LCFG_OPTIONS_ETHERBOND_SECOND eth2

The bonding mode may be specified using a resource - mode_bond0 - the default is active-backup

Further parameters may be specified using the params_bond0 tag list. For each tag there are param_key_bond0_$ and param_val_bond_$ resources. The value resource must be specified, the key resource is optional, it only needs to be specified if the parameter name cannot be expressed as a LCFG tag (e.g. it contains hyphens). For example:

!network.params_bond0                       mADD(monint)
network.param_key_bond0_monint     mii-monitor-interval
network.param_val_bond0_monint      5

Wake On Lan

The Wake-0n-LAN option can be explicitly enabled for an interface using the wakeonlan resource, e.g.:

!network.wakeonlan_eth0 mSET(true)

Optional Interfaces

If an interface might not be available at boot time (e.g. a USB network device which might not be plugged in) then it should be marked as optional so that networkd does not wait for it to become available. For example:

!network.optional_ev3dev mSET(true)

-- squinney - 2021-02-04