debnet

Table of Contents

  1. Overview
  2. Module Description - What the module does
  3. Setup - Basic usage of module debnet
  4. Advanced configuration methods
  5. Feature helpers

Overview

This module constructs the /etc/network/interfaces file on Debian based Linux distributions and enables an easy configuration of sophisticated network setups, such as bridges and bonding configurations.

Module Description

This module lets you use many debnet::iface resourses for setting up network interfaces.

Setup

Declaring a single resource of this module will cause debnet to take control over the file /etc/network/interfaces which than will contain stanzas generated by the module only. Every declaration of debnet::iface resources will create a corresponding stanza in /etc/network/interfaces.

Beginning with the module

To start with the debnet module the node can simply declare resources. Many nodes need at least a loopback interface which might look like:

debnet::iface::loopback { 'lo': }

Many other declaration may follow. Each of which will create an interface configuration. There are specialized resources available for many kind of configuration tasks, however, you may also use the simple debnet::iface resource to create generic interface stanzas. Be aware, that the specialized resources do some more validation, which makes the configuration less error prone.

Available configuration methods

The resource debnet::iface implements different configuration methods also available for the interfaces(5) stanzas. Currently supported methods are:

  • loopback
  • static
  • dhcp
  • manual

Configuring the loopback interface

Currently there is only a single way to create a configuration on the loopback interface.

debnet::iface::loopback { 'lo': }

Static IPv4 interface configuration

For a static IP configuration the attributes address and netmask are mandatory. Attributes broadcast, gateway, pointopoint, hwaddress, mtu and scope are optional.

debnet::iface::static { 'eth0':
  address => '192.168.0.10',
  netmask => 24,
  gateway => '192.168.0.1',
}

Available attributes:

  • ifname - (string) iface name (default: title)
  • address - (dotted-quad) static address (mandatory)
  • netmask - (int or dotted-quad) netmask (mandatory)
  • broadcast - (dotted-quad) broadcast address (optional)
  • metric - (int) metric for routing protocols
  • gateway - (dotted-quad) gateway to set default route
  • pointopoint - (dotted-quad) point-to-point address
  • hwaddress - (macaddress) hardware address to override with
  • mtu - (int) interface MTU
  • scope - (string) address scope

DHCP configuration

Configuring an interface by dhcp is enabled through method set to according. Optional attributes hostname, metric, leasetime, vendor, client and hwaddress may be set.

debnet::iface::dhcp { 'eth0': }

Available attributes:

  • ifname - (string) iface name (default: $title)
  • metric - (int) metric for routing protocols
  • hwaddress - (macaddress) hardware address to override with (optional)
  • hostname - (string) hostname to send with DHCP REQUEST (optional)
  • leasetime - (int) leasetime to request (optional)
  • vendor - (string) vendor id to send with request (optional)
  • client - (string) client id to send with request (optional)

Common attributes

Many resource types have some common attributes. These are:

  • auto - (bool) allow auto-bring-up interface (default: true)
  • allows - (array) allows-* features (default: [])
  • family - (string) only inet supported (default: inet)
  • order - (int) ordering of the resource (default: 0)

Advanced configuration methods

The module also gives a convenient way to declare more sofisticated network configurations like bonding of multiple interfaces or creating bridge devices. To leaverage from these it is necessary to learn how raw configuration of interfaces work by usage of debnet::iface type resource. This will allow the declaration of bonded interfaces through debnet::iface::bond and bridges through debnet::iface::bridge.

Raw interface configuration

Using the specialised resources is convenient but not feasable in some circumstances. Therefore it might be necessery, however, to create configurations using the debnet::iface generic resource type.

The above examples can be alternatively configured by using debnet::iface type as follows:

Loopback interface:

debnet::iface { 'lo':
  method => 'loopback',
}

Static interface:

debnet::iface { 'eth0':
  method  => 'static',
  address => '192.168.0.10',
  netmask => 24,
  gateway => '192.168.0.1',
}

DHCP configuration:

debnet::iface { 'eth0':
  method => 'dhcp',
}

Bridge configuration

Configuring a software bridge is enabled by declaring a resource of type debnet::iface::bridge. Mandatory attribute is the method of configuration of the bridge interface. Depending on the method, the mandatory attributes of the choosen method are also mandatory for the bridge resource. Optional attributes are ports, stp, prio, fwdelay and hello.

An example for configuring a bridge is:

debnet::iface::bridge { 'br0':
  ports  => ['eth1','eth2'],
  stp    => true,
  method => 'manual',
}

The debnet::iface::bridge resource is defining interfaces for many ports of the bridge with manual configuration to inhibit multiple use of the same interface.

Available attributes:

  • method - (string) interface configuration method (mandatory)
  • ifname - (string) iface name (default: $title)
  • ports - (array) ports to be added (default: [])
  • stp - (bool) enable IEEE 802.1d spanning tree protocol (default: false)
  • prio - (int) STP bridge priority (optional)
  • fwdelay - (int) forward delay (optional)
  • hello - (int) hello timing (optional)
  • maxage - (int) max BPDU age (optional)
  • maxwait - (int) max seconds to wait for ports to come up (optional)

Bonding configuration

The module allows to bond multiple interfaces together by configuring a linux bonding device.

debnet::iface::bond { 'bond0':
  ports => ['eth1', 'eth2'],
  method => 'manual',
}

Supported bonding modes are: balance-rr, active-backup, balance-xor, broadcast, 802.3ad, balance-tlb, balance-alb.

Available attributes:

  • ports - (array) slave interfaces (mandatory)
  • mode - (string) bonding mode (default: active-backup)
  • miimon - (int) mii monitor timing (default: 100)
  • use_carrier - (bool) enable carrier sense (default: true)
  • updelay - (int) setting the updelay timer (optional)
  • downdelay - (int) setting the downdelay timer (optional)

Such a configuration will create the interfaces(5) stanzas for many ports and the bonding device. The array in argument ports must have at least one item, and the first item will be configured as bond-primary.

Using Up and down command hooks

In many resources of the module you may use attributes ups, downs, pre-ups and post-downs declaring arrays of commands which will be called on the specific events. By declaring the attribute aux_ops with a hash, it is possilble to add auxiliary options to the interface stanza, which will be generated by using the key as option name and the value to the key as value. This obviously has the limitation of having every option name ones, however, the most important case this is useful, the up and down hooks can be handled through ups, downs, pre-ups and post-downs attributes.

Many debnet resources allow to add commands to the usual up/down hooks. The attributes pre_ups, ups, downs and post_downs are available for many resources. Each of which are typed as array and many elements will be added in order as pre-up, up, down or post-down options, respectively. High care must be taken while using these attributes, since the module does not do any kind of checks.

debnet::iface::dhcp { 'eth0':
  ups   => ['echo "eth0 is up"'],
  downs => ['echo "eth0 is going down"']
}

Feature helpers

The module provides feature helpers to enable sofisticated configuration features to be added easily.

Queue length

If the setting of the txqueuelen feature of ethernet interfaces needs to done, the attribute tx_queue can be added to any resource type other than loopback. The helper adds an up command to set the transmit queue of the interface. In case of types bond and bridge, the up command is applied to the corresponding slave interfaces.

debnet::iface::dhcp { 'eth0':
  tx_queue => 50,
}

Available attributes:

  • tx_queue - (int) length of the transmit queue (optional)

Static routes

Static routes can be added to any resource type which is configuring layer-3 of an interface. Declaring the routes attribute as a hash which is mapping gateway addresses (values) to specific destinations (keys). Destinations are declared by a dotted-quad and prefix length, the gateway addresses must be dotted-quads. Multiple routes may be declared. Many routes will be added as up and down commands to the containing interface.

debnet::iface::static { 'eth0':
  address => '192.168.0.10',
  netmask => 24,
  gateway => '192.168.0.1',
  routes  => {
    '172.16.0.0/12' => '192.168.0.2',
    '10.0.0.0/8'    => '192.168.0.3',
  },
}

Available attributes:

  • routes - (hash) maps routes to their gateways (optional)

DNS resolver settings

Many Debian installations make use of the resolvconf tools to setup the local DNS resolver dynamically. Feature helpers dns_nameservers and dns_search enables to add presets to be passed to resolvconf scripts when an interface is brought up.

debnet::iface::static { 'eth0':
  address         => '192.168.0.10',
  netmask         => 24,
  gateway         => '192.168.0.1',
  dns_search      => ['example.org', 'example.com'],
  dns_nameservers => ['192.168.0.2', '192.168.0.3'],
}

Available attributes:

  • dns_search - (array) DNS search list (optional)
  • dns_nameservers - (array) DNS nameserver list (optional)