DEBOPS.IFUPDOWN(5)

NAME
debops.ifupdown - Manage network interfaces using Ansible

SYNOPSIS

debops service/ifupdown [--limit group,host,...] [--diff] [--check] [--tags tag1,tag2,...] [--skip-tags tag1,tag2,...] [<ansible-playbook options>] ...

DESCRIPTION

ifupdown is a set of high-level scripts in Debian/Ubuntu Linux distributions which can be used to configure network interfaces, bridges, VLAN interfaces, bonding, and so on. You can find example configuration and usage guides on the NetworkConfiguration <https://wiki.debian.org/NetworkConfiguration> page of the Debian Wiki <https://wiki.debian.org/>.

debops.ifupdown is an Ansible role which wraps ifupdown in an easy to use, and Ansible-friendly interface. It aims to be a safe and reliable way to let you configure network interfaces on hosts managed using Ansible. It can be used either as a standalone role configured using role/inventory variables, or as a dependency of another role, to provide network configuration as needed.

GETTING STARTED

  Quick start guide

Here are some quick examples to get you started if you already know how to use DebOps roles. These examples are supposed to go into your Ansible inventory, specifically to the host configuration, for example ansible/inventory/host_vars/<hostname>/ifupdown.yml.

Create an anonymous bridge:

ifupdown__host_interfaces:
  'br2': {}

Create a bridge with static IP address and IPv4 NAT using SNAT translation:

ifupdown__host_interfaces:
  'br2':
    inet: 'static'
    inet6: 'static'
    addresses: [ '192.0.2.1/24', '2001:db8:feed:beef::1/64' ]
    nat: True

  Default network configuration

Without any additional configuration, debops.ifupdown role will try to select one of two default interface layouts depending on whether the host is an OpenVZ/LXC container or not. If it's a container, the role will use the dynamic interface layout which defines 1 or 2 network interfaces that are configured via DHCP (IPv4) and SLAAC (IPv6).

If the host is not a container, the role will select the bridge layout, which defines 1 or 2 network interfaces with attached bridges that are configured with DHCP (IPv4) and SLAAC (IPv6). This configuration is beneficial when a machine is used as a KVM, LXC or even a Docker host. With the bridges in place you can connect the VMs or containers to your external or internal network with ease.

  Automatic upgrades from older version

The debops.ifupdown role tracks its own version used on a host using the debops.debops_fact as an intermediary. If the currently applied version is older than 0.3.0 or the version cannot be found, role will remove the /etc/network/interfaces.config.d/ directory to make sure that the network configuration state is consistent. You might want to review and update your interface configuration in the Ansible inventory before applying a new version of the role to ensure that it has accurate information about interfaces present on the host.

  Example inventory

To enable the ifupdown interface management, you need to add the host to the [debops_service_ifupdown] Ansible inventory group:

[debops_service_ifupdown]
hostname

The role does not check if the host can manage network interfaces, therefore you should only enable this role on hosts that are allowed to do so. One of the limiting factors can be the presence of the cap_net_admin POSIX capability. Make sure that it is present on the host so that it can manage its own networking.

  Example playbook

If you are using this role without DebOps, here's an example Ansible playbook that uses the debops.ifupdown role:

---
- name: Manage network configuration using ifupdown
  collections: [ 'debops.debops', 'debops.roles01',
                 'debops.roles02', 'debops.roles03' ]
  hosts: [ 'debops_service_ifupdown' ]
  become: True
  environment: '{{ inventory__environment | d({})
                   | combine(inventory__group_environment | d({}))
                   | combine(inventory__host_environment  | d({})) }}'
  pre_tasks:
    - name: Prepare ifupdown environment
      import_role:
        name: 'ifupdown'
        tasks_from: 'main_env'
      tags: [ 'role::ifupdown', 'role::kmod', 'role::ferm', 'role::sysctl' ]
  roles:
    - role: resolvconf
      tags: [ 'role::resolvconf', 'skip::resolvconf' ]
      resolvconf__enabled: True
    - role: python
      tags: [ 'role::python', 'skip::python', 'role::kmod' ]
      python__dependent_packages3:
        - '{{ kmod__python__dependent_packages3 }}'
      python__dependent_packages2:
        - '{{ kmod__python__dependent_packages2 }}'
    - role: kmod
      tags: [ 'role::kmod', 'skip::kmod' ]
      kmod__dependent_load:
        - '{{ ifupdown__env_kmod__dependent_load }}'
    - role: ferm
      tags: [ 'role::ferm', 'skip::ferm' ]
      ferm__dependent_rules:
        - '{{ ifupdown__env_ferm__dependent_rules }}'
    - role: sysctl
      tags: [ 'role::sysctl', 'skip::sysctl' ]
      sysctl__dependent_parameters:
        - '{{ ifupdown__env_sysctl__dependent_parameters }}'
    - role: ifupdown
      tags: [ 'role::ifupdown', 'skip::ifupdown' ]

ENHANCEMENTS TO IFUPDOWN IN SYSTEMD

  ifup-all-auto.service

This systemd unit should make sure that all of the network interfaces that are enabled by allow-auto parameter are up before the network-online.target is reached. This makes that target usable on Debian/Ubuntu hosts; services that depend on that target should work properly with the assumption that the host has network connectivity at that point.

  ifup-allow-boot.service

This systemd unit will bring up all network interfaces that are marked by allow-boot and allow-hotplug parameters at system boot time. It is run after the networking.service unit and will use the command systemctl start ifup@<interface>.service to start the interfaces, so that any processes that are attached to them will be put in their separate cgroups. This allows better network management on systemd hosts.

CUSTOM IFUPDOWN HOOKS

The debops.ifupdown Ansible role can configure custom ifupdown hooks in other software to configure services related to network interfaces. The list of hooks can be found in the ifupdown__custom_hooks variable, which is a list of YAML dictionaries with specific parameters:

name
    Required. Name of the hook, used as an identifier.

hook
    Optional. Path of a Jinja2 template included with the debops.ifupdown role relative to the templates/ directory, which will be used to generate the hook script. The hook script will be placed at the same path on the target host.

src Optional. Override the path of the Jinja2 template (the .j2 extension needs to be specified).

dest
    Optional. Override the path of the generated hook on the remote host (path needs to start with /).

mode
    Optional. Set the file mode to use, by default 0755.

state
    Optional. If not specified or present, the hook will be generated. If absent, the hook will be removed.

  The filter-dhcp-options hook

This hook is a Bourne shell (/bin/sh) script that is sourced by the dhclient-script(8) <https://manpages.debian.org/dhclient-script(8)> command executed by the dhclient program during interface configuration via DHCP. The hook allows to filter and ignore received DHCP options per network interface, which can be useful on systems connected to multiple networks with each one providing DHCP services. A list of DHCP options can be found in the dhcp-options(5) <https://manpages.debian.org/dhcp-options(5)> manual page.

By default the hook does not filter any DHCP options. To configure it, add the dhcp_ignore parameter in the ifupdown__interfaces interface configuration. The parameter is a string or list of variables used by the dhclient-script command to represent DHCP options.

  Examples

Consider configuration of a host connected to two networks, br0 (internal network) and br1 (external network via a VLAN). By default the Debian Installer sets up only the internal network connection which is used for host configuration and management. The external connection is configured later, via a VLAN which cannot be automatically configured by the Debian Installer. Both networks are maintained using DHCP servers, each providing a default route through its network.

After the host is configured, you want to switch the default route from the internal network to the external network to allow public access to the services provided by this host. To do that, the default route from the internal DHCP server needs to be ignored, in which case the external network will take precedence.

Additionally, the external DHCP server provides information about nameservers that don't know about the internal network. You want to ignore the external nameservers and use the ones provided by the internal network to resolve queries, which lets you access other internal hosts via their hostnames.

ifupdown__host_interfaces:
  - iface: 'br0'
    comment: 'Internal network'
    type:  'bridge'
    inet:  'dhcp'
    inet6: 'auto'
    bridge_ports: 'eth0'
    dhcp_ignore: 'new_routers'
  - iface: 'br1'
    comment: 'External network'
    type:  'bridge'
    inet:  'dhcp'
    inet6: 'auto'
    bridge_ports: 'eth1'
    dhcp_ignore: 'new_domain_name_servers'

Just after installation the host will have only the internal network connection set up, used for configuration. When Ansible applies the debops.ifupdown configuration on the host, the default route to the external network will replace the default route to the internal network, however existing internal connections will work as usual. Any existing connections to the external network via internal router might be interrupted before the new route takes over.

The network configuration should be preserved across reboots - even though both of the DHCP servers send relevant configuration for default routes and nameservers, the DHCP options are filtered on the client side.

DEFAULT VARIABLE DETAILS

Some of debops.ifupdown default variables have more extensive configuration than simple strings or lists, here you can find documentation and examples for them.

  ifupdown__interfaces

The ifupdown__*_interfaces variables are YAML dictionaries which define what network interfaces are configured on a host. All dictionaries are recursively combined together in the order they appear in the defaults/main.yml file.

Each entry in the ifupdown__*_interfaces dictionaries is a YAML dictionary. The key of a given entry is either a network interface name (for example eth0, br0, etc.) or a "label" that holds the preferences for a network interface denoted by the iface parameter. Configuration parameters in labeled sections will be merged with the real network interface preferences.

You can also use YAML lists of dictionaries, however you cannot combine both dictionaries and lists in the same ifupdown__*_interfaces variable. YAML dictionaries specified in a list need to have the iface parameter that specifies the interface name, otherwise they will be skipped.

Each network interface will have its configuration in a separate file in /etc/network/interfaces.d/ directory on the managed hosts (both IPv4 and IPv6 configuration is in the same file).

  Network interface types

Each network interface has a particular type (ethernet, bridge, VLAN, etc.). The type can be specified by the type parameter. If this parameter is not defined, the role will try to select the correct type based on the interface name prefix:

en* or eth*
    The Ethernet network interfaces, marked as the ether type. If not configured specifically, this interface type will automatically enable an IPv4 DHCP configuration and IPv6 SLAAC configuration. The network interface will be configured to be brought up by the hotplug subsystem.

br* The network bridge interface, marked as the bridge type. If not configured specifically, the role will configure an anonymous bridge without any network interfaces connected, which will be started automatically at boot. The firewall will be configured to allow network traffic through the bridge, without IPv4 NAT.

vlan* or name with a dot (.)
    The VLAN interface, marked as the vlan type.

bond*
    The bonding interface, marked as the bonding type.

sl* The Serial Line Internet Protocol <https://en.wikipedia.org/wiki/Serial_Line_Internet_Protocol> interface, marked as the slip type.

wl* The Wireless LAN interface, marked as the wlan type.

ww* The Wireless WAN <https://en.wikipedia.org/wiki/Wireless_WAN> interface, marked as the wwan type.

tap*, tun*, mesh*, sit*
    The network tunnel interface, marked as the tunnel type.

6to4
    The IPv6 to IPv4 transition mechanism <https://en.wikipedia.org/wiki/6to4> interface, marked as the 6to4 type. If not configured specifically, this interface will be configured as 6to4 tunnel with local IPv6 address based on the default network interface IPv4 address.

mapping
    The interface configuration is selected dynamically by a specified script. See interfaces(5) <https://manpages.debian.org/interfaces(5)> for more details.

    Each network interface can have multiple parameters. Some parameters are specific to a particular interface type.

  General interface parameters

iface
    Name of the network interface to configure. If not specified, the network interface will be taken from the YAML dictionary key which holds the parameters.

    Example Ethernet interface configuration without and with iface parameter, and a version specified as a list:

    ifupdown__interfaces:
      'eth0':
        type: 'ether'
    ifupdown__group_interfaces:
      'external':
        iface: 'eth0'
        type: 'ether'
    ifupdown__host_interfaces:
      - iface: 'eth0'
        type: 'ether'

    The iface parameter can be templated by Jinja, unlike the dictionary key.

type
    Optional. Specify the interface type. If this parameter is not defined, role will try and guess the type based on the interface name (see Network interface types). The interface type affects the order in which interfaces are brought up/down and use/requirement of special parameters for certain types.
    Type | Weight | Notes
    mapping | 00 | interface configured dynamically via scripts
    bonding | 10 | virtual bonded interface
    ether | 20 | Ethernet (physical or virtual) interface
    slip | 30 | Serial Line Internet Protocol interface
    wlan | 30 | Wireless Local Area Network interface (WiFi)
    wwan | 30 | Wireless Wide Area Network interface (mobile networks, GSM)
    vlan | 40 | VLAN interface, requires another interface to be attached to
    bridge | 60 | network bridge
    6to4 | 80 | IPv6 in IPv4 tunnel
    tunnel | 80 | virtual network tunnel

    If the detected interface type is vlan, the role will check what parent interface is a given VLAN attached to and change the configuration to reorder the vlan interface after all of the parent interfaces, so that network interfaces are processed in the working order. This will only happen if weight_class parameter is not specified. If the interface is overridden, the weight parameter will be set to 5 to ensure proper interface order.

weight_class
    Optional. Override the specified type for a given interface so that the weight of another type will be used instead.

weight
    Optional. Positive or negative number (for example 2 or -2) which will be added to the base weight defined by the interface type. This can be used to affect the network interface order.

state
    Optional. If not specified or present, the given interface configuration file will be created. If absent, the interface configuration will be removed. If ignore, the interface configuration won't be modified in any way – this is useful if you want to make sure that some network interfaces are ignored by the role.

    If you use the dynamic interface layout, you might need to explicitly set the br0 and br1 bridge state to present because this interface layout will try to remove them by default.

auto
    Optional, boolean. If True, the network interface will be brought up by the networking service at boot time, which might be not what you actually want in the newer, systemd-based hosts. By default it will be set to False. See also allow parameter.

allow
    Optional, boolean, string or YAML list. If set to False, this option is disabled. If True, the hotplug subsystem can bring this interface up or down when the hotplug event is detected. You can also specify a list of specific conditions at which the interface is brought up, currently recognized conditions are:

•   auto: bring the interface up at boot time by the networking service. This might not be what you want on newer systems.

•   boot: bring the interface up at boot time by iface@.service systemd unit. This will put any processes related to a given interface in their separate cgroup, which allows for better control over the network interface. This is a custom implementation of the auto mechanism managed by this Ansible role.

•   hotplug: bring the interface up/down at hotplug events. This condition is required to be present for the ifup@.service systemd unit to work properly.

    If this parameter is not specified, the role will use the boot value for network interfaces other than physical Ethernet interfaces, which will use the hotplug value by default.

  IPv4 and IPv6 configuration parameters

inet
    Optional. IPv4 configuration method used by a given interface. There are many configuration methods described in the interfaces(5) <https://manpages.debian.org/interfaces(5)> manual page, most commonly used are: manual, dhcp, static. If you set this parameter to False, the IPv4 configuration will be disabled.

inet6
    Optional. IPv6 configuration method used by a given interface. There are many configuration methods described in the interfaces(5) <https://manpages.debian.org/interfaces(5)> manual page, most commonly used are: auto, manual, dhcp, static, v4tunnel, 6to4. If you set this parameter to False, the IPv6 configuration will be disabled.

address or addresses
    Optional. A string or an YAML list of IPv4 and/or IPv6 addresses to set on a given network interface, in the form of ipaddress/prefix or CIDR. Remember that you need to specify the host IP address and not the network; the 192.0.2.1/24 is the correct notation, and 192.0.2.0/24 is incorrect.

gateway or gateways
    Optional. Specify the IPv4 or IPv6 address of the network gateway to which outgoing packets will be directed. If it's a list of addresses, first valid address for a network type will be used as the gateway.

  DNS nameserver and search parameters

dns_nameservers
    Optional. String or list of IP addresses of the nameservers to configure in /etc/resolv.conf. Remember that only 3 nameservers are allowed at any time. They will be added to the IPv4 section of the network interface configuration unless IPv4 is disabled, in which case they will be configured in IPv6 section.

dns_search
    Optional. String or list of domains which should be searched in the DNS if a hostname without a domain is specified. They will be added to the /etc/resolv.conf. This list will be added to the IPv4 section of the network interface configuration unless IPv4 is disabled, in which case they will be configured in IPv6 section.

  Bonding parameters

slaves
    Optional. String or YAML list of network interfaces to bond together.

bond_*
    Optional. If an interface is a bonding, any parameters that have bond_ prefix will be added to that interface configuration. See the documentation included in the ifenslave package for possible configuration options.

  Bridge parameters

bridge_*
    Optional. If an interface is a bridge, any parameters that have bridge_ prefix will be added to that interface configuration. See the bridge-utils-interfaces(5) <https://manpages.debian.org/bridge-utils-interfaces(5)> manual for more details about possible bridge configuration options.

  VLAN parameters

vlan_device or vlan_raw_device
    Name of the network interface on which a VLAN will be configured. If the interface name contains a dot (for example eth0.10), the role will try to detect the network interface automatically.

  6to4 tunnel parameters

local
    Optional. Specify the public IPv4 address which will be used to create the IPv6 6to4 tunnel.

  Mapping parameters

script
    Absolute path to a script which will be used to select a specific interface configuration for a mapping dynamically. See interfaces(5) <https://manpages.debian.org/interfaces(5)> manual for more details.

  DHCP parameters

dhcp_ignore
    Optional. String or list of variable names used by the dhclient-script(8) <https://manpages.debian.org/dhclient-script(8)> script to configure the interface. The specified variables representing DHCP options will be unset by the configuration script; this can be used to selectively ignore DHCP options on a given network interface.

    See The filter-dhcp-options hook documentation for more details.

  Custom interface options

comment
    Optional. String or a YAML text block with a comment that will be added to a given interface configuration file.

comment4
    Optional. String or a YAML text block with a comment that will be added to a given interface configuration file near the IPv4 section.

comment6
    Optional. String or a YAML text block with a comment that will be added to a given interface configuration file near the IPv6 section.

options
    Optional. String or a YAML text block with custom options for the network interface. It will be added after the IPv4 section, unless IPv4 support is disabled in which case it will be added after IPv6 section. If this parameter is specified, autogenerated configuration for specific interface types will be disabled.

options4
    Optional. String or a YAML text block with custom options added to the IPv4 section of the network interface configuration. If this parameter is present, autogenerated configuration for specific interface types will be disabled.

options6
    Optional. String or a YAML text block with custom options added to the IPv6 section of the network interface configuration. If this parameter is present, autogenerated configuration for specific interface types will be disabled.

add_options
    Optional. String or a YAML text block with custom options for the network interface. It will be added after the IPv4 section, unless IPv4 support is disabled in which case it will be added after IPv6 section. You can use this parameter to add options to the autogenerated configuration, which will be still included.

add_options4
    Optional. String or a YAML text block with custom options added to the IPv4 section of the network interface configuration. You can use this parameter to add options to the autogenerated configuration, which will be still included.

add_options6
    Optional. String or a YAML text block with custom options added to the IPv6 section of the network interface configuration. You can use this parameter to add options to the autogenerated configuration, which will be still included.

debug
    Optional, boolean. If True, the role will add commented out debug information to the generated interface configuration file. It can be used to check what the role thinks the interface configuration should be like.

  Firewall parameters

forward
    Optional, boolean. If absent and an interface is a bridge, or present and True, the role will generate configuration for the debops.ferm and the debops.sysctl roles to enable packet forwarding for a given interface.

forward_ipv6
    Optional, boolean. Only makes sense with the forward parameter present. By default the role will enable forwarding on IPv6 networks, you can use this parameter to disable it by setting it to False.

forward_ipv4
    Optional, boolean. Only makes sense with the forward parameter present. By default the role will enable forwarding on IPv4 networks, you can use this parameter to disable it by setting it to False.

accept_ra
    Optional, by default not defined. If 0, the SLAAC Router Advertisements on IPv6 networks will be ignored by this interface. If 1, this interface will accept the SLAAC Router Advertisements when forwarding is disabled, ignore when forwarding is enabled. If 2, SLAAC Router Advertisements received on this interface will be accepted even when forwarding is enabled.

forward_interface_ferm_rule_enabled
    Optional, boolean. Should a Firewall rule be configured which matches new connection attempts entering the interface? If disabled using False, the default Firewall policy will apply. Defaults to True.

forward_interface_ferm_rule
    Optional, string. Default action or any custom ferm configuration. Defaults to ACCEPT.

forward_outerface_ferm_rule_enabled
    Optional, boolean. Should a Firewall rule be configured which matches new connection attempts exiting the interface? If disabled using False, the default Firewall policy will apply. Defaults to True.

forward_outerface_ferm_rule
    Optional, string. Default action or any custom ferm configuration. Defaults to ACCEPT.

nat Optional, boolean. If present and True, the firewall configuration for a given interface (usually a bridge) will include the IPv4 NAT rules. The default gateway IPv4 address will be used in the Source NAT configuration.

nat_masquerade
    Optional, boolean. If present and True, the role will use the MASQUERADE rule in the firewall configuration instead of the SNAT rule. This is useful when the host has no fixed default IP address, for example on a laptop. Defaults to ifupdown__default_nat_masquerade.

nat_snat_address
    Optional. Specify the SNAT IPv4 address to use for the NAT on a given bridge. If not specified, the role will use the host's default IPv4 address as the SNAT IP address.

nat_snat_interface
    Optional. If specified, the IPv4 address on a given network interface will be used to generate the SNAT firewall rules.

  Configuration examples

The examples below are based on the Debian Network Configuration <https://wiki.debian.org/NetworkConfiguration> and Debian IPv6 configuration <https://wiki.debian.org/DebianIPv6> pages to make comparison between /etc/network/interfaces configuration and debops.ifupdown configuration easier. Examples are verbose to reflect the examples from the wiki page, but some of the parameters can be omitted to let the role autogenerate them.

Keep in mind that the auto parameter, included in the examples for completeness, usually should be avoided in the newer OS releases (Jessie+, Trusty+) on systemd-based hosts. This is done so that the additional processes related to a given network interfaces are put in their own ifup@.service cgroup instead of being grouped together under the networking.service cgroup.

Use DHCP and SLAAC to automatically configure the network interface <https://wiki.debian.org/NetworkConfiguration#Using_DHCP_to_automatically_configure_the_interface>:

ifupdown__interfaces:
  'eth0':
    auto: True
    allow: 'hotplug'
    inet: 'dhcp'
    inet6: 'auto'

Configure the network interface manually <https://wiki.debian.org/NetworkConfiguration#Configuring_the_interface_manually> using static IPv4 and IPv6 configuration:

ifupdown__interfaces:
  'static-eth0':
    iface: 'eth0'
    auto: True
    inet: 'static'
    inet6: 'static'
    addresses: [ '192.0.2.7/24', '2001:db8::c0ca:1eaf/64' ]
    gateways:  [ '192.0.2.254', '2001:db8::1ead:ed:beef' ]

Configure an interface without an IP address <https://wiki.debian.org/NetworkConfiguration#Bringing_up_an_interface_without_an_IP_address>:

ifupdown__interfaces:
  'eth0':
    inet: 'manual'
    options: |
      pre-up ifconfig $IFACE up
      post-down ifconfig $IFACE down
 'eth0.99':
   inet: 'manual'
   options: |
     post-up ifconfig $IFACE up
     pre-down ifconfig $IFACE down

Configure DNS nameservers and search domains <https://wiki.debian.org/NetworkConfiguration#The_resolvconf_program> with an autogenerated default interface:

ifupdown__interfaces:
  'external':
    iface: '{{ ifupdown__external_interface }}'
    inet: 'dhcp'
    dns_nameservers: [ '12.34.56.78', '12.34.56.79' ]
    dns_search: 'example.com'

Configure static bridge <https://wiki.debian.org/NetworkConfiguration#Bridging> between two Ethernet interfaces:

ifupdown__interfaces:
  'eth0':
    inet: 'manual'
    inet6: False
  'eth1':
    inet: 'manual'
    inet6: False
  'br0':
    inet: 'static'
    address: '10.10.0.15/24'
    gateway: '10.10.0.1'
    bridge_ports: [ 'eth0', 'eth1' ]
    bridge_stp: 'on'

Create a static VLAN interface on an Ethernet interface <https://wiki.debian.org/NetworkConfiguration#Network_init_script_config>:

ifupdown__interfaces:
  'eth0.222':
    auto: True
    inet: 'static'
    address: '10.10.10.1/24'
    vlan_raw_device: 'eth0'

Connect a bridge to a VLAN on an Ethernet interface <https://wiki.debian.org/NetworkConfiguration#Caveats_when_using_bridging_and_vlan>:

ifupdown__interfaces:
  'eth0':
    auto: True
    inet: 'static'
    inet6: False
    address: '192.168.1.1/24'
  'eth0.110':
    inet: 'manual'
    vlan_device: 'eth0'
  'br0':
    auto: True
    inet: 'static'
    address: '192.168.110.1/24'
    bridge_ports: 'eth0.110'
    bridge_stp: 'on'
    bridge_maxwait: '10'

Create a bonded interface <https://wiki.debian.org/NetworkConfiguration#A.2Fetc.2Fnetwork.2Finterfaces> using two Ethernet interfaces and attached VLANs:

ifupdown__interfaces:
  'bond0':
    auto: True
    inet: 'manual'
    slaves: [ 'eth1', 'eth0' ]
    options: |
      up ifconfig bond0 0.0.0.0 up
  'vlan10':
    auto: True
    inet: 'static'
    address: '10.10.10.12/16'
    gateway: '10.10.0.1'
    vlan_raw_device: 'bond0'
    dns_nameservers: '10.10.0.2'
    dns_search: 'hup.hu'
  'vlan20':
    auto: True
    inet: 'static'
    address: '10.20.10.12/16'
    vlan_raw_device: 'bond0'
  'vlan30':
    auto: True
    inet: 'static'
    address: '10.30.10.12/16'
    vlan_raw_device: 'bond0'

Create advanced bonding configuration <https://wiki.debian.org/NetworkConfiguration#How_to_set_the_MTU_.28Max_transfer_unit_.2F_packet_size.29_with_VLANS_over_a_bonded__interface> with MTU and other parameters:

ifupdown__interfaces:
  'bond0':
    auto: True
    inet: 'manual'
    bond_slaves: [ 'eth0', 'eth1' ]
    bond_mode: '4'
    bond_miimon: '100'
    bond_downdelay: '200'
    bond_updelay: '200'
    bond_lacp_rate: '1'
    bond_xmit_hash_policy: 'layer2+3'
    options: |
      up ifconfig lacptrunk0 0.0.0.0 up
      post-up ifconfig eth0 mtu 9000 && ifconfig eth1 mtu 9000 && ifconfig bond0 mtu 9000
  'vlan101':
    auto: True
    inet: 'static'
    address: '10.101.60.123/24'
    gateway: '10.155.60.1'
    vlan_device: 'bond0'
  'vlan151':
    auto: True
    inet: 'static'
    address: '192.168.1.1/24'
    vlan_device: 'bond0'

Configure multiple IP addresses on an interface <https://wiki.debian.org/NetworkConfiguration#iproute2_method> using the "manual approach" method:

ifupdown__interfaces:
  'eth0':
    allow: [ 'auto', 'hotplug' ]
    addresses:
      - '192.168.1.42/24'
      - '192.168.1.43/24'
      - '192.168.1.44/24'
      - '10.10.10.14/24'
    gateway: '192.168.1.1'

Configure a 6to4 tunnel <https://wiki.debian.org/DebianIPv6#IPv6_6to4_Configuration> using your public, default IPv4 address (role will autogenerate most of the required configuration):

ifupdown__interfaces:
  '6to4': {}

Configure a restricted bridge network:

ifupdown__interfaces:
  'br2':
    type: 'bridge'
    inet6: 'static'
    inet: 'static'
    nat: True
    forward_interface_ferm_rule: 'outerface (br0 br2) ACCEPT'
    forward_outerface_ferm_rule_enabled: False
    addresses:
      - '2001:db8::23/64'
      - '192.0.2.23/24'

Hosts attached to the br2 bridge are allowed to talk to each other. Additionally, the hosts can initiate connections to the outside world thought br0. No connections can be initiated from the outside world to the hosts behind br2. SNAT is used for IPv4. For IPv6 it is expected that the prefix is routed to the host so that the host can forward packets to br2.

  ifupdown__custom_files

The ifupdown__*_custom_files list variables can be used to place custom scripts or other configuration files on the remote hosts needed for network configuration (for example mapping scripts). Each list element is a YAML dictionary with specific parameters:

dest or path
    Required. Absolute path to the destination file on remote host.

src Optional. Path to the source file on the Ansible Controller which will be copied to the remote host. Shouldn't be used with the content parameter.

content
    Optional. An YAML text block with the file contents which should be put in the specified destination file on the remote host. Shouldn't be used with the src parameter.

owner
    Optional. Specify the UNIX user account which will be an owner of the file. If not specified, root will be the owner.

group
    Optional. Specify the UNIX group which will be the primary group of the file. If not specified, root will be the primary group.

mode
    Optional. Specify the file mode which should be set for a given file. If not specified, 0644 mode will be set.

force
    Optional, boolean. If not specified or True, the role will ensure that the file contents are up to date on each run. If False, existing files won't be changed if they are different.

  Examples

Create an interface mapping script:

ifupdown__custom_files:
  - dest: '/usr/local/lib/ifupdown-map-wlan.sh'
    owner: 'root'
    group: 'root'
    mode: '0755'
    content: |
      #!/bin/sh
      # Script contents ...
      exit 0

AUTHOR
Maciej Delmanowski, Robin Schneider

COPYRIGHT
2014-2022, Maciej Delmanowski, Nick Janetakis, Robin Schneider and others