module:users - user account management

Configuration | Convert Existing Accounts

module:users provides user account management when run as a CFEngine module. The module primarily supports Unix, though also supports local user accounts on Windows and account management for other applications. See also module:groups for Unix group management.

Advantages of module:users include extensbility to support new operating systems and application interfaces, assuming appropriate list, add, modify, and remove command interfaces. Also, systems are not slaved to a directory service. This allows support for laptops and systems incompatible with the directory service du jour.

Disadvantages of module:users include scalability problems, and the need to run scripts everywhere.

With the no_modify class set in the CFALLCLASSES environment variable, module:users will only display what changes would be made to the system. This simplifies rollouts to previously unmanaged systems.

The source code for module:users is only available by request.



main.ini contains module defaults, and configuration classes that define how to list, create, and remove user accounts via any number of operating system or application interfaces.

missing_file = /var/cfengine/local/users/missing
unaccounted_file = /var/cfengine/local/users/unaccounted

cf_dir = /var/cfengine/local/users/os-base /var/cfengine/local/users/site

cf_class_add = action_user_added
cf_class_remove = action_user_removed

list_cmd = /usr/bin/nidump passwd /

install_cmd = /usr/sbin/useradd -c %{realname}
-s %{shell} -u %{id} -g %{gid} %{name} -d %{homedir}
remove_cmd = /usr/sbin/userdel %{name}

Several classes affect the behaviour of module:users; these include no_modify, which shows what actions would take place without affecting the system in question. Setting the cf_debug class in cfengine turns on additional logging.


The rules file contains rules that alter user account data, depending on the user in question or classes defined. As the rules data may change user account data (home directory, shell), system accounts should be tagged with system_account=true and the following rule used to prevent modification.

# do not mangle system accounts - must be first rule!
test: system_account eq true
flow: abort

Defaults can be set, and home directories changed, depending on the Operating System. Also, users can be locked out of the system by changing the shell.

# set default home directory
actions: homedir=/home/%{name}

# except on Mac OS X...
test: cf.classes contains macosx
actions: homdir=/Users/%{name}

# disable shell on no login systems, except for admins
test: cf.classes contains no_user_login
test: classes not contains group_sysadmin
actions: shell=/sbin/nologin

Another option for home directory management is to use an automount daemon, and push the home directory complexity into the automount configuration.


The users.ini should only list user accounts; system and application specific accounts are better managed under different files. Note the use of classes to define what CFEngine classes the user account applies to. See below for information on converting existing account data.

classes = group_sysadmin
email =
id = 1000
realname = John Doe
shell = /bin/zsh

classes = group_devel group_production
email =
id = 1001
realname = M. Smith
shell = /bin/bash

Convert Existing Accounts

Use passwd2ini and initidy to convert existing user account data from Unix to the *.ini files used by module:users. The following outlines the process used on a Mac OS X 10.4 system. The conversion should ideally be done on a newly installed system.

$ nidump passwd / \
| passwd2ini -a system_account=true -c macosx_10_4 \
| initidy > os-base/

Then, move user account into the main users.ini configuration file, and move any site or application specific accounts into other files as appropriate. For example, a site may always create a macadmin account as the first administrative account; this would be placed into site/ The following shows two example system accounts for Mac OS X 10.4.

classes = macosx_10_4
homedir = /var/empty
id = -2
realname = Unprivileged User
shell = /usr/bin/false
system_account = true

classes = macosx_10_4
homedir = /var/root
id = 0
realname = System Administrator
shell = /bin/sh
system_account = true

Application accounts required by Fink could be placed into a site/ configuration file. If an account is specific to a particular revision of Mac OS X, use a specific file, which will only be read if the macosx_10_4 class is defined. Use revision specific definitions, as vendors may change system accounts between major releases.

If application accounts differ depending on the Operating System, either ideally make them conform to a site-wide standard, or account for the difference in a $parent_class/$ configuration file. The CFEngine configuration may also need a variable to track the username, if different, across the different operating systems. An example of such an account: RedHat Linux uses postgres, and OpenBSD _postgres for the default PostgreSQL database user account.