Practical guide to the GLEP 81 migration

This article explains, how the GLEP 81 migration works and which special cases have to be considered.

Summary
In the past, user and group management was managed through various ebuilds, which were inheriting. This means that there was no central user and group management, as instead each ebuild added users and groups in its own way. In order to provide central management for user and groups, GLEP 81 was born.

Details
GLEP 81 describes how user and group management will be done in future. In practice this means, that ebuilds using a user/group will no longer create users or groups, but instead, all users and groups are managed through centralized ebuilds. Those centralized ebuilds will be provided by the categories  for groups and   for users. See Categories_acct-group_and_acct-user for more details in the technical implementation.

All ebuilds for  and   categories define which settings a group and an user will possess. Each ebuild which was previously inheriting  will depend on acct-* packages in the *DEPEND variable(s) after GLEP 81 migration.

Typical defined settings are:
 * UID and GID
 * Path to user home directory
 * Owner of user home directory
 * Permissions of home directory
 * An optional defined shell

This makes it possible to split all user and groups from the main ebuilds and provide separate updates to it. Each ebuild name in  and   categories represents the same name, which will be used for the added user and group to the local system.

In addition, all acct-* packages are using fixed UID and GID. This provides the benefit, as all users and groups will always use across multiple systems the same UID and GID. A list as source of truth is provided in Git via uid-gid.txt

Migration
Once a package has been migrated to GLEP 81, it will be automatically installed by a normal system update. This can be seen if pulls in the corresponding acct-* packages.

Override acct packages
As, by default, all local user and group changes will be reverted by acct-* packages, there are three options to preserve those changes:
 * 1) Disable any changes to the user, which will be modified by  . This can be set global or per package. This is discouraged because of possible inconsistencies that will be created in the system. If you must do this, do it locally per-package, not globally.
 * 2) Override assigned groups for the specified user. This is preferred to 1.
 * 3) Fork/copy the relevant   ebuilds into an ebuild repository configured with portage, and customise them there.

Override acct-user changes
To deactivate changes to users which have been already created, an environment variable  must be defined.

System-wide
For a system-wide setting, the setting  must be defined in

Per package
The better approach is to disable  changes per-package. This can be achieved by using the mechanism for acct-user packages. See the wiki article for how to create a per package configuration.

In this per package configuration,  must be defined.

Override user groups
If the local system has assigned various other groups to the user, which are not covered by the  package, this would be by default removed from the local system.

In order to preserve such assignments, it's necessary to provide a custom configuration which will ensure that such group assignments will be preserved.

A special environment variable is available for this purpose, called. Replace  with the local system user, which will be installed or updated by the   package. This variable contains a space-separated list.

System-wide
For a system-wide setting, the setting  must be defined in

Per package
The better approach is to disable  changes on a per-package basis. This can be achieved by using the  mechanism for acct-user packages. See the wiki article for how to create a per-package configuration.

In this per package configuration,  must be defined.

Example
Let's assume, you have currently installed, which is still based on  and with the newest updated, a GLEP 81 migrated version will be pulled in. This means, that would install  and. If you didn't made any changes to the  user, like assigning to different groups, you don't have to configure anything. But in this example, let's assume, you have assigned the  user to additional groups named   and.

In order to ensure, that this changes are not override by, as stated before, you would need to define. In practice, an environment variable called  must be definied with the values , to ensure, that the user   is added to the primary group   and to the secondary groups   and.

System-wide: Add  in.

Per package: Add  in per package configuration.