Skip to content
Permalink
Branch: master
Find file Copy path
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
3114 lines (1862 sloc) 84.2 KB

Reference

Table of Contents

Classes

  • simplib::reboot_notify: This is a simple controller class for global settings related to the 'reboot_notify' custom type
  • simplib::stages: This class expands on the Puppet Stdlib stages to add a few levels that we found necessary when developing various SIMP modules that had glob

Defined types

  • simplib::install: Manage packages based on Hash input This has been created as a Defined Type so that it can be properly referenced in manifest ordering

Resource types

  • ftpusers: Adds all system users to the named file, preserving any other entries currently in the file.
  • init_ulimit: Please use the systemd module for systems that support systemd Update ulimit settings in init scripts. The resource name does h
  • prepend_file_line: Type that can prepend whole a line to a file if it does not already contain it. Example: file_prepend_line { 'sudo_rule': path => '/etc/s
  • reboot_notify: Notifies users when a system reboot is required. This type creates a file at $target the contents of which provide a summary of the reasons
  • runlevel: Changes the system runlevel by re-evaluating the inittab or systemd link. Arguments: name - the runlevel to evaluate for the system persi
  • script_umask: Alters the umask settings in the passed file.
  • simp_file_line: Ensures that a given line is contained within a file. The implementation matches the full line, including whitespace at the beginning and en

Functions

  • array_include: Determine if the first passed array contains the contents of another array or string.
  • 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
  • array_union: Return the union of two Arrays.
  • bracketize: Add brackets to IP addresses and Arrays of IP addresses based on the rules for bracketing IPv6 addresses. Ignore anything that does not lo
  • generate_reboot_msg: Generate a reboot message from a passed Hash. Requires a Hash of the following form: ``ruby { 'id' => 'reason', 'id2' => 'reason2'
  • get_ports: Take an Array of items that may contain port numbers and appropriately return the port portion. Works with hostnames, IPv4, and IPv6.
  • h2n: Takes a single hostname and returns the associated IP address if it can determine it. If it cannot be determined, simply returns the passe
  • host_is_me: Detect if a local system identifier Hostname/IP address is contained in the passed whitespace delimited list. Whitespace and comma delimiter
  • inspect: Prints out Puppet warning messages that display the passed variable. This is mainly meant for debugging purposes.
  • ip_is_me: Detect if an IP address is contained in the passed whitespace delimited String.
  • 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 s
  • 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
  • join_mount_opts: Merge two sets of mount options in a reasonable fashion. The second set will always override the first.
  • 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 star
  • mapval: This function pulls a mapped value from a text file with the format: <key> | <value> Only the last value matched will be returned
  • nets2cidr: Take an input Array of networks and returns an equivalent Array in CIDR notation. It can also accept a String separated by spaces, com
  • nets2ddq: Take an input Array of networks and returns an equivalent Array in Dotted Quad notation. It can also accept a String separated by spac
  • parse_hosts: Take an Array of items that may contain port numbers or protocols and return the host information, ports, and protocols. Works with Hostna
  • passgen: Generates a random password string for a passed identifier. Uses Puppet[:vardir]/simp/environments/$environment/simp_autofiles/gen_passwd/
  • 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
  • simp_version: Return the version of SIMP that this server is running
  • simplib::assert_metadata: Fails a compile if the client system is not compatible with the module's metadata.json
  • simplib::assert_optional_dependency: Fails a compile if the system does not contain a correct version of the required module in the current environment. Provides a message about
  • simplib::bracketize: Add brackets to strings of IPv6 addresses and Arrays of IPv6 addresses based on the rules for bracketing IPv6 addresses. Ignores anything
  • simplib::deprecation: Function to print deprecation warnings, logging a warning once for a given key. Messages can be enabled if the SIMPLIB_LOG_DEPRECATIONS envi
  • simplib::dlookup: A function for performing lookups targeted at ease of use with defined types. Quite often you need to override something in an existing defi
  • simplib::filtered: Hiera v5 backend that takes a list of allowed hiera key names, and only returns results from the underlying backend function that match those
  • simplib::gen_random_password: Generates a random password string. Terminates catalog compilation if the password cannot be created in the allotted time.
  • simplib::hash_to_opts: Turn a hash into a options string, for use in a shell command
  • simplib::host_is_me: Detect if a local system identifier hostname/IPv4 address matches a specified hostname/IPv4 address or an entry in a list of hostnames and/o
  • simplib::in_bolt: Returns true if the run is active inside of Bolt and false otherwise. Presently, this function is extremely basic. However, this che
  • simplib::inspect: Prints the passed variable's Ruby type and value for debugging purposes This uses a Notify resource to print the information during the
  • simplib::ip_to_cron: Transforms an IP address to one or more interval values for cron. This can be used to avoid starting a certain cron job at the same time
  • simplib::ipaddresses: Return an Array of all IPv4 addresses known to be associated with the client, optionally excluding local addresses.
  • simplib::join_mount_opts: Merge two sets of mount options in a reasonable fashion, giving precedence to the second set.
  • simplib::knockout: uses the knockout prefix of '--' to remove elements from an array.
  • simplib::ldap::domain_to_dn: Generates a LDAP Base DN from a domain
  • simplib::lookup: A function for falling back to global scope variable lookups when the Puppet 4 lookup() function cannot find a value. While lookup()
  • simplib::mock_data: A mock data function
  • simplib::module_exist: Determines if a module exists in the current environment If passed with an author, such as simp/simplib or simp-simplib, will return whe
  • simplib::nets2cidr: Take an input list of networks and returns an equivalent Array in CIDR notation. * Hostnames are passed through untouched. * Terminates ca
  • simplib::nets2ddq: Tranforms a list of networks into an equivalent array in dotted quad notation. * CIDR networks are converted to dotted quad notation network
  • simplib::parse_hosts: Convert an Array of items that may contain port numbers or protocols into a structured Hash of host information. * Works with Hostnames
  • simplib::passgen: Generates/retrieves a random password string or its hash for a passed identifier. * Uses `Puppet.settings[:vardir]/simp/environments/$enviro
  • simplib::rand_cron: Transforms an input string to one or more interval values for cron. This can be used to avoid starting a certain cron job at the same tim
  • simplib::simp_version: Return the version of SIMP that this server is running or "unknown\n"
  • simplib::strip_ports: Extract list of unique hostnames and/or IP addresses from an Array of hosts, each of which may may contain protocols and/or port numbers T
  • simplib::to_integer: Converts the argument into an Integer. Terminates catalog compilation if the argument's class does not respond to the to_i() Ruby method
  • simplib::to_string: Converts the argument into a String.
  • simplib::validate_array_member: Validate that an single input is a member of another Array or an Array input is a subset of another Array. * The comparison can option
  • simplib::validate_between: Validate that the first value is between the second and third values numerically. The range is inclusive. Terminates catalog compilation if
  • simplib::validate_bool: Validate that all passed values are either true, 'true', false or 'false'. Terminates catalog compilation if validation fails.
  • simplib::validate_deep_hash: Perform a deep validation on two passed Hashes. * All keys must be defined in the reference Hash that is being validated against. * Un
  • simplib::validate_net_list: Validate that a passed list (Array or single String) of networks is filled with valid IP addresses, network addresses (CIDR notation), or
  • simplib::validate_port: Validates whether each passed argument contains valid port(s). * Each element of each argument must, numerically, be in the range [1, 6553
  • simplib::validate_re_array: Perform simple validation of a String, or Array of Strings, against one or more regular expressions. * Derived from the Puppet Labs st
  • simplib::validate_sysctl_value: Validate that the passed value is correct for the passed sysctl key. * If a key is not known, assumes the value is valid. * Terminates cat
  • simplib::validate_uri_list: Validate that a passed list (Array or single String) of URIs is valid according to Ruby's URI parser. * Caution: No scheme (protocol
  • simplib_deprecation: Function to print deprecation warnings for 3.X functions. The first argument is the uniqueness key, which allows deduping of messages. The se
  • 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 Ru
  • 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.
  • to_integer: Converts the argument into an Integer. Only works if the passed argument responds to the to_i() Ruby method.
  • to_string: Converts the argument into a String. Only works if the passed argument responds to the to_s() Ruby method.
  • 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,
  • validate_array_of_hashes: Validate that the passed argument is either an empty Array or an Array that only contains Hashes.
  • 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
  • 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 st
  • 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
  • validate_float: Validates whether or not the passed argument is a float
  • validate_macaddress: Validate that all passed values are valid MAC addresses.
  • 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 pe
  • validate_port: Validates whether or not the passed argument is a valid port (i.e. between 1 - 65535).
  • validate_re_array: Perform simple validation of a String, or Array of Strings, against one or more regular expressions. The first argument of this functio
  • validate_sysctl_value: Validate that the passed value is correct for the passed sysctl key. If a key is not known, simply returns that the value is valid.
  • validate_umask: Validate that the passed String is a valid umask
  • validate_uri_list: Usage: validate_uri_list([LIST],[<VALID_SCHEMES>]) Validate that a passed list (Array or single String) of URIs is valid according to Ru

Classes

simplib::reboot_notify

This is a simple controller class for global settings related to the 'reboot_notify' custom type

Parameters

The following parameters are available in the simplib::reboot_notify class.

log_level

Data type: Simplib::PuppetLogLevel

The Puppet log_level to use when generating output

To change the level of the reboot_notify messages add this class to the class list in hiera and set simplib::reboot_notify::log_level to the level you want.

  • Set to log_level todebug if you wish to disable output unless you're running in debug mode.

Default value: 'notice'

simplib::stages

This class expands on the Puppet Stdlib stages to add a few levels that we found necessary when developing various SIMP modules that had global ramifications.

Primarily, we wanted to ensure that anyone using the stdlib stages was not tripped up by any of our modules that may enable, or disable, various system, components; particularly ones that require a reboot.

Added Stages:

  • simp_prep -> Comes before stdlib's setup
  • simp_finalize -> Comes after stdlib's deploy

Defined types

simplib::install

Manage packages based on Hash input

This has been created as a Defined Type so that it can be properly referenced in manifest ordering

Parameters

The following parameters are available in the simplib::install defined type.

packages

Data type: Hash[String[1], Optional[Hash]]

Hash of the packages to install

  • If just a key is provided, will apply package_ensure to the item
  • A value may be provided to the package name key that will be passed along as the arguments for resource creation.
  • A special entry called defaults can be provided that will set the default package options for all packages in the Hash

@example Adding a package to be installed simplib::install({ 'my_package' => undef })

defaults

Data type: Hash[String[1], String[1]]

A Hash of default parameters to apply to all $packages

  • This will be overridden by any options applied to individual packages

@example Adding some packages with defaults simplib::install( # The package list { 'pkg1' => { 'ensure' => 'installed' }, 'pkg2' => undef }, # The defaults { 'ensure' => 'latest', 'configfiles' => 'replace' } )

Default value: { 'ensure' => 'present' }

Resource types

ftpusers

Adds all system users to the named file, preserving any other entries currently in the file.

Properties

The following properties are available in the ftpusers type.

to_write

Ignored, auto-populated from /etc/passwd

Default value: default

Parameters

The following parameters are available in the ftpusers type.

name

namevar

The file to which to write the values

min_id

The UID below which all values will be considered system users

Default value: 500

always_deny

Entries to always add to the file

Default value: ['nobody','nfsnobody']

init_ulimit

Please use the systemd module for systems that support systemd

Update ulimit settings in init scripts.

The resource name does have to be unique but is meaningless.

Valid limit_type names are:

  • b|socket_buffer_size
  • c|max_core_size
  • d|max_data_segment
  • e|max_nice
  • f|max_file_size
  • i|max_pending_signals
  • l|max_memory_lock_size
  • m|max_resident_set_size
  • n|max_open_files (default)
  • p|max_queue_size
  • r|max_real_time_pri
  • s|max_stack_size
  • t|max_cpu_time
  • u|max_num_procs
  • v|max_virt_memory
  • x|max_file_locks
  • T|max_threads

All of these are explained in the ulimit section of bash_builtins(1)

The parameter names are taken from the descriptive field names used in limits.conf.

Examples

Long Names
init_ulimit { 'rsyslog':
  ensure     => 'present',
  limit_type => 'both'
  item       => 'max_open_files',
  value      => 'unlimited'
}
Short Names
init_ulimit { 'rsyslog':
  item       => 'n',
  value      => 'unlimited'
}

Properties

The following properties are available in the init_ulimit type.

ensure

Valid values: present, absent

The basic property that the resource should be in.

Default value: present

value

Valid values: hard, soft, unlimited, /^\d+$/

The value to which to set the new limit.

Parameters

The following parameters are available in the init_ulimit type.

name

A unique name for the resource

target

namevar

The service that will be modified. If you specify a full path, that will be used instead.

limit_type

Valid values: soft, hard, both

The limit type: hard|soft|both

Default value: both

item

namevar

The system limit resource to modify

Default value: max_open_files

prepend_file_line

Type that can prepend whole a line to a file if it does not already contain it.

Example:

file_prepend_line { 'sudo_rule': path => '/etc/sudoers', line => '%admin ALL=(ALL) ALL', }

Properties

The following properties are available in the prepend_file_line type.

ensure

Valid values: present

The basic property that the resource should be in.

Default value: present

Parameters

The following parameters are available in the prepend_file_line type.

name

namevar

arbitrary name used as identity

line

The line to be prepended to the path.

path

File to possibly prepend a line to.

reboot_notify

Notifies users when a system reboot is required.

This type creates a file at $target the contents of which provide a summary of the reasons why the system requires a reboot.

NOTE: This type will only register entries on refresh. Any other use of the type will not report the necessary reboot.

A reboot notification will be printed at each puppet run until the system is successfully rebooted.

Properties

The following properties are available in the reboot_notify type.

ensure

Valid values: present, absent

The basic property that the resource should be in.

Default value: present

Parameters

The following parameters are available in the reboot_notify type.

name

namevar

The item that is being modified that requires a reboot

reason

An optional reason for rebooting

Default value: modified

control_only

Valid values: true, false, yes, no

This resource is only for control and should not add an item to the notification list

You may only have ONE resource with this set to true in your catalog

Default value: false

log_level

Valid values: alert, crit, debug, notice, emerg, err, info, warning

Set the message log level for notifications

This is only active with :control_only set to true

Default value: notice

runlevel

Changes the system runlevel by re-evaluating the inittab or systemd link. Arguments:

name

  • the runlevel to evaluate for the system

persist

  • boolean value that determines whether or not to set as the default runlevel of the system

Example:

runlevel { '3': persist => true, }

Properties

The following properties are available in the runlevel type.

level

Valid values: /^[1-5]$/, rescue, multi-user, graphical, default

The target runlevel of the system. Defaults to what is specified in :name

Default value: default

persist

Valid values: true, false

Whether or not to save the runlevel as default.

Default value: true

Parameters

The following parameters are available in the runlevel type.

name

Valid values: /^[1-5]$/, rescue, multi-user, graphical

namevar

The target runlevel of the system

transition_timeout

Valid values: /^\d+$/

How many seconds to wait for a runlevel switch before failing

Default value: 60

script_umask

Alters the umask settings in the passed file.

Properties

The following properties are available in the script_umask type.

umask

Valid values: /^[0-7]{3,4}$/

The umask that should be set in the target file.

Default value: 077

Parameters

The following parameters are available in the script_umask type.

name

namevar

The file to alter.

simp_file_line

Ensures that a given line is contained within a file. The implementation matches the full line, including whitespace at the beginning and end. If the line is not contained in the given file, Puppet will add the line to ensure the desired state. Multiple resources may be declared to manage multiple lines in the same file.

Example:

simp_file_line { 'sudo_rule':
  path => '/etc/sudoers',
  line => '%sudo ALL=(ALL) ALL',
}
simp_file_line { 'sudo_rule_nopw':
  path => '/etc/sudoers',
  line => '%sudonopw ALL=(ALL) NOPASSWD: ALL',
}

In this example, Puppet will ensure both of the specified lines are contained in the file /etc/sudoers.

This is an enhancement to the stdlib file_line that allows for the following additional options:

  • prepend => [binary] Prepend the line instead of appending it if not using 'match'
  • deconflict => [binary] Do not execute if there is a file resource that already manipulates the content of the target file.

Properties

The following properties are available in the simp_file_line type.

ensure

Valid values: present, absent

The basic property that the resource should be in.

Default value: present

Parameters

The following parameters are available in the simp_file_line type.

name

namevar

An arbitrary name used as the identity of the resource.

match

An optional regular expression to run against existing lines in the file. If a match is found, we replace that line rather than adding a new line.

line

The line to be added to the file located by the path parameter.

path

The file Puppet will ensure contains the line specified by the line parameter.

deconflict

Valid values: true, false

Do not execute this type if there is a file type that already manages the content of the target file unless $replace == false

Default value: false

prepend

Valid values: true, false

Prepend the line to the file if not using match

Default value: false

Functions

array_include

Type: Ruby 3.x API

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

array_include()

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

Returns: Boolean

array_size

Type: Ruby 3.x API

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.

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

Type: Ruby 3.x API

Return the union of two Arrays.

array_union()

Return the union of two Arrays.

Returns: Array

bracketize

Type: Ruby 3.x API

Add brackets to IP addresses and Arrays of IP addresses based on the rules for bracketing IPv6 addresses.

Ignore anything that does not look like an IPv6 address.

bracketize()

Add brackets to IP addresses and Arrays of IP addresses based on the rules for bracketing IPv6 addresses.

Ignore anything that does not look like an IPv6 address.

Returns: Variant[String, Array[String]]

generate_reboot_msg

Type: Ruby 3.x API

Generate a reboot message from a passed Hash.

Requires a Hash of the following form:

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

Will return a message such as:

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

generate_reboot_msg()

Generate a reboot message from a passed Hash.

Requires a Hash of the following form:

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

Will return a message such as:

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

Returns: Strin Strin

get_ports

Type: Ruby 3.x API

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

get_ports()

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

Returns: Array[Strin Array[Strin

h2n

Type: Ruby 3.x API

Takes a single hostname and returns the associated IP address if it can determine it.

If it cannot be determined, simply returns the passed hostname.

h2n()

Takes a single hostname and returns the associated IP address if it can determine it.

If it cannot be determined, simply returns the passed hostname.

Returns: Stri Stri

host_is_me

Type: Ruby 3.x API

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.

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: Variant[String, Arra Variant[String, Arra

inspect

Type: Ruby 3.x API

Prints out Puppet warning messages that display the passed variable.

This is mainly meant for debugging purposes.

inspect()

Prints out Puppet warning messages that display the passed variable.

This is mainly meant for debugging purposes.

Returns: N N

ip_is_me

Type: Ruby 3.x API

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

ip_is_me()

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

Returns: Boole Boole

ip_to_cron

Type: Ruby 3.x API

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: http://projects.puppetlabs.com/projects/puppet/wiki/Cron_Patterns/8/diff

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: http://projects.puppetlabs.com/projects/puppet/wiki/Cron_Patterns/8/diff

Returns: Variant[Integer[0,59], Array[Integer[0,59], Integer[0,23]]]

ipaddresses

Type: Ruby 3.x API

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.

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[Strin Array[Strin

join_mount_opts

Type: Ruby 3.x API

Merge two sets of mount options in a reasonable fashion.

The second set will always override the first.

join_mount_opts()

Merge two sets of mount options in a reasonable fashion.

The second set will always override the first.

Returns: Array[Strin Array[Strin

localuser

Type: Ruby 3.x API

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.

Lines beginning with the # symbol are ignored and commas , are not allowed in usernames or hostnames though any characters are allowed in passwords.

homedir is the home directory of the user and is optional. By default, the system will choose the home directory.

The function will return a String with the following contents:

[attr]<username>,MD5-based password hash with random salt

Hostname Ruby regular expressions are fully supported. The following formats are allowed:

  • /regex/opts,
  • /regex/,
  • regex,
  • *.,
  • fqdn,

localuser(Stdlib::Absolutepath $filename, Any $hostname)

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.

Lines beginning with the # symbol are ignored and commas , are not allowed in usernames or hostnames though any characters are allowed in passwords.

homedir is the home directory of the user and is optional. By default, the system will choose the home directory.

The function will return a String with the following contents:

[attr]<username>,MD5-based password hash with random salt

Hostname Ruby regular expressions are fully supported. The following formats are allowed:

  • /regex/opts,
  • /regex/,
  • regex,
  • *.,
  • fqdn,

Returns: String

filename

Data type: Stdlib::Absolutepath

path to the file containing the local users

hostname

Data type: Any

host that you are trying to match against

mapval

Type: Ruby 3.x API

This function pulls a mapped value from a text file with the format:

<key> | <value>

Only the last value matched will be returned

mapval(String $regex, Stdlib::Absolutepath $filename)

This function pulls a mapped value from a text file with the format:

<key> | <value>

Only the last value matched will be returned

Returns: Stri Stri

regex

Data type: String

Ruby regular expression that will be mapped. Do not add starting ^ or ending $

filename

Data type: Stdlib::Absolutepath

The filename from which to pull the value

nets2cidr

Type: Ruby 3.x API

Take an input Array of networks and returns an equivalent Array in CIDR notation.

It can also accept a String separated by spaces, commas, or semicolons.

nets2cidr(Variant[Array[String], String] $networks)

Take an input Array of networks and returns an equivalent Array in CIDR notation.

It can also accept a String separated by spaces, commas, or semicolons.

Returns: Variant[Array[String], Strin Variant[Array[String], Strin

networks

Data type: Variant[Array[String], String]

nets2ddq

Type: Ruby 3.x API

Take an input Array of networks and returns an equivalent Array in Dotted Quad notation.

It can also accept a String separated by spaces, commas, or semicolons.

nets2ddq(Variant[Array[String], String] $networks)

Take an input Array of networks and returns an equivalent Array in Dotted Quad notation.

It can also accept a String separated by spaces, commas, or semicolons.

Returns: Variant[Array[String], Strin Variant[Array[String], Strin

networks

Data type: Variant[Array[String], String]

parse_hosts

Type: Ruby 3.x API

Take an Array of items that may contain port numbers or protocols and return the host information, ports, and protocols.

Works with Hostnames as well as IPv4 and IPv6 addresses.

NOTE: IPv6 addresses will be returned normalized with square brackets around them for clarity.

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 as well as IPv4 and IPv6 addresses.

NOTE: IPv6 addresses will be returned normalized with square brackets around them for clarity.

Returns: Array[Strin Array[Strin

passgen

Type: Ruby 3.x API

Generates a random password string for a passed identifier.

Uses Puppet[:vardir]/simp/environments/$environment/simp_autofiles/gen_passwd/ as the destination directory.

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

Arguments: identifier, ; in that order.

passgen(String $identifier, Hash $modifier_hash)

Generates a random password string for a passed identifier.

Uses Puppet[:vardir]/simp/environments/$environment/simp_autofiles/gen_passwd/ as the destination directory.

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

Arguments: identifier, ; in that order.

Returns: Stri Stri

identifier

Data type: String

Unique String to identify the password usage

modifier_hash

Data type: 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

private options:

  • password => contains the string representation of the password to hash (used for testing)
  • salt => contains the string literal salt to use (used for testing)
  • complex_only => use only the characters explicitly added by the complexity rules (used for testing)

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

rand_cron

Type: Ruby 3.x API

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: http://projects.puppetlabs.com/projects/puppet/wiki/Cron_Patterns/8/diff

rand_cron(String $modifier, Integer $occurs, Integer $scope)

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: http://projects.puppetlabs.com/projects/puppet/wiki/Cron_Patterns/8/diff

Returns: Variant[Integer[0,59], Array[Integer[0,59], Integer[0,23]]]

modifier

Data type: String

Input range modifier

occurs

Data type: Integer

How many values to return

scope

Data type: Integer

Top range of randomly generated number

simp_version

Type: Ruby 3.x API

Return the version of SIMP that this server is running

simp_version()

Return the version of SIMP that this server is running

Returns: Stri Stri

simplib::assert_metadata

Type: Puppet Language

Fails a compile if the client system is not compatible with the module's metadata.json

`simplib::assert_metadata(String[1] $module_name, Optional[Struct[{

enable => Optional[Boolean],
os     => Optional[Struct[{
  validate => Optional[Boolean],
  options  => Struct[{
    release_match => Enum['none','full','major']
  }]
}]]

}]] $options = simplib::lookup('simplib::assert_metadata::options', { 'default_value' => undef }))`

Fails a compile if the client system is not compatible with the module's metadata.json

Returns: None

module_name

Data type: String[1]

The name of the module that should be checked

options

Data type: Optional[Struct[{ enable => Optional[Boolean], os => Optional[Struct[{ validate => Optional[Boolean], options => Struct[{ release_match => Enum['none','full','major'] }] }]] }]]

Behavior modifiers for the function

  • Can be set using simplib::assert_metadata::options in the lookup stack

Options

  • enable => If set to false disable all validation
  • os
    • validate => Whether or not to validate the OS settings
    • options
      • release_match
        • none -> No match on minor release (default)
        • full -> Full release must match
        • major -> Only the major release must match

simplib::assert_optional_dependency

Type: Ruby 4.x API

Fails a compile if the system does not contain a correct version of the required module in the current environment.

Provides a message about exactly which version of the module is required.

simplib::assert_optional_dependency(String[1] $source_module, Optional[String[1]] $target_module, Optional[String[1]] $dependency_tree)

Fails a compile if the system does not contain a correct version of the required module in the current environment.

Provides a message about exactly which version of the module is required.

Returns: None

source_module

Data type: String[1]

The name of the module containing the dependency information (usually the module that this function is being called from)

target_module

Data type: Optional[String[1]]

The target module to check. If not specified, all optional dependencies in the tree will be checked.

  • This may optionally be the full module name with the author in author/module form which allows for different logic paths that can use multiple vendor modules
dependency_tree

Data type: Optional[String[1]]

The root of the dependency tree in the module's metadata.json that contains the optional dependencies.

  • Nested levels should be separated by colons (:)

simplib::bracketize

Type: Ruby 4.x API

Add brackets to strings of IPv6 addresses and Arrays of IPv6 addresses based on the rules for bracketing IPv6 addresses.

Ignores anything that does not look like an IPv6 address and return those entries untouched.

simplib::bracketize(Array[String] $ip_arr)

The simplib::bracketize function.

Returns: Variant[String, Array[String]] converted input

ip_arr

Data type: Array[String]

The array of ipv6 to bracketize

simplib::bracketize(String $ipaddr_string)

The simplib::bracketize function.

Returns: Variant[String, Array[String]] converted input

ipaddr_string

Data type: String

The string of IPv6 addresses to bracketize (comma, space, and/or semi-colon separated)

simplib::deprecation

Type: Ruby 4.x API

Function to print deprecation warnings, logging a warning once for a given key.

Messages can be enabled if the SIMPLIB_LOG_DEPRECATIONS environment variable is set to 'true'

simplib::deprecation(String $key, String $message)

Function to print deprecation warnings, logging a warning once for a given key.

Messages can be enabled if the SIMPLIB_LOG_DEPRECATIONS environment variable is set to 'true'

Returns: Nil

key

Data type: String

Uniqueness key, which is used to dedupe messages.

message

Data type: String

Message to be printed, to which file and line information will be appended, if available.

simplib::dlookup

Type: Ruby 4.x API

A function for performing lookups targeted at ease of use with defined types.

Quite often you need to override something in an existing defined type and, presently, you have to do this by creating a resource collector and potentially ending up with unintended side-effects.

This function introduces the capability to consistently opt-in to a lookup syntax for overriding all parameters of a given defined type or parameters on a specific instance of a defined type.

This calls simplib::lookup under the hood after formatting the parameters appropriately but was split out in case the underlying syntax needs to change in the future.

There are two ways to call this method as shown in the following examples.

simplib::dlookup(String[1] $define_id, String[1] $param, Optional[Any] $options)

The literal unique identifier of the defined type resource ('mydef::global' in the examples)

Returns: Any The discovered data from Hiera

define_id

Data type: String[1]

param

Data type: String[1]

The parameter that you wish to look up

options

Data type: Optional[Any]

Hash of options for regular lookup()

  • This must follow the syntax rules for the Puppet lookup( [<NAME>], <OPTIONS HASH> ) version of lookup()
  • No other formats are supported!

simplib::dlookup(String[1] $define_id, String[1] $param, String[1] $resource_title, Optional[Any] $options)

The literal unique identifier of the defined type resource ('mydef::specific' in the examples)

Returns: Any The discovered data from Hiera

define_id

Data type: String[1]

param

Data type: String[1]

The parameter that you wish to look up

resource_title

Data type: String[1]

The $title of the resource

options

Data type: Optional[Any]

Hash of options for regular lookup()

  • This must follow the syntax rules for the Puppet lookup( [<NAME>], <OPTIONS HASH> ) version of lookup()
  • No other formats are supported!

simplib::filtered

Type: Ruby 4.x API

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)

simplib::filtered(Hash $options, Puppet::LookupContext $context)

The simplib::filtered function.

Returns: Hash

options

Data type: Hash

context

Data type: Puppet::LookupContext

simplib::filtered(String $key, Hash $options, Puppet::LookupContext $context)

The simplib::filtered function.

Returns: Hash

key

Data type: String

options

Data type: Hash

context

Data type: Puppet::LookupContext

simplib::gen_random_password

Type: Ruby 4.x API

Generates a random password string.

Terminates catalog compilation if the password cannot be created in the allotted time.

simplib::gen_random_password(Integer[8] $length, Optional[Integer[0,2]] $complexity, Optional[Boolean] $complex_only, Optional[Variant[Integer[0],Float[0]]] $timeout_seconds)

Generates a random password string.

Terminates catalog compilation if the password cannot be created in the allotted time.

Returns: String Generated password

Raises:

  • if password cannot be created within allotted time
length

Data type: Integer[8]

Length of the new password.

complexity

Data type: Optional[Integer[0,2]]

Specifies the types of characters to be used in the password

  • 0 => Use only Alphanumeric characters (safest)
  • 1 => Use Alphanumeric characters and reasonably safe symbols
  • 2 => Use any printable ASCII characters
complex_only

Data type: Optional[Boolean]

Use only the characters explicitly added by the complexity rules

timeout_seconds

Data type: Optional[Variant[Integer[0],Float[0]]]

Maximum time allotted to generate the password; a value of 0 disables the timeout

simplib::hash_to_opts

Type: Puppet Language

Turn a hash into a options string, for use in a shell command

`simplib::hash_to_opts(Hash[String,Variant[Array,String,Numeric,Boolean,Undef]] $input, Struct[{

Optional[connector] => String[1],
Optional[prefix]    => String[1],
Optional[repeat]    => Enum['comma','repeat'],
Optional[delimiter] => String[1],

}] $opts = {})`

Turn a hash into a options string, for use in a shell command

Returns: String

input

Data type: Hash[String,Variant[Array,String,Numeric,Boolean,Undef]]

Input hash, with Strings as keys and either a String, Array, Numeric, Boolean, or Undef as a value.

opts

Data type: Struct[{ Optional[connector] => String[1], Optional[prefix] => String[1], Optional[repeat] => Enum['comma','repeat'], Optional[delimiter] => String[1], }]

Options hash. It only takes 3 keys, none of them required:

  • connector: String that joins each key and value pair. Defaults to '='
  • prefix: String that prefixes each key value pair. Defaults to '--'
  • delimiter: When a value is an array, the string that is used to deliminate each item. Defaults to ','
  • repeat: Whether to return array values as a deliminated string, or by repeating the option with each unique value

simplib::host_is_me

Type: Ruby 4.x API

Detect if a local system identifier hostname/IPv4 address matches a specified hostname/IPv4 address or an entry in a list of hostnames and/or IPv4 addresses

simplib::host_is_me(Simplib::Host $host)

The simplib::host_is_me function.

Returns: Boolean true if a local system hostname/IPv4 address matches the specified host

host

Data type: Simplib::Host

Hostname/IPv4 address to compare against; 127.0.0.1 is never matched, use localhost instead

simplib::host_is_me(Array[Simplib::Host] $hosts)

The simplib::host_is_me function.

Returns: Boolean true if a local system hostname/IPv4 address matches any of the specified hosts

hosts

Data type: Array[Simplib::Host]

Array of Hostnames and/or IPv4 addresses to compare against; 127.0.0.1 is never matched, use localhost instead

simplib::in_bolt

Type: Puppet Language

Returns true if the run is active inside of Bolt and false otherwise.

Presently, this function is extremely basic. However, this check was placed here to allow us to update the check in the future without needing to modify more than one module or hunt down code.

simplib::in_bolt()

Returns true if the run is active inside of Bolt and false otherwise.

Presently, this function is extremely basic. However, this check was placed here to allow us to update the check in the future without needing to modify more than one module or hunt down code.

Returns: Boolean

simplib::inspect

Type: Puppet Language

Prints the passed variable's Ruby type and value for debugging purposes

This uses a Notify resource to print the information during the client run.

class my_test( String $var1, Hash $var2 ) { simplib::inspect('var1') simplib::inspect('var2') ... }

simplib::inspect(String $var_name, Enum['json','yaml', 'oneline_json'] $output_type = 'json')

Prints the passed variable's Ruby type and value for debugging purposes

This uses a Notify resource to print the information during the client run.

class my_test( String $var1, Hash $var2 ) { simplib::inspect('var1') simplib::inspect('var2') ... }

Returns: None

var_name

Data type: String

The actual name of the variable, fully scoped, as a String

output_type

Data type: Enum['json','yaml', 'oneline_json']

The format that you wish to use to display the output during the run. 'json' and 'yaml' result in multi-line message content. 'oneline_json' results in single-line message content.

simplib::ip_to_cron

Type: Ruby 4.x API

Transforms an IP address to one or more interval values for cron. This can be used to avoid starting a certain cron job at the same time on all servers.

simplib::ip_to_cron(Optional[Integer[1]] $occurs, Optional[Integer[1]] $max_value, Optional[IpToCronAlgorithm] $algorithm, Optional[Simplib::IP] $ip)

Transforms an IP address to one or more interval values for cron. This can be used to avoid starting a certain cron job at the same time on all servers.

Returns: Array[Integer] Array of integers suitable for use in the minute or hour cron field.

occurs

Data type: Optional[Integer[1]]

The occurrence within an interval, i.e., the number of values to be generated for the interval.

max_value

Data type: Optional[Integer[1]]

The maximum value for the interval. The values generated will be in the inclusive range [0, max_value].

algorithm

Data type: Optional[IpToCronAlgorithm]

When 'ip_mod', the modulus of the IP number is used as the basis for the returned values. This algorithm works well to create cron job intervals for multiple hosts, when the number of hosts exceeds the max_value and the hosts have largely, linearly- assigned IP addresses.

When 'sha256', a random number generated using the IP address string is the basis for the returned values. This algorithm works well to create cron job intervals for multiple hosts, when the number of hosts is less than the max_value or the hosts do not have linearly-assigned IP addresses.

ip

Data type: Optional[Simplib::IP]

The IP address to use as the basis for the generated values. When nil, the 'ipaddress' fact (IPv4) is used.

simplib::ipaddresses

Type: Ruby 4.x API

Return an Array of all IPv4 addresses known to be associated with the client, optionally excluding local addresses.

simplib::ipaddresses(Optional[Boolean] $only_remote)

Return an Array of all IPv4 addresses known to be associated with the client, optionally excluding local addresses.

Returns: Array[String] List of IP addresses for the client

only_remote

Data type: Optional[Boolean]

Whether to exclude local addresses from the return value (e.g., '127.0.0.1').

simplib::join_mount_opts

Type: Ruby 4.x API

Merge two sets of mount options in a reasonable fashion, giving precedence to the second set.

simplib::join_mount_opts(Array[String] $system_mount_opts, Array[String] $new_mount_opts)

Merge two sets of mount options in a reasonable fashion, giving precedence to the second set.

Returns: String Merged options string in which new_mount_opts mount options take precedence; options are comma delimited

system_mount_opts

Data type: Array[String]

System mount options

new_mount_opts

Data type: Array[String]

New mount options, which will override system_mount_opts when there are conflicts

simplib::knockout

Type: Puppet Language

uses the knockout prefix of '--' to remove elements from an array.

simplib::knockout(Array $array)

uses the knockout prefix of '--' to remove elements from an array.

Returns: Array Resulting array.

array

Data type: Array

The array to knockout

simplib::ldap::domain_to_dn

Type: Puppet Language

Generates a LDAP Base DN from a domain

simplib::ldap::domain_to_dn(String $domain = $facts['domain'], Boolean $downcase_attributes = false)

Generates a LDAP Base DN from a domain

Returns: String

domain

Data type: String

The domain to convert, defaults to the domain fact

downcase_attributes

Data type: Boolean

Whether to downcase the LDAP attributes

  • Different tools have bugs where they cannot, handle both upcased and downcased LDAP attribute elements

simplib::lookup

Type: Ruby 4.x API

A function for falling back to global scope variable lookups when the Puppet 4 lookup() function cannot find a value.

While lookup() will stop at the back-end data sources, simplib::lookup() will check the global scope first to see if the variable has been defined.

This means that you can pre-declare a class and/or use an ENC and look up the variable whether it is declared this way or via Hiera or some other back-end.

simplib::lookup(String $param, Optional[Any] $options)

A function for falling back to global scope variable lookups when the Puppet 4 lookup() function cannot find a value.

While lookup() will stop at the back-end data sources, simplib::lookup() will check the global scope first to see if the variable has been defined.

This means that you can pre-declare a class and/or use an ENC and look up the variable whether it is declared this way or via Hiera or some other back-end.

Returns: Any The value that is found in the system for the passed parameter.

param

Data type: String

The parameter that you wish to look up

options

Data type: Optional[Any]

Hash of options for regular lookup()

  • This must follow the syntax rules for the Puppet lookup( [<NAME>], <OPTIONS HASH> ) version of lookup()
  • No other formats are supported!

simplib::mock_data

Type: Ruby 4.x API

A mock data function

simplib::mock_data(Hash $options, Puppet::LookupContext $context)

The simplib::mock_data function.

Returns: Any

options

Data type: Hash

context

Data type: Puppet::LookupContext

simplib::mock_data(String $key, Hash $options, Puppet::LookupContext $context)

The simplib::mock_data function.

Returns: Any

key

Data type: String

options

Data type: Hash

context

Data type: Puppet::LookupContext

simplib::module_exist

Type: Ruby 4.x API

Determines if a module exists in the current environment

If passed with an author, such as simp/simplib or simp-simplib, will return whether or not that specific module exists.

simplib::module_exist(String[1] $module_name)

Determines if a module exists in the current environment

If passed with an author, such as simp/simplib or simp-simplib, will return whether or not that specific module exists.

Returns: Boolean Whether or not the module exists in the current environment

module_name

Data type: String[1]

The module name to check

simplib::nets2cidr

Type: Ruby 4.x API

Take an input list of networks and returns an equivalent Array in CIDR notation.

  • Hostnames are passed through untouched.
  • Terminates catalog compilation if any input item is not a valid network or hostname.

simplib::nets2cidr(String $network_list)

The simplib::nets2cidr function.

Returns: Array[String] Array of networks in CIDR notation

network_list

Data type: String

List of 1 or more networks separated by spaces, commas, or semicolons

simplib::nets2cidr(Array $networks)

The simplib::nets2cidr function.

Returns: Array[String] Array of networks in CIDR notation

networks

Data type: Array

Array of networks

simplib::nets2ddq

Type: Ruby 4.x API

Tranforms a list of networks into an equivalent array in dotted quad notation.

  • CIDR networks are converted to dotted quad notation networks. IP addresses and hostnames are left untouched.
  • Terminates catalog compilation if any input item is not a valid network or hostname.

simplib::nets2ddq(Array $networks)

The simplib::nets2ddq function.

Returns: Array[String] Converted input

networks

Data type: Array

The networks to convert

simplib::nets2ddq(String $networks_string)

The simplib::nets2ddq function.

Returns: Array[String] Converted input

networks_string

Data type: String

String containing the list of networks to convert; list elements are separated by spaces, commas or semicolons.

simplib::parse_hosts

Type: Ruby 4.x API

Convert an Array of items that may contain port numbers or protocols into a structured Hash of host information.

  • Works with Hostnames as well as IPv4 and IPv6 addresses.

  • IPv6 addresses will be returned normalized with square brackets around them for clarity.

  • Terminates catalog compilation if

    • A valid network or hostname cannot be extracted from all input items.
    • Any input item that contains a port specifies an invalid port.

simplib::parse_hosts(Array[String[1],1] $hosts)

Convert an Array of items that may contain port numbers or protocols into a structured Hash of host information.

  • Works with Hostnames as well as IPv4 and IPv6 addresses.

  • IPv6 addresses will be returned normalized with square brackets around them for clarity.

  • Terminates catalog compilation if

    • A valid network or hostname cannot be extracted from all input items.
    • Any input item that contains a port specifies an invalid port.

Returns: Hash Structured Hash of the host information

Raises:

  • if a valid network or hostname cannot be extracted from all input items
  • if any input item that contains a port specifies an invalid port
hosts

Data type: Array[String[1],1]

Array of host entries, where each entry may contain a protocol or both a protocol and port

simplib::passgen

Type: Ruby 4.x API

Generates/retrieves a random password string or its hash for a passed identifier.

  • Uses Puppet.settings[:vardir]/simp/environments/$environment/simp_autofiles/gen_passwd/ as the destination directory for password storage.
  • The minimum length password that this function will return is 8 characters.
  • Terminates catalog compilation if the password storage directory cannot be created/accessed by the Puppet user, the password cannot be created in the allotted time, or files not owned by the Puppet user are present in the password storage directory.

simplib::passgen(String[1] $identifier, Optional[Hash] $modifier_hash)

Generates/retrieves a random password string or its hash for a passed identifier.

  • Uses Puppet.settings[:vardir]/simp/environments/$environment/simp_autofiles/gen_passwd/ as the destination directory for password storage.
  • The minimum length password that this function will return is 8 characters.
  • Terminates catalog compilation if the password storage directory cannot be created/accessed by the Puppet user, the password cannot be created in the allotted time, or files not owned by the Puppet user are present in the password storage directory.

Returns: String Password or password hash specified. If no modifier_hash or an invalid modifier_hash is provided, it will return the currently stored/generated password.

identifier

Data type: String[1]

Unique String to identify the password usage.

modifier_hash

Data type: Optional[Hash]

Options Hash. May include 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 private options:
  • password => contains the string representation of the password to hash (used for testing)
  • salt => contains the string literal salt to use (used for testing)
  • complex_only => use only the characters explicitly added by the complexity rules (used for testing)

simplib::rand_cron

Type: Ruby 4.x API

Transforms an input string to one or more interval values for cron. This can be used to avoid starting a certain cron job at the same time on all servers.

simplib::rand_cron(String $modifier, RandCronAlgorithm $algorithm, Optional[Integer[1]] $occurs, Optional[Integer[1]] $max_value)

Transforms an input string to one or more interval values for cron. This can be used to avoid starting a certain cron job at the same time on all servers.

Returns: Array[Integer] Array of integers suitable for use in the minute or hour cron field.

modifier

Data type: String

The input string to use as the basis for the generated values.

algorithm

Data type: RandCronAlgorithm

Randomization algorithm to apply to transform the input string.

When 'sha256', a random number generated from the input string via sha256 is used as the basis for the returned values. If the input string is an IP address, this algorithm works well to create cron job intervals for multiple hosts, when the number of hosts is less than the max_value or the hosts do not have linearly-assigned IP addresses.

When 'ip_mod' and the input string is an IP address, the modulus of the numeric IP is used as the basis for the returned values. This algorithm works well to create cron job intervals for multiple hosts, when the number of hosts exceeds the max_value and the hosts have linearly-assigned IP addresses.

When 'ip_mod' and the input string is not an IP address, for backward compatibility, the crc32 of the input string will be used as the basis for the returned values.

When 'crc32', the crc32 of the input string will be used as the basis for the returned values.

occurs

Data type: Optional[Integer[1]]

The occurrence within an interval, i.e., the number of values to be generated for the interval. Defaults to 1.

max_value

Data type: Optional[Integer[1]]

The maximum value for the interval. The values generated will be in the inclusive range [0, max_value]. Defaults to 60 for use in the minute cron field.

simplib::simp_version

Type: Ruby 4.x API

Return the version of SIMP that this server is running or "unknown\n"

simplib::simp_version(Optional[Boolean] $strip_whitespace)

Return the version of SIMP that this server is running or "unknown\n"

Returns: String Version string if the version can be detected; "unknown\n" otherwise

strip_whitespace

Data type: Optional[Boolean]

Whether to strip whitespace from the version string. Without stripping, the string may end with a "\n"

simplib::strip_ports

Type: Ruby 4.x API

Extract list of unique hostnames and/or IP addresses from an Array of hosts, each of which may may contain protocols and/or port numbers

Terminates catalog compilation if

  • A valid network or hostname cannot be extracted from all input items.
  • Any input item that contains a port specifies an invalid port.

simplib::strip_ports(Array[String[1],1] $hosts)

Extract list of unique hostnames and/or IP addresses from an Array of hosts, each of which may may contain protocols and/or port numbers

Terminates catalog compilation if

  • A valid network or hostname cannot be extracted from all input items.
  • Any input item that contains a port specifies an invalid port.

Returns: Array[String] Non-port portion of hostnames

Raises:

  • if any input item that contains a port specifies an invalid port
hosts

Data type: Array[String[1],1]

List of hosts which may contain protocols and port numbers.

simplib::to_integer

Type: Ruby 4.x API

Converts the argument into an Integer.

Terminates catalog compilation if the argument's class does not respond to the to_i() Ruby method.

simplib::to_integer(Any $input)

Converts the argument into an Integer.

Terminates catalog compilation if the argument's class does not respond to the to_i() Ruby method.

Returns: Integer Converted input

Raises:

  • if input does not implement a to_i() method
input

Data type: Any

The argument to convert into an Integer

simplib::to_string

Type: Ruby 4.x API

Converts the argument into a String.

simplib::to_string(Any $input)

Converts the argument into a String.

Returns: String Converted input

input

Data type: Any

The argument to convert into a String

simplib::validate_array_member

Type: Ruby 4.x API

Validate that an single input is a member of another Array or an Array input is a subset of another Array.

  • The comparison can optionally ignore the case of String elements.
  • Terminates catalog compilation if validation fails.

simplib::validate_array_member(Variant[SimpleTypes,Array[SimpleTypes]] $input, Array[SimpleTypes] $target, Optional[Enum['i']] $modifier)

Validate that an single input is a member of another Array or an Array input is a subset of another Array.

  • The comparison can optionally ignore the case of String elements.
  • Terminates catalog compilation if validation fails.

Returns: Nil

Raises:

  • if validation fails
input

Data type: Variant[SimpleTypes,Array[SimpleTypes]]

Input to find within the target

target

Data type: Array[SimpleTypes]

modifier

Data type: Optional[Enum['i']]

Modification to be made to the comparison operation. Currently, 'i', string case invariance is the only supported modifier.

simplib::validate_between

Type: Ruby 4.x API

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

Terminates catalog compilation if validation fails.

simplib::validate_between(Variant[String[1],Numeric] $value, Numeric $min_value, Numeric $max_value)

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

Terminates catalog compilation if validation fails.

Returns: Nil

Raises:

  • if validation fails
value

Data type: Variant[String[1],Numeric]

Value to validate

min_value

Data type: Numeric

Minimum value that is valid

max_value

Data type: Numeric

Maximum value that is valid

simplib::validate_bool

Type: Ruby 4.x API

Validate that all passed values are either true, 'true', false or 'false'.

Terminates catalog compilation if validation fails.

simplib::validate_bool(Variant[String,Boolean] *$values_to_validate)

Validate that all passed values are either true, 'true', false or 'false'.

Terminates catalog compilation if validation fails.

Returns: Nil

Raises:

  • if validation fails
*values_to_validate

Data type: Variant[String,Boolean]

One or more values to validate

simplib::validate_deep_hash

Type: Ruby 4.x API

Perform a deep validation on two passed Hashes.

  • All keys must be defined in the reference Hash that is being validated against.
  • Unknown keys in the Hash being compared will cause a failure in validation
  • All values in the final leaves of the 'reference 'Hash' must be a String, Boolean, or nil.
  • All values in the final leaves of the Hash being compared must support a to_s() method.
  • Terminates catalog compilation if validation fails.

simplib::validate_deep_hash(Hash $reference, Hash $to_check)

Perform a deep validation on two passed Hashes.

  • All keys must be defined in the reference Hash that is being validated against.
  • Unknown keys in the Hash being compared will cause a failure in validation
  • All values in the final leaves of the 'reference 'Hash' must be a String, Boolean, or nil.
  • All values in the final leaves of the Hash being compared must support a to_s() method.
  • Terminates catalog compilation if validation fails.

Returns: Nil

Raises:

  • if validation fails
reference

Data type: Hash

Hash to validate against. Keys at all levels of the hash define the structure of the hash and the value at each final leaf in the hash tree contains a regular expression string, a boolean or nil for value validation:

  • When the validation value is a regular expression string, the string representation of the to_check value (from the to_s() method) will be compared to the regular expression contained in the reference string.

  • When the validation value is a Boolean, the string representation of the to_check value will be compared with the string representation of the Boolean (as provided by the to_s() method).

  • When the validation value is a nil or 'nil', no value validation will be done for the key.

  • When the to_check value contains an Array of values for a key, the validation for that key will be applied to each element in that array.

to_check

Data type: Hash

Hash to be validated against the reference

simplib::validate_net_list

Type: Ruby 4.x API

Validate that a passed list (Array or single String) of networks is filled with valid IP addresses, network addresses (CIDR notation), or hostnames.

  • Hostnames are checked per RFC 1123.
  • Ports appended with # a colon : are allowed for hostnames and individual IP addresses.
  • Terminates catalog compilation if validation fails.

simplib::validate_net_list(String $net, Optional[String] $str_match)

The simplib::validate_net_list function.

Returns: Nil

net

Data type: String

Single network to be validated.

str_match

Data type: Optional[String]

Stringified regular expression (regex without the // delimiters)

simplib::validate_net_list(Array[String] $net_list, Optional[String] $str_match)

The simplib::validate_net_list function.

Returns: Nil

net_list

Data type: Array[String]

Array of networks to be validated.

str_match

Data type: Optional[String]

Stringified regular expression (regex without the // delimiters)

simplib::validate_port

Type: Ruby 4.x API

Validates whether each passed argument contains valid port(s).

  • Each element of each argument must, numerically, be in the range [1, 65535].
  • Terminates catalog compilation if validation fails.

simplib::validate_port(Variant[String[1],Integer,StringOrIntegerArray] *$port_args)

Validates whether each passed argument contains valid port(s).

  • Each element of each argument must, numerically, be in the range [1, 65535].
  • Terminates catalog compilation if validation fails.

Returns: Nil

Raises:

  • if validation fails
*port_args

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

Arguments each of which contain either an individual port or an array of ports.

simplib::validate_re_array

Type: Ruby 4.x API

Perform simple validation of a String, or Array of Strings, against one or more regular expressions.

  • Derived from the Puppet Labs stdlib validate_re.
  • Terminates catalog compilation if validation fails.

simplib::validate_re_array(String $input, String $regex, Optional[String] $err_msg)

The simplib::validate_re_array function.

Returns: Nil

input

Data type: String

String to be validated

regex

Data type: String

Stringified regex expression (regex without the // delimiters)

err_msg

Data type: Optional[String]

Optional error message to emit upon failure

simplib::validate_re_array(String $input, Array $regex_list, Optional[String] $err_msg)

The simplib::validate_re_array function.

Returns: Nil

input

Data type: String

String to be validated

regex_list

Data type: Array

Array of stringified regex expressions ( regexes without the // delimiters)

err_msg

Data type: Optional[String]

Optional error message to emit upon failure

simplib::validate_re_array(Array $inputs, String $regex, Optional[String] $err_msg)

The simplib::validate_re_array function.

Returns: Nil

inputs

Data type: Array

Array of strings to be validated

regex

Data type: String

Stringified regex expression (regex without the // delimiters)

err_msg

Data type: Optional[String]

Optional error message to emit upon failure

simplib::validate_re_array(Array $inputs, Array $regex_list, Optional[String] $err_msg)

The simplib::validate_re_array function.

Returns: Nil

inputs

Data type: Array

Array of strings to be validated

regex_list

Data type: Array

Array of stringified regex expressions ( regexes without the // delimiters)

err_msg

Data type: Optional[String]

Optional error message to emit upon failure

simplib::validate_sysctl_value

Type: Ruby 4.x API

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

  • If a key is not known, assumes the value is valid.
  • Terminates catalog compilation if validation fails.

simplib::validate_sysctl_value(String $key, NotUndef $value)

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

  • If a key is not known, assumes the value is valid.
  • Terminates catalog compilation if validation fails.

Returns: Nil

Raises:

  • upon validation failure
key

Data type: String

sysctl setting whose value is to be validated

value

Data type: NotUndef

Value to be validated

simplib::validate_uri_list

Type: Ruby 4.x API

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

  • Caution: No scheme (protocol type) validation is done if the scheme_list parameter is not set.
  • Terminates catalog compilation if validation fails.

simplib::validate_uri_list(String[1] $uri, Optional[Array[String]] $scheme_list)

The simplib::validate_uri_list function.

Returns: Nil

uri

Data type: String[1]

URI to be validated.

scheme_list

Data type: Optional[Array[String]]

List of schemes (protocol types) allowed for the URI.

simplib::validate_uri_list(Array[String[1],1] $uri_list, Optional[Array[String]] $scheme_list)

The simplib::validate_uri_list function.

Returns: Nil

uri_list

Data type: Array[String[1],1]

1 or more URIs to be validated.

scheme_list

Data type: Optional[Array[String]]

List of schemes (protocol types) allowed for the URI.

simplib_deprecation

Type: Ruby 3.x API

Function to print deprecation warnings for 3.X functions. The first argument is the uniqueness key, which allows deduping of messages. The second argument is the message to be printed. Messages can be enabled if the SIMPLIB_LOG_DEPRECATIONS environment variable is set to 'true'.

simplib_deprecation()

Function to print deprecation warnings for 3.X functions. The first argument is the uniqueness key, which allows deduping of messages. The second argument is the message to be printed. Messages can be enabled if the SIMPLIB_LOG_DEPRECATIONS environment variable is set to 'true'.

Returns: Nil

slice_array

Type: Ruby 3.x API

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.

slice_array(Array $to_slice, Integer $max_length, String[1,1] $split_char)

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.

Returns: Array[Array[Any] Array[Array[Any]

to_slice

Data type: Array

The array to slice. This will be flattened if necessary.

max_length

Data type: Integer

The maximum length of each slice.

split_char

Data type: String[1,1]

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

strip_ports

Type: Ruby 3.x API

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

strip_ports(Array[String] $hosts)

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

Returns: Array[Str Array[Str

hosts

Data type: Array[String]

Array of hostnames which may contain port numbers.

to_integer

Type: Ruby 3.x API

Converts the argument into an Integer.

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

to_integer(Any $input)

Converts the argument into an Integer.

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

Returns: Any [

input

Data type: Any

The argument to convert into an Integer

to_string

Type: Ruby 3.x API

Converts the argument into a String.

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

to_string(Any $input)

Converts the argument into a String.

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

Returns: Any

input

Data type: Any

The argument to convert into a String

validate_array_member

Type: Ruby 3.x API

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.

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.

Returns: Boolean

validate_array_of_hashes

Type: Ruby 3.x API

Validate that the passed argument is either an empty Array or an Array that only contains Hashes.

validate_array_of_hashes()

Validate that the passed argument is either an empty Array or an Array that only contains Hashes.

Returns: Boolean

validate_between

Type: Ruby 3.x API

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

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

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

Type: Ruby 3.x API

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.

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.

Returns: Nil

validate_deep_hash

Type: Ruby 3.x API

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 nil top skip an entry.

Arrays of values will match each entry to the given regular expression.

All keys must be defined in the source Hash that is being validated against.

Unknown keys in the Hash being compared will cause a failure in validation

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 nil top skip an entry.

Arrays of values will match each entry to the given regular expression.

All keys must be defined in the source Hash that is being validated against.

Unknown keys in the Hash being compared will cause a failure in validation

Returns: Nil

validate_float

Type: Ruby 3.x API

Validates whether or not the passed argument is a float

validate_float()

Validates whether or not the passed argument is a float

Returns: N N

validate_macaddress

Type: Ruby 3.x API

Validate that all passed values are valid MAC addresses.

validate_macaddress()

Validate that all passed values are valid MAC addresses.

Returns: Nil

validate_net_list

Type: Ruby 3.x API

Validate that a passed list (Array or single String) of networks is filled with valid IP addresses or hostnames. Hostnames are checked per RFC 1123. 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.

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 RFC 1123. 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.

Returns: Nil

validate_port

Type: Ruby 3.x API

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

validate_port()

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

Returns: N N

validate_re_array

Type: Ruby 3.x API

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.

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.

Returns: Nil

validate_sysctl_value

Type: Ruby 3.x API

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

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

validate_sysctl_value()

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

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

Returns: Nil

validate_umask

Type: Ruby 3.x API

Validate that the passed String is a valid umask

validate_umask()

Validate that the passed String is a valid umask

Returns: Nil

validate_uri_list

Type: Ruby 3.x API

Usage: validate_uri_list([LIST],[<VALID_SCHEMES>])

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

validate_uri_list()

Usage: validate_uri_list([LIST],[<VALID_SCHEMES>])

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

Returns: Nil

You can’t perform that action at this time.