Using the auth component

The details below apply to lcfg-auth version 2.10 using the version 4 auth schema (which covers Ubuntu Focal and beyond). For information on the old version of the auth component (used on SL7) see AuthComponentLegacy.

passwd and group entries

If the auth.managepasswd resource is set to true then the LCFG auth component will actively manage local users and groups.

Unlike previous versions of this component it does not manage all users and groups. There are now two classes of users and groups - managed and unmanaged. Any user or group added at system install time or added via a package post-install script will be considered to be unmanaged until resources are added to the auth component for that entity. The reason for this change is that managing all possible users and groups required a considerable amount of effort and inevitably we never had complete support for all possible entities. This often had the undesirable result that when new packages were added the necessary entities would be created by the package install script and then at some point later erased by the auth component which would lead to annoying (and often unseen) breakage. It has also become apparent that in the modern world attempting to manage all users and groups is rather pointless as it is rarely necessary to manage them all for a system, typically a system administrator will just wish to add a few extra entities. The previous behaviour of the auth component was a relic from the days when software either wasn't packaged (e.g. old Unixes, Solaris et al) or the packages lacked scripts to do the work. It is usually now quite safe to assume that a package will do all the necessary preparatory work for the software to be usable "out of the box".

Further to this, we have previously attempted to micro-manage the IDs for users and groups, an approach which is only possible when you are managing all users and groups. When users and groups are created by package scripts they typically get allocated IDs within a specified range in a way which we cannot predict and that will vary from machine to machine. There is rarely any need for a system user (i.e. for a daemon to run safely as something other than the root user) to have an ID which is identical on all managed machines. The main reason for using the same ID is where network filesystems are involved (e.g. NFS or AFS) and we want to be able to easily access data from multiple machines. Whilst the new version of the auth component still supports the specifying of IDs the recommendation is that it is only done when truly necessary. If resources for a user or group do not include an ID then the entity will be created in the same way as it would be with a packaging script with the next available ID being allocated.

The Debian policy has details on the various ID ranges in the users and groups section.

Users

User information is specified using the following resources:

• pw_name_$ : The name of the user, the tag name is used if not specified.
• pw_uid_$ : The UID for the user, this is optional.
• pw_gid_$ : The primary group for the user, may be specified as a group name, this is optional.
• pw_passwd_$ : The password for the user, this is optional.
• pw_gecos_$ : Any GECOS information for the user, this is optional.
• pw_dir_$ : The home directory for the user, this is required.
• pw_shell_$ : The shell for the user, this is required.

NOTE - Using the old-style pwent resource is now an error.

The behaviour of the component can be modified via the following per-user resources:

• create_home_$ : Create the home directory if it does not exist (boolean, defaults to false).
• skel_dir_$ : Skeleton directory to use when creating the user.
• sysuser_$ : Select the UID and GID from the system user range (boolean, defaults to false).

Note that a user needs to be added to the auth.extrapasswd tag list. There is a library of standard users available in the lcfg/options/localaccounts.h header.

Groups

Group information is specified using the following resources:

• gr_name_$ : The name of the group, the tag name is used if not specified.
• gr_gid_$ : The GID for the user, this is optional.
• gr_passwd_$ : The password for the group, this is optional.
• gr_mem_$ : A list of users which are members of the group (for ease of mutating the resource this may be space-separated unlike the /etc/group file).

NOTE - Using the old-style grpent resource is now an error.

The behaviour of the component can be modified via the following per-group resources:

• sysgroup_$ : Select GID from the system group range (boolean, defaults to false).

Note that a group needs to be added to the auth.extragroup tag list. There is a library of standard groups available in the lcfg/options/localaccounts.h header.

Adding users and groups is most simply done using a variety of macros which are provided in the lcfg/defaults/auth.h header, see below for details:

Adding a system user

System users are typically used for local services. The simplest way to add one is using the AUTH_SYSUSER macro:

AUTH_SYSUSER(lldpd,LLDP daemon,/var/lib/lldpd,/sbin/nologin)

!auth.extrapasswd mADD(lldpd)

If the user lldpd does not already exist it will be created with uid and gid automatically allocated in the system range - see login.defs(5) and adduser.conf(5) for details - this is typically in the range 100-999.

The macro takes: gecos, home directory and shell, if the user already exists the info will be updated to match the requirements.

Usually the user name and group will match, if you need to create a user with a different primary group you can use the AUTH_SYSUSER_IN_GROUP macro:

AUTH_SYSUSER_IN_GROUP(foo,The Foo Service,/var/lib/foo,/sbin/nologin,bar)

!auth.extrapasswd mADD(foo)

The primary group may be specified as a name or an ID. The alternate primary group does not have to be specified as an LCFG resource but in that case it must already exist on the system.

Users are added to secondary groups via the gr_mem_$ resource for the relevant group, for details see below.

A library of standard users and groups is provided in the lcfg/options/localaccounts.h header.

Adding a normal user

The simplest way to add a normal user is using the AUTH_USER macro:

AUTH_USER(example1,1001,The First Example User,/home/example1,/bin/bash)

!auth.extrapasswd mADD(example1)

If the user example1 does not already exist it will be created with specified uid and gid. Note that if the user already exists but with a different UID the UID will NOT be changed.

Note that unlike the AUTH_SYSUSER macro this requires an ID that is because normal users usually require the same ID on all systems.

The macro takes: gecos, home directory, shell and ID, if the user already exists the info will be updated to match the requirements.

Usually the user name and group will match, if you need to create a user with a different primary group you can use the AUTH_USER_IN_GROUP macro:

AUTH_USER_IN_GROUP(example2,1002,The Second Example User,/home/example2,/bin/bash,people)

!auth.extrapasswd mADD(example2)

The primary group may be specified as a name or an ID. The alternate primary group does not have to be specified as an LCFG resource but in that case it must already exist on the system.

Users are added to secondary groups via the gr_mem_$ resource for the relevant group, for details see below.

Modifying user information

Once a user has been created only the primary group, password, gecos, home directory and shell may be modified, changing the UID is NOT supported.

For a managed user just change the associated LCFG resources.

For an existing unmanaged user you need to add all the resources to make it managed (see above).

Removing a user

When a managed user is removed from the auth.extrapasswd tag list it will be removed from the system. The only exception is when the UID is less than 100, users in that list are considered to be essential to the continued functioning of the system and will not be removed. The component does not support removing unmanaged users.

Adding a system group

System groups are typically used for local services. The simplest way to add one is using the AUTH_SYSGROUP macro:

AUTH_SYSGROUP(mock)

!auth.extragroup mADD(mock)

If the group mock does not already exist it will be created with gid automatically allocated in the system range - see login.defs(5) and adduser.conf(5) for details - this is typically in the range 100-999.

Users are added to secondary groups via the gr_mem_$ resource for the relevant group, for details see below.

A library of standard users and groups is provided in the lcfg/options/localaccounts.h header.

Adding a normal group

The simplest way to add a normal group is using the AUTH_GROUP macro:

AUTH_GROUP(example4,1004)

!auth.extragroup mADD(example4)

If the group example4 does not already exist it will be created with specified gid. Note that if the group already exists but with a different GID the GID will NOT be changed.

Note that unlike the AUTH_SYSGROUP macro this requires an ID that is because normal groups usually require the same ID on all systems.

Modifying group information

Once a group has been created only the password and members may be modified, changing the GID is NOT supported.

For a managed group just change the associated LCFG resources.

For an existing unmanaged group you need to add all the resources to make it managed (see above).

Adding users to a group

Users can be added to a managed group using the relevant gr_mem_$ resource. For example:

AUTH_SYSGROUP(mock)
!auth.gr_mem_mock mADD(example1)
!auth.gr_mem_mock mADD(example2)

To add users to an unmanaged group you first need to add all the resources to make it managed (see above).

Removing a group

When a managed group is removed from the auth.extragroup tag list it will be removed from the system. The only exception is when the GID is less than 100, groups in that list are considered to be essential to the continued functioning of the system and will not be removed. The component does not support removing unmanaged groups.

-- squinney - 2020-07-24