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