Using the auth component

The details below apply to lcfg-auth version 1.0.6 using the version 2 auth schema.

passwd and group entries

If the auth.managepasswd resource is set to true then the LCFG auth component will manage the contents of the /etc/passwd and /etc/group files. This means that all entries which are required by the installed packages must be specified using the auth component, anything added by a package post-install script will be overwritten at some point in time.

At the most basic the auth component creates the /etc/passwd file from the contents of the LCFGDATA/common/passwd2 template file and /etc/group from the LCFGDATA/common/group template file. These template files are supplied in the relevant lcfg-defetc package for the platform (e.g. lcfg-defetc-sl5 or lcfg-defetc-f13) and provide most of the system users and groups which are required by the packages supplied in the main distribution (i.e. for SL5/SL6 this does NOT include epel). If necessary a separate template can be supplied for either of the files which allows separate management of the passwd and group files, just change the auth.base_passwd and/or auth.base_group resources to point to the correct templates. However, this is not recommended, it is considered "good practice" to use LCFG resources to extend the contents of these files. This is a much more flexible approach which makes it easier to specify and mutate user and group entries as necessary.

The auth component allows for the setting of the root passwd. This can be done by either setting the _ROOTPWD macro at the beginning of an LCFG source profile or by mutating the auth.rootpwd resource. This resource takes the encrypted version of the root password not the the original string. If setting the password for the root user or any other user you should ensure the shadow password file is being used, this option is set through the auth.shadow resource (the default value is true). Note that, like all other LCFG resources, the passwords are queryable using qxprof by any user on your system so using strong encryption is essential.

Adding Extra Users

Prior to version 1.0.0 of the LCFG auth component there was only a very simple way to add new users to the passwd file. It had to be done like this:

!auth.extrapasswd               mSET(lcfg)
auth.pwent_lcfg                 lcfg:x:980:980:LCFG user:/tmp:/bin/false

This approach is still fully supported and if the full pwent resource is set then it will be preferred over the new method which is detailed below. This method makes it very difficult to mutate individual fields at a later stage in the LCFG profile so we have now added individual resources for each field. Users can now be added like this:

!auth.extrapasswd          mADD(fred)
auth.pw_uid_fred           1000
auth.pw_gid_fred           <%auth.gr_gid_fred%>
auth.pw_gecos_fred      Fred Flintstone
auth.pw_dir_fred            /home/fred
auth.pw_shell_fred         /bin/bash

If the username is not explicitly specified using a pw_name resource then the LCFG tag will be used (e.g. fred in the example above). Typically the name only needs to be explicitly set if it will contain characters that cannot appear in an LCFG tag (e.g. a hyphen).

There are not many limits on the contents of the resources but the pw_uid and pw_gid resources must be integers. The pw_passwd field defaults to * (an asterisk).

Some fields can be left empty (e.g. pw_gecos), others will be required to form a valid passwd file entry. The auth component applies some validation to the passwd entry resources before adding the entry to the passwd file but the final responsibility for ensuring the full entry is complete and valid lies with the user.

Adding Extra Groups

Prior to version 1.0.0 of the LCFG auth component there was only a very simple way to add new groups to the group file. It had to be done like this:

!auth.extragroup                mSET(lcfg)
!auth.grpent_lcfg               mSET(lcfg:x:980:)

This approach is still fully supported and if the full grpent resource is set then it will be preferred over the new method which is detailed below. This method makes it very difficult to mutate individual fields at a later stage in the LCFG profile so we have now added individual resources for each field. Groups can now be added like this:

!auth.extragroup              mADD(fred)
auth.gr_gid_fred             1000
auth.gr_mem_fred           fred

If the group name is not explicitly specified using a gr_name resource then the LCFG tag will be used (e.g. fred in the example above). Typically the name only needs to be explicitly set if it will contain characters that cannot appear in an LCFG tag (e.g. a hyphen).

There are not many limits on the contents of the resources but the gr_gid resource must be an integer. The gr_passwd field defaults to x.

Some fields can be left empty (e.g. gr_mem), others will be required to form a valid group file entry. The auth component applies some validation to the group entry resources before adding the entry to the group file but the final responsibility for ensuring the full entry is complete and valid lies with the user.

Adding extra members to a group was previously very problematic as it was difficult to know for sure if a colon or comma should be added before the new entry. The new resources make adding extra members trivial:

!auth.gr_mem_fred   mADD(barney)

Although the component can handle comma-separated entries in the gr_mem resources we strongly recommend that all entries are space-separated. The LCFG mutators only function with space-separated lists so using commas would lead to mutations failing.

Local UID/GID range

On Linux systems the UID/GID range from 0 to 1000 is generally considered to be for "system" and other "local" accounts for specific software. On Redhat/Fedora based systems there are a number of important system accounts using UIDs from 0 through to about 100 which are statically specified in the stub /etc/passwd and /etc/group= files (which are provided as part of the setup package). All other Redhat packages which need UIDs and GIDs are expected to use post-install scripts to select the next free ID counting down from 499.

Unlike the Redhat approach for these dynamically selected IDs, with LCFG we have chosen to use an approach where the IDs are consistent across all machines for a particular platform. This means that whenever a new package is installed it will first have to be delegated the necessary UIDs and GIDs. These are configured using the LCFG auth component and are specified in the /lcfg/options/localaccounts.h header file. Note that header file only contains the metadata for each passwd or group entry, it does not actually add anything to a system, that should be done in the service-specific header.

Also, unlike Redhat we have chosen to count down from 700 to give us a larger range within which to work. The range from 700 to 1000 is considered to be reserved for truly local usage within an individual unit. The exceptions to this rule are where some long-time accepted UIDs and GIDs have already been placed in that range due to the heritage of the configuration (e.g. it originally came from Informatics).

Summary of Usage

-- Main.squinney - 2011-07-12