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
4. Reference - An under-the-hood peek at what the module is doing and how
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 replaces Puppet Enterprise's built-in pe_accounts module, which is no longer included in PE 2015.3 and later versions.

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...== [email protected]',
    'ssh-dss AAAAB3Nza...== [email protected]',
  ],
}

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 set a custom path then only ssh keys in the custom path will be purged. 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...== [email protected]',
    'ssh-dss AAAAB9Aza...== [email protected]',
  ],
  password           => '!!',
}

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

Reference

Defined type: accounts::user

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

bashrc_content

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

bashrc_source

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

bash_profile_content

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

bash_profile_source

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

forward_content

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

forward_source

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

comment

A comment describing or regarding the user. Accepts a string. Default: '$name'.

ensure

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: 'present'.

gid

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

group

Specifies the name of the user's primary group. Must be specified as a string. Default: a group named the same as user name

groups

Specifies the user's group memberships. Valid values: an array. Default: an empty array.

create_group

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

expiry

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

forcelocal

Specifies whether you want to manage a local user/group that is also managed by a network name service. Valid values: true, false. Default: undef.

home

Specifies the path to the user's home directory. Default:

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

home_mode

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.

locked

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. Valid values: true, false. Default: false.

managehome

Specifies whether the user's home directory should be managed by puppet. In addition to the usual user resource managehome qualities, this attribute also purges the user's homedir if ensure is set to 'absent' and managehome is set to true. Default: true.

membership

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: 'minimum'.

password

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

ignore_password_if_empty

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. Valid values: true, false. Default: false.

purge_sshkeys

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. Valid values: true, false. Default: false.

shell

Manages the user shell. Default: '/bin/bash'.

sshkeys

An array of SSH public keys associated with the user. These should be complete public key strings that include the type and name of the key, exactly as the key would appear in its id_rsa.pub or id_dsa.pub file. Must be an array. Default: an empty array.

uid

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

system

Specifies if you want to create a system account. Default: false.

Functions

accounts_ssh_options_parser

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

Limitations

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

This module works with Puppet Enterprise 2015.3 and later.

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

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.