passwd#

Parse the Unix account databases /etc/passwd and /etc/group, and resolve a Docker/runc-style user[:group] specifier to numeric ids.

Installation#

Install with opam:

$ opam install passwd

If opam cannot find the package, it may not yet be released in the public opam-repository. Add the overlay repository, then install it:

$ opam repo add samoht https://tangled.org/gazagnaire.org/opam-overlay.git
$ opam update
$ opam install passwd

Overview#

A container image records the user its processes should run as — USER opam in a Dockerfile, or "User": "opam" in an OCI image config. Turning that name into the uid, primary gid and supplementary group ids the kernel needs means reading /etc/passwd and /etc/group inside the image, exactly as opencontainers/runc does at container start.

This library is that resolution step, and nothing more. Parsing is pure: it works over the file contents, never the filesystem, so the caller reads the databases (from a container rootfs, say) and passes the bytes.

Usage#

let passwd = "root:x:0:0:root:/root:/bin/sh\nopam:x:1000:1000::/home/opam:/bin/sh\n"
let group = "opam:x:1000:\nwheel:x:10:opam\n"

let resolved =
  let db = Passwd.v ~passwd ~group () in
  match Passwd.resolve db "opam" with
  | Ok { Passwd.uid; gid; additional_gids } -> Some (uid, gid, additional_gids)
  | Error (`Msg _m) -> None

Resolution rules#

Following libcontainer/user.GetExecUser, with defaults uid = 0, gid = 0 and no supplementary groups:

• The user part, and the optional group after a :, may each be a name or a numeric id.
• A user matching a passwd entry takes that entry's uid and gid. A numeric user with no entry keeps that uid; a named user with no entry is an error.
• An explicit group overrides the primary gid. A numeric group is accepted even with no group entry; a named group with no entry is an error.
• With no group given, the supplementary gids are those of every group listing the resolved user as a member. With a group given, there are none.

Related work#

• opencontainers/runc (Go) — libcontainer/user, the reference implementation of these rules, used by Docker and containerd.
• peercred — reads the uid/gid/pid of a connected Unix-socket peer; the complementary primitive for the running process rather than an image's configured user.

License#

MIT License. See LICENSE for details.