NOTE: This page was generated from the Puppet source code on 2024-08-28 16:45:59 -0700
Manage users. This type is mostly built to manage system users, so it is lacking some features useful for managing normal users.
This resource type uses the prescribed native tools for creating
groups and generally uses POSIX APIs for retrieving information about
them. It does not directly modify /etc/passwd
or
anything.
Autorequires: If Puppet is managing the user’s
primary group (as provided in the gid
attribute) or any
group listed in the groups
attribute then the user resource
will autorequire that group. If Puppet is managing any role accounts
corresponding to the user’s roles, the user resource will autorequire
those role accounts.
user { 'resource title':
name => # (namevar) The user name. While naming limitations vary by...
ensure => # The basic state that the object should be in....
allowdupe => # Whether to allow duplicate UIDs. Default...
attribute_membership => # Whether specified attribute value pairs should...
attributes => # Specify AIX attributes for the user in an array...
auth_membership => # Whether specified auths should be considered the
auths => # The auths the user has. Multiple auths should...
comment => # A description of the user. Generally the user's
expiry => # The expiry date for this user. Provide as either
forcelocal => # Forces the management of local accounts when...
gid => # The user's primary group. Can be specified...
groups => # The groups to which the user belongs. The...
home => # The home directory of the user. The directory...
ia_load_module => # The name of the I&A module to use to manage this
iterations => # This is the number of iterations of a chained...
key_membership => # Whether specified key/value pairs should be...
keys => # Specify user attributes in an array of key ...
loginclass => # The name of login class to which the user...
managehome => # Whether to manage the home directory when Puppet
membership => # If `minimum` is specified, Puppet will ensure...
password => # The user's password, in whatever encrypted...
password_max_age => # The maximum number of days a password may be...
password_min_age => # The minimum number of days a password must be...
password_warn_days => # The number of days before a password is going to
profile_membership => # Whether specified roles should be treated as the
profiles => # The profiles the user has. Multiple profiles...
project => # The name of the project associated with a...
provider => # The specific backend to use for this `user...
purge_ssh_keys => # Whether to purge authorized SSH keys for this...
role_membership => # Whether specified roles should be considered the
roles => # The roles the user has. Multiple roles should...
salt => # This is the 32-byte salt used to generate the...
shell => # The user's login shell. The shell must exist...
system => # Whether the user is a system user, according to...
uid => # The user ID; must be specified numerically. If...
# ...plus any applicable metaparameters.
}
(Namevar: If omitted, this attribute’s value defaults to the resource’s title.)
The user name. While naming limitations vary by operating system, it is advisable to restrict names to the lowest common denominator, which is a maximum of 8 characters beginning with a letter.
Note that Puppet considers user names to be case-sensitive, regardless of the platform’s own rules; be sure to always use the same case when referring to a given user.
(Property: This attribute represents concrete state on the target system.)
The basic state that the object should be in.
Allowed values:
present
absent
role
Whether to allow duplicate UIDs.
Default: false
Allowed values:
true
false
yes
no
Whether specified attribute value pairs should be treated as the
complete list (inclusive
) or the
minimum list (minimum
) of attribute/value
pairs for the user.
Default: minimum
Allowed values:
inclusive
minimum
(Property: This attribute represents concrete state on the target system.)
Specify AIX attributes for the user in an array or hash of attribute = value pairs.
For example:
['minage=0', 'maxage=5', 'SYSTEM=compat']
or
attributes => { 'minage' => '0', 'maxage' => '5', 'SYSTEM' => 'compat' }
Requires features manages_aix_lam.
Whether specified auths should be considered the complete
list (inclusive
) or the minimum
list (minimum
) of auths the user has. This setting
is specific to managing Solaris authorizations.
Default: minimum
Allowed values:
inclusive
minimum
(Property: This attribute represents concrete state on the target system.)
The auths the user has. Multiple auths should be specified as an array.
Requires features manages_solaris_rbac.
(Property: This attribute represents concrete state on the target system.)
A description of the user. Generally the user’s full name.
(Property: This attribute represents concrete state on the target system.)
The expiry date for this user. Provide as either the special value
absent
to ensure that the account never expires, or as a
zero-padded YYYY-MM-DD format – for example, 2010-02-19.
Allowed values:
absent
/^\d{4}-\d{2}-\d{2}$/
Requires features manages_expiry.
Forces the management of local accounts when accounts are also being
managed by some other Name Service Switch (NSS). For AIX, refer to the
ia_load_module
parameter.
This option relies on your operating system’s implementation of
luser*
commands, such as luseradd
, and
lgroupadd
, lusermod
. The
forcelocal
option could behave unpredictably in some
circumstances. If the tools it depends on are not available, it might
have no effect at all.
Default: false
Allowed values:
true
false
yes
no
Requires features manages_local_users_and_groups.
(Property: This attribute represents concrete state on the target system.)
The user’s primary group. Can be specified numerically or by name.
This attribute is not supported on Windows systems; use the
groups
attribute instead. (On Windows, designating a
primary group is only meaningful for domain accounts, which Puppet does
not currently manage.)
(Property: This attribute represents concrete state on the target system.)
The groups to which the user belongs. The primary group should not be listed, and groups should be identified by name rather than by GID. Multiple groups should be specified as an array.
(Property: This attribute represents concrete state on the target system.)
The home directory of the user. The directory must be created separately and is not currently checked for existence.
The name of the I&A module to use to manage this user. This
should be set to files
if managing local users.
Requires features manages_aix_lam.
(Property: This attribute represents concrete state on the target system.)
This is the number of iterations of a chained computation of the PBKDF2 password hash. This parameter is used in OS X, and is required for managing passwords on OS X 10.8 and newer.
Requires features manages_password_salt.
Whether specified key/value pairs should be considered the
complete list (inclusive
) or the
minimum list (minimum
) of the user’s
attributes.
Default: minimum
Allowed values:
inclusive
minimum
(Property: This attribute represents concrete state on the target system.)
Specify user attributes in an array of key = value pairs.
Requires features manages_solaris_rbac.
(Property: This attribute represents concrete state on the target system.)
The name of login class to which the user belongs.
Requires features manages_loginclass.
Whether to manage the home directory when Puppet creates or removes the user. This creates the home directory if Puppet also creates the user account, and deletes the home directory if Puppet also removes the user account.
This parameter has no effect unless Puppet is also creating or
removing the user in the resource at the same time. For instance, Puppet
creates a home directory for a managed user if
ensure => present
and the user does not exist at the
time of the Puppet run. If the home directory is then deleted manually,
Puppet will not recreate it on the next run.
Note that on Windows, this manages creation/deletion of the user
profile instead of the home directory. The user profile is stored in the
C:\\Users\\<username>
directory.
Default: false
Allowed values:
true
false
yes
no
If minimum
is specified, Puppet will ensure that the
user is a member of all specified groups, but will not remove any other
groups that the user is a part of.
If inclusive
is specified, Puppet will ensure that the
user is a member of only specified groups.
Default: minimum
Allowed values:
inclusive
minimum
(Property: This attribute represents concrete state on the target system.)
The user’s password, in whatever encrypted format the local system requires. Consult your operating system’s documentation for acceptable password encryption formats and requirements.
sha1
function to generate a salted SHA1 hash from a password.str2saltedsha512
function which can
generate password hashes for these operating systems.salt
and
iterations
attributes need to be specified as well as the
password.Enclose any value that includes a dollar sign ($) in single quotes (’) to avoid accidental variable interpolation.
To redact passwords from reports to PuppetDB, use the
Sensitive
data type. For example, this resource protects
the password:
user { 'foo':
ensure => present,
password => Sensitive("my secret password")
}
This results in the password being redacted from the report, as in
the previous_value
, desired_value
, and
message
fields below.
events:
- !ruby/object:Puppet::Transaction::Event
audited: false
property: password
previous_value: "[redacted]"
desired_value: "[redacted]"
historical_value:
message: changed [redacted] to [redacted]
name: :password_changed
status: success
time: 2017-05-17 16:06:02.934398293 -07:00
redacted: true
corrective_change: false
corrective_change: false
Requires features manages_passwords.
(Property: This attribute represents concrete state on the target system.)
The maximum number of days a password may be used before it must be changed.
Requires features manages_password_age.
(Property: This attribute represents concrete state on the target system.)
The minimum number of days a password must be used before it may be changed.
Requires features manages_password_age.
(Property: This attribute represents concrete state on the target system.)
The number of days before a password is going to expire (see the maximum password age) during which the user should be warned.
Requires features manages_password_age.
Whether specified roles should be treated as the complete
list (inclusive
) or the minimum
list (minimum
) of roles of which the user is a
member.
Default: minimum
Allowed values:
inclusive
minimum
(Property: This attribute represents concrete state on the target system.)
The profiles the user has. Multiple profiles should be specified as an array.
Requires features manages_solaris_rbac.
(Property: This attribute represents concrete state on the target system.)
The name of the project associated with a user.
Requires features manages_solaris_rbac.
The specific backend to use for this user
resource. You
will seldom need to specify this — Puppet will usually discover the
appropriate provider for your platform.
Available providers are:
Whether to purge authorized SSH keys for this user if they are not
managed with the ssh_authorized_key
resource type. This
parameter is a noop if the ssh_authorized_key type is not available.
Allowed values are:
false
(default) — don’t purge SSH keys for this
user.true
— look for keys in the
.ssh/authorized_keys
file in the user’s home directory.
Purge any keys that aren’t managed as ssh_authorized_key
resources.ssh_authorized_key
resources. If any of these paths starts with ~
or
%h
, that token will be replaced with the user’s home
directory.Default: false
Allowed values:
true
false
Whether specified roles should be considered the complete
list (inclusive
) or the minimum
list (minimum
) of roles the user has.
Default: minimum
Allowed values:
inclusive
minimum
(Property: This attribute represents concrete state on the target system.)
The roles the user has. Multiple roles should be specified as an array.
Requires features manages_roles.
(Property: This attribute represents concrete state on the target system.)
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.
Requires features manages_password_salt.
(Property: This attribute represents concrete state on the target system.)
The user’s login shell. The shell must exist and be executable.
This attribute cannot be managed on Windows systems.
Requires features manages_shell.
Whether the user is a system user, according to the OS’s criteria; on most platforms, a UID less than or equal to 500 indicates a system user. This parameter is only used when the resource is created and will not affect the UID when the user is present.
Default: false
Allowed values:
true
false
yes
no
(Property: This attribute represents concrete state on the target system.)
The user ID; must be specified numerically. If no user ID is specified when creating a new user, then one will be chosen automatically. This will likely result in the same user having different UIDs on different systems, which is not recommended. This is especially noteworthy when managing the same user on both Darwin and other platforms, since Puppet does UID generation on Darwin, but the underlying tools do so on other platforms.
On Windows, this property is read-only and will return the user’s security identifier (SID).
User management for AIX.
/bin/chpasswd
,
/usr/bin/chuser
, /usr/bin/mkuser
,
/usr/sbin/lsuser
, /usr/sbin/rmuser
os.name == aix
["os.name", "aix"] ==
manages_aix_lam
,
manages_expiry
, manages_homedir
,
manages_local_users_and_groups
,
manages_password_age
, manages_passwords
,
manages_shell
User management on OS X.
/usr/bin/dscacheutil
,
/usr/bin/dscl
, /usr/bin/dsimport
,
/usr/bin/uuidgen
os.name == darwin
,
feature == cfpropertylist
["os.name", "darwin"] ==
manages_password_salt
,
manages_passwords
, manages_shell
User management for HP-UX. This provider uses the undocumented
-F
switch to HP-UX’s special usermod
binary to
work around the fact that its standard usermod
cannot make
changes while the user is logged in. New functionality provides for
changing trusted computing passwords and resetting password expirations
under trusted computing.
/usr/sam/lbin/useradd.sam
,
/usr/sam/lbin/userdel.sam
,
/usr/sam/lbin/usermod.sam
os.name == hp-ux
["os.name", "hp-ux"] ==
allows_duplicates
,
manages_homedir
, manages_passwords
User management via LDAP.
This provider requires that you have valid values for all of the
LDAP-related settings in puppet.conf
, including
ldapbase
. You will almost definitely need settings for
ldapuser
and ldappassword
in order for your
clients to write to LDAP.
Note that this provider will automatically generate a UID for you if you do not specify one, but it is a potentially expensive operation, as it iterates across all existing users to pick the appropriate next one.
feature == ldap
,
false == (Puppet[:ldapuser] == "")
manages_passwords
,
manages_shell
User management via useradd
and its ilk for OpenBSD.
Note that you will need to install Ruby’s shadow password library
(package known as ruby-shadow
) if you wish to manage user
passwords.
passwd
, useradd
,
userdel
, usermod
os.name == openbsd
["os.name", "openbsd"] ==
manages_expiry
,
manages_homedir
, manages_shell
,
system_users
User management via pw
on FreeBSD and DragonFly BSD.
pw
os.name == [:freebsd, :dragonfly]
["os.name", "[:freebsd, :dragonfly]"] ==
allows_duplicates
,
manages_expiry
, manages_homedir
,
manages_passwords
, manages_shell
User and role management on Solaris, via useradd
and
roleadd
.
passwd
, roleadd
,
roledel
, rolemod
, useradd
,
userdel
, usermod
["os.family", "solaris"] ==
allows_duplicates
,
manages_homedir
, manages_password_age
,
manages_passwords
, manages_roles
,
manages_shell
, manages_solaris_rbac
User management via useradd
and its ilk. Note that you
will need to install Ruby’s shadow password library (often known as
ruby-libshadow
) if you wish to manage user passwords.
To use the forcelocal
parameter, you need to install the
libuser
package (providing /usr/sbin/lgroupadd
and /usr/sbin/luseradd
).
chage
, chpasswd
,
useradd
, userdel
, usermod
allows_duplicates
,
manages_expiry
, manages_homedir
,
manages_shell
Local user management for Windows.
os.name == windows
["os.name", "windows"] ==
manages_homedir
,
manages_passwords
, manages_roles
Available features:
allows_duplicates
— The provider supports duplicate
users with the same UID.manages_aix_lam
— The provider can manage AIX Loadable
Authentication Module (LAM) system.manages_expiry
— The provider can manage the expiry
date for a user.manages_homedir
— The provider can create and remove
home directories.manages_local_users_and_groups
— Allows local users to
be managed on systems that also use some other remote Name Service
Switch (NSS) method of managing accounts.manages_loginclass
— The provider can manage the login
class for a user.manages_password_age
— The provider can set age
requirements and restrictions for passwords.manages_password_salt
— The provider can set a password
salt. This is for providers that implement PBKDF2 passwords with salt
properties.manages_passwords
— The provider can modify user
passwords, by accepting a password hash.manages_roles
— The provider can manage rolesmanages_shell
— The provider allows for setting shell
and validates if possiblemanages_solaris_rbac
— The provider can manage normal
userssystem_users
— The provider allows you to create system
users with lower UIDs.Provider support: