users

Table of contents

User promises are promises made aboutlocal users on a host. Theyexpress which users should be present on a system, and whichattributes and group memberships the users should have.

Every user promise has at least one attribute,policy, whichdescribes whether or not the user should be present on the system. Otherattributes are optional; they allow you to specify UID, home directory, loginshell, group membership, description, and password. Platform native tools areused to create/modify/delete users (C api on Windows, anduseraddusermoduserdel on Unix, Linux and similar platforms). User presence is determined bytheNetUserGetInfo function on Windows and reading/etc/passwd on Unix,Linux and similar platforms nix External/non-local for example LDAP are ignored.

A bundle can be associated with a user promise, such as when a user is createdin order to do housekeeping tasks in his/her home directory, like puttingdefault configuration files in place, installing encryption keys, and storinga login picture.

Note: This promise type does not create or delete groups (not even a usersprimary group). The groups the user is promised to be in need to be managedseparately.

History: Introduced in CFEngine 3.6.0

Example:

code

users:"jsmith"policy=>"present",description=>"John Smith",home_dir=>"/remote/home/jsmith",group_primary=>"users",groups_secondary=>{"printers","webadmin"},shell=>"/bin/bash";

Attributes

Common attributes

Common attributes are available to all promise types. Full details for commonattributes can be found in theCommon promise attributes section ofthePromise types page. The common attributes are as follows:

action

classes

comment

depends_on

handle

if

unless

with

description

Description: Thedescription string sets the descriptionassociated with a user.

The exact use of this string depends on the operating system,but most systems treat it as the full name of the user and thereforedisplay it on graphical login terminals.

Type:string

Allowed input range: (arbitrary string)

Example:

code

users:"jsmith"policy=>"present",description=>"John Smith";

group_primary

Description: Thegroup_primary attribute sets the user's primary group.

Note: On Windows, no difference exists between primary andsecondary groups so specifying either one works.

Type:string

Allowed input range: (arbitrary string)

Example:

code

users:"jsmith"policy=>"present",group_primary=>"users";

groups_secondary

Description: Thegroups_secondary attributes sets the user'ssecondary group membership(s), in addition to his/her primary group.

Note: On Windows, no difference exists between primary andsecondary groups so specifying either one works.

Type:slist

Allowed input range:.*

Example:

code

users:"jsmith"policy=>"present",groups_secondary=>{"site_a","tester"};

home_bundle

Description: Thehome_bundle attribute specifies a bundle thatis evaluated when the user is created.

If the user already exists, the bundle is not evaluated.

The name of the promised user is not passed to the bundledirectly, but you can specify a bundle with parameters in order topass it in.

Note that this attribute does not set the home directory in the userdatabase. For that, you must use thehome_dir attribute.

Type:bundle

Example:

code

bundleagentmain{vars:"users"slist=>{"jack","john"};"skel"string=>"/etc/skel";users:!windows::"$(users)"policy=>"present",home_dir=>"/home/$(users)",home_bundle=>home_skel($(users),$(skel));}

code

bundleagenthome_skel(user,skel){files:"/home/$(user)/."create=>"true",copy_from=>seed_cp($(skel)),depth_search=>recurse("inf");}

This example uses implicit looping to create the two users, "jack"and "john." Each has his respective home directory that is created bythefiles promise.

home_bundle_inherit

Description: Thehome_bundle_inherit attribute specifies if classes setin the current bundle are inherited by the bundle specified in thehome_bundle attribute.

Type:boolean

Example:

code

bundleagentmain{vars:"user"string=>"jack";classes:"should_have_home_dir"expression=>regcmp("j.*","$(user)");users:"$(user)"policy=>"present",home_dir=>"/home/$(user)",home_bundle=>setup_home_dir("$(user)"),home_bundle_inherit=>"true";}bundleagentsetup_home_dir(user){files:should_have_home_dir::"/home/$(user)/."create=>"true";}

The user "jack" will have his home directory created, since hisusername starts with "j".

home_dir

Description: Thehome_dir attribute associates a user with thegiven home directory.

Note that this attribute does not create the directory. For that youmust use thehome_bundle attribute. This just sets the homedirectory in the user database.

Type:string

Allowed input range:"?(/.*)

Example:

code

users:"jsmith"policy=>"present",home_dir=>"/home/j/jsmith";

password

Description: Thepassword attribute specifies apassword bodythat contains information about a user's password.

Type:body password

Example:

code

bodypassworduser_password{format=>"hash";data=>"jiJSlLSkZuVLE";# "CFEngine"}

See also:Common body attributes

format

Description: Specifies the format of the given password data.

If the value is "hash," then thedata attribute is expected tocontain a string with a password in hashed format. Note that CFEnginedoes not validate that the given hash format is supported bythe platform. The system administrator must verify this.However, CFEngine continues to run even in the event of anunsupported password format, so it can always be corrected by updatingthe policy.

If the value is "plaintext," then thedata attribute containsthe password in plain text.

Note: On Windows, only the "plaintext" password type is supported,due to a lack of support from the operating system for settinghashed passwords.

Type: (menu option)

Allowed input range:

plaintext
hash

Example:

code

bodypassworduser_password{format=>"plaintext";data=>"CFEngine";}

data

Description: Specifies the password data.

The format of the password data depends on theformat attribute.

Type:string

Allowed input range: (arbitrary string)

Example:

code

bodypassworduser_password{format=>"plaintext";data=>"CFEngine";}

policy

Description: Thepolicy attribute specifies what state the useraccount has on the system.

If the policy ispresent, the user is present and activeon the system. Note that an unset password might still prevent the userfrom logging in.

If the policy islocked, and the user does not exist, it is created withpassword authentication disabled. If the user account already exists itspassword digest is prepended with a "!", disabling password authentication.Note that only logins via the PAM framework are prevented. This includes normalconsole logins and SSH logins on most systems.

If the policy isabsent, the user does not exist on the system. Notethat if a user previously existed, his/her files are notautomatically removed. You must create a separatefiles promise forthis.

Note: When CFEngine locks an account it does two things, it disablesthe login password, and it sets the account expiration date far in thepast. The expiration date is to prevent key based SSH logins. However,on Solaris it is not possible to set the account expiration date in thisway, hence SSH logins may still work there after an account is lockedand additional steps may be required.

Type: (menu option)

Allowed input range:

present
absent
locked

Example:

code

users:"jsmith"policy=>"locked";

shell

Description: Theshell attribute specifies the user's loginshell.

Type:string

Allowed input range:"?(/.*)

Example:

code

users:"jsmith"shell=>"/bin/bash";

uid

Description: Theuid attribute specifies the user's UID number.

Note that if the UID of an existing user is changed, the files ownedby that user do not automatically change ownership. You must create aseparatefiles promise for this.

Type:int

Allowed input range:-99999999999,99999999999

Example:

code