chpst

chpst [options] command

chpst changes the process state according to the given options and runs prog. It is part of the runit service supervision suite and provides a standardized way to set user, limits, and environment for service processes.The tool consolidates several common process modifications: changing user/group identity, setting resource limits, loading environment from files, and obtaining locks. This simplifies service run scripts that would otherwise need multiple commands.Environment directories (used with -e) contain files named for environment variables, with file contents as values. This pattern is common in runit and daemontools service management.

-u user[:group]

Set UID and GID before running command.

Set environment variables from files in directory.

Limit data segment, stack, and locked memory.

Limit data segment size.

Limit number of open file descriptors.

Limit number of processes.

Limit output file size.

Limit core dump size.

Adjust nice level.

Change root directory (chroot).

Change working directory to pwd before starting prog. Combined with -/, the directory is changed after chroot.

Run prog with argv0 as its 0th argument.

Open lock for writing, obtain an exclusive lock, and fail immediately if lock is held by another process.

Open lock for writing, obtain an exclusive lock, and wait if lock is held by another process.

Run prog in a new process group.

Close standard input (0), standard output (1), or standard error (2) before starting prog.

Print verbose messages to standard error.

Changing user requires root privileges. Resource limits are per-process; child processes inherit but have their own limits. The chroot option requires a complete root filesystem at the target. Lock files must be on a filesystem supporting locks. chpst exits 100 when called with wrong options, and exits 111 if it has trouble changing the process state.

chpst was created by Gerrit Pape as part of runit, a Unix init scheme with service supervision, released in the early 2000s. It was inspired by similar tools from daemontools (setuidgid, softlimit, envdir) but combines their functionality into a single command. The tool remains popular for its simplicity and is used beyond runit in various service management contexts.

runsv(8), runsvdir(8), sv(8)