Skip to content

Latest commit

 

History

History
771 lines (489 loc) · 22.9 KB

REFERENCE.md

File metadata and controls

771 lines (489 loc) · 22.9 KB
Raw

Reference

Table of Contents

Classes

Defined types

Public Defined types

  • accounts::user: This resource manages the user, group, vim/, .ssh/, .bash_profile, .bashrc, homedir, .ssh/authorized_keys files, and directories.

Private Defined types

  • accounts::home_dir: This resource specifies how home directories are managed.
  • accounts::key_management: This resource specifies where ssh keys are managed.
  • accounts::manage_keys: This resource manages ssh keys for a user.

Functions

  • accounts_ssh_authorized_keys_line_parser: Parse an ssh authorized_keys line string into an array using its expected pattern by using a combination of regex matching and extracting the
  • accounts_ssh_options_parser: Parse an ssh authorized_keys option string into an array using its expected pattern which matches a crazy regex slightly modified from shell

Data types

Classes

accounts

This class auto-creates user and group resources from hiera data.

Parameters

The following parameters are available in the accounts class:

group_defaults

Data type: Accounts::Group::Resource

Hash of default attributes for group resources managed by this class.

Default value: {}

group_list

Data type: Accounts::Group::Hash

Hash of group resources for this class to manage. The hash is keyed by group name.

Default value: {}

user_defaults

Data type: Accounts::User::Resource

Hash of default attributes for accounts::user resources managed by this class.

Default value: {}

user_list

Data type: Accounts::User::Hash

Hash of accounts::user resources for this class to manage. The hash is keyed by user name.

Default value: {}

accounts::user::defaults

Load some user defaults from hiera data.

Parameters

The following parameters are available in the accounts::user::defaults class:

home_template

Data type: Stdlib::AbsolutePath

The sprintf template used to determine a user's home directory.

Default value: '/home/%s'

locked_shell

Data type: Stdlib::AbsolutePath

The shell assigned to locked user accounts.

Default value: '/sbin/nologin'

root_home

Data type: Stdlib::AbsolutePath

The home directory of the root user.

Default value: '/root'

Defined types

accounts::user

This resource manages the user, group, vim/, .ssh/, .bash_profile, .bashrc, homedir, .ssh/authorized_keys files, and directories.

Examples

Basic usage
accounts::user { 'bob':
  uid      => '4001',
  gid      => '4001',
  group    => 'staff',
  shell    => '/bin/bash',
  password => '!!',
  locked   => false,
}

Parameters

The following parameters are available in the accounts::user defined type:

ensure

Data type: Enum['absent','present']

Specifies whether the user, its primary group, homedir, and ssh keys should exist. Valid values are 'present' and 'absent'. Note that when a user is created, a group with the same name as the user is also created.

Default value: 'present'

allowdupe

Data type: Boolean

Whether to allow duplicate UIDs. By default false

Default value: false

bash_profile_content

Data type: Optional[String]

The content to place in the user's ~/.bash_profile file. Mutually exclusive to bash_profile_source.

Default value: undef

bash_profile_source

Data type: Optional[Stdlib::Filesource]

A source file containing the content to place in the user's ~/.bash_profile file. Mutually exclusive to bash_profile_content.

Default value: undef

bashrc_content

Data type: Optional[String]

The content to place in the user's ~/.bashrc file. Mutually exclusive to bashrc_source.

Default value: undef

bashrc_source

Data type: Optional[Stdlib::Filesource]

A source file containing the content to place in the user's ~/.bashrc file. Mutually exclusive to bashrc_content.

Default value: undef

comment

Data type: String

A comment describing or regarding the user.

Default value: $name

create_group

Data type: Boolean

Specifies if you want to create a group with the user's name.

Default value: true

expiry

Data type: Optional[Accounts::User::Expiry]

Specifies the date the user account expires on. Valid values: YYYY-MM-DD date format, or 'absent' to remove expiry date.

Default value: undef

forcelocal

Data type: Optional[Boolean]

Specifies whether you want to manage a local user/group that is also managed by a network name service.

Default value: undef

forward_content

Data type: Optional[String]

The content to place in the user's ~/.forward file. Mutually exclusive to forward_source.

Default value: undef

forward_source

Data type: Optional[Stdlib::Filesource]

A source file containing the content to place in the user's ~/.forward file. Mutually exclusive to forward_content.

Default value: undef

gid

Data type: Optional[Accounts::User::Uid]

Specifies the gid of the user's primary group. Must be specified numerically.

Default value: undef

group

Data type: Accounts::User::Name

Specifies the name of the user's primary group. By default, this uses a group named the same as user name

Default value: $name

groups

Data type: Array[Accounts::User::Name]

Specifies the user's group memberships.

Default value: []

home

Data type: Optional[Stdlib::Unixpath]

Specifies the path to the user's home directory.

  • Linux, non-root user: '/home/$name'

  • Linux, root user: '/root'

  • Solaris, non-root user: '/export/home/$name'

  • Solaris, root user: '/'

Default value: undef

home_mode

Data type: Optional[Stdlib::Filemode]

Manages the user's home directory permission mode. Valid values are in octal notation, specified as a string. Defaults to undef, which creates a home directory with 0700 permissions. It does not touch them if the directory already exists. Keeping it undef also allows a user to manage their own permissions. If home_mode is set, Puppet enforces the permissions on every run.

Default value: undef

ignore_password_if_empty

Data type: Boolean

Specifies whether an empty password attribute should be ignored. If set to true, a password attribute that is defined but set to the empty string is ignored, allowing the password to be managed outside of this Puppet module. If set to false, it sets the password to an empty value.

Default value: false

iterations

Data type: Optional[Accounts::User::Iterations]

This is the number of iterations of a chained computation of the PBKDF2 password hash. This field is required for managing passwords on OS X >= 10.8.

Default value: undef

locked

Data type: Boolean

Specifies whether the account should be locked and the user prevented from logging in. Set to true for users whose login privileges have been revoked.

Default value: false

managehome

Data type: Boolean

Specifies whether the user's home directory should be created when adding a user.

Default value: true

managevim

Data type: Boolean

Specifies whether or not the .vim folder should be created within the managed accounts home directory.

Default value: true

membership

Data type: Enum['inclusive','minimum']

Establishes whether specified groups should be considered the complete list (inclusive) or the minimum list (minimum) of groups to which the user belongs. Valid values: 'inclusive', 'minimum'.

Default value: 'minimum'

name

Name of the user.

password

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

The user's password, in whatever encrypted format the local machine requires. Default: '!!', which prevents the user from logging in with a password.

Default value: '!!'

password_max_age

Data type: Optional[Accounts::User::PasswordMaxAge]

Maximum number of days a password may be used before it must be changed. Allows any integer from -1 to 99999. See the user resource.

Default value: undef

purge_sshkeys

Data type: Boolean

Whether keys not included in sshkeys should be removed from the user. If purge_sshkeys is true and sshkeys is an empty array, all SSH keys will be removed from the user.

Default value: false

purge_user_home

Data type: Boolean

Whether to force recurse remove user home directories when removing a user. Defaults to false.

Default value: false

salt

Data type: Optional[String]

This is the 32-byte salt used to generate the PBKDF2 password used in OS X. This field is required for managing passwords on OS X >= 10.8.

Default value: undef

shell

Data type: Stdlib::Unixpath

Manages the user shell.

Default value: '/bin/bash'

sshkey_custom_path

Data type: Optional[Stdlib::Unixpath]

Custom location for ssh public key file.

Default value: undef

sshkey_group

Data type: Optional[Accounts::User::Name]

Specifies the group of the sshkey file

Default value: $group

sshkey_owner

Data type: Optional[Accounts::User::Name]

Specifies the owner of the sshkey file

Default value: $name

sshkey_mode

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

Specifies the mode of the sshkey file .ssh/authorized_keys.

Default value: '0600'

sshkeys

Data type: Array[String[1]]

An array of SSH public keys associated with the user. These should be complete public key strings that include the type, content and name of the key, exactly as it would appear in its id_*.pub file, or with an optional options string preceding the other components, as it would appear as an entry in an authorized_keys file. Must be an array.

Examples:

Note that for multiple keys, the name component (the last) must be unique.

Default value: []

system

Data type: Boolean

Specifies if you want to create a system account.

Default value: false

uid

Data type: Optional[Accounts::User::Uid]

Specifies the user's uid number. Must be specified numerically.

Default value: undef

Functions

accounts_ssh_authorized_keys_line_parser

Type: Ruby 4.x API

Parse an ssh authorized_keys line string into an array using its expected pattern by using a combination of regex matching and extracting the substring before the match as ssh-options. This allows whitespaces inside the options and inside the comment and is consistent with the behavior of openssh. The returned options element can by an empty string.

Examples

Calling the function
accounts_ssh_authorized_keys_line_parser_string('options ssh-rsa AAAA... comment)

accounts_ssh_authorized_keys_line_parser(String[1] $str)

Parse an ssh authorized_keys line string into an array using its expected pattern by using a combination of regex matching and extracting the substring before the match as ssh-options. This allows whitespaces inside the options and inside the comment and is consistent with the behavior of openssh. The returned options element can by an empty string.

Returns: Array of authroized_keys_line components: ['options','keytype','key','comment']

Examples
Calling the function
accounts_ssh_authorized_keys_line_parser_string('options ssh-rsa AAAA... comment)
str

Data type: String[1]

ssh authorized_keys line string

accounts_ssh_options_parser

Type: Ruby 4.x API

Parse an ssh authorized_keys option string into an array using its expected pattern which matches a crazy regex slightly modified from shell words. The pattern should be a string.

Examples

Calling the function
accounts_ssh_option_parser_string()

accounts_ssh_options_parser(String $str)

Parse an ssh authorized_keys option string into an array using its expected pattern which matches a crazy regex slightly modified from shell words. The pattern should be a string.

Returns: Array Separated components of the string

Examples
Calling the function
accounts_ssh_option_parser_string()
str

Data type: String

ssh authorized_keys option string

Data types

Accounts::Group::Hash

Group resoureces hash. Passed as the second parameter of the ensure_resources function.

Alias of Hash[Accounts::User::Name, Accounts::Group::Resource]

Accounts::Group::Provider

Group provider. You will seldom need to specify this -- Puppet will usually discover the appropriate provider for your platform.

Alias of Enum['aix', 'directoryservice', 'groupadd', 'ldap', 'pw', 'windows_adsi']

Accounts::Group::Resource

Group attributes hash. Passed as the third parameter of the ensure_resources function.

Alias of

Struct[{ Optional[ensure]          => Enum['absent', 'present'],
    Optional[allowdupe]       => Boolean,
    Optional[auth_membership] => Boolean,
    Optional[forcelocal]      => Boolean,
    Optional[gid]             => Accounts::User::Uid,
    Optional[members]         => Array[Accounts::User::Name],
    Optional[name]            => Accounts::User::Name,
    Optional[provider]        => Accounts::Group::Provider,
    Optional[system]          => Boolean,
  }]

Accounts::User::Expiry

Account expiration date. Either 'absent' or a YYYY-MM-DD datestring.

Alias of Variant[Enum['absent'], Pattern[/\A(19|[2-9]\d)\d\d-(0[1-9]|1[012])-(0[1-9]|[12][0-9]|3[01])\z/]]

Accounts::User::Hash

User resources hash. Passed as the second parameter of the ensure_resources function.

Alias of Hash[Accounts::User::Name, Accounts::User::Resource]

Accounts::User::Iterations

Password hash iterations. This parameter is used in OS X, and is required for managing passwords on OS X 10.8 and newer.

Alias of Variant[Integer[1,], Pattern[/\A[1-9]\d*\z/]]

Accounts::User::Name

Account (user or group) name. From useradd(8): It is usually recommended to only use usernames that begin with a lower case letter or an underscore, followed by lower case letters, digits, underscores, or dashes. They can end with a dollar sign. Usernames may only be up to 32 characters long.

Many installations also allow capitals or periods, for example to separate first and last names.

Alias of Pattern[/\A[a-zA-Z0-9_]([a-zA-Z.0-9_-]{0,30}[a-zA-Z0-9_$-])?\z/]

Accounts::User::PasswordMaxAge

Max password age. On most systems, the default value of 99999 is about 274 years, which effectively disables password aging.

Alias of Integer[-1, 99999]

Accounts::User::Resource

User attributes hash. Passed as the third parameter of the ensure_resources function.

Alias of

Struct[{ Optional[ensure]                   => Enum['absent','present'],
    Optional[allowdupe]                => Boolean,
    Optional[bash_profile_content]     => String,
    Optional[bash_profile_source]      => Stdlib::Filesource,
    Optional[bashrc_content]           => String,
    Optional[bashrc_source]            => Stdlib::Filesource,
    Optional[comment]                  => String,
    Optional[create_group]             => Boolean,
    Optional[expiry]                   => Accounts::User::Expiry,
    Optional[forcelocal]               => Boolean,
    Optional[forward_content]          => String,
    Optional[forward_source]           => Stdlib::Filesource,
    Optional[gid]                      => Accounts::User::Uid,
    Optional[group]                    => Accounts::User::Name,
    Optional[groups]                   => Array[Accounts::User::Name],
    Optional[name]                     => Accounts::User::Name,
    Optional[home]                     => Stdlib::Unixpath,
    Optional[home_mode]                => Stdlib::Filemode,
    Optional[ignore_password_if_empty] => Boolean,
    Optional[iterations]               => Accounts::User::Iterations,
    Optional[locked]                   => Boolean,
    Optional[managehome]               => Boolean,
    Optional[managevim]                => Boolean,
    Optional[membership]               => Enum['inclusive','minimum'],
    Optional[password]                 => String,
    Optional[password_max_age]         => Accounts::User::PasswordMaxAge,
    Optional[purge_sshkeys]            => Boolean,
    Optional[purge_user_home]          => Boolean,
    Optional[salt]                     => String,
    Optional[shell]                    => Stdlib::Unixpath,
    Optional[sshkey_custom_path]       => Stdlib::Unixpath,
    Optional[sshkey_owner]             => Accounts::User::Name,
    Optional[sshkey_group]             => Accounts::User::Name,
    Optional[sshkeys]                  => Array[String],
    Optional[system]                   => Boolean,
    Optional[uid]                      => Accounts::User::Uid,
  }]

Accounts::User::Uid

Numeric user ID. On most Unix systems, the highest uid is 2^32 - 1, or 4294967295.

Alias of

Variant[Integer[0,4294967295], Pattern[/\A0\z/,
    /\A[1-3]\d{0,9}\z/,
    /\A[4-9]\d{0,8}\z/,
    /\A4[0-1]\d{8}\z/,
    /\A42[0-8]\d{7}\z/,
    /\A429[0-3]\d{6}\z/,
    /\A4294[0-8]\d{5}\z/,
    /\A42949[0-5]\d{4}\z/,
    /\A429496[0-6]\d{3}\z/,
    /\A4294967[0-1]\d{2}\z/,
    /\A42949672[0-8]\d\z/,
    /\A429496729[0-5]\z/,
  ]]