The s6-envuidgid program

s6-envuidgid potentially sets the UID, GID and GIDLIST environment variables according to the options and arguments it is given; then it executes into another program.

Interface

     s6-envuidgid [ -u | -g | -B ] [ -n ] [ -i | -D uid:gid ] account prog...

s6-envuidgid looks account up by name in the account database.
It sets the UID environment variable to account's uid, and the GID environment variable to account's gid.
It also sets the GIDLIST environment variable to a comma-separated list of supplementary group ids account is a member of according to the group database. (If account doesn't belong to any other group than its primary group, GIDLIST is still set, but empty.)
Then it executes into prog....

Options

-u : user. account will be interpreted as a user name; the UID environment variable will be set to its numerical value, and the GID and GIDLIST variables will not be touched.
-g : group. account will be interpreted as a group name instead of a user name; the GID environment variable will be set to its numerical value, and the UID and GIDLIST variables will not be touched.
-B : both user and group. account will be interpreted as user:group. The GIDLIST variable will not be touched. If user exists, the UID variable will be set; if group exists, the GID variable will be set.
-n : numerical fallback. If account cannot be found in the user or group database, try to interpret the given values literally. For instance, s6-envuidgid -B root:42 will fail if there's no group named 42 in the group database, but s6-envuidgid -nB root:42 will set UID to 0 and GID to 42. This option implies -B.
-i : insist. If account is unknown, exit 1 with an error message. This is the default.
-D uid:gid : if account is unknown, use uid and gid as the values for UID and GID. This options implies -B.

Notes

s6-envuidgid without options behaves like envuidgid, except that the exit code is 1 if account doesn't exist.
s6-envuidgid is useful when running a program that must start as root but can drop its privileges later. Such a program can read its new uid/gid/groups info from the UID, GID and GIDLIST environment variables. Superservers such as s6-tcpserver4 make use of this.
s6-envuidgid only sets GIDLIST when no option (or only -i) is given. If s6-envuidgid risks defaulting to a given numerical value for UID or GID, it will not interpret account as a complete account name with uid, gid and supplementary group list; instead, it interprets it as an arbitrary combination of user name and group name.