s6
Software
skarnet.org

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:gidlist ] 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 does not exist, the UID variable will be set to 0 unless a better default is provided with the -D option. If group does not exist, the GID variable will be set to 0 unless a better default is provided with the -D option.
• -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.
• -i : insist. If account is unknown, exit 1 with an error message. This is the default.
• -D uid:gid:gidlist : if account is unknown, use uid, gid and gidlist as the values for UID, GID and GIDLIST.

Notes

• s6-envuidgid without options behaves like envuidgid, except that the exit code is 1 if account doesn't exist, and it also exports supplementary groups.
• 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. Super-servers such as s6-tcpserver make use of this.