Table of Contents

  1. Overview

  2. Module Description - What the module does and why it is useful

  3. Setup - The basics of getting started with simplib

  4. Usage - Configuration options and additional functionality

  5. Reference - An under-the-hood peek at what the module is doing and how

  6. Development - Guide for contributing to the module

This is a SIMP module

This module is a component of the System Integrity Management Platform, a compliance-management framework built on Puppet.

If you find any issues, they can be submitted to our JIRA.

Module Description

simp/simplib is a collection custom functions, facts, and small types.

Setup

What simplib affects

simplib contains functions, facts, and small utility classes.

Setup Requirements

Agents will need to enable pluginsync.

Usage

Please see reference for usage.

Full documentation can be found in the module docs

Reference

A list of things provided by simplib is below.

Please reference the doc/ directory in the top level of the repo or the code itself for more detailed documentation.

Facts

  • acpid_enabled - Return true if ACPI is available on the system

  • boot_dir_uuid - Return the UUID of the partition holding the boot directory

  • cmdline - Returns the contents of /proc/cmdline as a hash

  • cpuinfo - Returns the contents of /proc/cpuinfo as a hash

  • defaultgateway - Return the default gateway of the system

  • defaultgatewayiface - Return the default gw interface of the system

  • fips_ciphers - Returns a list of available OpenSSL ciphers

  • fips_enabled - Determine whether or not FIPS is enabled on this system

  • fullrun - Determine whether or not to do an intensive run

  • gdm_version - Return the version of GDM that is installed

  • grub_version - Return the grub version installed on the system

  • init_systems - Return a list of all init systems present on the system

  • ipv6_enabled - Return true if IPv6 is enabled and false if not

  • reboot_required - Returns a hash of 'name' => 'reason' entries

  • runlevel - Return the current system runlevel

  • shmall - Return the value of shmall from sysctl

  • puppet_settings - Returns a hash of all Puppet settings on a node

  • tmp_mounts - This fact provides information about /tmp, /var/tmp, and /dev/shm should they be present on the system

  • uid_min - Return the minimum uid allowed

Functions

array_include

Determine if the first passed array contains the contents of another array or string.

Example:

$arr_x = [ 'foo', 'bar' ]
$arr_y = [ 'foo', 'baz', 'bar' ]

if array_include($arr_x, $arr_y) {
  notice('this will be printed')
}
if array_include($arr_x, 'bar') {
  notice('this will be printed')
}
if array_include($arr_x, 'baz') {
  notice('this will not be printed')
}

Returns: boolean

array_size

Returns the number of elements in an array. If a string is passed, simply returns '1'.

This is in contrast to the Puppet Labs stdlib 'size' function which returns the size of an array or the length of a string when called.

Returns: integer

array_union

Return the union of two arrays.

Example:

$arr_x = ['1','2']
$arr_y = ['2','3','4']

$res = array_union($arr_x, $arr_y)

$res contains: ['1','2','3','4']

Returns: array

bracketize

Add brackets to IP addresses and arrays of IP addresses based on the rules for bracketing IPv6 addresses. Ignore anything that doesn't look like an IPv6 address.

Returns: string or array

deep_merge

Perform a deep merge on two passed hashes.

This code is shamelessly stolen from the guts of ActiveSupport::CoreExtensions::Hash::DeepMerge and munged together with the Puppet Labs stdlib 'merge' function.

Returns: hash

filtered

data_hash variant

Hiera v5 backend that takes a list of allowed hiera key names, and only returns results from the underlying backend function that match those keys.

This allows hiera data to be delegated to end users in a multi-tenant environment without allowing them the ability to override every hiera data point (and potentially break systems)

Usage: yaml --- version: 5 # Specific version of hiera we are using, required for v4 and v5 defaults: # Used for any hierarchy level that omits these keys. datadir: "data" # This path is relative to hiera.yaml's directory. data_hash: "yaml_data" # Use the built-in YAML backend. hierarchy: # Each hierarchy consists of multiple levels - name: "OSFamily" path: "osfamily/%{facts.osfamily}.yaml" - name: "datamodules" data_hash: simplib::filtered datadir: "delegated-data" paths: - "%{facts.sitename}/osfamily/%{facts.osfamily}.yaml" - "%{facts.sitename}/os/%{facts.operatingsystem}.yaml" - "%{facts.sitename}/host/%{facts.fqdn}.yaml" - "%{facts.sitename}/common.yaml" options: function: yaml_data filter: - profiles::ntp::servers - profiles::.* - name: "Common" path: "common.yaml"

Returns: hash

generate_reboot_msg

Generate a reboot message from a passed hash.

Requires a hash of the following form:

{
  'id'  => 'reason',
  'id2' => 'reason2',
  ...
}

Will return a message such as:

A system reboot is required due to:
  id => reason
  id2 => reason2

Returns: hash

get_ports

Take an array of items that may contain port numbers and appropriately return the port portion. Works with hostnames, IPv4, and IPv6.

$foo = ['https://mysite.net:8443','http://yoursite.net:8081']

$bar = strip_ports($foo)

$bar contains: ['8443','8081']

Returns: array

h2n

Return an IP address for the passed hostname.

Returns: string

host_is_me

Detect if a local system identifier Hostname/IP address is contained in the passed whitespace delimited list. Whitespace and comma delimiters and passed arrays are accepted. 127.0.0.1 and ::1 are never matched, use 'localhost' or 'localhost6' for that if necessary.

Returns: boolean

inspect

Prints out Puppet warning messages that display the passed variable.

This is mainly meant for debugging purposes.

Returns: string

ipaddresses

Return an array of all IP addresses known to be associated with the client. If an argument is passed, and is not false, then only return non-local addresses.

Returns: array

ip_is_me

Detect if an IP address is contained in the passed whitespace delimited list.

Returns: boolean

ip_to_cron

Provides a “random” value to cron based on the passed integer value. Used to avoid starting a certain cron job at the same time on all servers. If used with no parameters, it will return a single value between 0-59. first argument is the occurrence within a timeframe, for example if you want it to run 2 times per hour the second argument is the timeframe, by default its 60 minutes, but it could also be 24 hours etc

Pulled from: projects.puppetlabs.com/projects/puppet/wiki/Cron_Patterns/8/diff Author: ohadlevy@gmail.com License: None

Example:

ip_to_cron()     - returns one value between 0..59
ip_to_cron(2)    - returns an array of two values between 0..59
ip_to_cron(2,24) - returns an array of two values between 0..23

Returns: integer or array

join_mount_opts

Merge two sets of 'mount' options in a reasonable fashion. The second set will always override the first.

Returns: string

localuser

Pull a pre-set password from a password list and return an array of user details associated with the passed hostname.

If the password starts with the string '$1$' and the length is 34 characters, then it will be assumed to be an MD5 hash to be directly applied to the system.

If the password is in plain text form, then it will be hashed and stored back into the source file for future use. The plain text version will be commented out in the file.

Arguments: * filename (path to the file containing the local users) * hostname (host that you are trying to match against)

Returns: array

mapval

Pull a mapped value from a text file. Must provide a Ruby regex!.

Returns: string

nets2cidr

Convert an array of networks into CIDR notation

Returns: array

nets2ddq

Convert an array of networks into dotted quad notation

Returns: array

parse_hosts

Take an array of items that may contain port numbers or protocols and return the host information, ports, and protocols. Works with hostnames, IPv4, and IPv6.

Example:

parse_hosts([ '1.2.3.4', '<http://1.2.3.4>', '<https://1.2.3.4:443>' ])

Returns: '1.2.3.4' => {
           ports => ['443'],
           protocols => {
             'http' => [],
             'https' => ['443']
           }
         }

NOTE

IPv6 addresses will be returned normalized with square brackets


Returns: hash

passgen

Generates a random password string for a passed identifier. Uses Puppet/$environment/simp_autofiles/gen_passwd/ as the destination directory.

The minimum length password that this function will return is 6
characters.

    Arguments: identifier, <modifier hash>; in that order.

    <modifier hash> may contain any of the following options:
      - 'last' => false(*) or true
        * Return the last generated password
      - 'length' => Integer
        * Length of the new password
      - 'hash' => false(*), true, md5, sha256 (true), sha512
        * Return a hash of the password instead of the password itself.
      - 'complexity' => 0(*), 1, 2
        * 0 => Use only Alphanumeric characters in your password (safest) 1 =>
        * Add reasonably safe symbols 2 => Printable ASCII

    If no, or an invalid, second argument is provided then it will return the
    currently stored string.

Returns: string

rand_cron

Provides a “random” value to cron based on the passed integer value. Used to avoid starting a certain cron job at the same time on all servers. If used with no parameters, it will return a single value between 0-59 first argument is the occurrence within a timeframe, for example if you want it to run 2 times per hour the second argument is the timeframe, by default its 60 minutes, but it could also be 24 hours etc

Based on: projects.puppetlabs.com/projects/puppet/wiki/Cron_Patterns/8/diff Author: ohadlevy@gmail.com License: None Posted

Example: ruby int_to_cron('100') - returns one value between 0..59 based on the value 100 int_to_cron(100,2) - returns an array of two values between 0..59 based on the value 100 int_to_cron(100,2,24) - returns an array of two values between 0..23 based on the value 100

Returns: integer or array

simp_version

Return the version of SIMP that this server is running.

Returns: string

slice_array

Split an array into an array of arrays that contain groupings of 'max_length' size. This is similar to 'each_slice' in newer versions of Ruby.

* Options *

  to_slice => The array to slice. This will be flattened if necessary.

  max_length => The maximum length of each slice.

  split_char => An optional character upon which to count sub-elements
  as multiples. Only one per subelement is supported.

Returns: array of arrays

strip_ports

Take an array of items that may contain port numbers and appropriately return the non-port portion. Works with hostnames, IPv4, and IPv6.

$foo = ['https://mysite.net:8443',
        'http://yoursite.net:8081',
        'https://theirsite.com']

$bar = strip_ports($foo)

$bar contains: ['https://mysite.net','http://yoursite.net','theirsite.com']

Returns: array

to_integer

Converts the argument into an Integer.

Only works if the passed argument responds to the 'to_i' Ruby method.

Returns: integer

to_string

Converts the argument into a String.

Only works if the passed argument responds to the 'to_s' Ruby method.

Returns: string

validate_array_of_hashes

Validate that the passed argument is either an empty array or an array that only contains hashes.

Examples:

validate_array_of_hashes([{'foo' => 'bar'}]) # => OK
validate_array_of_hashes([])                 # => OK
validate_array_of_hashes(['FOO','BAR'])      # => BAD

Returns: boolean

validate_array_member

Validate that the first string (or array) passed is a member of the second array passed. An optional third argument of i can be passed, which ignores the case of the objects inside the array.

Examples:

validate_array_member('foo',['foo','bar'])     # => true
validate_array_member('foo',['FOO','BAR'])     # => false

#Optional 'i' as third object, ignoring case of FOO and BAR#

validate_array_member('foo',['FOO','BAR'],'i') # => true

Returns: boolean

validate_between

Validate that the first value is between the second and third values numerically.

This is a pure Ruby comparison, not a human comparison.

Returns: boolean

validate_bool_simp

Validate that all passed values are either true or false. Abort catalog compilation if any value fails this check.

Modified from the stdlib validate_bool to handle the strings 'true' and 'false'.

The following values will pass:

$iamtrue = true

validate_bool(true)
validate_bool("false")
validate_bool("true")
validate_bool(true, 'true', false, $iamtrue)

The following values will fail, causing compilation to abort:

$some_array = [ true ]

validate_bool($some_array)

Returns: boolean

validate_deep_hash

Perform a deep validation on two passed hashes.

The first hash is the one to validate against, and the second is the one being validated. The first hash (i.e. the source) exists to define a valid structure and potential regular expression to validate against, or to skip an entry. Arrays of values will match each entry to the given regular expression. Below are examples of a source hash and a hash to compare against it:

'source' = {
       'foo' => {
         'bar' => {
           #NOTE: Use single quotes for regular expressions
           'baz' => '^\d+$',
           'abc' => '^\w+$',
           'def' => nil #NOTE: not 'nil' in quotes
         },
         'baz' => {
           'xyz' => '^true|false$'
         }
       }
     }

    'to_check' = {
       'foo' => {
         'bar' => {
           'baz' => '123',
           'abc' => [ 'these', 'are', 'words' ],
           'def' => 'Anything will work here!'
         },
         'baz' => {
           'xyz' => 'false'
         }
       }

This fails because we expect the value of 'foo' to be a series of digits, not letters.

Additionally, all keys must be defined in the source hash that is being validated against. Unknown keys in the hash being compared will cause a

Returns: boolean

validate_float

Validates whether or not the passed argument is a float.

Returns: boolean

validate_integer

Validates whether or not the passed argument is an integer.

Returns: boolean

validate_macaddress

Validate that all passed values are valid MAC addresses.

The following values will pass:

$macaddress = 'CA:FE:BE:EF:00:11'

validate_macaddress($macaddress)
validate_macaddress($macaddress,'00:11:22:33:44:55')
validate_macaddress([$macaddress,'00:11:22:33:44:55'])

Returns: boolean

validate_port

Validates whether or not the passed argument is a valid port (i.e. between 1 - 65535).

The following values will pass:

$port = '10541'
$ports = ['5555', '7777', '1', '65535']

validate_port($port)
validate_port($ports)
validate_port('11', '22')

The following values will not pass:

validate_port('0')
validate_port('65536')

Returns: boolean

validate_net_list

Validate that a passed list (Array or single String) of networks is filled with valid IP addresses or hostnames. Hostnames are checked per 1123[https://tools.ietf.org/html/rfc1123].Ports appended with a colon (:) are allowed.

There is a second, optional argument that is a regex of strings that should be ignored from the list. Omit the beginning and ending '/' delimiters.

The following values will pass:

$trusted_nets = ['10.10.10.0/24','1.2.3.4','1.3.4.5:400']
validate_net_list($trusted_nets)

$trusted_nets = '10.10.10.0/24'
validate_net_list($trusted_nets)

$trusted_nets = ['10.10.10.0/24','1.2.3.4','any','ALL']
validate_net_list($trusted_nets,'^(any|ALL)$')

The following values will fail:

$trusted_nets = '10.10.10.0/24,1.2.3.4'
validate_net_list($trusted_nets)

$trusted_nets = 'bad stuff'
validate_net_list($trusted_nets)

Returns: boolean

validate_re_array

Perform simple validation of a string, or array of strings, against one or more regular expressions. The first argument of this function should be a string to test, and the second argument should be a stringified regular expression (without the // delimiters) or an array of regular expressions. If none of the regular expressions match the string passed in, compilation will abort with a parse error.

If a third argument is specified, this will be the error message raised and seen by the user.

The following strings will validate against the regular expressions:

validate_re_array('one', '^one$')
validate_re_array('one', [ '^one','^two' ])
validate_re_array(['one','two'], [ '^one', '^two' ])

The following strings will fail to validate, causing compilation to abort:

validate_re_array('one', [ '^two', '^three' ])

A helpful error message can be returned like this:

validate_re_array($::puppetversion, '^2.7', 'The $puppetversion fact
value does not match 2.7')

Returns: boolean

validate_sysctl_value

Validate that the passed value is correct for the passed sysctl key.

If a key is not know, simply returns that the value is valid.

Example:

Returns: boolean

validate_umask

Validate that the passed value is a valid umask string.

Examples:

$val = '0077' validate_umask($val) # => OK

$val = '0078' validate_umask($val) # => BAD

Returns: boolean

validate_uri_list

Usage: validate_uri_list(,[])

Validate that a passed list (Array or single String) of URIs is valid according to Ruby's URI parser.

The following values will pass:

$uris = [http://foo.bar.baz:1234','ldap://my.ldap.server']
validate_uri_list($uris)

$uris = ['ldap://my.ldap.server','ldaps://my.ldap.server']
validate_uri_list($uris,['ldap','ldaps'])

Returns: boolean

Types

  • ftpusers

  • init_ulimit

  • prepend_file_line

  • reboot_notify

  • runlevel

  • script_umask

  • simp_file_line

Data Types

The following Puppet 4 compatible Data Types have been added for convenience and validation across the SIMP codebase.

  • Simplib::EmailAddress

    • Simple e-mail address validator

      • foo@bar.com

      • foo@bar.com

    • Simple e-mail address validator

      • foo@bar.com

  • Simplib::Host

    • A single Host or an IP Address

      • 1.2.3.4

      • my-host.com

  • Simplib::Host::Port

    • A single Host or an IP Address with a Port

      • 1.2.3.4:80

      • my-host.com:443

  • Simplib::Hostname

    • A hostname, Unicode hostnames are not currently supported

      • my-host.com

      • aa.bb

  • Simplib::IP

    • An IP Address

      • 1.2.3.4

      • 2001:0db8:85a3:0000:0000:8a2e:0370:7334

  • Simplib::IP::Port

    • An IP Address (V4 or V6) with a Port

  • Simplib::IP::V4

    • An IPv4 Address

      • 1.2.3.4

  • Simplib::IP::CIDR

    • An IPv4 or IPv6 Address with a CIDR Subnet

      • 1.2.3.4/24

      • 2001:0db8:85a3:0000:0000:8a2e:0370:7334/96

  • Simplib::IP::V4::CIDR

    • An IPv4 Address with a CIDR Subnet

      • 1.2.3.4/24

  • Simplib::IP::V4::DDQ

    • An IPv4 Address with a Dotted Quad Subnet

      • 1.2.3.4/255.255.0.0

  • Simplib::IP::V4::Port

    • An IPv4 Address with an attached Port

      • 1.2.3.4:443

  • Simplib::IP::V6

    • An IPv6 Address

      • ::1

      • 2001:0db8:85a3:0000:0000:8a2e:0370:7334

      • [::1]

      • [2001:0db8:85a3:0000:0000:8a2e:0370:7334]

  • Simplib::IP::V6::Base

    • A regular IPv6 Address

      • ::1

      • 2001:0db8:85a3:0000:0000:8a2e:0370:7334

  • Simplib::IP::V6::Bracketed

    • A bracketed IPv6 Address

      • [::1]

      • [2001:0db8:85a3:0000:0000:8a2e:0370:7334]

  • Simplib::IP::V6::CIDR

    • An IPv6 address with a CIDR subnet

      • 2001:0db8:85a3:0000:0000:8a2e:0370:7334/96

  • Simplib::IP::V6::Port

    • An IPv6 address with an attached Port

      • [2001:0db8:85a3:0000:0000:8a2e:0370:7334]:443

  • Simplib::Netlist

    • An Array of network-relevant entries

      • Hostname

      • IPv4

      • IPv4 with Subnet

      • IPv4 with Port

      • IPv6

      • IPv4 with Subnet

      • IPv4 with Port

  • Simplib::Netlist::Host

    • An Array of Hosts

      • Hostname

      • IPv4

      • IPv6

  • Simplib::Netlist::IP

    • An Array of IP Addresses

      • IPv4

      • IPv6

  • Simplib::Netlist::IP::V4

    • An Array of IPv4 Addresses

  • Simplib::Netlist::IP::V6

    • An Array of IPv6 Addresses

  • Simplib::Netlist::Port

    • An Array of Hosts with Ports

  • Simplib::Port

    • A Port Number

  • Simplib::Port::Dynamic

    • Either 49152 or 65535

  • Simplib::Port::Random

    • Port 0

  • Simplib::Port::System

    • 1-1024

  • Simplib::Port::User

    • 1025-49151

    • 49153-65534

  • Simplib::Syslog::CFacility

  • A syslog log facility, in the form expected by syslog(3)

    • LOG_KERN

    • LOG_LOCAL6

  • Simplib::Syslog::CPriority

  • A syslog log priority, in the form expected by syslog(3)

    • LOG_KERN.LOG_INFO

    • LOG_LOCAL6.LOG_WARNING

  • Simplib::Syslog::CSeverity

  • A syslog log severity, in the form expected by syslog(3)

    • LOG_INFO

    • LOG_WARNING

  • Simplib::Syslog::Facility

  • A syslog log facility, in either all uppercase or all lowercase.

    • kern

    • local6

    • LOCAL6

  • Simplib::Syslog::LowerFacility

  • A syslog log facility, in all lowercase.

    • auth

    • local4

  • Simplib::Syslog::UpperFacility

  • A syslog log facility, in all uppercase.

    • MAIL

    • LOCAL7

  • Simplib::Syslog::Severity

  • A syslog severity level, in either all uppercase or all lowercase.

    • info

    • WARNING

  • Simplib::Syslog::LowerSeverity

  • A syslog severity level, in all lowercase.

    • info

    • emerg

  • Simplib::Syslog::UpperSeverity

  • A syslog severity level, in all uppercase.

    • DEBUG

    • WARNING

  • Simplib::Syslog::Priority

  • A syslog priority destination, in format 'facility.severity' and in either all uppercase or all lowercase. This type only accepts the keyword facilities and severities.

    • mail.info

    • KERN.EMERG

  • Simplib::Syslog::LowerPriority

  • A syslog priority destination, in format 'facility.severity' and in only all lowercase. This type only accepts the keyword facilities and severities.

    • mail.info

    • user.err

  • Simplib::Syslog::UpperPriority

  • A syslog priority destination, in format 'facility.severity' and in only all uppercase. This type only accepts the keyword facilities and severities.

    • SYSLOG.WARNING

    • AUTHPRIV.INFO

  • Simplib::Umask

    • A valid Umask

  • Simplib::URI

    • A valid URI string (lightly sanity checked)

Development

Please read our Contribution Guide and visit our Developer Wiki

If you find any issues, they can be submitted to our JIRA.

System Integrity Management Platform