Puppet BSD

A Puppet module for managing aspects of BSD. Currently supported are FreeBSD and OpenBSD. In here will be various facts, functions and classes for tuning and configuring a system.

It is intended that Puppet users of this code use only the classes and facts in their manifests. The rest of the code here is simply to support the interface supplied by the manifests. Implementing the functions directly is not advised, as the implementation may shift over time as the module requires.

Dependencies

This module requires the 'ipaddress' ruby gem to be installed.

gem install ipaddress

or let Puppet take care:

package { 'ipaddress':
  ensure   => 'present',
  provider => 'gem',
}

Installation

The easiest way to install is to install from the forge.

puppet module install zleslie/bsd

Network

Network configuration is handled under the bsd::network name space. Under this space you will find classes available to configure basic network configuration items like gateways and static address, to more advanced topics like vlan(4) and carp(4) interfaces.

Ideally, this module should support any useful aspect of network configuration, including things like wireless (AP and client) and static routes.

Gateways

The gateway can be configured for both router and hosts.

host

To configure static addressing on a host, first you may wish to configure the gateway(s).

class { 'bsd::network':
  v4gateway => '10.0.0.1',
  v6gateway => 'fc00::',
}

router

To set the upstream gateway on a router system as well as turn on dual stack forwarding, use the following configuration.

class { 'bsd::network':
  v4gateway    => '1.1.1.1',
  v6gateway    => '2001:b:b::1',
  v4forwarding => true,
  v6forwarding => true,
}

Addressing

Once you have the gateway set, you may wish to set some interface addresses.

bsd::network::interface { 'em0':
  description => 'Primary Interface',
  addresses   => [ '10.0.0.2/24', 'fc00::b0b/64' ],
}

This will do the needful of setting the configuration for setting the interface address and gateway.

NOTE: This only sets the configuration, it does not currently set the running interfaces addresses.

Interface configuration order

Clonable interfaces might require other interfaces to be configured first. The bsd::network::interface defined type has a 'parents' parameter that can take a string or array of interface names, that in turn will be required to be configured before. Note that the parent interfaces are not required to be managed via Puppet.

Interfaces

Interface configurations are handled per interface type. Each supported type will have an implementation of the library through the user of functions and expose a manifest to the user for configuration.

vlan(4)

To create a vlan(4) interface and assign an address to it, use a manifest like the following.

bsd::network::interface::vlan { 'vlan100':
  id         => 100,
  device     => 'em0',
  address    => ['10.0.0.1/24'],
  raw_values => ['!/sbin/route add -net 10.10.10.0/24 10.10.0.254',],
}

It is sometimes desirable to create a VLAN interface without needing to set any interface addresses on it. In such a case, simply leave off the address, and specify the VLAN ID and the device to attach the VLAN to.

bsd::network::interface::vlan { 'vlan100':
  id      => 100,
  device  => 'em0',
}

carp(4)

The carp(4) device is supported through the bsd::network::interface::carp defined type. Carp interface preemption is handled via the bsd::network::carp class, and defaults to false. This class is automatically included, when a carp device is managed.

class { 'bsd::network::carp':
  preempt => true,
}

bsd::network::interface::carp { "carp0":
  id         => 1,
  address    => ['10.0.0.1/24'],
  carpdev    => 'em0',
  pass       => 'TopSecret',
  raw_values => ['!/sbin/route add -net 10.10.10.0/24 10.0.0.254',],
}

pfsync(4)

Closely related to carp(4) interfaces are the pfsync(4) interfaces. They are supported by bsd::network::interface::pfsync defined type.

bsd::network::interface::pfsync { "pfsync0":
  description => 'PF state sync interface',
  syncdev     => 'bge0',
  syncpeer    => '10.0.0.123',
  maxupd      => 128,
  defer       => false,
}

lagg(4) and trunk(4)

bsd::network::interface::trunk { "trunk0":
  interface => ['em0','em1],
  address   => ['10.0.0.1/24'],
}

vlan trunks

To configure a set of interfaces as a trunk passing multiple vlans, just leave the address off of the trunk(4) interface and use it as the device for the vlan(4) interface.

bsd::network::interface::trunk { "trunk0":
  interface => ['em0','em1'],
}

bsd::network::interface::vlan { "vlan10":
  id      => 10,
  address => ['10.0.10.1/24'],
  device  => 'trunk0',
}

bsd::network::interface::vlan { "vlan11":
  id         => 11,
  address    => ['10.0.11.1/24'],
  device     => 'trunk0',
  raw_values => ['!/sbin/route add -net 10.10.10.0/24 10.0.11.254',],
}

tun tunnel devices

The tun(4) device is supported directly through the bsd::network::interface defined type.

bsd::network::interface { 'tun0':
  raw_values => [
    'up',
    '!/usr/local/bin/openvpn --daemon'
  ]
}

gif tunnel devices

The gif(4) device is supported directly through the bsd::network::interface defined type. I.e. an IPv6 via IPv4 tunnel could look like:

bsd::network::interface { 'gif0':
  description => 'IPv6 in IPv4 tunnel',
  parents     => 'em0',
  raw_values  => [
    'tunnel 1.2.3.4 5.6.7.8',
    'inet6 alias 2001:470:6c:bbb::2 2001:470:6c:bbb::1 prefixlen 128',
    '!/sbin/route -n add -inet6 default 2001:470:6c:bbb::1',
  ],
}

Note: Ethernet-over-IP modes are not yet supported via this module.

gre tunnel devices

The gre(4) device is supported directly through the bsd::network::interface defined type. Prior to make GRE interfaces work, GRE needs to be allowed. Additionally WCCPv1-style GRE packets can be enabled as well as MobileIP packets. Example of the bsd::network::gre class below shows the default values.

class { 'bsd::network::gre':
  allowed  => true,
  wccp     => false,
  mobileip => false,
}

bsd::network::interface { 'gre0':
  description => 'Tunnel interface',
  parents     => 'em0',
  raw_values  => [
    '172.16.0.1 172.16.0.2 netmask 0xffffffff link0 up',
    'tunnel 1.2.3.4 5.6.7.8',
  ],
}

pflow interfaces

The pflow(4) device is supported directly through the bsd::network::interface defined type.

bsd::network::interface { 'pflow0':
  description => 'Pflow to collector',
  parents     => 'em0',
  raw_values  => [
    'flowsrc 1.2.3.4 flowdst 5.6.7.8:1234',
    'pflowproto 10',
  ],
}

wireless interfaces

There are many networking options for wifi. See [http://www.openbsd.org/faq/faq6.html#Wireless](the openbsd documentation) for more information.

Use the following to connect to a wireless network using WPA.

bsd::network::interface::wifi { 'athn0':
  network_name => 'myssid',
  network_key  => 'mysecretkey',
}

bridge(4) interfaces

bsd::network::interface::bridge { "bridge0":
  interface => ['em0','em1'],
}

Storing interface data in Hiera example

Now that the primitives of this module have been outlined, you may want to consider storing the data for your interfaces in Hiera. Below is an outline of how this might easily be accomplished.

First we leverage all the standard interface definitions from our hiera_hash() lookup to pass to create_resources().

class profile::network::interfaces {

  case $::osfamily {
    /(Open|Free)BSD/: {
      include bsd::network

      # Manage physical interfaces
      $interfaces = hiera_hash('bsd::network::interface', {})
      create_resources('bsd::network::interface', $interfaces)
    }
  }
}

Next we repeat the pattern for the various virtual interfaces, including the above class.

class profile::network::interfaces::trunk {
  include profile::network::interfaces

  case $::osfamily {
    /(Open|Free)BSD/: {
      # Setup the trunk interfaces
      $trunk_interfaces = hiera_hash('bsd::network::interface::trunk', {})
      create_resources('bsd::network::interface::trunk', $trunk_interfaces)
    }
  }
}

A complete example for one users "Jail Host" role looks like the following, assuming the above two classes are included.

bsd::network::v4gateway: '172.16.0.1'
bsd::network::v6gateway: '2001:111:111:111::111'
bsd::network::v4forwarding: true
bsd::network::v6forwarding: true

bsd::network::interface:
  igb0:
    description: "Router trunk member interface"
    ensure: 'up'
  igb1:
    description: "Router trunk member interface"
    ensure: 'up'
  lo1:
    description: "Jail service loopback"
    ensure: 'up'
    addresses:
      - '2001:111:111:200::100/120'
      - '172.16.1.0/27'

bsd::network::interface::trunk:
  lagg0:
    interface:
      - 'igb0'
      - 'igb1'
    address:
      - '2001:111:111:111::120/120'
      - '172.16.0.2/24'

Contributing

Please help make this module better by sending pull requests and filing issues for feature requests or bugs. Please adhere to the style and be mindful of the tests.

Unreleased

2019-08-15 2.4.0

• tidy up ruby style
• fix issue with cloned interface detection for multi-digit interface names

2018-02-10 2.2.1

Summary

Fixes to usage of raw_values for interfaces on FreeBSD.

2018-02-10 2.2.0

Summary

This release contains adjustments to dependencies and new files to support pushing released versions to the forge.

2017-10-15 2.1.1

Summary

This release contains fixes to cloned_interfaces to ensure proper detection of those interfaces that need to be created at boot.

2017-09-30 2.1.0

Summary

This release contains improvements to FreeBSD support to include lagg(4) support through the trunk classes, and fixes addressing issues on the vlan interfaces for FreeBSD.

2016-11-10 2.0.0

Summary

This release contains contains backwards incompatible parameter name and data type changes. Also here, is native Puppet 4 support, dropping Puppet 3 support, and lots of plumbing changes to make configuration validation a bit cleaner.

Features

• Drop Puppet 3.x support, leveraging native Puppet 4.x type validation
  • Validation change, VLAN IDs are now integers.
  • Validation change, address parameters are arrays.
• The old 'values' param has been renamed to 'raw_values' to make it clear that the items will be written unmodified.
• Library code has been much improved, centralizing the configuration validation between the BSDs to allow for easier addition of interface types, or future configuration changes. The PuppetX::BSD::PuppetInterface parent class is now used to create a new interface type and provide the necessary validation. This reduces the interface type specific code considerably.
• 'network_key' has been renamed to 'wpa_key' on wifi interfaces
• Add support for managing interface MTU

Bugfixes

• Fix an issue where MTU is not properly read from the output of ifconfig

2016-06-29 1.2.0

Summary

This release contains updates for testing including platform test matrix.

Features

• drop testing on old Puppet 3.x versions, keeping only 3.8.7
• improve manifest test coverage

2016-06-20 1.1.0

Summary

This release contains a change in dependency for sysctl. The two modules should co-exist without issue, but the new dependency must be present.

Features

• drop duritong/sysctl in favor of herculesteam-augeasproviders_sysctl

2016-05-19 1.0.0

Summary

This release contains a backwards incompatible dependency change. Please see the metadata for the new dependency list.

Features

• drop shell_config in favor of augeas_providers
• begin changelog