hosts

A template-based module to manage /etc/hosts. The main goal for this module is to add entries for localhost and primary address based on existing ip-adresses on existing interfaces. as reported by structured fact networking[]. Tested by me on Gentoo, SLES, RedHat, and OS X. But it should work or any Linux and Unix-like OS.

This module unconditionally overwrites your hosts file.

Usage

class { 'hosts': }

Hiera example

hosts::one_primary_ipv4: false
hosts::one_primary_ipv6: false
hosts::entries:
  '::2':
    - 'localhost2'
  'Foocluster nodes':
    '2001:db8:abba::1':
      - 'node1.example.org'
      - 'node1'
    '2001:db8:abba::2':
      - 'node2.example.org'
      - 'node2'

Reference

Table of Contents

Classes

• hosts: Manage /etc/hosts

Functions

Public Functions

Private Functions

• hosts::collect_lo: Collect addresses on the loopback interface from fact networking.
• hosts::collect_other: Collect addresses from all interfaces except loopback from fact networking.
• hosts::excludefilter: Helper function for exclusion of addresses
• hosts::includefilter: Helper function for inclusion of addresses
• hosts::tabs: Helper function for creating right amount of tabs for alignment.

Classes

hosts

Manage /etc/hosts

Examples

With default entries only

include hosts

With all primary addresses

class { 'hosts':
  'one_primary_ipv4' => false,
  'one_primary_ipv6' => false,
}

Parameters

The following parameters are available in the hosts class:

• file
• one_primary_ipv4
• one_primary_ipv6
• enable_ipv4
• enable_ipv6
• include_ipv4
• include_ipv6
• exclude_ipv4
• exclude_ipv6
• include_ifs
• exclude_ifs
• loopback_if
• lo_ipv4
• lo_ipv6
• primary_ipv4
• primary_ipv6
• lo_names
• primary_names
• root_group
• entries

file

Data type: Stdlib::Absolutepath

The file to manage.

Default value: '/etc/hosts'

one_primary_ipv4

Data type: Boolean

If true, only use the first address from primary_ipv4.

Default value: true

one_primary_ipv6

Data type: Boolean

If true, only use the first address from primary_ipv6.

Default value: true

enable_ipv4

Data type: Boolean

If false, don't add IPv4 loopback or primary addresses. (IPv4 addresses from hosts::entries is still added)

Default value: true

enable_ipv6

Data type: Boolean

If false, don't add IPv6 loopback or primary addresses. (IPv6 addresses from hosts::entries is still added)

Default value: true

include_ipv4

Data type: Array[String]

A list of regexp. If the list is empty all IPv4 addresses are included. If the list is not empty all IPv4 addresses matching any of the regexps are included.

Default value: []

include_ipv6

Data type: Array[String]

A list of regexp. If the list is empty all IPv6 addresses are included. If the list is not empty all IPv6 addresses matching any of the regexps are included.

Default value: []

exclude_ipv4

Data type: Array[String]

A list of regexp. Exclude IPv4 addresses that matches any of the regexps.

Default value: []

exclude_ipv6

Data type: Array[String]

A list of regexp. Exclude IPv6 addresses that matches any of the regexps.

Default value: []

include_ifs

Data type: Array[String]

A list of regexp. If the list is empty addresses from all interfaces are included. If the list is not empty only addresses from interfaces matching any of the regexps are included.

Default value: []

exclude_ifs

Data type: Array[String]

A list of regexp. Exclude addresses from interfaces that match any of the regexps.

Default value: []

loopback_if

Data type: String

The name of the loopback interface.

Default value: 'lo'

lo_ipv4

Data type: Array[Stdlib::IP::Address::V4::Nosubnet]

List of IPv4 addresses for localhost. Empty list means no entry.

Default value: hosts::collect_lo('ip',$loopback_if)

lo_ipv6

Data type: Array[Stdlib::IP::Address::V6::Nosubnet]

List of IPv6 addresses for localhost. Empty list means no entry.

Default value: hosts::collect_lo('ip6',$loopback_if)

primary_ipv4

Data type: Array[Stdlib::IP::Address::V4::Nosubnet]

List of IPv4 addresses. Empty list means no entry.

Default value: hosts::collect_other('ip',$loopback_if, $include_ifs,$exclude_ifs)

primary_ipv6

Data type: Array[Stdlib::IP::Address::V6::Nosubnet]

List of IPv6 addresses. Empty list means no entry.

Default value: hosts::collect_other('ip6',$loopback_if, $include_ifs,$exclude_ifs)

lo_names

Data type: Array[String]

List of names for localhost.

Default value: [ 'localhost' ]

primary_names

Data type: Array[String]

List of names for primary addresses.

Default value: [ $::fqdn, $::hostname ]

root_group

Data type: Variant[Integer[0],String[1]]

Group that should own the hosts file.

Default value: 'root'

entries

Data type: Hash

A hash with additional host entries to add. Entries in this hash overrides automatic hostentries for IP's on local interfaces. The content can be either comment => { ip => [ names ], ... } or just ip => [ names ].

Default value: {}

Functions

4.1.1

Jan 24, 2025

• Raise stdlib boundary

4.1.0

Apr 29, 2023

• Replace remaining references to legacy facts, needed for puppet-8

4.0.4

Apr 17, 2022

• Make $root_group a parameter with defaults in hiera
• Add defaults for Solaris

4.0.3

Mar 26, 2022

• Use 'lo0' as default loopback interface on FreeBSD.

4.0.2

Oct 26, 2021

• Fix bug if IPv6 is disabled.

4.0.1

Oct 25, 2021

• puppet-5.5 compatibility

4.0.0

Oct 23, 2021

Major rewrite

• Replaced ruby-code to collect addresses from interfaces with puppet code to collect addresses from structured fact networking.
• Replaced complex erb template with much simpler epp template.
• Added parameters exclude_ifs and include_ifs

3.2.0

Apr 04, 2021

• Added ability to filter the lists of addresses with lists of regexps.

3.1.0

May 10, 2020

• Sort IP-adresses to make hosts content stable across runs.

3.0.0

Jul 29, 2019

• Replace deprecated validate-functions with puppet-4 data types.

2.4.0

Dec 31, 2018

• Converted to pdk.

2.3.1

Apr 03, 2017

• Bugfix: Reject nil IP

2.3.0

Feb 23, 2017

• Ability to merge entries by hiera

2.2.7

Jun 22, 2016

• Bugfixes to fact handling.

2.2.6

Jun 15, 2016

• Add boolean parameters enable_ipv4 & enable_ipv6

2.2.5

Apr 22, 2016

• Use exceptions in custom fact.

2.2.4

Apr 18, 2016

• Put standard ipaddress facts first in lists, to get the expected ip-address if using one_primary_ipv4 or one_primary_ipv6

2.2.3

Apr 12, 2016

• Change order of IP loaders in facter to be compatible with AIX

2.2.2

Apr 05, 2016

• Fixed so that hosts::entries in new format overrides IP's on local interfaces

2.2.1

Apr 04, 2016

• Entries in hosts::entries can now be grouped, resulting in a comment before each group in /etc/hosts. Example,

hosts::entries:
  'Foocluster nodes':
    '2001:db8:abba::1':
      - 'node1.example.org'
      - 'node1'
    '2001:db8:abba::2':
      - 'node2.example.org'
      - 'node2'

This change is backward compatible. The old data-structure still works as before.

2.2.0

Mar 20, 2016

• Entries in hosts::entries now overrides IP's on local interfaces

2.1.1

Mar 19, 2016

• Changed domain used as example.

2.1.0

Feb 19, 2016

• Fallback to std fact values for IP-adresses if custom facts fails.

2.0.5

Feb 11, 2016

• Support for AIX, by Maxime Anciaux.

2.0.4

Jan 05, 2016

• Added support for Darwin (OS X)

2.0.3

Dec 29, 2015

• Added compatibility for ruby18, with much help from Frank Wall

2.0.2

Dec 09, 2015

• Added support for FreeBSD, by Frank Wall

2.0.1

Nov 17, 2015

• Workaround for older facter not handling arrays

2.0.0

Jul 15, 2015

• Rewritten the code to find the local IP-addresses, to use a custom fact which uses ruby class socket.

This is to get better control than core-facts can supply. And to be able to use all addresses configured on an interface instead of just one. The default is still to use just one address, but that is easy configured with parameters one_primary_ipv4 and one_primary_ipv6