hasher-privd(8)

HASHER-PRIVD(8)

System Administration Utilities

HASHER-PRIVD(8)

NAME

hasher-privd - service daemon for the hasher project

SYNOPSIS

hasher-privd [options]

DESCRIPTION

-D, --daemonize: run in the background;
-l, --loglevel=LEVEL: set the minimal log level;
-p, --pidfile=FILE: set the pid file location;
-V, --version: print program version and exit;
-h, --help: show this text and exit.

OVERVIEW

As described in hasher(7), hasher runs isolated workloads in a Unix-like three-user environment; processes can run as caller, builder and pseudoroot. This program performs various actions that require privileges on behalf of unprivileged processes run by the caller. It accepts requests via a Unix stream socket and fulfills or rejects them. hasher-privd is intended to be run as a system-wide service as part of the startup sequence. Consumer programs like hsh(1) invoke a client program, which can talk to hasher-privd. The communication protocol is not in any way stable and is expected to change as needed in future versions of hasher-priv. It is only guaranteed to match across a client and a server of the same release.

The main daemon process only exists to spawn a "session" process for the client's peercreds and subconfig ID.

The session process then listens on a different Unix socket and accepts job requests from clients of a particular UID and subconfig ID. A job is a single logical action for the server to do on the client's request, coupled with optional metadata like textual parameters and passed file descriptors. Contrary to its name, the session process does not track job runners and the subprocesses they spawn at all. Since a job request consists of many messages, and each message can invalidate the entire request (and the server will have to drop all received state), the current implementation passes the connection socket for a request to a child subprocess, the job handler, and proceeds to poll socket events or reap children.

If the request is invalid, the job handler sends an error reply with an optional message and exits. Otherwise, it spawns yet another child, the job runner, and exits immediately, reparenting it to pid 1 or a subreaper. (This design relieves the session process from having to call wait(2) on runners.)

The job runner's only purpose is to join the client's cgroup (so the resources it consumes are attributed to the client), spawn the job executor and wait for one of the following, whatever happens first:

- the client disconnects from the runner, so the job must be aborted;

- the job finishes, so the runner sends a reply to the client with the job's exit status.

If the service is restarted, runners are not killed and are expected to continue running.

The executor process, in turn, closes unknown file descriptors and does the privileged action requested.

All the processes appear in e.g. ps(1) output with description strings denoting their role and credentials.

NOTES

Since 2.0.2, before a program is executed as part of a chrootuid job, the process it will run in calls prctl(PR_SET_NO_NEW_PRIVS, 1). This may or may not impact unaware workloads.

Since 2.0, hasher-privd(8) replaces a setuid-root program, which had performed the same duties. All subprocesses of that program naturally were part of the client's cgroup. The job-running child processes of hasher-privd(8) are part of the server's cgroup and have to be put in the cgroup of the client manually. On systems employing systemd(1) this may lead to races if the client is in a managed unit's cgroup. The client (or its caller) has to ask systemd(1) to put itself in a transient scope to avoid possible races, if necessary. The hasher utilities that make use of the chrootuid operation take care of this automatically.

FILES

/etc/hasher-priv/daemon.conf: service daemon configuration file
/etc/hasher-priv/system: systemwide hasher-priv configuration file
/etc/hasher-priv/user.d/USER: per-user hasher-priv configuration files
/etc/hasher-priv/user.d/USER:NUMBER: per-user per-number subconfig files

AUTHOR

Written by Dmitry V. Levin <ldv@altlinux.org> et al.

COPYRIGHT

Copyright © 2003-2023 Dmitry V. Levin <ldv@altlinux.org>
Copyright © 2019 Alexey Gladkov <legion@altlinux.org>
Copyright © 2022 Arseny Maslennikov <arseny@altlinux.org>
Copyright © 2022 Gleb Fotengauer-Malinovskiy <glebfm@altlinux.org>

This is free software; see the source for copying conditions. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.