Standard

table of contents

1. module description – what the module does and why it is useful
2. setup – the basics of getting started with standard
   • what standard affects
   • setup requirements
   • beginning with standard
3. limitations – OS compatibility, etc.
4. development – guide for contributing to the module

module description

• This module provides a select collection of standardized functions and data types within the Puppet ® ecosystem. If you are familiar with the referenced standards, e. g. POSIX™ or RFC number so-and-so, you will know how something works. Minor extensions that amount to de-facto standards are provided, too, and there are some bonus templates.
• “You write code for humans.” Identifiers are kept human-readable: No abbreviations are used. Particularly in a large code base the function of objects should be apparent without consulting other sources.

setup

what standard affects

The standard module affects nothing (except occupying the standard identifier/namespace, duh!).

setup requirements

There are no setup requirements.

beginning with standard

Simply put the module data at its right location and use the functions, data types or templates it provides. There are no manifests. You cannot include this module.

limitations

The standard module has a number of limitations:

• Implementation limitations are documented in the reference.md.
• There is no Standard::InternetProtocolVersion6address data type. ☹
• Not everything that was desired/considered for inclusion is indeed formally standardized.
• Standards that focus on one operating system are deliberately ignored (e. g. ISO/IEC 23360‑* “Linux Standard Base”).

development

• Make your case (how is something useful for a system managed by Puppet), reference specific sections of standards, if possible provide implementation and documentation, and do not forgot a copyright statement (public domain) in the commit message(s) of any commit(s) you may provide.
• Note, this module focuses on free open-source systems. Access to standards needs to be royalty-free (cmp. ISO standards).

reference

For quick reference an example value has been provided too:

1. data types
   • Standard::AbsoluteDirectoryName – '/.'
   • Standard::AbsolutePathname – '/dev/urandom'
   • Standard::Filemode – 01755
   • Standard::Filename – '.'
   • Standard::FQDN – 'puppet.com.'
   • Standard::FullyQualifiedDomainName – 'puppetlabs.com.'
   • Standard::InternetProtocolVersion4address – 134743044
   • Standard::Line – "Hello world!\n"
   • Standard::NormalizedPortableAbsolutePathname – '/dev/null'
   • Standard::OrdinaryPortableFilename – 'rc.conf'
   • Standard::OrdinaryPortableFilenameDictionary – {'abc' => 'def'}
   • Standard::PartiallyQualifiedDomainName – 'puppetlabs.com'
   • Standard::Pathname – '.profile'
   • Standard::PortableAbsoluteDirectoryName – '/etc/.'
   • Standard::PortableAbsolutePathname – '/dev//urandom'
   • Standard::PortableFilename – '..'
   • Standard::PortableGroupName – 'wheel'
   • Standard::PortablePathname – '.profile'
   • Standard::PortableRelativePathname – '..'
   • Standard::PortableUserName – 'root'
   • Standard::PQDN – 'puppet.com'
   • Standard::ShellCommandLanguageName – 'LC_ALL'
   • Standard::SpecialFilename – '..'
   • Standard::SpecialPortableFilename – '..'
   • Standard::SymbolicFileMode – 'u=rwx,go=rx'
   • Standard::SystemErrorLogFacility – 'LOG_DAEMON'
   • Standard::SystemErrorLogPriority – 'LOG_ERR'
2. functions
   • standard::directory_name – '/'
   • standard::dotted_decimal – '123.456.789'
   • standard::internet_protocol_version_4_address – 134743044
3. templates
   • standard/shell_variable_assignments.epp – 'VARIABLE=word'

data types

Standard::AbsoluteDirectoryName

description:

• This is like Standard::AbsolutePathname except that it must end with slash-dot (/.) thus (unambiguously) identifying a directory.
• Some authors use just a trailing slash to denote directories. This distinguishes a symbolic link (i. e. the file that implements the symbolic link) vs. the resolved symbolic link (i. e. the target a symbolic link points to). If the resolved symbolic link does not point to a directory, an error is emitted.
• The final dot is added so that the standardized dirname utility (return the directory portion of a pathname) returns the directory file name.

examples:

• '/.'

compliance:

• POSIX.1-2017
  • The notion of “absolute directory name” is not mentioned explicitly.
  • ✘ Pathnames ending on '/..' are not accepted. It is assessed to be more likely a mistake.

Standard::AbsolutePathname

description:

• This is Standard::Pathname except that it must start with one or more than two slashes (/).

examples:

• '/x/y/z'
• '/home/example_user/文件'
• '////'

compliance:

• POSIX.1-2017
  • ✔ begins with one or more than two slash (/) characters

Standard::Filemode

description:

• A filemode is either a non-negative Integer ≤ 7777₈ or Standard::SymbolicFilemode.

example:

• 0644

compliance:

• POSIX.1-2017
  • ✔ the Integer variant corresponds to mode_t

Standard::Filename

description:

• A filename is a non-empty sequence of bytes excluding the values for NUL and slash (/).

examples:

• 'Meine Überdatei²'
• "Robert'); DROP TABLE Students;"

compliance:

• POSIX.1-2017
  • ✔ Note this data type cannot observe the NAME_MAX length limit. On a POSIX-compliant system this value is at least 14 (fourteen) bytes.

Standard::FullyQualifiedDomainName

description:

• This data type provides a very limited subset of possible FQDNs. It is a String data type implemented via regular expressions. It matches up to five labels plus a final empty label (the root label). Labels are separated from each other by a single dot (.).
• A label is a non-empty sequence of up to 63 ASCII letters or digits (A – Z, a – z, 0 – 9).
  • The first character must be a letter.
  • In the middle dashes (-) may appear too.
• The entire string’s length may not exceed 255 characters. Due to the implementation via regular expressions (as a compromise) the labels’ maximum length varies if five labels need to be specified (57, 56, 56, 56, 24). The limits are subject to adjustment.
• In many contexts in fact a fully-qualified domain name is expected but the terminating separator for the root label is treated as an error. Use the built-in chop function to remove the root label separator, or use Standard::PartiallyQualifiedDomainName if a (as in any) PQDN is acceptable, too.

examples:

• 'forge.puppet.com.'
• 'xn--7qv.xn--ses554g.'
• '1.0.0.127.IN-ADDR.ARPA.'

limited compliance:

• RFC 1035
  • ✔ “The domain name terminates with the zero length octet for the null label of the root.”
  • ✔ Labels are composed of ASCII letters and digits.
  • ✔ “The labels must follow the rules for ARPANET host names. They must start with a letter, end with a letter or digit, and have as interior characters only letters, digits, and hyphen.”
  • ✔ “Labels must be 63 characters or less.”
  • ✔ “[…] the total length of a domain name […] is restricted to 255 octets or less.”
  • ✔ “IN-ADDR.ARPA domain”
  • ✘ Standard::FullyQualifiedDomainName is capped to to six labels (including the root label). Technically it ought to be possible to accept up to 127 labels.

Standard::FQDN

description:

• This is an alias for Standard::FullyQualifiedDomainName. If the context implies the meaning of the acronym FQDN, you may use this identifier. However, its removal (e. g. outsourcing to a different module focusing on network management) is considered.

Standard::InternetProtocolVersion4address

description:

• This is a non-negative integer less than 2³².

examples:

• 2130706433
• 0xFEDCBA98

compliance:

• POSIX.1-2017
  • ✔ corresponds to in_addr_t (which is equivalent to uint32_t)
• RFC 791
  • Standard::InternetProtocolVersion4address is at least a 32-bit quantity.

Standard::Line

description:

• A line is a possibly empty sequence of non-newline characters concluding with a single newline character.

example:

• "Hello world!\n"

compliance:

• POSIX.1-2017

Standard::NormalizedPortableAbsolutePathname

description:

• This is Standard::PortableAbsolutePathname, but it may not contain consecutive slash characters.
• It has not yet been decided whether this application case should be implemented via a custom data type (a regular expression to be precise) or whether a (set of) function(s) would be more adequate. Deliberation is mainly driven by considering which situations should lead to a catalog compilation failure. Evidently '/foo///bar' is a valid pathname and will be accepted by the operating system.

Standard::OrdinaryPortableFilename

description:

• The filenames '.' and '..' are special (conveying same directory and parent directory respectively). This data type is Standard::PortableFilename but it does not match said special filenames.

example:

• 'rc.conf'

limited compliance:

• POSIX.1-2017
  • The notion of “ordinary portable filename” is not expressly defined.
  • This data type cannot observe the NAME_MAX limit (the minimum is 14).

Standard::OrdinaryPortableFilenameDictionary

description:

• This is merely a Hash that has Standard::OrdinaryPortableFilename both as key and value.

examples:

• {}
• {'std' => 'standard'}

no compliance:

• This is a convenience definition not backed by specfic standard definitions.

Standard::PartiallyQualifiedDomainName

description:

• This is Standard::FullyQualifiedDomainName but a final dot must be absent. Accordingly the length is capped at 254 characters.
• To be logically consistent IN-ADDR.ARPA addresses are not available. The root domain (that is the string '.') cannot be specified either.

examples:

• 'www.example.com'
• 'forge.puppet.com'

compliance:

• See Standard::FullyQualifiedDomainName with the exception of a final dot in mind.

Standard::PQDN

description:

• This is an alias for Standard::PartiallyQualifiedDomainName. If the context implies the meaning of the acronym PQDN, you may use this identifier.
• Notice: A removal (outsourcing to a different module focusing on network management) is considered.

Standard::Pathname

description:

• This is a String data type. Strings must be non-empty.
• A terminating NUL character is implicit and must not be indicated.

example:

• 'קובץ'

compliance:

• POSIX.1-2017
  • ✔ Note, there is no observance of PATH_MAX. On a POSIX-compliant systems this is at least 256 bytes.

Standard::PortableAbsoluteDirectoryName

description:

• This is like Standard::PortableAbsolutePathname except that it must end with slash-dot (/.) thus (unambiguously) identifying a directory.
• Some authors use just a trailing slash to denote directories. This distinguishes a symbolic link (i. e. the file that implements the symbolic link) vs. the resolved symbolic link (i. e. the target a symbolic link points to). If the resolved symbolic link does not point to a directory, an error is emitted.
• The final dot is added so that the standardized dirname utility (return the directory portion of a pathname) returns the directory file name.

examples:

• '/etc/rc.conf.d/.'

compliance:

• POSIX.1-2017
  • The notion of “portable absolute directory name” is not mentioned explicitly.
  • ✘ Pathnames ending with '/..' are not accepted. It is assessed to be more likely a mistake.

Standard::PortableAbsolutePathname

description:

• This is Standard::PortablePathname except that it must start with one or more than two slashes (/).

examples:

• '/var/log//kern.log'

compliance:

• POSIX.1-2017
  • ✔ begins with one or more than two slash (/) characters

Standard::PortableFilename

description:

• Filenames are a non-empty sequence of characters except slashes and NUL-characters. This data type is restricted to the “portable filename character set” thus only modern Latin alphabet letters, Western-Arabic digits, underscores, dots, and dashes are accepted.
• Note, filenames starting with a dash (-) are accepted. They may cause troubles on the command line interface if supplied as the first component of a working-directory-relative pathname.

examples:

• '..'
• 'crash.dump'

compliance:

• POSIX.1-2017
  • ✔ Note this data type cannot observe the NAME_MAX length limit. On a POSIX-compliant system this value is at least 14 (fourteen) bytes.

Standard::PortablePathname

description:

• A portable pathname is a Standard::Pathname restricted to the portable filename character set and slash characters. A terminating NUL character is not indicated.

examples:

• '//proxy

compliance:

• POSIX.1-2017
  • ✔ with the consideration of NUL characters

Standard::PortableGroupName

description:

• This is identical to Standard::PortableUserName. This data type is primarily provided for documentation purposes.

example:

• 'wheel'

compliance:

• POSIX.1-2017

Standard::PortableRelativePathname

description:

• This is Standard::PortablePathname except that it may not start with a slash.

examples:

• './reference.md'
• 'puppet/../..'

compliance:

• POSIX.1-2017
  • ✔ does not begin a slash (/) character

Standard::PortableUserName

description:

• A portable user name is a non-empty string composed of ASCII letters and digits, dots, underscores, and dashes. The first character may not be a dash. (A leading dash usually indicates an option in the command-line interface.)

example:

• 'puppet'

compliance:

• POSIX.1-2017
  • ✔ Note that the LOGIN_NAME_MAX length limit cannot be observed. On a POSIX-compliant system this limit permits at least 8 characters for a user name. For maximum portability cap your user names at eight characters.

Standard::ShellCommandLanguageName

description:

• A name in the (POSIX) shell command language. It consists of a non-empty sequence of modern Latin alphabet characters, Western-Arabic digits, and underscores. The first character, however, may not be a digit.

examples:

• 'foobar'
• 'LD_SHOW_AUXV'

compliance:

• POSIX.1-2017
  • ✔ fully-compliant to “name” as specified in the Base Definitions

Standard::SpecialFilename

description:

• The file names '.' and '..' have special meaning conveying current directory or parent directory respectively.
• This data type is primarily provided for meaningful =~ data type matching.

  if $my_value =~ Standard::SpecialFilename { fail('$my_value may not be special.') }
  

all values:

• '.'
• '..'

compliance:

• POSIX.1-2017
  • the category of special file name is inferred

Standard::SpecialPortableFilename

description:

• This is an alias for Standard::SpecialFilename. However, use of this identifier can be deemed confusing since “portable” does not add any quality to the permitted values. It is only provided to supply an orthogonal set of identifiers.

Standard::SymbolicFileMode

description:

• A spelled out file mode description suitable as mode attribute of a file resource or for tools such as chmod.

example:

• 'u=rw,go=r' (the owning user has read and write permissions, the owning group and others have read permissions)

compliance:

• POSIX.1-2017
  • ✔ fully-compliant to symbolic_mode described in chmod.

Standard::SystemErrorLogFacility

description:

• A symbolic constant name for a system error log facility.

example:

• 'LOG_DAEMON'

compliance:

• POSIX.1-2017
  • The Puppet ® data type matches string values, but should be identifiers.

Standard::SystemErrorLogPriority

description:

• A symbolic constant name for a system error log priority.

example:

• 'LOG_DEBUG'

compliance:

• POSIX.1-2017
  • The Puppet ® data type matches string values, but should be identifiers.

functions

standard::directory_name

description:

• This is a wrapper for Ruby’s File.dirname function.

example:

• standard::directory_name('//foo') returns '/'

compliance:

• POSIX.1-2017
  • Ruby documentation does not make any assertions and the implementation has not been verified, but it is expected to correspond to the dirname function

standard::dotted_decimal

description:

• This function takes a non-negative integer and converts it to a string using the dotted decimal notation.
• The second integer parameter denotes the maximum range per group. It must be greater than one (1).
• The optional third positive integer parameter will augment leading zero-groups.

examples:

• standard::dotted_decimal(0xFF00, 256) yields '255.0'
• standard::dotted_decimal(0x7F000001, 256, 4) yields '127.0.0.1'

compliance:

• POSIX.1-2017
  • If invoked as standard::dotted_decimal($n, 256, 4) this corresponds to inet_ntoa in functionality unless $n exceeds the value of 0xFFFFFFFF.

standard::internet_protocol_version_4_address

description:

• The function takes a non-empty string containing hexadecimal digits, the letter x and dots.

examples:

• standard::internet_protocol_version_4_address('127.123.45678') yields 2138813038
• standard::internet_protocol_version_4_address('255.255.255.255') yields 4294967295

compliance:

• POSIX.1-2017
  • ✔ This function corresponds to inet_addr.
  • ✔ accepts octal, decimal, hexadecimal parts
  • ✔ up to four parts with shift applied

templates

standard/shell_variable_assignments.epp

description:

• Applications employing the KISS principle frequently use shell-based configuration files if there is no demand for complicated constructs.
• This template provides a quick way to fill a file with a host of variable assignments. The mandatory parameter $setting is a Hash. Acceptable keys are Standard::ShellCommandLanguageName. Acceptable values are ScalarData (that is Boolean, Integer, Float and String data types).
• Integer, float and Boolean values are rendered using the automatic conversion mechanisms Puppet ® provides. Optional $integer_format, $float_format and $boolean_format string parameters may override this. See Puppet’s function reference for details.
• Strings are surrounded by inch signs (") if they contain anything to expand (e. g. shell variables), otherwise typewriter apostrophes (') are used.
• It is recommended to verify that the application at hand uses a shell-based configuration by design, or whether its resemblance is a mere coincidence (and thus a later application version may significantly deviate from it).

example:

• epp('standard/shell_variable_assignments.epp', {$setting => {'FOO' => 'bar'}}) yields

  FOO='bar'
  

limited compliance:

• POSIX.1-2017
  • It has not been established that it is impossible to pass values that will render this template’s output invalid shell input. Therefore setting validate_cmd to '/bin/sh ‑o noexec %' is recommended.