linux-system-roles/network

Overview

The network role enables users to configure network on the target machines. This role can be used to configure:

• Ethernet interfaces
• Bridge interfaces
• Bonded interfaces
• VLAN interfaces
• MacVLAN interfaces
• Infiniband interfaces
• Wireless (WiFi) interfaces
• IP configuration
• 802.1x authentication

Introduction

The network role supports two providers: nm and initscripts. nm is used by default since RHEL7 and initscripts in RHEL6. The initscripts provider requires network-scripts package which is deprecated in RHEL8 and dropped in RHEL9. These providers can be configured per host via the network_provider variable. In absence of explicit configuration, it is autodetected based on the distribution. However, note that either nm or initscripts is not tied to a certain distribution. The network role works everywhere the required API is available. This means that nm requires at least NetworkManager's API version 1.2 available and certain settings supported by nm provider also requires higher NetworkManager's API version since which the settings are introduced.

The network role supports two modules: network_connections and network_state.

Since the backend of network_state is Nmstate, the network_state modules represents the future direction for the network role, aiming to provide a more streamlined and reliable way of managing network. As a result, the focus is on promoting the use of network_state over the network_connections variable to ensure better consistency and functionality moving forward. Additionally, most of the features currently supported in NetworkManager are also available with network_state. For more information and examples on how to configure the network using Nmstate schema in network_state variable, please refer to the official documentation at nmstate.io. For detailed syntax and explanations of each parameter, visit nmstate's API documentation.

For each host a list of networking profiles can be configured via the network_connections variable.

• For initscripts, profiles correspond to ifcfg files in the /etc/sysconfig/network-scripts/ directory and those ifcfg files has the line NM_CONTROLLED=no written.

• For nm, profiles correspond to connection profiles are handled by NetworkManager and only NetworkManager keyfile format profiles are supported in /etc/NetworkManager/system-connections/ since RHEL9.

For each host the network state configuration can also be applied to the interface directly via the network_state variable, and only the nm provider supports using the network_state variable.

Note that the network role both operates on the connection profiles of the devices (via the network_connections variable) and on devices directly (via the network_state variable). When configuring the connection profiles through the role, it uses the profile name by default as the interface name. It is also possible to create generic profiles, by creating for example a profile with a certain IP configuration without activating the profile. To apply the configuration to the actual networking interface, use the nmcli commands on the target system.

Warning: The network role updates or creates all connection profiles on the target system as specified in the network_connections variable. Therefore, the network role removes options from the specified profiles if the options are only present on the system but not in the network_connections variable. Exceptions are mentioned below. However, the partial networking configuration can be achieved via specifying the network state configuration in the network_state variable.

Requirements

See below

Collection requirements

The role requires external collections only for management of rpm-ostree nodes. Please run the following command to install them if you need to manage rpm-ostree nodes:

ansible-galaxy collection install -vv -r meta/collection-requirements.yml

Variables

The network role is configured via variables starting with network_ as the name prefix. List of variables:

• network_provider - The network_provider variable allows to set a specific provider (nm or initscripts) . Setting it to {{ network_provider_os_default }}, the provider is set depending on the operating system. This is usually nm except for RHEL 6 or CentOS 6 systems. Changing the provider for an existing profile is not supported. To switch providers, it is recommended to first remove profiles with the old provider and then create new profiles with the new provider.
• network_connections - The connection profiles are configured as network_connections, which is a list of dictionaries that include specific options.
• network_allow_restart - It defaults to false. To load NetworkManager plugins after installation, NetworkManager requires to be restarted. For example, if a wireless connection is configured and NetworkManager-wifi is not installed, NetworkManager must be restarted prior to the connection being configured. The restart can result in connectivity loss and therefore the role does not allow it without explicit consent. The user can consent to it by setting network_allow_restart to true. Setting network_allow_restart to false will prevent the role from restarting NetworkManager.
• network_state - The network state settings can be configured in the managed host, and the format and the syntax of the configuration should be consistent with the nmstate state examples (YAML).

Examples of Variables

Setting the variables

network_provider: nm
network_connections:
  - name: eth0
    #...
network_allow_restart: true

network_provider: nm
network_state:
  interfaces:
    - name: eth0
    #...
  routes:
    config:
      #...
  dns-resolver:
    config:
      #...

network_connections Options

The network_connections variable is a list of dictionaries that include the following options. List of options:

name (usually required)

The name option identifies the connection profile to be configured. It is not the name of the networking interface for which the profile applies, though we can associate the profile with an interface and give them the same name. Note that you can have multiple profiles for the same device, but only one profile can be active on the device each time. For NetworkManager, a connection can only be active at one device each time.

• For NetworkManager, the name option corresponds to the connection.id property option. Although NetworkManager supports multiple connections with the same connection.id, the network role cannot handle a duplicate name. Specifying a name multiple times refers to the same connection profile.

• For initscripts, the name option determines the ifcfg file name /etc/sysconfig/network-scripts/ifcfg-$NAME. Note that the name does not specify the DEVICE but a filename. As a consequence, '/' is not a valid character for the name.

You can also use the same connectio