s6: the s6-envuidgid program
Keywords: s6 command s6-envuidgid uid gid environment modification

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.