New in version 1.3.0.

The POSIXUsers tool handles the creation of users and groups as defined by POSIXUser and POSIXGroup entries. For a full description of those tags, see Rules.

The POSIXUsers tool relies on the useradd, usermod, userdel, groupadd, groupmod, and groupdel tools, since there is no Python library to manage users and groups. It expects those tools to be in /usr/sbin.

Primary group creation

Each user must have a primary group, which can be specified with the group attribute of the POSIXUser tag. (If the group attribute is not specified, then a group with the same name as the user will be used.) If that group does not exist, the POSIXUsers tool will create it automatically. It does this by adding a POSIXGroup entry on the fly; this has a few repercussions:

  • When run in interactive mode (-I), Bcfg2 will prompt for installation of the group separately from the user.
  • The POSIXGroup entry is added to the same bundle as the POSIXUser entry, so if the group is created, the bundle is considered to have been modified and consequently Actions will be run and Services will be restarted. This should never be a concern, since the group can only be created, not modified (it has no attributes other than its name), and if the group is being created then the user will certainly be created or modified as well.
  • The group is created with no specified GID number. If you need to specify a particular GID number, you must explicitly define a POSIXGroup entry for the group.

Managed UID/GID Ranges

In many cases, there will be users on a system that you do not want to manage with Bcfg2, nor do you want them to be flagged as extra entries. For example, users from an LDAP directory. In this case, you may want to manage the local users on a machine with Bcfg2, while leaving the LDAP users to be managed by the LDAP directory. To do this, you can configure the UID and GID ranges that are to be managed by Bcfg2 by setting the following options in the [POSIXUsers] section of bcfg2.conf on the client:

  • uid_whitelist
  • uid_blacklist
  • gid_whitelist
  • gid_blacklist

Each option takes a comma-delimited list of numeric ranges, inclusive at both bounds, one of which may be open-ended on the upper bound, e.g.:


This would tell Bcfg2 to manage all users whose uid numbers were not greater than or equal to 1000, and all groups whose gid numbers were 0 <= gid <= 500 or 700 <= gid <= 999.

If a whitelist is provided, it will be used; otherwise, the blacklist will be used. (I.e., if you provide both, the blacklist will be ignored.)

If a user or group is added to the specification with a uid or gid in an unmanaged range, it will produce an error.


If you specify POSIXUser or POSIXGroup tags without an explicit uid or gid, this will not prevent the users/groups from being created with a uid/gid in an unmanaged range. If you want that to happen, you will need to configure your useradd/groupadd defaults appropriately. Note also, however, that this will not cause Bcfg2 errors; it is only an error if a POSIXUser or POSIXGroup has an explicit uid/gid in an unmanaged range.

Creating a baseline configuration

The majority of users on many systems are created by the packages that are installed, but currently Bcfg2 cannot query the package database to determine these users. (In some cases, this is a limitation of the packaging system.) The often-tedious task of creating a baseline that defines all users and groups can be simplified by use of the tools/ script, which outputs a bundle containing all users and groups on the machine it’s run on.

Table Of Contents

Previous topic


Next topic

VCS Client Tool

This Page