Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/rtib/tib-debnet

Puppet module to manage Debian network interfaces configuration file
https://github.com/rtib/tib-debnet

Last synced: 6 months ago
JSON representation

Puppet module to manage Debian network interfaces configuration file

Awesome Lists containing this project

README 

          
# debnet #

[![Build Status](https://travis-ci.org/rtib/tib-debnet.svg?branch=master)](https://travis-ci.org/rtib/tib-debnet)



####Table of Contents



1. [Overview](#overview)

2. [Module Description - What the module does](#module-description)

3. [Setup - Basic usage of module debnet](#setup)

    * [Beginning with the module](#beginning-with-the-module)

    * [Available configuration methods](#available-configuration-methods)

    * [Configuring the loopback interface](#configuring-the-loopback-interface)

    * [Static IPv4 configuration](#static-ipv4-interface-configuration)

    * [DHCP configuration](#dhcp-configuration)

    * [Common attributes](#common-attributes)

4. [Advanced configuration methods](#advanced-configuration-methods)

    * [Raw interface configuration](#Raw-interface-configuration)

    * [Bridge configuration](#bridge-configuration)

    * [Bonding configuration](#bonding-configuration)

    * [Using Up and down command hooks](#using-up-and-down-command-hooks)

5. [Feature helpers](#feature-helpers)

    * [Queue length](#queue-length)

    * [Static routes](#static-routes)

    * [DNS resolver settings](#dns-resolver-settings)

6. [Auxiliary support](#auxiliary-support)

    * [wvdial](#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

[![donate.png](donate.png)](bitcoin:1GhfvVwTxEQXCok7eECCoAf88LVHPFiAe3?label=donate%3A%20PuppetForge%20debnet%20module)



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



```puppet

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.



```puppet

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.



```puppet

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.



```puppet

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:

```puppet

debnet::iface { 'lo':

  method => 'loopback',

}

```



Static interface:

```puppet

debnet::iface { 'eth0':

  method  => 'static',

  address => '192.168.0.10',

  netmask => 24,

  gateway => '192.168.0.1',

}

```

DHCP configuration:

```puppet

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

```puppet

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.

```puppet

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.



```puppet

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.



```puppet

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.



```puppet

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.



```puppet

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.