Ubuntu Manpage: xchpst — eXtended CHange Process STate

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.

--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 /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, /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 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-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).

--scheduler other | batch | idle
Set the scheduler policy, as per sched_setscheduler(2).

--io-nice 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.

-s bytes Set soft limit for stack segment size.

-a bytes Set soft limit for address space size.

--memlock bytes
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-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.

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.

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.

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

HISTORY

       xchpst version 0.x has an unstable interface for initial feature development.

       xchpst  was  written  from  scratch  to  be  backwards  compatible with chpst.  The extent of the planned
       extensions dwarfing the complexity of the original options led to the decision to write a new tool rather
       than extending the existing one.  The new xchpst tool is targeted at new versions of Linux  distributions
       so is written with a recent tooling and kernel baseline.

       xchpst  has  different  design  principles  from chpst.  Use xchpst if you need the additional options to
       harden runit-supervised tasks; use chpst if you do not need them, for a minimal footprint.

AUTHORS

       Andrew Bower <andrew@bower.uk>

BUGS

       Please raise bug reports at: https://gitlab.com/abower/xchpst/-/issues

Debian                                          December 25, 2024                                      xchpst(8)