.. -*- mode: rst -*-

.. _client-tools-posixusers:

==========
POSIXUsers
==========

.. versionadded:: 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 :ref:`server-plugins-generators-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.::

    [POSIXUsers]
    uid_blacklist=1000-
    gid_whitelist=0-500,700-999

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.

.. note::

    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/posixusers_baseline.py`` script, which outputs a bundle
containing all users and groups on the machine it's run on.