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.2.1) the component supports the following:

• Simple static and DHCP configurations
• Bonded interfaces in active-backup mode
• VLAN interfaces

We intend to add support for bridges and other bonding modes. 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.

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)

Bonded Interfaces

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