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