Defined Type: accounts::user

Defined in:
manifests/user.pp

Summary

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

Overview

Examples:

Basic usage

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

Parameters:

  • ensure (Enum['absent','present']) (defaults to: '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.

  • allowdupe (Boolean) (defaults to: false)

    Whether to allow duplicate UIDs. By default false

  • bash_profile_content (Optional[String]) (defaults to: undef)

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

  • bash_profile_source (Optional[Stdlib::Filesource]) (defaults to: undef)

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

  • bashrc_content (Optional[String]) (defaults to: undef)

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

  • bashrc_source (Optional[Stdlib::Filesource]) (defaults to: undef)

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

  • comment (String) (defaults to: $name)

    A comment describing or regarding the user.

  • create_group (Boolean) (defaults to: true)

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

  • expiry (Optional[Accounts::User::Expiry]) (defaults to: undef)

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

  • forcelocal (Optional[Boolean]) (defaults to: undef)

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

  • forward_content (Optional[String]) (defaults to: undef)

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

  • forward_source (Optional[Stdlib::Filesource]) (defaults to: undef)

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

  • gid (Optional[Accounts::User::Uid]) (defaults to: undef)

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

  • group (Accounts::User::Name) (defaults to: $name)

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

  • groups (Array[Accounts::User::Name]) (defaults to: [])

    Specifies the user’s group memberships.

  • home (Optional[Stdlib::Unixpath]) (defaults to: undef)

    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: ‘/’

  • home_mode (Optional[Stdlib::Filemode]) (defaults to: undef)

    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.

  • ignore_password_if_empty (Boolean) (defaults to: false)

    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.

  • iterations (Optional[Accounts::User::Iterations]) (defaults to: undef)

    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.

  • locked (Boolean) (defaults to: false)

    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.

  • managehome (Boolean) (defaults to: true)

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

  • managevim (Boolean) (defaults to: true)

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

  • membership (Enum['inclusive','minimum']) (defaults to: '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’.

  • name

    Name of the user.

  • password (Variant[String, Sensitive[String]]) (defaults to: '!!')

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

  • password_max_age (Optional[Accounts::User::PasswordMaxAge]) (defaults to: undef)

    Maximum number of days a password may be used before it must be changed. Allows any integer from ‘0` to `99999`. See the [`user`](puppet.com/docs/puppet/latest/types/user.html#user-attribute-password_max_age) resource.

  • purge_sshkeys (Boolean) (defaults to: false)

    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.

  • purge_user_home (Boolean) (defaults to: false)

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

  • salt (Optional[String]) (defaults to: undef)

    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.

  • shell (Stdlib::Unixpath) (defaults to: '/bin/bash')

    Manages the user shell.

  • sshkey_custom_path (Optional[Stdlib::Unixpath]) (defaults to: undef)

    Custom location for ssh public key file.

  • sshkey_group (Optional[Accounts::User::Name]) (defaults to: $group)

    Specifies the group of the sshkey file

  • sshkey_owner (Optional[Accounts::User::Name]) (defaults to: $name)

    Specifies the owner of the sshkey file

  • sshkey_mode (Variant[Integer[0],String]) (defaults to: '0600')

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

  • sshkeys (Array[String]) (defaults to: [])

    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.

  • system (Boolean) (defaults to: false)

    Specifies if you want to create a system account.

  • uid (Optional[Accounts::User::Uid]) (defaults to: undef)

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



182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
# File 'manifests/user.pp', line 182

define accounts::user (
  Enum['absent','present']                 $ensure                   = 'present',
  Boolean                                  $allowdupe                = false,
  Optional[String]                         $bash_profile_content     = undef,
  Optional[Stdlib::Filesource]             $bash_profile_source      = undef,
  Optional[String]                         $bashrc_content           = undef,
  Optional[Stdlib::Filesource]             $bashrc_source            = undef,
  String                                   $comment                  = $name,
  Boolean                                  $create_group             = true,
  Optional[Accounts::User::Expiry]         $expiry                   = undef,
  Optional[Boolean]                        $forcelocal               = undef,
  Optional[String]                         $forward_content          = undef,
  Optional[Stdlib::Filesource]             $forward_source           = undef,
  Optional[Accounts::User::Uid]            $gid                      = undef,
  Accounts::User::Name                     $group                    = $name,
  Array[Accounts::User::Name]              $groups                   = [],
  Optional[Stdlib::Unixpath]               $home                     = undef,
  Optional[Stdlib::Filemode]               $home_mode                = undef,
  Boolean                                  $ignore_password_if_empty = false,
  Optional[Accounts::User::Iterations]     $iterations               = undef,
  Boolean                                  $locked                   = false,
  Boolean                                  $managehome               = true,
  Boolean                                  $managevim                = true,
  Enum['inclusive','minimum']              $membership               = 'minimum',
  Variant[String, Sensitive[String]]       $password                 = '!!',
  Optional[Accounts::User::PasswordMaxAge] $password_max_age         = undef,
  Boolean                                  $purge_sshkeys            = false,
  Boolean                                  $purge_user_home          = false,
  Optional[String]                         $salt                     = undef,
  Stdlib::Unixpath                         $shell                    = '/bin/bash',
  Optional[Stdlib::Unixpath]               $sshkey_custom_path       = undef,
  Optional[Accounts::User::Name]           $sshkey_group             = $group,
  Optional[Accounts::User::Name]           $sshkey_owner             = $name,
  Variant[Integer[0],String]               $sshkey_mode              = '0600',
  Array[String]                            $sshkeys                  = [],
  Boolean                                  $system                   = false,
  Optional[Accounts::User::Uid]            $uid                      = undef,
) {
  assert_type(Accounts::User::Name, $name)

  include accounts::user::defaults

  $_home = $home ? {
    undef => $name ? {
      'root'  => $accounts::user::defaults::root_home,
      default => $accounts::user::defaults::home_template.sprintf($name),
    },
    default => $home,
  }

  if $ensure == 'absent' {
    user { $name:
      ensure     => 'absent',
      forcelocal => $forcelocal,
      home       => $_home,
      managehome => false,  # Workaround for PUP-9706; see below.
    }
    # The core `user` resource will fail when removing users on Solaris if
    # `ensure => 'absent', managhome => true` and the homedir does not exist.
    # We therefore force `managehome => false` when `ensure => 'absent'`, and
    # remove the homedir as a separate operation.
    # See https://tickets.puppetlabs.com/browse/PUP-9706
    if $purge_user_home {
      file { $_home:
        ensure  => 'absent',
        recurse => true,
        force   => true,
      }
    }
    # End workaround.
    User[$name] -> Group <| ensure == 'absent' |>
    if $create_group {
      # Only remove the group if it is the same as user name as it may be shared.
      if $name == $group {
        ensure_resource(
          'group',
          $group,
          { 'ensure'     => 'absent',
            'forcelocal' => $forcelocal,
          }
        )
      }
    }
    accounts::key_management { "${name}_key_management":
      ensure             => 'absent',
      user               => $name,
      user_home          => $_home,
      sshkeys            => $sshkeys,
      sshkey_custom_path => $sshkey_custom_path,
      sshkey_owner       => $sshkey_owner,
      sshkey_group       => $sshkey_group,
      sshkey_mode        => $sshkey_mode,
      purge_user_home    => $purge_user_home,
    }
  } else {
    # Check if user wants to create the group
    if $create_group and ! defined(Group[$group]) {
      Group[$group] -> User[$name]
      ensure_resource(
        'group',
        $group,
        { ensure     => 'present',
          gid        => $gid,
          system     => $system,
          forcelocal => $forcelocal,
        }
      )
    }
    $_password = (($password =~ String and $password == '') and $ignore_password_if_empty) ? {
      true    => undef,
      default => $password,
    }
    $_purge_sshkeys = ($purge_sshkeys and $sshkey_custom_path != undef) ? {
      true => [String($sshkey_custom_path)],
      default => $purge_sshkeys,
    }
    $_shell = $locked ? {
      true    => $accounts::user::defaults::locked_shell,
      default => $shell,
    }
    user { $name:
      ensure           => 'present',
      allowdupe        => $allowdupe,
      comment          => String($comment),
      expiry           => $expiry,
      forcelocal       => $forcelocal,
      gid              => $group,
      groups           => $groups,
      home             => $_home,
      iterations       => $iterations,
      managehome       => $managehome,
      membership       => $membership,
      password         => $_password,
      password_max_age => $password_max_age,
      purge_ssh_keys   => $_purge_sshkeys,
      salt             => $salt,
      shell            => $_shell,
      system           => $system,
      uid              => $uid,
    }
    if $managehome {
      accounts::home_dir { $_home:
        ensure               => 'present',
        mode                 => $home_mode,
        managevim            => $managevim,
        bashrc_content       => $bashrc_content,
        bashrc_source        => $bashrc_source,
        bash_profile_content => $bash_profile_content,
        bash_profile_source  => $bash_profile_source,
        forward_content      => $forward_content,
        forward_source       => $forward_source,
        user                 => $name,
        group                => $group,
        require              => [User[$name]],
      }
      accounts::key_management { "${name}_key_management":
        ensure             => 'present',
        user               => $name,
        group              => $group,
        user_home          => $_home,
        sshkeys            => $sshkeys,
        sshkey_custom_path => $sshkey_custom_path,
        sshkey_owner       => $sshkey_owner,
        sshkey_group       => $sshkey_group,
        sshkey_mode        => $sshkey_mode,
        purge_user_home    => $purge_user_home,
        require            => Accounts::Home_dir[$_home],
      }
    } elsif $sshkeys != [] {
      # We are not managing the user's home directory but we have specified a
      # custom, non-home directory for the ssh keys.
      if (($sshkey_custom_path != undef) and ($ensure == 'present')) {
        accounts::key_management { "${name}_key_management":
          ensure             => 'present',
          user               => $name,
          group              => $group,
          sshkeys            => $sshkeys,
          sshkey_owner       => $sshkey_owner,
          sshkey_group       => $sshkey_group,
          sshkey_mode        => $sshkey_mode,
          sshkey_custom_path => $sshkey_custom_path,
        }
      } else {
        warning("ssh keys were passed for user ${name} but managehome is set to false; not managing user ssh keys")
      }
    }
  }
}