net_interface

Table of Contents

1. Overview
2. Module Description - What the module does and why it is useful
3. Usage - Configuration options and additional functionality
   • Static IPv4
   • DHCP IPv4
   • Disabled IPv4
   • Auto IPv6
   • Static IPv6
   • DHCP IPv6
   • Disabled IPv6
4. Reference - An under-the-hood peek at what the module is doing and how
   • Parameters
5. Limitations - OS compatibility, etc.
6. Development - Guide for contributing to the module

Overview

This puppet module manages network interface settings for config file to be placed under /etc/network/interfaces.d/IFNAME on a Debian system. This was specifically written to handle multiple addresses per interface as well as support IPv6 settings.

Module Description

Any declaration of net_interface class will cause this puppet module to take control of the file /etc/network/interfaces.d/IFNAME where IFNAME is specified with the ifname parameter to the class. Thus, ifname is a REQUIRED parameter.

The module allows for static, or DHCP-based configuration for both IPv4 and IPv6. Static configs allow for multiple addresses to be assigned, as well as defining additional static routes. Either IPv4 or IPv6 can be set as "disabled" which essentially leaves that family unconfigured for the interface. If BOTH IPv4 and IPv6 are set as "disabled", the interface is left disabled entirely.

The module actions are as follows: the interface is brought down using ifdown IFNAME, the config file is modified as specified, and the interface is brought up (if applicable) using ifup IFNAME. If the definitions being applied cause no change in the config file, then no further action is performed on the interface.

Usage

The ifname parameter is required. Any of the IPv4 methods can be combined with any of the IPv6 methods, but you can NOT specify more than one method for either family.

Static IPv4

For static IPv4 configuration, specify at least one address/mask to assign. You can optionally specify default gateway, MTU, or metric.

The routes4 parameter can be used to specify a list of static routes and their next-hops to be added when the interface is brought up.

class { 'net_interface':
  ifname   => 'eth0',
  static4  => { addrs   => [ '1.2.3.4/24', ],
                gateway => '1.2.3.254',
                mtu     => 1500,
              },
  disable6 => true,
}

class { 'net_interface':
  ifname   => 'eth0',
  static4  => { addrs   => [ '172.17.205.2/16',
                             '5.6.7.8/16', ],
                gateway => '172.17.214.1',
              },
  routes4  => { '10.11.12.0/24'  => '172.17.214.6',
                '134.141.0.0/16' => '172.17.99.99', },
  disable6 => true,
}

DHCP IPv4

When specifying DHCP for IPv4, options include metric, preferred hostname, lease time, and vendor and client strings.

class { 'net_interface':
  ifname   => 'eth0',
  dhcp4    => {},  # Use DHCPv4 - no extra options
  disable6 => true,
}

class { 'net_interface':
  ifname   => 'eth0',
  dhcp4    => { hostname  => 'hal9000',
                leasetime => 3600, },
  disable6 => true,
}

Disabled IPv4

If IPv4 is set as "disabled", the v4 address family is left unconfigured. If both address families are set "disabled", the interface as a whole is left administratively down.

class { 'net_interface':
  ifname   => 'eth0',
  disable4 => true,
  disable6 => true,
}

Auto IPv6

This is SLAAC (stateless address auto configuration). There are options to enable privacy extensions, adjust acceptance of router advertisements, and use stateless DHCP to acquire other config attributes besides the address assignment.

class { 'net_interface':
  ifname  => 'eth0',
  dhcp4   => {},
  auto6   => {},   # Use auto IPv6 with no added options
}

class { 'net_interface':
  ifname  => 'eth0',
  dhcp4   => {},
  auto6   => { privext   => 'prefer',
               accept_ra => 'on', },
}

Static IPv6

For static IPv6 configuration, specify at least one address/mask to assign. You can optionally specify default gateway or MTU. Also there are options for privacy extensions and controlling how routing advertisements are accepted.

The routes6 parameter can be used to specify a list of static routes and their next-hops to be added when the interface is brought up.

class { 'net_interface':
  ifname  => 'eth0',
  dhcp4   => {},
  static6 => { addrs   => [ '2002:c000:203::1/64',
               gateway => '2002:c000:203::ff',
               privext => 'prefer' },
}

class { 'net_interface':
  ifname   => 'eth0',
  static6  => { addrs     => [ '2605:2700:0:3::4444:630e/64',
                               '2605:2700:1:f00d::1/64',
                               '2605:2700:1:f00d::beef/64', ],
                gateway   => '2605:2700:0:3::1',
                mtu       => 2048,
              },
  routes6  => { '6:7:8::9/32'     => '2605:2700:0:3::1',
                'a:b:c::d:e:f/93' => '2605:2700:0:3::1', },
  disable4 => true,
}

DHCP IPv6

This is Stateful DHCPv6. There's an added option to control how routing advertisements are accepted.

class { 'net_interface':
  ifname   => 'eth0',
  disable4 => true,
  dhcp6    => {},  # Use DHCPv6 - no extra options
}

class { 'net_interface':
  ifname => 'eth0',
  dhcp6  => { accept_ra => 'off', },
}

Disabled IPv6

If IPv6 is set as "disabled", the v6 address family is left unconfigured. This does not prevent the usual link-local address from being assigned! So, an interface with v6 "disabled" will likely still have a v6 address in the end. Unless...

If both address families are set "disabled", the interface as a whole is left administratively down.

class { 'net_interface':
  ifname   => 'eth0',
  disable4 => true,
  disable6 => true,
}

Reference

Note that several of the high-level parameters are hashes with certain keys supported as outlined.

Parameters

• ifname - (string) interface name (mandatory)
• dhcp4 - (hash) use DHCP method for IPv4 address family; valid option keys for "key => value" pairs:
  • client - (string) client identifier
  • hostname - (string) requested hostname
  • leasetime - (int) preferred lease time in seconds
  • metric - (int) metric for added routes
  • vendor - (string) vendor class identifier
• disable4 - (bool) disable IPv4 address family (default: false) - as a boolean, be sure to pass true not the string 'true'
• static4 - (hash) use static address assignment for IPv4 address family; valid option keys for "key => value" pairs:
  • addrs - (string list) address/maskbits ('A.B.C.D/M') strings to assign to interface (mandatory at least one)
  • gateway - (string) default gateway ('A.B.C.D')
  • metric - (int) metric for added routes
  • mtu - (int) max transmissable unit size
• routes4 - (hash list) a list of "route_prefix => next_hop" ('A.B.C.0/24' => 'W.X.Y.Z') pairs defining additional IPv4 static routes to be set
• auto6 - (hash) use SLAAC to set the address; valid option keys for "key => value" pairs:
  • privext - (enum) use RFC4941 privacy extensions; accepted values: 'off', 'assign', 'prefer' (default: 'off')
  • accept_ra - (enum) accept router advertisements; accepted values: 'off', 'on', 'on+forwarding' (default: 'on+forwarding')
  • dhcp - (bool) use stateless DHCPv6 (default: false)
• dhcp6 - (hash) use DHCP method for IPv6 address family; valid option keys for "key => value" pairs:
  • accept_ra - (enum) accept router advertisements; accepted values: 'off', 'on', 'on+forwarding' (default: 'on')
• disable6 - (bool) disable IPv6 address family (default: false) - as a boolean, be sure to pass true not the string 'true'
• static6 - (hash) use static address assignment for IPv6 address family; valid option keys for "key => value" pairs:
  • addrs - (string list) address/maskbits ('AA:BB::0099/M') strings to assign to interface (mandatory at least one)
  • gateway - (string) default gateway ('AA:BB::0C:0D')
  • mtu - (int) max transmissable unit size
  • privext - (enum) use RFC4941 privacy extensions; accepted values: 'off', 'assign', 'prefer' (default: 'off')
  • accept_ra - (enum) accept router advertisements; accepted values: 'off', 'on', 'on+forwarding' (default: 'on+forwarding')
• routes6 - (hash list) a list of "route_prefix => next_hop" ('AA:BB::9:0/64' => '11::22:03:56') pairs defining additional IPv6 static routes to be set

Limitations

This is where you list OS compatibility, version compatibility, etc.

Development

Since your module is awesome, other users will want to play with it. Let them know what the ground rules for contributing are.