Skip to content
Account management module
Ruby Puppet Pascal Shell
Branch: master
Clone or download
Type Name Latest commit message Commit time
Failed to load latest commit information.
.vscode pdksync_heads/master-0-g7827fc2 Jun 10, 2019
data fix small typo on the root_home key at Debian.yaml Oct 5, 2019
examples (MODULES-9697) fix for correct management of sshkey_custom_path Aug 12, 2019
files/shell (#8582) Add basic bash Puppet customizations Jul 26, 2011
lib/puppet/functions (MODULES-8909) Add type-aliases and auto-loading. (#214) Apr 29, 2019
locales (L10n) Updating translations for locales/ja/puppetlabs-accounts.po Jan 24, 2019
manifests Allow substitution in accounts::key_management::sshkey_custom_path pa… Oct 2, 2019
readmes (L10n) Updating translations for readmes/ Jan 24, 2019
spec (maint) Update for PDK templates Nov 1, 2019
types Document type-aliases. Aug 13, 2019
.fixtures.yml (FM-8634) ensure encrypted communication for fixtures Nov 1, 2019
.gitattributes pdksync_heads/master-0-gbf720df Dec 17, 2018
.gitignore (maint) update gitignore and pdkignore for .project file removal Nov 21, 2019
.pdkignore (maint) update gitignore and pdkignore for .project file removal Nov 21, 2019
.puppet-lint.rc pdksync - (maint) Update pdk-template to f778803 Apr 15, 2019
.rspec (maint) modulesync f6e2070 Jul 14, 2016
.rubocop.yml (maint) Update for PDK templates Nov 1, 2019
.rubocop_todo.yml Cleanup ruby code via rubocop Nov 14, 2017
.sync.yml MODULES-10236 disable deploy_to_forge for the module Dec 6, 2019
.travis.yml MODULES-10236 disable deploy_to_forge for the module Dec 6, 2019
.yardopts pdksync_heads/master-0-g34e3266 May 18, 2018
CODEOWNERS (maint) Add a codeowners file Sep 17, 2019 (maint) modulesync 892c4cf Sep 18, 2017
Gemfile (maint) Update to PDK 1.14.1 Nov 27, 2019 (MODULES-7729) - Release prep for 3.0.0 release Sep 7, 2018
LICENSE (maint) modulesync f6e2070 Jul 14, 2016
NOTICE (maint) modulesync 65530a4 Update Travis Jan 3, 2018 (FM-8391) Update README per team practices Oct 31, 2019 Release version 6.0.0 Nov 11, 2019
Rakefile (maint) Update for PDK templates Nov 1, 2019
distelli-manifest.yml (FM-8231) Convert testing to litmus Jun 14, 2019
hiera.yaml Move os-specific data into hiera. Aug 13, 2019
metadata.json MODULES-10236 disable deploy_to_forge for the module Dec 6, 2019
provision.yaml MODULES-10242 Add ubuntu14 support back to the modules Dec 6, 2019


Table of Contents

  1. Description
  2. Setup - The basics of getting started with accounts
  3. Usage - Configuration options and additional functionality
  4. Reference - An under-the-hood peek at what the module is doing and how * Data Types
  5. Limitations - OS compatibility, etc.
  6. Development - Guide for contributing to the module


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.


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.


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


accounts::user { 'jeff':
  comment => 'Jeff McCune',
  groups  => [
  uid     => '1112',
  gid     => '1112',
  sshkeys => [
    'ssh-rsa AAAAB3Nza...==',
    'ssh-dss AAAAB3Nza...==',

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.


accounts::user { 'gerrard':
  sshkey_custom_path => '/var/lib/ssh/gerrard/authorized_keys',
  sshkey_group       => 'root',
  sshkey_owner       => 'root',
  shell              => '/bin/zsh',
  comment            => 'Gerrard Geldenhuis',
  groups             => [
  uid                => '1117',
  gid                => '1117',
  sshkeys            => [
    'ssh-rsa AAAAB9Aza...==',
    'ssh-dss AAAAB9Aza...==',
  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.


  system: true
  admins: {}
  users:  {}
  groups: [ 'users' ]
  managehome: true
  system:     false
    groups: ['admins', 'users']
      - &joe_sshkey 'ssh-rsa ...'
      - &sally_sshkey 'ssh-rsa ...'
      - *joe_sshkey
      - *sally_sshkey
    system: true
include ::accounts



Data types


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


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

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


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


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


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


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


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)


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


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


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


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.


Acceptance tests for this module leverage puppet_litmus. To run the acceptance tests follow the instructions here. You can also find a tutorial and walkthrough of using Litmus and the PDK on YouTube.

If you run into an issue with this module, or if you would like to request a feature, please file a ticket. Every Monday the Puppet IA Content Team has office hours in the Puppet Community Slack, alternating between an EMEA friendly time (1300 UTC) and an Americas friendly time (0900 Pacific, 1700 UTC).

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
You can’t perform that action at this time.