Man page - xchpst(8)
Packages contains this manual
Manual
xchpst (8) System Managerās Manual xchpst (8)
NAME
xchpst ā eXtended CHange Process STate
SYNOPSIS
xchpst --help
xchpst --version
xchpst --exit
[=
retcode
]
xchpst
[
OPTIONS
] [
--
]
command
...
DESCRIPTION
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.
Extended xchpst options
The extra options provided by xchpst are as follows:
--help
Show help text and usage.
--file file
Read options from file . See āOptions fileā for the file format.
--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-net path
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 --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 /tmp directory will still be accessible if the stacked mount is removed.
--protect-home
Mount isolated /home , /root and /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
Convert /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. Alternatively, use --cap-bs-drop to remove the āCAP_SYS_ADMINā capability, preventing the bind mount from being unmounted.
--ro-home
Convert /home , /root and and /run/usr into read-only mounts. This option has the same limitations as --ro-sys .
--ro-etc
Convert /etc into a read-only mount. This option has the same limitations as --ro-sys .
--caps-bs-keep capability [,capability...]
Keeps only the listed capabilities in the bounding set.
--caps-bs-drop capability [,capability...]
Drops the listed capabilities from the bounding set. Use only one of the two options governing the bounding set.
--caps-keep capability [,capability...]
Retain the listed capabilities when dropping to a non-root user.
--caps-drop capability [,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).
--cpu-scheduler other | batch | idle
Set the scheduler policy, as per sched_setscheduler (2).
--io-scheduler rt | best-effort | idle [: priority ]
Set the I/O scheduler policy and priority, as per ionice (1).
--cpus
start
[
-
end
[
:
stride
]][,...]
Set CPU affinity in the same format as taskset (1).
--umask mode
Set umask to the octal value mode .
--app name
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.
--oom adjustment
Set the out-of-memory (OOM) score adjustment to adjustment .
-s bytes
Set soft limit for stack segment size.
-a bytes
Set soft limit for address space size.
--limit-memlock bytes
Set soft limit for amount of locked memory.
--limit-msgqueue bytes
Set soft limit for message queue space for this user.
--limit-nice niceness
Set 20 minus the minimum niceness possible for this process.
--limit-rtptio prio
Set soft limit for real time priority of the process.
--limit-rttime ms
Set soft limit for amount of real time processing between blocking system calls.
--limit-sigpending number
Set soft limit for the number of pending signals permitted for the process.
--limit-locks number
Set soft limit for the number of file locks that this process may hold.
--hardlimit
Also set the hard limit for any soft limit option that follows.
-@
Switch 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-compatible options
The options compatible with classic chpst are as follows:
-u
user
[
: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.
-U
user
[
:group
]
Like -u but the environment variables UID and GID are set instead of changing the user. Supplementary groups are ignored.
-b argv0
Set argv[0] to argv0 instead of the target executable path when launching the program.
-e dir
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.
-C dir
Change directory. Change to the dir directory (after any chroot setting is applied).
-n inc
Increase niceness by inc , which can be negative, resulting in the process taking a higher priority.
-l file
Wait for lock. Take a lock out on file and wait to obtain it before proceeding to exec ().
-L file
Try to obtain lock; bail out if it canāt be obtained.
-m bytes
Set soft limit for data and stack segments and virtual memory size and locked memory.
-d bytes
Set soft limit for data segment size.
-o files
Set soft limit for the number of open files.
-p procs
Set soft limit for the number of processes for this user.
-f bytes
Set soft limit for the size of file that this process may create.
-c bytes
Set soft limit for the size of core this process may dump.
-t seconds
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.
Resource limit options
The resource limit options above take a parameter in one of the following forms:
soft
Set only the soft limit, in the style of chpst and softlimit , unless --hardlimit has previously been specified, in which case both soft and hard limits are defined, in the style of prlimit .
soft :
Set only the soft limit, in the style of prlimit (1).
soft : hard
Set soft and hard limits.
: hard
Set only the hard limit.
+ both
Set both soft and hard limits.
An unlimited limit may be selected by any value of ā-1ā, āunlimitedā or āinfinityā.
Emulating ancestor tools
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.
Options file
An options file specifies additional options to apply, one option per line. Each line begins with an option name. Options that take an argument have horizontal white space and the option value following the option name. Comments begin with a ā#ā character and may only be preceded by whitespace, otherwise they will be interpreted as part of an option name or value.
Example options file:
# Comment line
private-tmp
app my app
run-dir
pid-ns
EXIT STATUS
0
The default exit status when --exit is specified is 0. This can be used for a quick test that xchpst is available on the system in shell scripts and that the given options are supported.
100
The return code when an invalid option or option argument is specified, including if a username cannot be resolved, for example.
111
When the requested process state cannot be changed.
other
The --exit option takes an optional argument with a return code to use.
If there is no error and the intended application is exec ()ād, the exit status will be that of the application, not xchpst .
Behaviour on failure to apply
The table below divides the process change options between those that abort on failure to effect the requested change (with error code 111) and those that continue execution. Nonsense configuration values always fail with error code 100.
[1]
If capabilities are not available in the kernel, errors are ignored. Otherwise any failure causes an abort. See āBUGSā
NOTES
systemd option mapping
The table below shows how some systemd service directives map onto xchpst options. See systemd.exec (5) This is not an exhaustive list.
Resource limit option mapping
The table below shows how xchpst resource limit options correspond to those of other tools.
The following options from the bash ulimit command are not available: b k p P T .
BUGS
The --cpu-scheduler option should accept more scheduling policies and should accept additional parameters to qualify those policies. Currently unknown policy names are treated as the default Linux scheduling policy.
When the kernel supports capabilities but not specific capabilities that have been requested to be dropped or kept, xchpst should continue rather than aborting.
EXAMPLES
Testing the emulation of āenvdirā:
xchpst -b envdir -- xchpst
Launch with read-only filesystem if xchpst is available, else use chpst :
xchpst --exit && exec xchpst --ro-sys -l /var/lock/ntpsec-ntpdate ntpd; exec chpst -l /var/log/ntpsec-ntpdate ntpd
Drop a capability from the bounding set:
xchpst --cap-bs-drop CAP_SYS_ADMIN -- acmed
Drop user while retaining some capabilities:
xchpst -u :500:500 --caps-keep CAP_DAC_OVERRIDE fakeroot /usr/sbin/gpm -D -m /dev/input/mice -t exps2
Diagnostics
To see what is going on, including options enabled implicitly due to other options, add the ā--verboseā option.
Use ā--loginā without a command name to explore the hardened environment from a shell.
You can enter the created namespaces (but not other aspects of hardening), including any synthesised root filesystem, by identifying the process id of the hardened application and running:
nsenter -a -t PID
SEE ALSO
chpst (8), runit (8), unshare (1), capsh (1), taskset (1), chrt (1), choom (1), proc_pid_oom_score_adj (5), prlimit (1), prlimit (2), namespaces (7), capabilities (7)
AUTHORS
Andrew Bower < andrew@bower.uk > Debian March 21, 2025 xchpst (8)