Using Netplan with Linux on IBM Z

Each Linux distribution has recommended tool or utility for Network Management, In RHEL Network Manager is the utility to go and in Ubuntu 20.04 server edition the supported tool is Netplan. These tools helps System Administrator in managing the complex network by providing an abstract layer above the basic network commands. This article focuses on how to use Netplan with systemd-networkd as the renderer with Linux on IBM Z.

Table of contents

1. What is Netplan?
2. Why Netplan?
3. Netplan commands
4. How Netplan works
1. Network Manager
2. Systemd-networkd (default option)
5. How to use Netplan for managing connections on IBM Z
1. Configuring the devices
2. Managing connections
3. Link files
6. Details on Netplan commands
7. Samples of YAML files for different connection types
8. Limitations of Netplan
9. Conclusion
   

What is Netplan?

Netplan is a utility in the Ubuntu Linux distribution for managing network configurations. It is an abstraction layer above systemd-networkd or NetworkManager. systemd-networkd is the default in most Linux distributions. Netplan simplifies the configuration of more complex network setups like VLAN, bonding, and more.

Why Netplan?

Canonical made Netplan the default for networking configuration, starting with Ubuntu 20.04. Netplan uses YAML files to manage connections. YAML which is a human-friendly, unicode based data serialization language. More info on the syntax can be found here. The YAML format helps in the Cloud and containerization environments, as YAML files can be pulled from git repositories, and included in CI pipelines.

Netplan Commands

1. netplan try: Validates YAML files present under /etc/netplan
2. netplan generate: Generate configuration files
3. netplan apply: Generate and apply all the configuration from YAML files  
   

All of the commands above can be used in debug mode:

    netplan --debug <command>

How netplan works

Netplan reads network configuration files from /etc/netplan/*.yaml. During early boot, Netplan generates backend-specific configuration files in /run to hand off control of devices to the backend renderer.

Netplan currently supports two backend renderers:

1. Network Manager
2. Systemd-networkd    
   

Network Manager
Netplan uses Network Manager as a backend to create network configuration files and hands off the control of devices to the Network Manager daemon.  As the Ubuntu 20.04 server edition does not support Network Manager, it can not be used as a backend for Netplan for IBM Z.

Systemd-networkd (default option)
Netplan uses networkd as a backend to create network configuration files, and hands off the control of devices to the systemd-networkd daemon. Configured devices are handled by systemd-networkd by default, unless a different renderer like NetworkManager is specified.

On applying the configuration using the netplan apply command the respective system files are created in the /run locations depending on the selected renderer.

• Netplan with NetworkManager generates a single run time file (.nmconnection) for both physical and virtual connections
• Netplan with systemd-networkd as the renderer generates one run time file (.network) for physical network connection (Ethernet) and two run time files (.network and .netdev) for virtual connections  
  

The following table shows the differences between the two renderers

	NetworkManager	systemd-networkd
Suggested for	Desktop edition	Server edition
Configuration file location	/run/NetworkManager/system-connections/*	/run/systemd/network/*
Naming convention	netplan-<device_name>.nmconnection	10-netplan-<device-name>.network
Physical connections (Ethernet)	/run/NetworkManager/system-connections/netplan-<iface>.nmconnection	/run/systemd/network/10-netplan-<iface>.network
Virtual connections (VLAN or Bond)	/run/NetworkManager/system-connections/netplan-vlan1.nmconnection	/run/systemd/\network/10-netplan-vlan10.netdev /run/systemd/network/10-netplan-vlan10.network
Sample file content	[connection] id=netplan-vlan1 type=vlan interface-name=vlan1 [vlan] id=1 parent=enc1d40 [ipv4] method=auto [ipv6] method=ignore	[Match] Name=vlan1 [Network] DHCP=ipv4 LinkLocalAddressing=ipv6 ConfigureWithoutCarrier=yes [DHCP] RouteMetric=100 UseMTU=true

Here is a sample YAML file:
  network:
   version: 2
   renderer: networkd
   ethernets:
    enc1d40:
      addresses: [ 10.2.1.196/24 ]
      dhcp4: no
      gateway4:  10.2.1.1

How to use Netplan for managing connections on IBM Z

Configuring the devices
Linux on IBM Z provides a number of commands to list, configure and unconfigure OSA and HiperSockets devices. Depending upon the underlying Linux distribution, one of the following commands can be used:

1. znetconf
2. chzdev  
   

znetconf  
This command is used to transiently configure a network device on IBM Z. Use
 

  znetconf -c

to list all configured devices, and

  znetconf -u

to list all unconfigured devices.

Examples:

  root@hostname:~# znetconf -c
  Device IDs                  Type     Card Type  CHPID  Drv.  Name     State
  ----------------------------------------------------------------------------
  0.0.1a80,0.0.1a81,0.0.1a82  1731/01  OSD_10GIG  A8     qeth  enc1a80  online
  0.0.1d40,0.0.1d41,0.0.1d42  1731/01  OSD_1000   A5     qeth  enc1d40  online

  root@hostname:~# znetconf -u
  Scanning for network devices...
  Device IDs                 Type    Card Type     CHPID Drv.
  -----------------------------------------------------------
  0.0.19c0,0.0.19c1,0.0.19c2 1731/01 OSA (QDIO)       a2 qeth
  0.0.8f00,0.0.8f01,0.0.8f02 1731/05 HiperSockets     af qeth
  0.0.8f03,0.0.8f04,0.0.8f05 1731/05 HiperSockets     af qeth
  0.0.1b83,0.0.1b84,0.0.1b85 1731/01 OSA (QDIO)       b8 qeth


chzdev
This command configures I/O devices for Linux on Z, e.g. OSA-Express adapters, storage devices like DASD and SCSI, and more. Configuration changes can be either persistent (default), or transient.
chzdev supports enabling and disabling of devices, exporting and importing configuration data to and from a file, and displaying a list of available device types and attributes.
To enable or bring a network device online, use the command chzdev -e <bus_id> as follows:

  root@hostname:~# chzdev -e 1d40
  QETH device 0.0.1d40:0.0.1d41:0.0.1d42 configured


Managing connections  
The steps below describe how connections are created, modified and deleted.
To create a connection for a configured device, write a netplan configuration file. The interface name (here: enc1d40) is the identifier which associates the device with the corresponding netplan configuration.

  network:  
   version: 2  
   renderer: networkd  
   ethernets:  
    enc1d40:  
      addresses: [ 10.2.1.196/24 ]  
      gateway4:  10.2.1.1  

Copy the YAML file to /etc/netplan and run netplan apply to apply the new connection.
Netplan will apply all available configurations when the netplan apply command is executed - there is no option to modify an individual interface only.
To modify a network connection, update the YAML file contents and execute the netplan apply command.
To delete a network connection, remove the respective interface section from or delete the YAML file, then execute netplan apply.
To list network connections use the networkctl list command:

  root@hostname:~# networkctl list
  IDX   LINK       TYPE       OPERATIONAL   SETUP  
  1     lo         loopback   carrier       unmanaged
  2     eth0       ether      routable      unmanaged  
  3     eth1       ether      routable      configuring  
  4     testbond2  bond       routable      unmanaged  
  5     bon1       bond       no-carrier    unmanaged
  5 links listed.

The unique ID for each network connection is the link interface name, see column LINK.


Link files
Link files are used to update device and interface properties, e.g. the name. They are used when respective udev events fire, e.g. when devices appear or disappear. A certain way to make changes take effect is to reboot.

All connections are created referring to a default link file /usr/lib/systemd/network/99-default.link. Depending on specific requirements, one can create individual link files with appropriate names, because these files are collectively stored and processed in lexical order. More about the link file properties can be found here.

Here is an example of a default link file:

  root@hostname:~# cat /usr/lib/systemd/network/99-default.link
  #  SPDX-License-Identifier: LGPL-2.1+
  #
  #  This file is part of systemd.
  #
  #  systemd is free software; you can redistribute it and/or modify it
  #  under the terms of the GNU Lesser General Public License as published by
  #  the Free Software Foundation; either version 2.1 of the License, or
  #  (at your option) any later version.
  [Match]
  OriginalName=*

  [Link]
  NamePolicy=keep kernel database onboard slot path
  AlternativeNamesPolicy=database onboard slot path
  MACAddressPolicy=persistent

Details on netplan commands  

To apply a configuration in a safe manner, netplan provides the netplan try command.  
First, this command validates the syntax in three phases:

1. YAML syntax validation
2. Missing mandatory attributes (E.g., VLAN id for VLAN)
3. Check for invalid attributes or values, e.g. specifying a wrong mode value for bonding
   

Next, netplan try applies the changes. Once applied, the user is prompted to keep the network configuration. This extra confirmation step prevents users from permanently applying a configuration that breaks connectivity: 

  root@hostname:~# netplan try
  Do you want to keep these settings?
  Press ENTER before the timeout to accept the new configuration
  Changes will revert in 120 seconds 

Here is an example of a validation failure due to a typo during netplan try:

  root@hostname:/etc/netplan# netplan try
  /etc/netplan/e.yaml:6:32: Error in network definition: invalid boolean value 'tru'
                dhcp4: tru
                       ^
  An error occurred: the configuration could not be generated
  Reverting.

To apply the configuration without a safety net as provided by netplan try, use the netplan apply command.

Specify option --debug to get a better understanding of what is happening as part of a command like netplan apply.
Here is some sample output:

  root@hostname:# netplan --debug  apply
  ** (generate:224184): DEBUG: 05:48:22.269: Processing input file
                        /etc/netplan/e.yaml..
  ** (generate:224184): DEBUG: 05:48:22.269: starting new processing pass
  ** (generate:224184): DEBUG: 05:48:22.269: We have some netdefs, pass them
                        through a final round of validation
  ** (generate:224184): DEBUG: 05:48:22.269: enc1d40: setting default backend to 1
  ** (generate:224184): DEBUG: 05:48:22.269: Configuration is valid
  ** (generate:224184): DEBUG: 05:48:22.269: Generating output files..
  ** (generate:224184): DEBUG: 05:48:22.269: openvswitch: definition enc1d40 is
                        not for us (backend 1)
  ** (generate:224184): DEBUG: 05:48:22.269: NetworkManager: definition enc1d40
                        is not for us (backend 1)
  DEBUG:netplan generated networkd configuration changed, restarting networkd
  DEBUG:{}
  DEBUG:netplan triggering .link rules for enc1d40
  DEBUG:Merged config:
  network:
    bonds: {}
    bridges: {}
     ethernets:
      enc1d40:
        dhcp4: true
    ovs_ports: {}
    vlans: {}
    wifis: {}

Samples of YAML files for different connection types  

YAML file for creating an Ethernet connection:
  network:
      version: 2
      renderer: networkd
      ethernets:
          enc1d40:
              addresses: [10.2.3.199/23]
              dhcp4: false
              gateway4: 10.2.3.1 

YAML file for creating a VLAN connection:

  network:
      version: 2
      renderer: networkd
      ethernets:
          enc1d40:
              dhcp4: false
      vlans:
          vlan1:
              id: 66
              link: enc1d40
              dhcp4: true 

YAML file for Creating a Bond Connection  (Mode=active backup, monitoring=MII):

  network:
      version: 2
      ethernets:
          enc1d40: { }
          enc8f00: { }
      bonds:
          bond0:
          dhcp4: false
          dhcp6: false
          interfaces:
              - enc1d40
              - enc8f00
          parameters:
              mode: active-backup
              primary: enc1d40
              primary-reselect-policy: always
              fail-over-mac-policy: none
              gratuitious-arp: 1
              arp-interval: 0
              mii-monitor-interval: 1
              up-delay: 1
              down-delay: 1 

YAML file for Creating a Bond Connection  (Mode=802.3ad, Monitoring=mii)

  network:
      version: 2
      renderer: networkd
      bonds:
          bond0:
          addresses: [9.152.151.211/24, 10.2.1.96/21]
          interfaces:
              - enc1d40
              - enc1a83
          parameters:
              mode: 802.3ad
              lacp-rate: fast
              transmit-hash-policy: layer2
              mii-monitor-interval: 1
              up-delay: 1
              down-delay: 1 

YAML file for Creating a Bond Connection (Mode=Round Robin, Monitoring=ARP)

  network:
      version: 2
      renderer: networkd
      bonds:
          bond0:
              addresses: [9.152.151.211/24, 10.2.1.96/21]
              interfaces:
                  - enc1d40
                  - enc1a83
              parameters:
                  mode: balance-rr
                  arp-interval: 1
                  arp-ip-targets: [10.2.1.98, 10.2.1.99]

Limitations of Netplan

Netplan does not delete virtual connections like VLAN and bonding setup upon removal of the respective config. A workaround is to fetch the entry from networkctl list manually and delete it, using

        networkctl delete <link name>

Furthermore, no command support for activating or deactivating connections is provided - use native ip commands instead.

Conclusion

Creating complex network connection setups in server environments with Netplan is very simple. This article is intended to serve as a starting point to explore managing network connectivity easily on IBM Z with Ubuntu 20.04.

Authors

Asha Shekharappa  
Jyothi Sankar Reddy Musalikunta  
Sakthi Nathiarasan