jflorian/doubledog-network

A Puppet module to manage network services and interfaces

network

Table of Contents

1. Description
2. Setup - The basics of getting started with network
   • What network affects
   • Setup requirements
   • Beginning with network
3. Usage - Configuration options and additional functionality
4. Reference - An under-the-hood peek at what the module is doing and how
   • Classes
   • Defined types
   • Data types
   • Facts
5. Limitations - OS compatibility, etc.
6. Development - Guide for contributing to the module

Description

This module lets you manage network.

Setup

What network Affects

Setup Requirements

Beginning with network

Usage

Reference

Classes:

• network
• network::wireless

Defined types:

• network::interface

Data types:

• Network::Vlan_id
• Network::Vlan_id

Facts:

Classes

network class

This class manages a host's network configuration.

domain (required)

Name of the network domain.

service (required)

Use 'legacy' (default) or 'nm' (NetworkManager) service.

enable

The selected service is to be started at boot. Either true (default) or false.

ensure

The selected service is to be 'running' (default) or 'stopped'. Alternatively, a Boolean value may also be used with true equivalent to 'running' and false equivalent to 'stopped'.

interfaces

A hash whose keys are interface names and whose values are hashes comprising the same parameters you would otherwise pass to the network::interface defined type.

legacy_packages

An array of package names needed for a legacy network installation. The default should be correct for supported platforms.

legacy_service

The name of the legacy network service. The default should be correct for supported platforms.

legacy_service_provider

The name of the Puppet provider to manage the legacy network service. The default should be correct for supported platforms.

manager_packages

An array of package names needed for a NetworkManager installation. The default should be correct for supported platforms.

manager_service

The name of the NetworkManager service. The default should be correct for supported platforms.

name_servers

Array of IP address strings that provide DNS address resolution. Typically not required for hosts with interfaces configured exclusively by DHCP. If set, this will cause the name resolver configuration to be managed.

unmanaged

Array of strings stating which network interface devices, if any, that NetworkManager is to leave unmanaged. The format for each is described in the section called "Device List Format" of NetworkManager.conf(5). This is ignored if service is 'legacy'.

network::wireless class

This class manages the packages required for wireless networking. It is included, as needed, by the network class.

packages

An array of package names needed for a wireless network installation. The default should be correct for supported platforms.

Defined types

network::interface defined type

This defined type manages a network interface configuration.

namevar (required)

An arbitrary identifier for the instance unless the device parameter is not set in which case this must provide the value normally set with the device parameter.

template (required)

The particular template to be used. Must be one of 'dhcp', 'dhcp-bridge', 'static', 'static-bridge' or 'wireless'. The 'wireless' template assumes a DHCP configuration and is only supported when $network::service is 'nm' (NetworkManager).

ensure

Instance is to be 'present' (default) or 'absent'.

bridge

Name of the associated bridge interface, if any. Ignored when template is one of 'dhcp-bridge', 'static-bridge' or 'wireless'.

country

Country code for CRDA when template is 'wireless'. Ignored for all other templates.

device

Name of the device interface, e.g., 'eth0' or 'wlan0'. This may be used in place of namevar if it's beneficial to give namevar an arbitrary value.

essid

Extended Service Set Identification (ESSID) of the wireless network. Required when template is 'wireless' and ignored for all others.

eth_offload

Any device-specific options supported by ethtool's -K option expressed as a simple string passed along unmodified. E.g., 'gso off'.

gateway

The default route IP address to be assigned to the interface. Recommended when template is 'static' or 'static-bridge' and ignored for all others.

ip_address

The IP address to be assigned to the interface. Required when template is 'static' or 'static-bridge'. Optional when template is 'dhcp' (to allow both a dynamic and static addresses concurrently). Ignored for all other values.

key_mgmt

Key management method for wireless encryption. Must be one of 'WPA-PSK' (default) or ???. Required when template is 'wireless' and ignored for all others.

mac_address

The MAC address to be assigned to the interface. This is not used for identifying/matching a physical interface but rather to override what the manufacturer assigned.

metric

Metric for the default route specified by gateway. The default is whatever the iproute2 package assigns, usually (always?) 100.

mode

Wireless mode. Must be one of 'Managed' (default, also known as infrastructure mode) or ???. Required when template is 'wireless' and ignored for all others.

netmask

The network mask for this interface. Required when template is 'static' or 'static-bridge'. Optional when template is 'dhcp' (to allow both a dynamic and static addresses concurrently). Ignored for all other values.

peer_dns

Use the name servers provided by DHCP? Either true (default) or false. Ignored when template is 'static' or 'static-bridge'.

peer_ntp

Use the time servers provided by DHCP? Either true (default) or false. Ignored when template is 'static' or 'static-bridge'.

persistent_dhcp

Should the DHCP client persist attempting to gain a lease if it encounters continual failure? Either true (default) or false. Ignored when template is 'static' or 'static-bridge'.

psk

Pre-shared key for wireless encryption. Required when template is 'wireless' and ignored for all others.

routes

Static routes for this interface expressed as a hash whose keys are arbitrary and may be used to describe each route. The corresponding value for each such key must be another hash whose keys must include 'address' and 'netmask' with strings providing the appropriate values to define the route. This same hash may also include gateway, metric and options to further define the static route. The default is to have no static routes.

stp

Enable the Spanning Tree Protocol (STP)? Either true (default) or false. Ignored unless template is 'static-bridge'.

vlan

If set with a VLAN ID, this interface will tag all outbound packets with this ID and only accept packets tagged with this ID. Valid IDs range from 1 to 4094.

This alone does not affect the name of the interface so it is necessary to make the tagged interface distinct from the base interface. One common convention is to set namevar so that its the base interface name followed by a dot followed by the VLAN ID, e.g., 'eth0.123'.

Data types

Network::Template data type

Matches acceptable values for the template parameter of the network::interface defined type.

Network::Vlan_id data type

Matches acceptable values for a VLAN ID, specifically a positive integer no less than 1 and no greater than 4094. This also accepts a string so long as the value matches the same restrictions.

Facts

Limitations

Tested on modern Fedora and CentOS releases, but likely to work on any Red Hat variant. Adaptations for other operating systems should be trivial as this module follows the data-in-module paradigm. See data/common.yaml for the most likely obstructions. If "one size can't fit all", the value should be moved from data/common.yaml to data/os/%{facts.os.name}.yaml instead. See hiera.yaml for how this is handled.

Development

Contributions are welcome via pull requests. All code should generally be compliant with puppet-lint.