Skip to content

Latest commit

 

History

History
1541 lines (914 loc) · 42.6 KB

REFERENCE.md

File metadata and controls

1541 lines (914 loc) · 42.6 KB

Reference

Table of Contents

Classes

Defined types

Resource types

  • krb5_acl: Manages krb5 kadmind ACL entries per kadmind(8). When removing an entry, you can specify a regex for the operation_target and all associated
  • krb5kdc_auto_keytabs: Auto-generates principals and keytabs on a functional KDC and outputs the keytabs to a directory of the user's choosing. Can optionally take

Functions

Classes

krb5

This base class installs everything necessary for basic KRB client use

We modify the default /etc/krb5.conf to use an include structure under /etc/krb5.conf.simp.d. Each [subsection] is broken out into a separate directory and all files in that directory are included.

Parameters

The following parameters are available in the krb5 class:

ldap

Data type: Boolean

Configure the system to incorporate LDAP components

  • This presently does not set up the LDAP back-end for KRB5

Default value: simplib::lookup('simp_options::ldap', { 'default_value' => false })

firewall

Data type: Boolean

Use the SIMP iptables module

Default value: simplib::lookup('simp_options::firewall', { 'default_value' => false })

haveged

Data type: Boolean

Use the SIMP haveged module

Default value: simplib::lookup('simp_options::haveged', { 'default_value' => true })

enctypes

Data type: Array[String]

An Array of default permitted encryption types

Default value: [ 'aes256-cts-hmac-sha1-96', 'aes128-cts-hmac-sha1-96' ]

krb5::client

By default, this is set up to connect with the KDC that would be configured if you use the default options.

Parameters

The following parameters are available in the krb5::client class:

realms

Data type:

Hash[
    String,
    Struct[{
      admin_server  => Simplib::Host,
      Optional[kdc] => Simplib::Host
    }]
  ]

A Hash of Kerberos Realms that provide a Realm paired with an Admin Server and a KDC

  • If you specify nothing here, then the system will try to set up a client with the Puppet server as the KDC. This will fail if no server is specified.

Default value: {}

krb5::config

NOTE: THIS IS A PRIVATE CLASS

Basic configuration of the MIT Kerberos client

Parameters

The following parameters are available in the krb5::config class:

config_dir

Data type: Stdlib::Absolutepath

The path to the Puppet managed config files.

Default value: '/etc/krb5.conf.simp.d'

default_realm

Data type: String

Default realm to which to bind.

Default value: inline_template('<%= @domain.upcase %>')

realm_domains

Data type: Array[String]

Array of domains bound to the default realm set in $default_realm.

Default value: [ ".${facts['networking']['domain']}", $facts['networking']['domain'] ]

dns_lookup_realm

Data type: Boolean

Use DNS TXT records to lookup the realm.

Default value: false

dns_lookup_kdc

Data type: Boolean

Use DNS SRV records to lookup the KDC.

Default value: true

renew_lifetime

Data type: String

The default renewable lifetime for initial tickets. Should be a valid krb5 Time Duration string. @see http://web.mit.edu/kerberos/krb5-1.13/doc/basic/date_format.html#duration

Default value: '7d'

forwardable

Data type: Boolean

Whether or not to make initial tickets forwardable by default. This is needed for SSH GSSAPI.

Default value: true

clockskew

Data type: Integer[0]

Max allowable amount of seconds of clockskew allowed before assuming that a message is invalid.

Default value: 500

permitted_tgs_enctypes

Data type: Array[String]

Supported encryption types reported by the KDC.

Default value: $krb5::enctypes

permitted_tkt_enctypes

Data type: Array[String]

Permitted client encryption types.

Default value: $krb5::enctypes

permitted_enctypes

Data type: Array[String]

Permitted session key encryption types.

Default value: $krb5::enctypes

puppet_exclusive_managed

Data type: Boolean

Set to false to allow users to add files to the /etc/krb5.conf.d directory manually.

Default value: true

krb5::config::default_settings

NOTE: THIS IS A PRIVATE CLASS

krb5::install

NOTE: THIS IS A PRIVATE CLASS

Parameters

The following parameters are available in the krb5::install class:

packages

Data type: Array[String[1]]

The list of pakages to install

  • Provided by module data
ensure

Data type: String[1]

The package state to ensure

  • Compatible with the Package Resource ensure parameter can

Default value: simplib::lookup('simp_options::package_ensure', { 'default_value' => 'installed' })

haveged

Data type: Boolean

Include haveged for entropy generation.

Default value: $krb5::haveged

krb5::kdc

The variables used here can be found in kdc.conf(5).

Any variable not covered here can be managed using file resources.

Examples

Add Your Own Custom Config Snippet
class my_krb5kdc {
  include 'krb5::kdc'

  file { "${krb5::kdc::config_dir}/my_snippet__custom":
    content => "My Custom Content"
  }

  Class['krb5::kdc'] -> Class['my_krb5kdc']
  Class['my_krb5kdc'] ~> Class['krb5::kdc::service']
}

Parameters

The following parameters are available in the krb5::kdc class:

trusted_nets

Data type: Simplib::Netlist

An Array of hostnames or IP addresses that are allowed into this system. Only used by the IPTables settings.

Default value: simplib::lookup('simp_options::trusted_nets', { 'default_value' => ['127.0.0.1', '::1'] })

config_dir

Data type: Stdlib::Absolutepath

The path to the Puppet managed config files.

Default value: '/var/kerberos/krb5kdc/kdc.conf.simp.d'

ldap

Data type: Boolean

If set, configure the system to incorporate LDAP components. @note This presently does not set up the LDAP back-end for KRB5

Default value: $krb5::ldap

firewall

Data type: Boolean

If set, use the SIMP iptables module.

Default value: $krb5::firewall

haveged

Data type: Boolean

If set, enable the HAVEGE daemon for entropy

Default value: $krb5::haveged

auto_initialize

Data type: Boolean

If set, create a default realm do all necessary work to set up the environment for production. @note This will simply use the system defaults. If you want something other than that, you'll need to call the krb5::kdc::realm define directly.

If you select this, this will automatically initialize your Kerberos database and prepare your system to run.

Default value: true

auto_realm

Data type: String

If $auto_initialize is set, then use this string as your default Kerberos Realm.

Default value: $facts['networking']['domain']

auto_management_principal

Data type: String

If $auto_initialize is set, then use this string as the primary Kerberos principal name for the default Realm.

Default value: 'puppet_auto'

auto_generate_host_keytabs

Data type: Boolean

If set, create keytabs for all hosts that Puppet currently knows about. @note Host Principals are identified by having a 'host/' entry in the list of principals. Any host without one of these entries will be ignored.

This is not dependent on $auto_initialize! You may want to toggle some of the parameters in the krb5::kdc::auto_keytabs class to tailor the generation.

This capability expects a ${module_name}_files module to be present in the environment's module path. It is not recommended that you place this module inside of the standard module path. Instead, the containing directory should be added to the modulepath directive of your environment.conf. @see https://docs.puppet.com/puppet/4.5/reference/config_file_environment.html With the ${module_name}_files module, you should also have a section in your Puppet auth.conf that looks something like the following and is placed before the path /file stanza.

@example auth.conf update # Restrict access to a directory that matches the hostname # Example: /environments/production/krb5_files/files/my.host.name.domain

path ~ ^/file_(metadata|content)/modules/krb5_files/([^/]+)
allow $2

Default value: true

krb5::kdc::auto_keytabs

NOTE: THIS IS A PRIVATE CLASS

The keytabs will be collected in a directory that is, by default, located at /var/kerberos/krb5kdc/generated_keytabs.

The target directory will have subdirectories created, one per host/fqdn@REALM principal that match the fqdn of the host.

Each of those directories will have a krb5.keytab file created that contains all discovered keytabs for the principal, regardless of REALM.

  • Note If this is enabled on a Puppet server, and $introspect is true, it will attempt to install the keytabs into the ${environmentpath}/${environment}/site_files/${module_name}_files/files/keytabs directory.

It will also attempt to automatically create host keytabs for any hosts in one of the following two directories:

  • ${environmentpath}/${environment}/keydist
  • ${environmentpath}/${environment}/site_files/pki_files/files/keydist

@note For any of the above, if $environmentpath is empty, or does not exist, then $confdir will be substituted for ${environmentpath}/${environment}

Parameters

The following parameters are available in the krb5::kdc::auto_keytabs class:

introspect

Data type: Boolean

If set, attempt to discover, and create all relevant keytabs from data on the Puppet server. @note This has no effect if you aren't running on a Puppet server.

Default value: true

output_dir

Data type: Optional[Stdlib::Absolutepath]

The directory into which to install the keytabs.

Default value: undef

all_known

Data type: Boolean

If set, generate keytabs for any 'host/.*' entries known to the KDC.

Default value: false

user

Data type: String

The user that should own the keytab files.

Default value: 'root'

group

Data type: String

The group that should own the keytab files.

Default value: 'puppet'

realms

Data type: String

The REALMs into which the hosts should be added unless otherwise specified in the $hosts Hash. Will be auto-upcased.

Default value: simplib::lookup('krb5::kdc::auto_realm', { 'default_value' => $facts['networking']['domain'] })

global_services

Data type: Array[String]

An Array of Kerberos services that should be added to all hosts.

Default value: []

hosts

Data type:

Hash[String,
    Struct[{'ensure'             => Enum['absent','present'],
            Optional['realms']   => Array[String],
            Optional['services'] => Array[String]
    }]
  ]

A Hash of hosts for which keytabs should be generated, and kept in the KDC by Puppet. This is done as a Hash so that you don't end up with thousands of Puppet resources in your catalog. @note The Hash should be formatted as follows: { 'fqdn' => 'ensure' => ('absent'|'present') # Required 'realms' => ['REALM1', 'REALM2'] # Optional. Will be auto upcased. 'services' => ['svc1','svc2'] # Optional }

@note This will be combined with the auto-generated hosts if $auto_generate is true

Default value: {}

purge

Data type: Boolean

If set, purge any keytab directories for systems that we don't know about.

Default value: true

krb5::kdc::config

NOTE: THIS IS A PRIVATE CLASS

The variables used here can be found in kdc.conf(5).

Any variable not covered here can be managed using file resources.

Examples

Add Your Own Custom Config Snippet
class my_krb5kdc {
  include 'krb5::kdc'

  file { "${krb5::kdc::config_dir}/my_snippet__custom":
    content => "My Custom Content"
  }

  Class['krb5::kdc'] -> Class['my_krb5kdc']
  Class['my_krb5kdc'] ~> Class['krb5::kdc::service']
}

Parameters

The following parameters are available in the krb5::kdc::config class:

kdb5_password

Data type: String

The password that should be used for auto-initializing the Principal database

  • If this password is changed, there will be no effect unless the password file is physically removed from the system

@note For safety, the Principal database will not be rebuilt unless it is physically absent from the system

Default value: simplib::passgen('kdb5kdc', { 'length' => 1024 })

kdc_ports

Data type: Array[Simplib::Port]

The UDP ports on which the KDC should listen

Default value: [88, 750]

kdc_tcp_ports

Data type: Array[Simplib::Port]

The TCP ports on which the KDC should listen

Default value: [88, 750]

krb5::kdc::firewall

NOTE: THIS IS A PRIVATE CLASS

Parameters

The following parameters are available in the krb5::kdc::firewall class:

kdc_ports

Data type: Array[Simplib::Port]

The UDP ports on which the KDC should listen

Default value: $krb5::kdc::config::kdc_ports

kdc_tcp_ports

Data type: Array[Simplib::Port]

The TCP ports on which the KDC should listen

Default value: $krb5::kdc::config::kdc_tcp_ports

trusted_nets

Data type: Simplib::Netlist

Hostnames and/or IP addresses that are allowed into this system

  • Only used by the IPTables settings

Default value: $krb5::kdc::config::_trusted_nets

allow_kadmind

Data type: Boolean

Allow remote connections to kadmind

  • You should probably always allow this

Default value: true

kadmind_udp_ports

Data type: Array[Simplib::Port]

The UDP ports on which kadmind should listen

Default value: [464]

kadmind_tcp_ports

Data type: Array[Simplib::Port]

The TCP ports on which kadmind should listen

Default value: [464, 749]

krb5::kdc::install

NOTE: THIS IS A PRIVATE CLASS

Parameters

The following parameters are available in the krb5::kdc::install class:

ensure

Data type: String

The package state to ensure

  • Accepts all valid options for the Package resource's ensure parameter

Default value: simplib::lookup('simp_options::package_ensure', { 'default_value' => 'installed' })

krb5::kdc::selinux_hotfix

NOTE: THIS IS A PRIVATE CLASS

The OS confinement of this class should be done elsewhere.

krb5::kdc::service

NOTE: THIS IS A PRIVATE CLASS

Parameters

The following parameters are available in the krb5::kdc::service class:

ensure

Data type: String

May be one of 'running' or 'stopped'.

Default value: 'running'

enable

Data type: Boolean

If true, enable the services at boot time.

Default value: true

krb5::keytab

Users should feel free to do what they like, but this will be consistent

Parameters

The following parameters are available in the krb5::keytab class:

keytab_source

Data type: Any

The File resource compatible source for the system keytab

Default value: "puppet:///modules/krb5_files/keytabs/${facts['networking']['fqdn']}"

owner

Data type: Any

The keytab file owner

Default value: 'root'

group

Data type: Any

The keytab file group

Default value: 'root'

mode

Data type: Any

The keytab file mode

Default value: '0400'

Defined types

krb5::kdc::realm

Note: The kdc.conf file is fully managed by Puppet

  • See also
    • kdc.conf(5)
      • -> REALMS SECTION

Parameters

The following parameters are available in the krb5::kdc::realm defined type:

initialize

Data type: Boolean

If set, auto-initialize the Realm. This will add an initial Principal for this Realm.

Default value: false

auto_principal

Data type: String

If $initialize is set, this principal will be created as an administrative Principal on the Realm.

Default value: 'puppet_auto'

trusted_nets

Data type: Simplib::Netlist

networks to allow access into the KDC realm.

Default value:

pick(
                                                                    getvar('krb5::kdc::trusted_nets'),
                                                                    simplib::lookup('simp_options::trusted_nets', { 'default_value' => ['127.0.0.1']})
                                                                  )
acl_file

Data type: Stdlib::Absolutepath

The path to the KDC realm ACL file.

Default value: "/var/kerberos/krb5kdc/kadm5_${name}.acl"

admin_keytab

Data type: Stdlib::Absolutepath

The path to the KDC realm keytab.

Default value: "/var/kerberos/krb5kdc/kadm5_${name}.keytab"

database_name

Data type: Optional[String]

The path to the KDC realm database.

Default value: undef

default_principal_expiration

Data type: Optional[String]

The Absolute Time for expiring the principal expiration date for this realm. @see http://web.mit.edu/kerberos/krb5-devel/doc/basic/date_format.html#abstime

Default value: undef

default_principal_flags

Data type: Array[String]

An array following the format prescribed in the man page. The absence of a '-' in front of the entry implies that a '+' will be added.

Default value: []

dict_file

Data type: Stdlib::Absolutepath

The path to the dictionary file of strings that are not allowed as passwords.

Default value: '/usr/share/dict/words'

kadmind_port

Data type: Optional[Simplib::Port]

The port on which kadmind should listen.

Default value: undef

kpasswd_port

Data type: Optional[Simplib::Port]

The port on which kpasswd should listen.

Default value: undef

key_stash_file

Data type: Optional[Stdlib::Absolutepath]

The path to the KDC realm master key.

Default value: undef

kdc_ports

Data type: Array[Simplib::Port]

UDP ports upon which the KDC should listen.

Default value: []

kdc_tcp_ports

Data type: Array[Simplib::Port]

TCP ports upon which the KDC should listen.

Default value: []

master_key_name

Data type: Optional[String]

The principal associated with the master key.

Default value: undef

master_key_type

Data type: String

The master key's key type.

Default value: 'aes256-cts'

max_life

Data type: Optional[String]

The maximum time period for which a ticket may be valid. Should be a valid krb5 Time Duration string. @see http://web.mit.edu/kerberos/krb5-1.13/doc/basic/date_format.html#duration

Default value: undef

max_renewable_life

Data type: Optional[String]

The maximum time period during which a valid ticket may be renewed. Should be a valid krb5 Time Duration string.

Default value: undef

iprop_enable

Data type: Optional[Boolean]

Whether incremental database propogation is enabled.

Default value: undef

iprop_master_ulogsize

Data type: Optional[Integer]

The maximum number of log entries for incremental propogation.

Default value: undef

iprop_slave_poll

Data type: Optional[String]

How often the KDC polls for new updates from the master.

Default value: undef

supported_enctypes

Data type: Array[String]

The default key/salt combinations for this realm.

Default value: [ 'aes256-cts:normal', 'aes128-cts:normal' ]

reject_bad_transit

Data type: Optional[Boolean]

Whether to check the list of transited realms for cross-realm tickets.

Default value: undef

config_dir

Data type: Stdlib::Absolutepath

The path to the Puppet managed config files.

Default value: simplib::lookup('krb5::kdc::config_dir', { 'default_value' => '/var/kerberos/krb5kdc/kdc.conf.simp.d' })

ensure

Data type: String

Whether to set or clear the key. Valid values are 'present' and 'absent'. Setting anything besides 'absent' will default to 'present'.

Default value: 'present'

firewall

Data type: Boolean

Whether to add appropriate iptables rules for KDC

Default value: simplib::lookup('krb5::kdc::firewall', { 'default_value' => false })

krb5::setting

Sections with nested sub-sections or allowed repeated keys have their own specialized defines.

  • See also
    • krb5.conf(5)

Parameters

The following parameters are available in the krb5::setting defined type:

value

Data type: Scalar

The number/string/boolean that should be used to set the designated value. This will not be processed so make sure that it's what you want to output to the system.

target

Data type: Stdlib::Absolutepath

The target directory to which to add setting files.

Default value: pick(getvar('krb5::config::config_dir'), '/etc/krb5.conf.d')

ensure

Data type: String

Whether to set or clear the key. Valid values are 'present' and 'absent'. Setting anything besides 'absent' will default to 'present'.

Default value: 'present'

filemode

Data type: String

The File mode (per the Puppet File resource) that should be set on the settings files.

Default value: '0644'

seltype

Data type: String

The SELinux Type to which to set the file that holds the setting.

Default value: 'krb5_conf_t'

krb5::setting::domain_realm

It was specifically created so that you could pass in your domains as a name array and then your realm as a value.

  • See also
    • krb5.conf(5)

Parameters

The following parameters are available in the krb5::setting::domain_realm defined type:

ensure

Data type: String

Whether to set or clear the key. Valid values are 'present' and 'absent'. Setting anything besides 'absent' will default to 'present'.

Default value: 'present'

realm

Data type: String

The realm to which to map your domain.

target

Data type: Stdlib::Absolutepath

The target directory to which to add setting files.

Default value: pick(getvar('krb5::config::config_dir'), '/etc/krb5.conf.d')

krb5::setting::realm

Allows you to add a realm to the [realms] section of /etc/krb5.conf.

  • See also
    • krb5.conf(5)
      • -> REALMS SECTION

Parameters

The following parameters are available in the krb5::setting::realm defined type:

admin_server

Data type: Simplib::Host

The host where the admin server is running.

kdc

Data type: Optional[Simplib::Host]

The host where the KDC is running.

Default value: undef

default_domain

Data type: Optional[String]

The default domain in which hosts are assumed to be present.

Default value: undef

v4_instance_convert

Data type: Hash[String,String]

A hash of 'tag name' to 'tag value' mappings for default domain mapping translations.

Default value: {}

v4_realm

Data type: Optional[String]

The v4 realm to be used when talking to legacy systems.

Default value: undef

auth_to_local_names

Data type: Hash[String,String]

A hash of 'principal names' to 'local user names' per the man page.

Default value: {}

auth_to_local

Data type: Optional[String]

A general rule for mapping to local user names. The following values are allowed: DB: RULE: DEFAULT

Default value: undef

target

Data type: Stdlib::Absolutepath

The path to the Puppet managed config files.

Default value: pick(getvar('krb5::config::config_dir'), '/etc/krb5.conf.d')

owner

Data type: String

Default value: 'root'

group

Data type: String

Default value: 'root'

mode

Data type: String

Default value: '0644'

Resource types

krb5_acl

Manages krb5 kadmind ACL entries per kadmind(8). When removing an entry, you can specify a regex for the operation_target and all associated entries will be removed.

Properties

The following properties are available in the krb5_acl type.

ensure

Valid values: present, absent

The basic property that the resource should be in.

Default value: present

operation_mask

Valid values: %r{^([admcilpADMCILP]+|[x*])$}

The operation mask per kadmind(8). Be aware that lower case activates a mask and upper case deactivates it

Parameters

The following parameters are available in the krb5_acl type.

name

namevar

A required, but meaningless, name

operation_target

An optional partially, or fully, qualified Kerberos 5 principal name upon which 'principal' is allowed to operate. If this is specified, the 'principal', 'operation_mask', and 'ensure' options will be restricted. This must be specified as a ruby regex without '/' in the case of ensure => 'absent'.

Default value: undef

principal

The partially, or fully, qualified Kerberos 5 principal name. This is what must appear as the usual 'name' of the resource.

provider

The specific backend to use for this krb5_acl resource. You will seldom need to specify this --- Puppet will usually discover the appropriate provider for your platform.

target

The ACL file upon which to operate

Default value: /var/kerberos/krb5kdc/kadm5.acl

krb5kdc_auto_keytabs

Auto-generates principals and keytabs on a functional KDC and outputs the keytabs to a directory of the user's choosing.

Can optionally take a hash of hosts, with associated principal metadata, to be created on the KDC. Will warn if you are attempting to add a host that does not have a valid REALM.

Properties

The following properties are available in the krb5kdc_auto_keytabs type.

ensure

Valid values: present, generated, absent

The state to enforce on the resource

Default value: present

Parameters

The following parameters are available in the krb5kdc_auto_keytabs type.

all_known

Valid values: true, false, yes, no

Generate keytabs for any 'host/.*' entires known to the KDC.

Default value: false

global_services

The global services that should be applied to every auto-generated principal

group

The group that should own the generated keytabs, defaults to '#{Puppet[:group]}' when installing into a Puppet Environment and 'root' otherwise.

Default value: group

hosts

A Hash of hosts that should be managed in the KDC.

The Hash format should be as follows:

{ 'fqdn' => { 'ensure' => ('absent' | 'present') # Required 'realms' => ['REALM1', 'REALM2'] # Optional. Will be auto-upcased 'services' => ['svc1','svc2'] # Optional } }

If '$global_services' is set, it will be added to the list of services for each host here.

introspect

Valid values: true, false, yes, no

Attempt to discover, and create, all relevant keytabs from data on the Puppet server.

This will create host principals for discovered entities if they do not exist already!

This takes a best guess from the SIMP default PKI key locations:

  • ${environmentpath}/${environment}/keydist
  • /var/simp/environments/${environment}/site_files/pki_files/files/keydist

If $environmentpath is not set, then $confdir will be substituted for ${environmentpath}/${environment}

Default value: true

name

namevar

The output directory to which to write the keytabs

If 'default' will be set to either /var/simp/environments/${environment}/site_files/krb5_files/files/keytabs or /var/kerberos/krb5kdc/generated_keytabs depending on which target path exists.

provider

The specific backend to use for this krb5kdc_auto_keytabs resource. You will seldom need to specify this --- Puppet will usually discover the appropriate provider for your platform.

purge

Valid values: true, false, yes, no

Remove all unmanaged keytabs from the '$name' directory

Default value: true

realms

The realms under which the hosts should be generated

Default value: Facter.value(:networking)['domain']

user

The user that should own the generated keytabs, defaults to '#{Puppet[:user]}' when installing into a Puppet Environment and 'root' otherwise.

Default value: root

Functions

krb5::munge_conf_filename

Type: Ruby 4.x API

Returns a string that is safe to use as a filename for including in krb5 configuration files.

krb5::munge_conf_filename(String $name)

Returns a string that is safe to use as a filename for including in krb5 configuration files.

Returns: Any String transformed filename

name

Data type: String

String to be converted to a k4b6 configuration filename

krb5::validate_time_duration

Type: Ruby 4.x API

Validates that the passed string is a valid krb5 time duration per http://web.mit.edu/kerberos/krb5-1.13/doc/basic/date_format.html#duration.

krb5::validate_time_duration(String $time_duration)

Validates that the passed string is a valid krb5 time duration per http://web.mit.edu/kerberos/krb5-1.13/doc/basic/date_format.html#duration.

Returns: Undef

time_duration

Data type: String

Time duration string to be validated