An ansible role for configuring different network interfaces.
WARNING: This role can be dangerous to use. If you lose network connectivity to your target host by incorrectly configuring your networking, you may be unable to recover without physical access to the machine.
- Ethernet interfaces
- Bridge interfaces
- Bonded interfaces
- Network routes
- IP routing tables
- IP routing rules
The variables that can be passed to this role and a brief description about them are as follows:
# The list of route tables to be defined
interfaces_route_tables: []
# The list of ethernet interfaces to be added to the system
interfaces_ether_interfaces: []
# The list of bridge interfaces to be added to the system
interfaces_bridge_interfaces: []
# The list of bonded interfaces to be added to the system
interfaces_bond_interfaces: []
# An optional filter parameter to pass to the setup module.
interfaces_setup_filter: "{{ omit }}"
# An optional gather_subset parameter to pass to the setup module.
interfaces_setup_gather_subset: "{{ omit }}"
# An option to merge all configurations setup with merge: true
# in the global interfaces file (Debian-Family only)
interfaces_merge: false
Note: The values for the list are listed in the examples below.
- Configure eth1 and eth2 on a host with a static IP and a dhcp IP. Also define static routes and a gateway.
- hosts: myhost
roles:
- role: MichaelRigart.interfaces
interfaces_ether_interfaces:
- device: eth1
bootproto: static
address: 192.168.1.150
netmask: 255.255.255.0
gateway: 192.168.1.1
dnsnameservers: 192.0.2.1 192.0.2.2
dnssearch: example.com
mtu: 9000
pre_up: sleep 5
route:
- network: 192.168.200.0
netmask: 255.255.255.0
gateway: 192.168.1.1
- network: 192.168.100.0
netmask: 255.255.255.0
gateway: 192.168.1.1
- device: eth2
bootproto: dhcp
- Configure a bridge interface with multiple NICs added to the bridge.
- hosts: myhost
roles:
- role: MichaelRigart.interfaces
interfaces_bridge_interfaces:
- device: br1
type: bridge
address: 192.168.1.150
netmask: 255.255.255.0
bootproto: static
stp: "on"
mtu: 1500
ports: [eth1, eth2]
Note: Routes can also be added for this interface in the same way routes are added for ethernet interfaces.
- Configure a bond interface with an "active-backup" slave configuration.
- hosts: myhost
roles:
- role: MichaelRigart.interfaces
interfaces_bond_interfaces:
- device: bond0
mtu: 9000
address: 192.168.1.150
netmask: 255.255.255.0
bootproto: static
bond_mode: active-backup
bond_miimon: 100
bond_slaves: [eth1, eth2]
route:
- network: 192.168.222.0
netmask: 255.255.255.0
gateway: 192.168.1.1
- Configure a bonded interface with "802.3ad" as the bonding mode, specify the 802.3ad aggregation selection logic to use the aggregator with largest aggregate bandwidth, and IP address obtained via DHCP.
- hosts: myhost
roles:
- role: MichaelRigart.interfaces
interfaces_bond_interfaces:
- device: bond0
bootproto: dhcp
bond_mode: 802.3ad
bond_ad_select: bandwidth
bond_miimon: 100
bond_downdelay: 200
bond_updelay: 200
bond_lacp_rate: 1
bond_xmit_hash_policy: layer3+4
bond_slaves: [eth1, eth2]
- Configure a routing table
myroutetable
, and an Ethernet interfaceeth1
with an IP routing rule that defines when to use the routing table. It also configures an IP route on the interface for themyroutetable
routing table.
- hosts: myhost
roles:
- role: MichaelRigart.interfaces
interfaces_route_tables:
- name: myroutetable
id: 42
interfaces_ether_interfaces:
- device: eth1
bootproto: static
address: 192.168.1.150
netmask: 255.255.255.0
dnsnameservers: 192.0.2.1 192.0.2.2
dnssearch: example.com
mtu: 9000
route:
- network: 192.168.200.0
netmask: 255.255.255.0
gateway: 192.168.1.1
table: myroutetable
rules:
- from 192.168.200.0/24 table myroutetable
- Configure a hot-pluggable Wifi interface
wlan0
with a static IP and awpa_supplicant
configuration. Also configure eth0 with a dhcp IP.
- hosts: myhost
roles:
- role: MichaelRigart.interfaces
interfaces_ether_interfaces:
- device: wlan0
allowclass: allow-hotplug
bootproto: static
address: 192.168.1.150
netmask: 255.255.255.0
network: 192.168.1.0
broadcast: 192.168.1.255
gateway: 192.168.1.1
dnsnameservers: 192.168.1.1
wpaconf: /etc/wpa_supplicant/wpa_supplicant.conf
- device: eth0
bootproto: dhcp
- Configure a static IPv4 address, route along with an IPv6 address and route on an interface.
- hosts: myhost
roles:
- role: MichaelRigart.interfaces
interfaces_ether_interfaces:
- device: ens160
bootproto: static
address: 10.99.99.2
netmask: 255.255.255.0
route:
- network: 10.99.98.0
netmask: 255.255.255.0
gateway: 10.99.99.1
ip6:
address: fd49:f9f5:ccb4:2acd::ac18:1002
prefix: 120
route:
- network: 64:FF9B::/96
gateway: fd49:f9f5:ccb4:2acd::ac18:1001
- All the above examples show how to configure a single host, The below example shows how to define your network configurations for all your machines.
Assume your host inventory is as follows:
[dc1]
host1
host2
Describe your network configuration for each host in host vars:
interfaces_ether_interfaces:
- device: eth1
bootproto: static
address: 192.168.1.150
netmask: 255.255.255.0
gateway: 192.168.1.1
route:
- network: 192.168.200.0
netmask: 255.255.255.0
gateway: 192.168.1.1
interfaces_bond_interfaces:
- device: bond0
mtu: 9000
bootproto: dhcp
bond_mode: 802.3ad
bond_miimon: 100
bond_slaves: [eth2, eth3]
interfaces_ether_interfaces:
- device: eth0
bootproto: static
address: 192.168.1.150
netmask: 255.255.255.0
gateway: 192.168.1.1
Create a playbook which applies this role to all hosts as shown below, and run the playbook. All the servers should have their network interfaces configured and routes updated.
- hosts: all
roles:
- role: MichaelRigart.interfaces
Note: Ansible needs network connectivity throughout the playbook process, you may need to have a control interface that you do not modify using this method so that Ansible has a stable connection to configure the target systems.
- CentOS 8 cloud image workaround
CentOS 8 cloud images ship with ifcfg files for ens3 and eth0. ifcfg-ens3 seems to be a relic from the image build process, and causes the network service to fail. ifcfg-eth0 is useful for most virtual machines, but if a cloud image is deployed on bare metal and eth0 is absent, the network service will fail. This role will by default remove these files, if there is no such interface on the system, and no such interface is specified in the role variables.
This workaround is configured via interfaces_workaround_centos_remove
. To
set a different interface file to remove:
interfaces_workaround_centos_remove:
- eth1
Or to avoid performing this workaround:
interfaces_workaround_centos_remove: []
- Allowed addresses
Sometimes it may be useful to not immediately assign an IP address to an
interface, but to allow another process to assign one. An example use case is a
virtual IP address dynamically added or by a process such as keepalived.
This may be configured via an allowed_addresses
field in an Ethernet, bond or
bridge interface configuration.
- hosts: myhost
roles:
- role: MichaelRigart.interfaces
interfaces_ether_interfaces:
- device: eth0
bootproto: static
address: 0.0.0.0
allowed_addresses:
- 10.0.0.2
- Custom options for static routes
Adding custom options to static routes is possible via the options
attribute,
which should be a list.
- hosts: myhost
roles:
- role: MichaelRigart.interfaces
interfaces_ether_interfaces:
- device: eth0
bootproto: static
address: 0.0.0.0
route:
- network: 192.168.200.0
netmask: 255.255.255.0
gateway: 192.168.1.1
options:
- onlink
- metric 400
- Configure an IPoIB (infiniband) interface
Configuring an IPoIB interface is possible using type: ipoib
when defining the interface.
WARNING: You can configure the ip address and routes for an IPoIB interface but other functionalities like vlans are not supported in infiniband networks
- hosts: myhost
roles:
- role: MichaelRigart.interfaces
interfaces_ether_interfaces:
- device: eth0
bootproto: static
address: 192.168.1.150
netmask: 255.255.255.0
gateway: 192.168.1.1
- device: ib0
bootproto: static
address: 10.10.1.10
netmask: 255.255.255.0
type: ipoib
- Configure ethtool options (RedHat-family only)
Setting ethtool options on an interface is possible using the ethtool_opts
attribute, which should be a string. For example, this can be used to set RX/TX
ring parameters. This is only supported on distributions of the RedHat family.
- hosts: myhost
roles:
- role: MichaelRigart.interfaces
interfaces_ether_interfaces:
- device: eth0
bootproto: static
address: 192.168.1.150
netmask: 255.255.255.0
gateway: 192.168.1.1
ethtool_opts: "-G ${DEVICE} rx 8192 tx 8192"
To apply ethtool options to bond slaves or bridge ports, set the attribute on the bond or bridge itself. Setting different options per underlying interface is not supported at this time.
- Configure firewalld zones (RedHat-family only)
Adding interface to firewalld zone is possible using the zone
attribute.
This is only supported on distributions of the RedHat family.
- hosts: myhost
roles:
- role: MichaelRigart.interfaces
interfaces_ether_interfaces:
- device: eth0
bootproto: static
address: 192.168.1.150
netmask: 255.255.255.0
gateway: 192.168.1.1
zone: trusted
- Pause to wait for interfaces to become active
On some OS distributions (including Ubuntu), it may be necessary to wait after
bouncing network interfaces before they are active. This can be done by setting
interfaces_pause_time
to a number of seconds to delay.
- Configure HW(MAC) address for interface
Configuring interface HW adrress is possible using the hwaddr
attribute.
This alone may not be sufficient to change MAC from default one, however
specifying hw address is necessary for some systems.
- hosts: myhost
roles:
- role: MichaelRigart.interfaces
interfaces_ether_interfaces:
- device: eth0
bootproto: static
address: 192.168.1.150
netmask: 255.255.255.0
gateway: 192.168.1.1
hwaddr: 00:11:22:33:44:55
- Configure HW(MAC) address for bonded/bridged interface
Configuring interface HW adrress is possible using the hwaddr
attribute.
- hosts: myhost
roles:
- role: MichaelRigart.interfaces
interfaces_bond_interfaces:
- device: bond0
bootproto: dhcp
bond_mode: 802.3ad
hwaddr: 00:11:22:33:44:55
interfaces_bridge_interfaces:
- device: br1
type: bridge
bootproto: dhcp
hwaddr: 00:11:22:33:44:66
ports: [eth1, eth2]
-
Routes and rules can be a mix of strings and hashes (a.k.a. dict, mapping, associative array, etc.) allowing the role to handle rules and routes outside the expected formats.
The example below configures an interface, to act as a second interface so that any traffic that hits it is returned via the same interface. In addition internal traffic is marked so it can be picked up by some other service (like HAproxy).
interfaces_route_tables:
- name: frontend
id: 200
- name: marktable
id: 100
interfaces_ether_interfaces:
- device: eth1
bootproto: static
address: 10.10.10.1
netmask: 255.255.255.0
defroute: false
route:
- table: frontend
device: eth1
network: 0.0.0.0
netmask: 0.0.0.0
gateway: 10.10.10.254
- "local 0.0.0.0/0 dev lo table marktable"
rules:
- from: 10.10.10.1
table: frontend
- "fwmark 1 lookup marktable"
- hosts: servers
roles:
- { role: MichaelRigart.interfaces, become: true }
GPLv3
Michaël Rigart michael@netronix.be