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  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  will pull in the corresponding acct-* packages.

= Override ACCT = 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 your local overlay [Custom_ebuild_repository#Creating_a_local_repository] 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 definied 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 /etc/portage/package.env package.env, 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 definied 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 /etc/portage/package.env package.env, how to create a per-package configuration.

In this per package configuration,  must be defined.