debnet

####Table of Contents

1. Overview
2. Module Description - What the module does
3. Setup - Basic usage of module debnet
   • Beginning with the module
   • Available configuration methods
   • Configuring the loopback interface
   • Static IPv4 configuration
   • DHCP configuration
   • Common attributes
4. Advanced configuration methods
   • Raw interface configuration
   • Bridge configuration
   • Bonding configuration
   • Using Up and down command hooks
5. Feature helpers
   • Queue length
   • Static routes
   • DNS resolver settings
6. Auxiliary support
   • wvdial

##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.

##Donate If you like this project feel free to support via Bitcoin

##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
• wvdial

###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.

To simply bridge two devices without bringing them up on layer-3, e.g.:

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

The debnet::iface::bridge resource is defining interfaces for each port 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.

The following example will bond devices eth1 and eth2 as active-passive slaves of bond0, and will bring up the layer-3 config with static address and gateway settings.

debnet::iface::bond { 'bond0':
  ports   => ['eth1', 'eth2'],
  method  => 'static',
  address => '192.168.0.10',
  netmask => 24,
  gateway => '192.168.0.1',
}

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)

##Auxiliary support ###WVDial Have a look to examples/support/wvdial.pp for an example.