From 89e290303282ec1efa98798b255906e8b177e52e Mon Sep 17 00:00:00 2001 From: Vaclav Dolezal Date: Wed, 26 Sep 2018 17:47:45 +0200 Subject: [PATCH] Update and cleanup README Co-author: Ioanna Gkioka Signed-off-by: Vaclav Dolezal --- README.md | 843 ++++++++++++++++++++++++++++-------------------------- 1 file changed, 439 insertions(+), 404 deletions(-) diff --git a/README.md b/README.md index ebf8de1..e4c3c2e 100644 --- a/README.md +++ b/README.md @@ -4,8 +4,11 @@ linux-system-roles/network [![Travis Build Status](https://travis-ci.org/linux-system-roles/network.svg?branch=master)](https://travis-ci.org/linux-system-roles/network) [![Code Style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/ambv/black) -This role enables users to configure network on target machines. -The role can be used to configure: +Overview +-------- + +The `network` role enables users to configure network on the target machines. +This role can be used to configure: - Ethernet interfaces - Bridge interfaces @@ -15,251 +18,331 @@ The role can be used to configure: - Infiniband interfaces - IP configuration -General -------- - -The role supports two providers: `nm` and `initscripts`. The provider can be +Introduction +------------ +The `network` role supports two providers: `nm` and `initscripts`. `nm` is +used by default in RHEL7 and `initscripts` in RHEL6. These providers can be configured per host via the [`network_provider`](#provider) variable. In absence of explicit configuration, it is autodetected based on the -distribution. The `nm` provider is used by default on RHEL7 and `initscripts` -on RHEL6. However, note that the provider is not tied to a certain -distribution, given that the required API is available. For `nm` this means -that at least version 1.2 of NetworkManager's API is available. For -`initscripts`, it requires the legacy network service as commonly available on -Fedora/RHEL. +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. +For `initscripts`, the legacy network service is required as used in Fedora or RHEL. -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/ifcfg-*` directory. -- For initscripts, profiles correspond to ifcfg files in `/etc/sysconfig/network-scripts/ifcfg-*`. +- For `NetworkManager`, profiles correspond to connection profiles as handled by + NetworkManager. Fedora and RHEL use the `ifcfg-rh-plugin` for NetworkManager, + which also writes or reads configuration files to `/etc/sysconfig/network-scripts/ifcfg-*` + for compatibility. -- For NetworkManager, profiles correspond to connection profiles as handled by NetworkManager. Fedora and RHEL use the `rh-plugin` for NetworkManager which also writes configuration files to `/etc/sysconfig/network-scripts/ifcfg-*` for compatibility. - -Note that the role primarily operates on networking profiles (connections) and -not on devices but it defaults to use the profile name as the interface name. -But it is also possible to create generic profiles, by creating for example a +Note that the `network` role primarily operates on networking profiles (connections) and +not on devices, but 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, a command like -`nmcli` needs to be used on the target system. +apply the configuration to the actual networking interface, use the `nmcli` +commands on the target system. For each host, a list of networking profiles can +be configured via the `network_connections` variable. -### Warning - -The role updates or creates all connection profiles on the target system as -specified in the `network_connections` variable. Therefore, the role will -remove settings from the specified profiles if the settings are only present on -the system but not in the `network_connections` variable. The following -exceptions apply: - -* For profiles that only contain a `state` setting, the role will only activate - or deactivate the connection without changing its configuration. - -* The `route_append_only` setting allows to only add new routes to the - existing routes on the system. - -* The `rule_append_only` setting allows to preserve the current routing rules. - There is no support to specify routing rules at the moment. - -See also [Limitations](#limitations). +**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. Variables --------- +The `network` role is configured via variables starting with `network_` as the name prefix. +List of required variables: -The role is configured via variables with a `network_` name prefix. -The connection profiles are configured as `network_connections`, which -is a list of dictionaries that have a `name`. +* `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. + +* `network_connections` - The connection profiles are configured as `network_connections`, + which is a list of dictionaries that include specific options. + + +Examples of Variables +--------------------- + +Setting the variables + +```yaml +network_provider: nm +network_connections: + - name: eth0 + #... +``` + +Options +------- +The `network_connections` variable is a list of dictionaries that includes the following options. +List of required options: ### `name` -The `name` identifies the connection profile. It is not the name of the -networking interface for which the profile applies, though it makes -sense to restrict the profile to an interface and give them the same name. -Note also that you can have multiple profiles for the same device, but of -course only one profile can be active on the device at each time. Note that -for NetworkManager, a connection can only be active at one device at a time. +The `name` option identifies the connection profile. 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` translates to [`connection.id`](https://developer.gnome.org/NetworkManager/stable/nm-settings.html#nm-settings.property.connection.id). - Altough NetworkManager supports multiple connections with the same `connection.id`, - this role cannot handle a duplicate `name`. Specifying a `name` multiple +* For `NetworkManager`, the `name` option corresponds to the + [`connection.id`](https://developer.gnome.org/NetworkManager/stable/nm-settings.html#nm-settings.property.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 determines the ifcfg file name `/etc/sysconfig/network-scripts/ifcfg-$NAME`. - Note that here too the name doesn't specify the `DEVICE` but a filename. As a consequence - `'/'` is not a valid character for the name. +* 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`. -### `state` and `persistent_state` +You can also use the same connection profile multiple times. Therefore, it is possible to create a profile and activate it separately. -Each connection profile can have a runtime state, represented by the `state` -setting and a persistent state, represtented by the `persistent_state` setting. +### `state` -The optional `state` setting supports the following values: +The `state` option identifies what is the runtime state of each connection profile. The `state` option (optional) can be set to the following values: -- `up` -- `down` +* `up` - the connection profile is activated +* `down` - the connection profile is deactivated -It defines whether the profile is activated (`up`) or deactivated (`down`). If -it is unset, the profile's runtime state will not be changed. +#### `state: up` +- For `NetworkManager`, this corresponds to `nmcli connection id {{name}} up`. -The `persistent_state` setting is either `present` (default) or `absent`. If -the `persistent_state` setting is `present` and the connection profile contains -a `type` setting, the profile will be created or updated. If the profile is -incomplete (lacks the `type` setting) and `persistent_state` is `present`, -the behavior is undefined. The value `absent` makes the role ensure -that the profile is not present on the target host. +- For `initscripts`, this corresponds to `ifup {{name}}`. + +When the `state` option is set to `up`, you can also specify the `wait` option (optional): + +* `wait: 0` - initiates only the activation, but not wait until the device is fully connected. +The connection is completed, for example after a DHCP lease received. +* `wait: ` is a timeout that enables you to decide how long you give the device to +activate. The default is using a suitable timeout. Note that the `wait` option is +only supported by NetworkManager. + +**TODO**: `wait` different from a `zero` value is not yet implemented. + +Note that `state: up` always re-activates the profile and possibly changes the +networking configuration, even if the profile was already active before. As +a consequence, `state: up` always changes the system. + +#### `state: down` + +- For `NetworkManager`, it corresponds to `nmcli connection id {{name}} down`. + +- For `initscripts`, it corresponds to call `ifdown {{name}}`. + +You can deactivate a connection profile, even if is currently not active. As a consequence, `state: down` always changes the system. + +Note that if the `state` option is unset, the connection profile’s runtime state will not be changed. -#### Example +### `persistent_state` -```yaml -network_connections: - - name: eth0 - persistent_state: absent -``` +The `persistent_state` option identifies if a connection profile is in a persistent state. The `persistent_state` option can be set to the following values: -Above example ensures the absence of a connection profile. If a profile with `name` `eth0` -exists, it will be deleted. +* `present` (default) -* For NetworkManager this deletes all connection profiles with the matching `connection.id`. - Deleting a profile usually does not change the current networking configuration, unless - the profile was currently activated on a device. In that case deleting the currently - active connection profile disconnects the device. That makes the device eligible - to autoconnect another connection (see also [rh#1401515](https://bugzilla.redhat.com/show_bug.cgi?id=1401515)). + Note that if `persistent_state` is `present` and the connection profile contains + the `type` option, the profile will be created or updated. If the connection profile is + incomplete (no `type` option), the behavior is undefined. Also, the `present` value + does not directly result in a change in the network configuration. If the `state` option + is not set to `up`, the profile is only created or modified, not activated. -* For initscripts it results in the deletion of the ifcfg file. Usually that - has no side-effect, unless some component is watching the sysconfig directory. +* `absent` -#### Example + The `absent` value ensures that the profile is not present on the target host. For + example, if a profile with `name` `eth0` exists, it will be deleted. In this case: -```yaml -network_connections: - - name: eth0 - #persistent_state: present # default - type: ethernet - autoconnect: yes - mac: 00:00:5e:00:53:5d - ip: - dhcp4: yes -``` + - `NetworkManager` deletes all connection profiles with the corresponding `connection.id`. + Deleting a profile usually does not change the current networking configuration, unless + the profile was currently activated on a device. Deleting the currently + active connection profile disconnects the device. That makes the device eligible + to autoconnect another connection (for more details, see [rh#1401515](https://bugzilla.redhat.com/show_bug.cgi?id=1401515)). -Above example creates a new connection profile or ensures that it is present -with the given configuration. It implies the `persistent_state` setting to be -`present`. + - ` initscripts` deletes the ifcfg file in most cases with no impact on the system unless a component relies on the sysconfig directory. -Valid values for `type` are: +**Note**: For profiles that only contain a `state` option, the `network` role only activates +or deactivates the connection without changing its configuration. + + +### `type` + +The `type` option can be set to the following values: - - `bond` - - `bridge` - `ethernet` - - `infiniband` - - `macvlan` + - `bridge` + - `bond` - `team` - `vlan` + - `macvlan` + - `infiniband` -The value `present` for the `persistent_state` setting does not directly -result in a change in the network configuration. That is, without `state` -set to `up`, the profile is only created or modified, not activated. +#### `type: ethernet` + +The `type:ethernet` should be specified as a dictionary with the following +items (options): `autoneg`, `speed` and `duplex`, which correspond to the +settings of the `ethtool` utility with the same name. + +* `autoneg`: `yes` (default) or `no` [if auto-negotiation is enabled or disabled] +* `speed`: speed in Mbit/s +* `duplex`: `half` or `full` + +Note that the `speed` and `duplex` link settings are required when autonegotiation is disabled (autoneg:no). + +#### `type: bridge`, `type:bond`, `type: team` + +The `bridge`, `bond`, `team` device types work similar. Note that `team` is not supported in RHEL6 kernels. + +For slaves, the `slave_type` and `master` properties must be set. Note that slaves should not have `ip` settings. + +The `master` refers to the `name` of a profile in the ansible +Playbook. It is neither an interface-name nor a connection-id of +NetworkManager. + +- For `NetworkManager`, `master` corresponds to the `connection.uuid` + of the corresponding profile. + +- For `initscripts`, `master` determines the `DEVICE` from the corresponding + ifcfg file. + +As `master` refers to other profiles of the same or another play, +the order of the `connections` list matters. Also, `--check` ignores +the value of the `master` and assumes it will be present during a real +run. That means, in presence of an invalid `master`, `--check` may +signal success but the actual play run fails. + +#### `type: vlan` + +Similar to `master`, the `parent` references the connection profile in the ansible +role. + +#### `type: macvlan` + +Similar to `master` and `vlan`, the `parent` references the connection profile in the ansible +role. -- For NetworkManager, note the new connection profile is created with - `autoconnect` turned on by default. Thus, NetworkManager may very well decide - right away to activate the new profile on a currently disconnected device. - ([rh#1401515](https://bugzilla.redhat.com/show_bug.cgi?id=1401515)). ### `autoconnect` +For NetworkManager, the new connection profile is created when the `autoconnect` +option is enabled by default. Therefore, NetworkManager can activate the new +profile on a currently disconnected device. ([rh#1401515](https://bugzilla.redhat.com/show_bug.cgi?id=1401515)). + By default, profiles are created with autoconnect enabled. -- For NetworkManager, this translates to the `connection.autoconnect` property. +- For `NetworkManager`, this corresponds to the `connection.autoconnect` property. -- For initscripts, this corresponds to the `ONBOOT` property. +- For `initscripts`, this corresponds to the `ONBOOT` property. ### `mac` The `mac` address is optional and restricts the profile to be usable only on devices with the given MAC address. `mac` is only allowed for `type` -`ethernet` or `type` `infiniband` to match a non-virtual device with the +`ethernet` or `infiniband` to match a non-virtual device with the profile. -- For NetworkManager `mac` is the permanent MAC address `ethernet.mac-address`. +- For `NetworkManager`, `mac` is the permanent MAC address, `ethernet.mac-address`. -- For initscripts, this means the currently configured MAC address of the device (`HWADDR`). +- For `initscripts`, `mac` is the currently configured MAC address of the device (`HWADDR`). ### `interface_name` -For the types `ethernet` and `infiniband`, this option restricts the profile to +For the `ethernet` and `infiniband` types, the `interface_name` option restricts the profile to the given interface by name. This argument is optional and by default the profile name is used unless a mac address is specified using the `mac` key. -Specifying an empty string (`""`) allows to specify that the profile is not +Specifying an empty string (`""`) means that the profile is not restricted to a network interface. - **Note:** With [persistent interface naming](https://access.redhat.com/documentation/en-US/Red_Hat_Enterprise_Linux/7/html/Networking_Guide/ch-Consistent_Network_Device_Naming.html), the interface is predictable based on the hardware configuration. Otherwise, the `mac` address might be an option. -For virtual interface types like bridges, this argument is the name of the created -interface. In case of a missing `interface_name`, the profile name `name` is used. +For virtual interface types such as bridges, the `interface_name` is the name of the created +interface. In case of a missing `interface_name`, the `name` of the profile name is used. -**Note:** The profile name `name` and the device name `interface_name` may be +**Note:** The `name` (the profile name) and the `interface_name` (the device name) may be different or the profile may not be tied to an interface at all. ### `zone` -Sets the firewalld zone for the interface. +The `zone` option sets the firewalld zone for the interface. -Slaves to bridge/bond/team devices cannot specify a zone. +Slaves to the bridge, bond or team devices cannot specify a zone. -### `state: up` -#### Example +### `ip` -```yaml -network_connections: - - name: eth0 - state: up -``` +The IP configuration supports the following options: -The above example requires an existing profile to activate. +* `address` -- For NetworkManager this results in `nmcli connection id {{name}} up`. + Manual addressing can be specified via a list of addresses under the `address` option. -- For initscripts it is the same as `ifup {{name}}`. +* `dhcp4` and `auto6` -State `up` also supports an optional integer setting `wait`. `wait: 0` will -only initiate the activation but not wait until the device is fully connected. -Connection will complete in the background, for example after a DHCP lease was -received. `wait: ` is a timeout for how long we give the device to -activate. The default is using a suitable timeout. Note that this setting is -only supported by NetworkManager. -**TODO** `wait` different from zero is not yet implemented. + Also, manual addressing can be specified by setting either `dhcp4` or `auto6`. + The `dhcp4` key is for DHCPv4 and `auto6` for StateLess Address Auto Configuration + (SLAAC). Note that the `dhcp4` and `auto6` keys can be omitted and the default key + depends on the presence of manual addresses. -Note that state `up` always re-activates the profile and possibly changes the -networking configuration, even if the profile was already active before. As -such, it always changes the system. -### `state: down` +* `dhcp4_send_hostname` -#### Example + If `dhcp4` is enabled, it can be configured whether the DHCPv4 request includes + the hostname via the `dhcp4_send_hostname` option. Note that `dhcp4_send_hostname` + is only supported by the `nm` provider and corresponds to + [`ipv4.dhcp-send-hostname`](https://developer.gnome.org/NetworkManager/stable/nm-settings.html#nm-settings.property.ipv4.dhcp-send-hostname) + property. -```yaml -network_connections: - - name: eth0 - state: down -``` +* `dns` and `dns_search` -Another `state` is `down`. + Manual DNS configuration can be specified via a list of addresses + given in the `dns` option and a list of domains to search given in the + `dns_search` option. -- For NetworkManager it is like calling `nmcli connection id {{name}} down`. -- For initscripts this means to call `ifdown {{name}}`. +* `route_metric4` and `route_metric6` -This is the opposite of the `up` state. It also will always issue the command -to deactivate the profile, even it if seemingly is currently not active. As -such, `down` always changes the system. + - For `NetworkManager`, `route_metric4` and `route_metric6` corresponds to the + [`ipv4.route-metric`](https://developer.gnome.org/NetworkManager/stable/nm-settings.html#nm-settings.property.ipv4.route-metric) and + [`ipv6.route-metric`](https://developer.gnome.org/NetworkManager/stable/nm-settings.html#nm-settings.property.ipv6.route-metric) + properties, respectively. If specified, it determines the route metric for DHCP + assigned routes and the default route, and thus the priority for multiple interfaces. -For NetworkManager, a `wait` argument is supported like for `up` state. +* `route` -### Refer to the same connection multiple times + Static route configuration can be specified via a list of routes given in the `route` + option. The default value is an empty list. Each route is a dictionary with the following + entries: `network`, `prefix`, `gateway` and `metric`. `network` and `prefix` specify + the destination network. + Note that Classless inter-domain routing (CIDR) notation or network mask notation are not supported yet. -#### Example +* `route_append_only` + + The `route_append_only` option allows only to add new routes to the + existing routes on the system. + + If the `route_append_only` boolean option is set to `yes`, the specified routes are appended to the existing routes. + If `route_append_only` is set to `no` (default), the current routes are replaced. + Note that setting `route_append_only` to `yes` without setting `route` has the effect of preserving the current static routes. + +* `rule_append_only` + + The `rule_append_only` boolean option allows to preserve the current routing rules. + Note that specifying routing rules is not supported yet. + +**Note:** When `route_append_only` or `rule_append_only` is not specified, the `network` role deletes the current routes or routing rules. + +**Note:** Slaves to the bridge, bond or team devices cannot specify `ip` settings. + + +Examples of Options +------------------- + +Setting the same connection profile multiple times: ```yaml network_connections: @@ -273,13 +356,143 @@ network_connections: state: up ``` -As said, the `name` identifies a unique profile. However, you can refer to the -same profile multiple times. Therefore it is possible to create a profile and -activate it separately. +Setting a connection profile activated: -### `ip` +```yaml +network_connections: + - name: eth0 + state: up +``` -The IP configuration supports the following options: +Setting a connection profile deactivated: + +```yaml +network_connections: + - name: eth0 + state: down +``` + +Creating a present connection profile: + +```yaml +network_connections: + - name: eth0 + #persistent_state: present # default + type: ethernet + autoconnect: yes + mac: 00:00:5e:00:53:5d + ip: + dhcp4: yes +``` + +Setting an absent connection profile: + +```yaml +network_connections: + - name: eth0 + persistent_state: absent +``` + +Configuring the Ethernet link settings: + +```yaml +network_connections: + - name: eth0 + type: ethernet + + ethernet: + autoneg: no + speed: 1000 + duplex: full +``` + +Configuring a bridge connection type: + +```yaml +network_connections: + - name: br0 + type: bridge + #interface_name: br0 # defaults to the connection name +``` + + +Configuring a bridge connection: + +```yaml +network_connections: + - name: internal-br0 + interface_name: br0 + type: bridge + ip: + dhcp4: no + auto6: no +``` + +Setting `master` and `slave_type`: + +```yaml +network_connections: + - name: br0-bond0 + type: bond + interface_name: bond0 + master: internal-br0 + slave_type: bridge + + - name: br0-bond0-eth1 + type: ethernet + interface_name: eth1 + master: br0-bond0 + slave_type: bond +``` + +Configuring VLANs: + +```yaml +network_connections: + - name: eth1-profile + autoconnet: no + type: ethernet + interface_name: eth1 + ip: + dhcp4: no + auto6: no + + - name: eth1.6 + autoconnect: no + type: vlan + parent: eth1-profile + vlan: + id: 6 + ip: + address: + - 192.0.2.5/24 + auto6: no +``` + +Configuring macvlan: + +```yaml +network_connections: + - name: eth0-profile + type: ethernet + interface_name: eth0 + ip: + address: + - 192.168.0.1/24 + + - name: veth0 + type: macvlan + parent: eth0-profile + macvlan: + mode: bridge + promiscuous: yes + tap: no + ip: + address: + - 192.168.1.1/24 +``` + +Setting the IP configuration: ```yaml network_connections: @@ -320,265 +533,87 @@ network_connections: rule_append_only: yes ``` -Manual addressing can be specified via a list of addresses and prefixes `address`. -Also, manual addressing can be combined with either `dhcp4` and `auto6` for DHCPv4 -and SLAAC. The `dhcp4` and `auto6` keys can be omitted and the default depends on the -presence of manual addresses. +### Invalid and Wrong Configuration -If `dhcp4` is enabled, it can be configured whether -the DHCPv4 request includes the hostname via `dhcp4_send_hostname`. -Note that `dhcp4_send_hostname` is only supported by the `nm` provider and translates -to [`ipv4.dhcp-send-hostname`](https://developer.gnome.org/NetworkManager/stable/nm-settings.html#nm-settings.property.ipv4.dhcp-send-hostname) -property. +The `network` role rejects invalid configurations. It is recommended to test the role +with `--check` first. There is no protection against wrong (but valid) configuration. +Double-check your configuration before applying it. -Manual DNS configuration can be specified via a list of addresses -given in the `dns` option and a list of domains to search given in the -`dns_search` option. -- For NetworkManager, `route_metric4` and `route_metric6` corresponds to the -[`ipv4.route-metric`](https://developer.gnome.org/NetworkManager/stable/nm-settings.html#nm-settings.property.ipv4.route-metric) and -[`ipv6.route-metric`](https://developer.gnome.org/NetworkManager/stable/nm-settings.html#nm-settings.property.ipv6.route-metric) - properties, respectively. If specified, it determines the route metric -for DHCP assigned routes and the default route, and thus the priority for multiple interfaces. +Compatibility +------------- -Static route configuration can be specified via a list of routes given in the `route` -option. The default value is an empty list. Each route is a dictionary with the following -entries: `network`, `prefix`, `gateway` and `metric`. `network` and `prefix` together specify -the destination network. CIDR notation or network mask notation are not supported yet. If the -boolean option `route_append_only` is `yes`, the specified routes are appended to the -existing routes, if it is `no` (default), the current routes are replaced. Setting this -option to `yes` without setting `route` has the effect of preserving the current static routes. The -boolean option `rule_append_only` works in a similar way for routing rules. Note that there is -no further support for routing rules at the moment, so this option serves merely the purpose -of preserving the current routing rules. Note also that when -`route_append_only`/`rule_append_only` is not specified, the current routes/routing rules will -be deleted by the role. +The `network` role supports the same configuration scheme for both providers (`nm` +and `initscripts`). That means, you can use the same playbook with NetworkManager +and initscripts. However, note that not every option is handled exactly the same +by every provider. Do a test run first with `--check`. -Slaves to bridge/bond/team devices cannot specify `ip` settings. +It is not supported to create a configuration for one provider, and expect another +provider to handle them. For example, creating profiles with the `initscripts` provider, +and later enabling NetworkManager is not guaranteed to work automatically. Possibly, +you have to adjust the configuration so that it can be used by another provider. -### `type: ethernet` +For example, configuring a RHEL6 host with initscripts and upgrading to +RHEL7 while continuing to use initscripts in RHEL7 is an acceptable scenario. What +is not guaranteed is to upgrade to RHEL7, disable initscripts and expect NetworkManager +to take over the configuration automatically. -Ethernet-specific options can be set using the connection profile variable `ethernet`. This -variable should be specified as a dictionary with the following items (options): `autoneg`, `speed` and `duplex`, -which correspond to the settings of the `ethtool` utility with the same name. `speed` is an -integer giving the speed in Mb/s, the valid values of `duplex` are `half` and `full`, and -`autoneg` accepts a boolean value (default is `yes`) to configure autonegotiation. The `speed` and `duplex` settings are required when autonegotiation is disabled. - -```yaml -network_connections: - - name: eth0 - type: ethernet - - ethernet: - autoneg: no - speed: 1000 - duplex: full -``` - -### Virtual types and Slaves - -Device types like `bridge`, `bond`, `team` work similar: - -```yaml -network_connections: - - name: br0 - type: bridge - #interface_name: br0 # defaults to the connection name -``` - -Note that `team` is not supported on RHEL6 kernels. - -For slaves of these virtual types, the special properites `slave_type` and -`master` must be set. Also note that slaves cannot have `ip` settings. - -```yaml -network_connections: - - name: internal-br0 - interface_name: br0 - type: bridge - ip: - dhcp4: no - auto6: no - - - name: br0-bond0 - type: bond - interface_name: bond0 - master: internal-br0 - slave_type: bridge - - - name: br0-bond0-eth1 - type: ethernet - interface_name: eth1 - master: br0-bond0 - slave_type: bond -``` - -Note that the `master` refers to the `name` of a profile in the ansible -playbook. That is, it is neither an interface-name, nor a connection-id of -NetworkManager. - -- For NetworkManager, `master` will be converted to the `connection.uuid` - of the corresponding profile. - -- For initscripts, the master is looked up as the `DEVICE` from the corresponding - ifcfg file. - -As `master` refers to other profiles of the same or another play, -the order of the `connections` list matters. Also, `--check` ignores -the value of the `master` and assumes it will be present during a real -run. That means, in presence of an invalid `master`, `--check` may -signal success but the actual play run fails. - -### `type: vlan` - -VLANs work too: - -```yaml -network_connections: - - name: eth1-profile - autoconnet: no - type: ethernet - interface_name: eth1 - ip: - dhcp4: no - auto6: no - - - name: eth1.6 - autoconnect: no - type: vlan - parent: eth1-profile - vlan: - id: 6 - ip: - address: - - 192.0.2.5/24 - auto6: no -``` - -Like for `master`, the `parent` references the connection profile in the ansible -role. - -### `type: macvlan` - -MACVLANs also work: - -```yaml -network_connections: - - name: eth0-profile - type: ethernet - interface_name: eth0 - ip: - address: - - 192.168.0.1/24 - - - name: veth0 - type: macvlan - parent: eth0-profile - macvlan: - mode: bridge - promiscuous: yes - tap: no - ip: - address: - - 192.168.1.1/24 -``` - -Like for `master` and `vlan`, the `parent` references the connection profile in the ansible -role. - -### `network_provider` - -When Network Manager is running on the target system, the role will use the -`nm` provider and `initscripts` otherwise. The variable `network_provider` -allows to specify a specific provider. Setting it to -`network_provider_os_default` will choose the provider depening on the -operating system. This is usually `nm` except for RHEL 6 or CentOS 6 systems. - -#### Example - -```yaml -network_provider: nm -network_connections: - - name: eth0 - #... -``` +Depending on NetworkManager's configuration, connections may be stored as ifcfg files +as well, but it is not guaranteed that plain initscripts can handle these ifcfg files +after disabling the NetworkManager service. Limitations ----------- -### Configure over the Network +Ansible usually works via the network, for example via SSH. There are some limitations to be considered: -Ansible usually works via the network, for example via SSH. This role doesn't answer -how to bootstrap networking configuration. One option may be [ansible-pull](https://docs.ansible.com/ansible/playbooks_intro.html#ansible-pull). -Another to initially auto-configure the host during installation (ISO based, kickstart, etc.), -so that the host is connected to a management LAN or VLAN. It strongly depends on your environment. +The `network` role does not support how to bootstrap networking configuration. One +option may be [ansible-pull](https://docs.ansible.com/ansible/playbooks_intro.html#ansible-pull). +Another option maybe be to initially auto-configure the host during installation +(ISO based, kickstart, etc.), so that the host is connected to a management LAN +or VLAN. It strongly depends on your environment. -- For initscripts provider, deploying a profile merely means to create the ifcfg - files. Nothing happening automatically until the play issues `ifup` or `ifdown` - via the `up` or `down` [states](#state) -- unless of course, there are other - components that watch the ifcfg files and react on changes. +For `initscripts` provider, deploying a profile merely means to create the ifcfg +files. Nothing happens automatically until the play issues `ifup` or `ifdown` +via the `up` or `down` [states](#state) -- unless there are other +components that rely on the ifcfg files and react on changes. -- The initscripts provider requires the different profiles to be in the right - order when they depend on each other, for example the bonding master device - needs to be specified before the slave devices. +The `initscripts` provider requires the different profiles to be in the right +order when they depend on each other. For example the bonding master device +needs to be specified before the slave devices. -- When removing a profile for NetworkManager it will also take the connection - down and possibly remove virtual interfaces. With the initscripts provider - removing a profile does not change its current runtime state (this is going - to be the case for NetworkManager in the future, too.). +When removing a profile for NetworkManager it also takes the connection +down and possibly removes virtual interfaces. With the `initscripts` provider +removing a profile does not change its current runtime state (this is a future +deployment for NetworkManager as well). -- For NetworkManager, modifying a connection with autoconnect enabled - may result in the activation of the new profile on a previously disconnected - interface. Also, deleting a NetworkManager connection that is currently active - will tear down the interface. Therefore, the order of the steps may matter - and or careful handling of [autoconnect](#autoconnect) property may be necessary. - This should be improved in NetworkManager RFE [rh#1401515](https://bugzilla.redhat.com/show_bug.cgi?id=1401515). +For NetworkManager, modifying a connection with autoconnect enabled +may result in the activation of a new profile on a previously disconnected +interface. Also, deleting a NetworkManager connection that is currently active +results in removing the interface. Therefore, the order of the steps should be +followed, and carefully handling of [autoconnect](#autoconnect) property may be +necessary. This should be improved in NetworkManager RFE [rh#1401515](https://bugzilla.redhat.com/show_bug.cgi?id=1401515). -- It seems difficult to change networking of the target host in a way that breaks the current - SSH connection of ansible. If you want to do that, ansible-pull might be a solution. - Alternatively, a combination of `async`/`poll` with changing the `ansible_host` midway - of the play. - **TODO** The current role doesn't yet support to easily split the - play in a pre-configure step, and a second step to activate the new configuration. +It seems difficult to change networking of the target host in a way that breaks +the current SSH connection of ansible. If you want to do that, ansible-pull might +be a solution. Alternatively, a combination of `async`/`poll` with changing +the `ansible_host` midway of the play. -In general, to successfully run the play, one must understand which configuration is -active in the first place and then carefully configure a sequence of steps to change to -the new configuration. Don't cut off the branch on which you are sitting. The actual -solution depends strongly on your environment. +**TODO** The current role does not yet support to easily split the +play in a pre-configure step, and a second step to activate the new configuration. -### If something goes wrong +In general, to successfully run the play, determine which configuration is +active in the first place, and then carefully configure a sequence of steps to change to +the new configuration. The actual solution depends strongly on your environment. -When something goes wrong while configuring the networking remotely, you might need -to get phyisical access to the machine to recover. +### Handling potential problems -- **TODO** NetworkManager supports a [checkpoint/rollback](https://developer.gnome.org/NetworkManager/stable/gdbus-org.freedesktop.NetworkManager.html#gdbus-method-org-freedesktop-NetworkManager.CheckpointCreate) - feature. At the beginning of the play we could create a checkpoint and if we lose connectivity - due to an error, NetworkManager would automatically rollback after timeout. - The limitations is that this would only work with NetworkManager, and it's not - clear that rollback will result in a working configuration either. +When something goes wrong while configuring networking remotely, you might need +to get physical access to the machine to recover. -#### Invalid and Wrong Configuration - -The role will reject invalid configurations, so it is a good idea to test the role -with `--check` first. There is no protection against wrong (but valid) configuration. -Double-check your configuration before applying it. - -### Compatibility - -The role supports the same configuration scheme for both providers. That means, you can -use the same playbook with NetworkManager and initscripts. Note however, that not every -option is handled exactly the same by every provider. Do a test run first with `--check`. - -It is also not supported to create a configuration for one provider, and expect another -provider to handle them. For example, creating proviles with `initscripts` provider -and later enabling NetworkManager is not guaranteed to work automatically. Possibly -you have to adjust the configuration so that it can be used by another provider. - -For example what will work is to configure a RHEL6 host with initscripts and upgrade to -RHEL7 while continuing to use initscripts on RHEL7. What is not guaranteed to work -it to upgrade to RHEL7, disable initscripts and expect NetworkManager to take over -the configuration automatically. - -Depending on NetworkManager's configuration, connections may be stored as ifcfg files -as well, but again it is not guaranteed that plain initscripts can handle these ifcfg files -after disabling the NetworkManager service. +**TODO** NetworkManager supports a +[checkpoint/rollback](https://developer.gnome.org/NetworkManager/stable/gdbus-org.freedesktop.NetworkManager.html#gdbus-method-org-freedesktop-NetworkManager.CheckpointCreate) +feature. At the beginning of the play we could create a checkpoint and if we lose +connectivity due to an error, NetworkManager would automatically rollback after +timeout. The limitations is that this would only work with NetworkManager, and +it is not clear that rollback will result in a working configuration.