accounts

Table of Contents

1. Description
2. Setup - The basics of getting started with accounts
3. Usage - Configuration options and additional functionality
   • Declare user accounts
   • Customize the home directory
   • Lock accounts
   • Manage SSH keys
   • Data in hiera
4. Reference - An under-the-hood peek at what the module is doing and how

   * [Data Types](#data-types)
   

5. Limitations - OS compatibility, etc.
6. Development - Guide for contributing to the module

Description

The accounts module manages resources related to login and service accounts.

This module works on many UNIX/Linux operating systems. It does not support configuring accounts on Microsoft Windows platforms.

Setup

Beginning with accounts

Declare the accounts class in a Puppet-managed node's manifest:

node default {
  accounts::user { 'dan': }
  accounts::user { 'morgan': }
}

The above example creates accounts, home directories, and groups for Dan and Morgan.

Usage

Declare user accounts

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

Customize the home directory

A simple bashrc and bash_profile rc file is managed by Puppet for each account. These rc files add some simple aliases, update the prompt, add ~/bin to the path, and source the following files (which are not managed by this module) in the following order:

1. /etc/bashrc
2. /etc/bashrc.puppet
3. ~/.bashrc.custom

Account holders can customize their shells by managing their bashrc.custom files. In addition, the system administrator can make profile changes that affect all accounts with a bash shell by managing the '/etc/bashrc.puppet' file.

To install an email foward, configure the .forward file by using the forward_content or forward_source parameters.

Lock accounts

Lock accounts by setting the locked parameter of an account to true.

For example:

accounts::user { 'villain':
  comment => 'Bad Person',
  locked  => true
}

The accounts module sets the account to an invalid shell appropriate for the system Puppet is managing and displays the following message if a user tries to access the account:

$ ssh villain@centos56
This account is currently not available.
Connection to 172.16.214.129 closed.

Manage SSH keys

Manage SSH keys with the sshkeys attribute of the accounts::user defined type. This parameter accepts an array of public key contents as strings.

Example:

accounts::user { 'jeff':
  comment => 'Jeff McCune',
  groups  => [
    'admin',
    'sudonopw',
  ],
  uid     => '1112',
  gid     => '1112',
  sshkeys => [
    'ssh-rsa AAAAB3Nza...== jeff@puppetlabs.com',
    'ssh-dss AAAAB3Nza...== jeff@metamachine.net',
  ],
}

The module supports placing sshkeys in a custom location. If you specify a value for the sshkey_custom_path attribute of the accounts::user defined type, the module will place the keys in the specified file. The module will only manage the specified file and not the full path. If you set purge_sshkeys to true, and you have also set a custom path, it will only purge the ssh keys in the custom path.

Example:

accounts::user { 'gerrard':
  sshkey_custom_path => '/var/lib/ssh/gerrard/authorized_keys',
  shell              => '/bin/zsh',
  comment            => 'Gerrard Geldenhuis',
  groups             => [
    'engineering',
    'automation',
  ],
  uid                => '1117',
  gid                => '1117',
  sshkeys            => [
    'ssh-rsa AAAAB9Aza...== gerrard@dirtyfruit.co.uk',
    'ssh-dss AAAAB9Aza...== gerrard@dojo.training',
  ],
  password           => '!!',
}

Setting sshkey_custom_path is typically associated with setting AuthorizedKeysFile /var/lib/ssh/%u/authorized_keys in your sshd config file.

Data in Hiera

The accounts module supports storing all account data in Hiera.

Example:

accounts::group_defaults:
  system: true
accounts::group_list:
  admins: {}
  users:  {}
accounts::user_defaults:
  groups: [ 'users' ]
  managehome: true
  system:     false
accounts::user_list:
  admin:
    groups: ['admins', 'users']
  joe:
    sshkeys:
      - &joe_sshkey 'ssh-rsa ... joe@corp.com'
  sally:
    sshkeys:
      - &sally_sshkey 'ssh-rsa ... sally@corp.com'
  dba:
    sshkeys:
      - *joe_sshkey
      - *sally_sshkey
    system: true

include ::accounts

Reference

See REFERENCE.md

Data types

Accounts::Group::Hash

A hash of group data suitable for passing as the second parameter to ensure_resources.

Accounts::Group::Provider

The allowed values for the provider attribute. Currently, this is:

• aix
• directoryservice
• groupadd
• ldap
• pw
• windows_adsi

Accounts::Group::Resource

A struct of group attributes suitable for passing as the third parameter to ensure_resource.

Accounts::User::Expiry

Allows either 'absent' or a YYY-MM-DD datestring.

Accounts::User::Hash

A hash of user data suitable for passing as the second parameter to ensure_resources.

Accounts::User::Iterations

The iterations attribute allows any positive integer, optionally expressed as a string.

Accounts::User::Name

Allows strings up to 32 characters long that begin with a lower case letter or underscore, followed by lower case letters, digits, underscores, or dashes, and optionally ending in a dollar sign. See useradd(8)

Accounts::User::PasswordMaxAge

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

Accounts::User::Resource

A struct of user attributes suitable for passing as the third parameter to ensure_resource.

Accounts::User::Uid

Allows any integer from 0 to 4294967295 (232 - 1), optionally expressed as a string.

Limitations

For an extensive list of supported operating systems, see metadata.json

Changes from pe_accounts

The accounts module is designed to take the place of the pe_accounts module that shipped with PE versions 2015.2 and earlier. Some of the changes include the removal of the base class, improving the validation, and allowing more flexibility regarding which files should or should not be managed in a user's home directory.

For example, the .bashrc and .bash_profile files are not managed by default but allow custom content to be passed in using the bashrc_content and bash_profile_content parameters. The content for these two files as managed by pe_accounts can continue to be used by passing bashrc_content => file('accounts/shell/bashrc') and bash_profile_content => file('accounts/shell/bash_profile') to the accounts::user defined type.

Development

We are experimenting with a new tool for running acceptance tests. It's name is puppet_litmus this replaces beaker as the test runner. To run the acceptance tests follow the instructions here.

If you run into an issue with this module, or if you would like to request a feature, please file a ticket.

If you have problems getting this module up and running, please contact Support.

If you submit a change to this module, be sure to regenerate the reference documentation as follows:

puppet strings generate --format markdown --out REFERENCE.md

Reference

Table of Contents

Classes

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

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_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

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: {}

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 field should be ignored. If set to true, this ignores a password field that is defined but empty. 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: 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 0 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: Optional[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_owner

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

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

Default value: $name

sshkeys

Data type: Array[String]

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:

• ssh-rsa AAAAB3NzaC1y... bob@example.com

• from="myhost.example.com,192.168.1.1" ssh-rsa AAAAQ4ng... bob2@example.com

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_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

Change log

All notable changes to this project will be documented in this file. The format is based on Keep a Changelog and this project adheres to Semantic Versioning.

v4.2.0 (2019-08-02)

Full Changelog

Added

• (FM-8231) Convert testing to litmus #230 (eimlav)

Fixed

• MODULES-9447 -- Narrow dependency between removed user and group. #232 (pillarsdotnet)

v4.1.0 (2019-05-29)

Full Changelog

Added

• (FM-8023) Add RedHat 8 support #227 (eimlav)
• (MODULES-7469) Add password_max_age parameter #221 (eimlav)

Fixed

• (MODULES-8968) Test account removal. #226 (pillarsdotnet)

v4.0.0 (2019-05-10)

Full Changelog

Changed

• pdksync - (MODULES-8444) - Raise lower Puppet bound #218 (david22swan)
• (MODULES-8909) Add type-aliases and auto-loading. #214 (pillarsdotnet)

Fixed

• (MODULES-8909) Allow periods in usernames. #220 (pillarsdotnet)
• Remove user when custom sshkey file is set #213 (tuxmea)

3.2.0 (2019-01-18)

Full Changelog

Added

• (MODULES-8302) - Add allowdupe parameter #199 (eimlav)
• (MODULES-8149) - Addition of support for SLES 15 #197 (david22swan)

Fixed

• (MODULES-8216) - Fix fail when custom_sshkey_path and managehome=false #194 (eimlav)
• Fixing the limitations section of the README #191 (HelenCampbell)

3.1.0 (2018-09-27)

Full Changelog

Added

• pdksync - (FM-7392) puppet 6 testing changes #187 (tphoney)
• pdksync - (MODULES-6805) metadata.json shows support for puppet 6 #185 (tphoney)
• (LOC-173) Delivering translation for readmes/README_ja_JP.markdown #177 (ehom)

Fixed

• (maint) corrected filename extension for both en and ja #182 (ehom)
• Only take care of ssh-keys if ensure is set to 'present' #174 (opteamax)
• Rename README.markdown to README.MD #173 (clairecadman)

3.0.0 (2018-09-07)

Full Changelog

Changed

• Adding ability to specify custom ssh_key location #149 (ggeldenhuis)

Added

• (MODULES-7687) - Added Darwin compatibility #167 (eimlav)
• (FM-7287) - i18n Process Implemented. #159 (david22swan)
• (MODULES-5222) - managevim option added to manifests. #156 (david22swan)
• (FM-7289) - Added Puppet 4 data types to parameters #155 (eimlav)
• (MODULES-7671) - Support spaces in ssh key options #153 (dleske)
• (FM-7254) - Addition of support for Ubuntu 18.04 #150 (david22swan)

Fixed

• pdksync - (MODULES-7658) use beaker4 in puppet-module-gems #170 (tphoney)
• Fix error when deploying key into directory not owned by user #152 (tuxmea)

2.0.0

Summary

This release drops support for Debian 7, adds support for Debian 9 and includes several small features and bug fixes.

Added

• [FM-7052] Addition of Debian 9 support to accounts
• (MODULES-3989) Allow management of local accounts despite an NSS
• Allow mode for homedir to be undef
• Add expiry property to user resource.

Fixed

• (MODULES-6607) - Update docs to reflect correct default value for ignore_password_if_empty.
• Update tests and README
• Removed Debian 7 support

Bugfixes

• Allow sshkeys to be reused for multiple accounts
• Set home_mode explicitly in tests
• Fix test for ssh key to allow new comment format

Supported Release 1.3.0

Summary

This release uses the PDK convert functionality which in return makes the module PDK compliant. It also includes a roll up of maintenance changes.

Added

• PDK Convert accounts (MODULES-6328).

Fixed

• Don't create accounts::home_dir resources.
• Multiple maintenance changes.

Supported Release 1.2.1

Summary

This release is to update the formatting of the module, Rubocop having been run for all ruby files and been set to run automatically on all future commits.

Changed

• Rubocop has been implemented.

Supported Release 1.2.0

Summary

This release is a rollup of changes. Several attributes have been added as requested and submitted from our community.

Added

• Attribute ignore_password_if_empty is added which, if set to true, shall ignore password changes if the password is empty.
• Removal of dependency on group resource if create_group is set to false.
• Add attribute to allow custom group names.
• Add attribute to set system user or group.
• Add attribute to set the user or group to be the system account.
• Add attribute to create a group (or not) with the username.
• Add support for .forward.
• Add support for ssh options in authorization_keys.
• Add ECDSA support.
• Add support for ssh authorized key options.
• Allow the use of the `source` param for bash files
• Removal of end-of-life Ubuntu 12.04 support from metadata.
• Update Puppet version compatibility.
• Modulesync and Gemfile updates.

Fixed

• Multiple fixes to tests.

Supported Release 1.1.0

Summary

A feature rich release, with the addition of Debian 8 support. Also several generic fixes to tests.

Features

• Now allows SSH keys to be purged from user.
• Multiple updates and fixes to the README.
• RSpec-puppet has now been unpinned.
• Addition of Debian 8 compatibility to metadata.
• Addition of OSfamily fact to tests.
• Several modulesync updates.

Bugfixes

• Multiple fixes to tests.

Supported Release 1.0.0

Summary:

This is the initial release of the rewrite of puppetlabs-pe_accounts for a more general usage.

Differences from the pe_accounts module is that the data model is gone, and thus the base class that accepts hashes (ie, from hiera). Instead, the module is designed around the use of the accounts::user defined resource.

To regain the old hiera behavior, use the create_resources() function in combination with accounts::user; eg: create_resources('accounts::user', hiera_hash('accounts::users'))

* This Changelog was automatically generated by github_changelog_generator