The xchpst utility changes process state according to the supplied options and then calls exec() on a
named executable with the positional arguments.
xchpst is a backwards-compatible extension to the chpst(8) tool which is supplied with runit. xchpst
enables runit service scripts to take advantage of hardening capabilities available with recent Linux
kernels such as namespaces and capabilities. xchpst can set up shadow subtrees within the filesystem
hierarchy to isolate long-running services from parts of the system to which they ought to need no
access, e.g. with private /tmp areas and read-only /usr.Extendedxchpstoptions
The extra options provided by xchpst are as follows:
--help Show help text and usage.
--exit[=retcode]
Exit immediately with exit status 0 if the given options are supported. retcode if
specified.
--mount-ns Create new mount namespace. Various other options also implicitly enable mount namespaces as
this is important to their operation; this option is rarely likely to be needed to be
specified explicitly.
--net-ns Create new network namespace. This will more or less isolate the process from the networking
subsystem.
--uts-ns Create new UTS namespace.
--pid-ns Create a PID namespace. This implies --fork-join because a new process is needed to act as
PID 1 and in order to be able to mount a new procfs for the namespace.
--fork-join
Fork a new process and wait for it to finish, passing on to the child process any signals
received by the xchpst process. This option is necessary to take advantage of PID
namespaces. The exit status is that of the child process.
--user-ns Create a user namespace.
--adopt-netpath
Adopt the network namespace bound to path. The binding will be deleted from the filesystem
meaning that the namespace will disappear when the process exits, if there is no other
reference to it. This allows the calling script to set up a suitable networking environment
for the process and hand it over.
--new-root Create a new root filesystem (will implicitly enable the creation of a new mount namespace).
The new root filesystem is created as a tmpfs and all the top-level directories in the
original root filesystem are bind mounted and any symlinks are replicated.
--private-run
Mount an isolated /run directory for the process. Unless /X.Fl -new-root is also specified,
the old shared /run directory will still be accessible if the stacked mount is removed.
--private-tmp
Mount an isolated /tmp directory for the process. Unless --new-root is also specified, the
old shared /run directory will still be accessible if the stacked mount is removed.
--protect-home
Mount isolated /home, /rootand/run/user directories for the process. Unless --new-root is
also specified, the old shared host directories will still be accessible if the stacked
mounts are removed.
--ro-sys Create a read-only filesystem hierarchy. Converts /usr and /boot into read-only mounts.
Note that if the hardened process has the rights to unmount filesystems, it can reveal the
original writable filesystems. The --new-root option is designed to prevent this.
--caps-bs-keepcapability[,capability...]
Keeps only the listed capabilities in the bounding set.
--caps-bs-dropcapability[,capability...]
Drops the listed capabilities from the bounding set. Use only one of the two options
governing the bounding set.
--caps-keepcapability[,capability...]
Retain the listed capabilities when dropping to a non-root user.
--caps-dropcapability[,capability...]
Drop the listed capabilities when dropping to a non-root user, but retain all others.
--no-new-privs
Prevent the target application from obtaining any new privileges. See
PR_SET_NO_NEW_PRIVS(2const).
--schedulerother | batch | idle
Set the scheduler policy, as per sched_setscheduler(2).
--io-nicert|best-effort|idle[:priority]
Set the I/O scheduler policy and priority, as per ionice(1).
--cpusstart[-end[:stride]][,...]
Set CPU affinity in the same format as taskset(1).
--umaskmode
Set umask to the octal value mode.
--appname Override program name used for pre-creating system directories.
--run-dir Create a directory for the program under /run, owned by the appropriate user.
--state-dir
Create a directory for the program under /var/lib, owned by the appropriate user.
--log-dir Create a directory for the program under /var/log, owned by the appropriate user.
--cache-dir
Create a directory for the program under /var/cache, owned by the appropriate user.
--login Create a login environment, using the user specified by -u, -U or the current user, in order
of preference. If this option is specified and no command is specified to be executed, then
the shell defined for the given user is launched, instead of an error being returned.
-sbytes Set soft limit for stack segment size.
-abytes Set soft limit for address space size.
--memlockbytes
Set soft limit for amount of locked memory.
-@ Switches to chpst-compatible option handling only for the remaining options. This is to
support scripts that can convert an xchpst invocation into a command line for chpst if xchpst
is not present on the system.
chpst-compatibleoptions
The options compatible with classic chpst are as follows:
-uuser[:group]...
Set uid, gid and supplementary groups. Prepend the argument with a colon for numerical inputs
rather than names to be looked up. If no group is specified then the specified user's group is
used. There is no space within the argument.
-Uuser[:group]
Like -u but the environment variables UID and GID are set instead of changing the user.
Supplementary groups are ignored.
-bargv0 Set argv[0] to argv0 instead of the target executable path when launching the program.
-edir Populate environment. For every file within dir, the filename represents an environment
variable that will be set or unset. The first line of the corresponding files is the content
to be set, with NUL characters replaced by LF and trailing whitespace removed. If the file is
0 bytes long then the variable is unset. (So a file with just a newline results in the
variable being set with an empty value.)
-/dir Run in a chroot. Change to the dir directory and make it the new root.
-Cdir Change directory. Change to the dir directory (after any chroot setting is applied).
-ninc Increase niceness by inc, which can be negative, resulting in the process taking a higher
priority.
-lfile Wait for lock. Take a lock out on file and wait to obtain it before proceeding to exec().
-Lfile Try to obtain lock; bail out if it can't be obtained.
-mbytes Set soft limit for data and stack segments and virtual memory size and locked memory.
-dbytes Set soft limit for data segment size.
-ofiles Set soft limit for the number of open files.
-pprocs Set soft limit for the number of processes for this user.
-fbytes Set soft limit for the size of file that this process may create.
-cbytes Set soft limit for the size of core this process may dump.
-tseconds
Set soft limit for the amount of CPU time this process may consume.
-v Be verbose. This option may be repeated for increased verbosity to support debugging.
-V Show xchpst version number.
-P Make this process the process group leader, allocating a new session idea.
-0 Close stdin.
-1 Close stout.
-2 Close stderr.
Emulatingancestortools
When invoked as chpst, envdir, envuidgid, pgrphack, setlock, setuidgid, or softlimit, the xchpst
executable emulates the corresponding tools from the “runit” or “daemontools” packages respectively. As
an additional feature, all these tools when so invoked, accept the -v option to increase verbosity.
Install Now
PNG Icons
SVG Icons
