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.

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

--id-map self|identity|full
    Set uid and gid map in user namespace to map only the root user (the default), the first 65536 ids or the whole id space respectively.

--adopt-net path
    Adopt the network namespace bound to path. Per convention among other network-namespace aware applications, e.g. ip(8), it is interpreted relative to /var/run/netns. 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.

    A later version of this tool may replace the asymmetric --adopt-net option with a general mechanism to enter an existing namespace without then unbinding it from the filesystem.

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

    This mode of operation stops a command that retains the capability to unmount filesystems from unmounting any read-only or private bind mounts (from --ro-sys, --ro-home, --ro-etc, --private-tmp or --private-run) to reveal the stacked read-write mounts. When used in combination with --ro-home, which bind mounts /run/user as read only, or any other case where the read-only bind mount is not on an existing mountpoint, there may still end up stacked read-write mounts underneath.

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

-a, --limit-as bytes
    Set soft limit for address space size. The short version of this option matches softlimit emulation but is deprecated in case a future version of chpst, which does not provide it, uses this option character for a different purpose and my be removed.

-r, --limit-rss bytes
    Set soft limit for resident set size. The short version of this option matches softlimit emulation but is deprecated in case a future version of chpst, which does not provide it, uses this option character for a different purpose and may be removed. This option is basically useless on any system new enough to run xchpst (see setrlimit(2)).

-s, --limit-stack bytes
    Set soft limit for stack segment size. The short version of this option matches softlimit emulation but is deprecated in case a future version of chpst, which does not provide it, uses this option character for a different purpose and may be removed.

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

--dev-null
    Change the behaviour of any following -0, -1 or -2 options to redirect the given file descriptor to or from /dev/null instead of closing it.

-@  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 and as an extension to chpst, supplementary groups are also looked up.

-U [:]user[:group]...
    Like -u but the environment variables UID and GID are set instead of changing the user. As an extension to chpst, supplementary groups, if present, are joined in a comma-separated list in the GIDLIST environment variable.

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

-F, --fghack
    Attempt to retain foreground control of a process that backgrounds itself, by implicitly enabling --jork-join, operating as a sub-reaper and waiting on all orphaned sub-processes. If --pid-ns is also enabled then additionally operate as the PID 1 ‘init’ process. (Combining these features is the way in which chpst implements its -F option.)

    Signals are passed on to direct child processes in contrast to the chpst implementation which passes them on to all descendants. If the main process exits uncleanly, supervision will end for all spawned processes.

    This is a new approach to implementing the daemontools fghack(8) tool.

-I, --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.

  s6-inspired options
The following options to xchpst correspond to options from the s6-applyuidgid command and their implementation supports the emulation mode thereof:

--ugids-from-env
    Set uid, gid and comma-separated supplementary groups from the UID, GID and GIDLIST environment variables. The values must be numeric and are not looked up in the password database, by design.

--ugids-clear-env
    Clear the UID, GID and GIDLIST environment variables before starting the next process.

  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 daemontools family tools
xchpst follows chpst in emulating chain-loading utilities from the daemontools suite and other suites in the daemontools 'family', which tend to follow similar principles and have partially-compatible options and behaviour. These emulated modes take effect when the xchpst executable is invoked under the name of the respective tool such as via a symbolic link. The matching of argv[0] against emulated tool names ignores file extensions (*.ext) and known suite prefixes (s6-*).

Note that there can be variations between the options and behaviour of equivalent tools from the different suites so documentation should be checked before relying on emulation modes.

The following table describes the emulated tools, their home suite, the equivalent xchpst option and notable differences in behaviour.

Tool | Home suite | Equivalent xchpst option | Differences
chpst | runit |  | supplemental group lookup
envdir | daemontools | -e
envuidgid | daemontools | -U
pgrphack | daemontools | -P
fghack | daemontools | -F | uses subreaper method
setlock | daemontools | -l
setuidgid | daemontools | -u
softlimit | daemontools
applyuidgid | s6 | --ugids-from-env
setuidgid-fromenv | nosh | --ugids-from-env

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.

Options may be bracketed by lines of the form ‘opt[’ and ‘opt]’ to indicate that they should be silently ignored if unknown to this version of xchpst. This allows the use of new options which are not essential to safe operation of the target command without having to express an incompatibility with older versions of xchpst.

Example options file:

    # Comment line
    private-tmp
    app my-service
    run-dir
    pid-ns
    opt[
    option-from-the-future
    Z 33
    opt]
    hardlimit
    o 2048

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.

Option group | Abort on error | Continue on error
chpst | u U e / C n L l m d o p f c r t F I | b 0 1 2
rlimit | s a limit-memlock limit-msgqueue limit-nice limit-rtprio limit-rttime limit-sigpending limit-locks
namespaces | fork-join new-root mount-ns net-ns user-ns pid-ns uts-ns net-adopt | id-map
capabilities |  | cap-bs-keep cap-bs-drop caps-keep caps-drop
filesystem | private-run private-tmp protect-home ro-sys ro-home ro-etc run-dir state-dir cache-dir log-dir |
other |  | cpus cpu-scheduler io-scheduler no-new-privs umask oom login ugids-from-env ugids-clear-env

[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.
systemd | xchpst | Notes
ProtectSystem=yes | ro-sys
ProtectSystem=full | ro-sys ro-etc
ProtectHome=read-only | ro-home
ProtectHome=tmpfs | protect-home
PrivateTmp=yes | private-tmp
PrivateUsers=self|identity|full | user-ns id-map=self|identity|full | default mapping is
CapabilityBoundingSet= | cap-bs-keep
CapabilityBoundingSet=~ | cap-bs-drop
AmbientCapabilities= | caps-keep
AmbientCapabilities=~ | caps-drop
NoNewPrivileges=yes | no-new-privs
CPUAffinity= | cpus | use format
CPUSchedulingPolicy= | cpu-scheduler
IOSchedulingClass= IOSchedulingPriority= | io-scheduler
UMask= | umask
RuntimeDirectory= | run-dir | Leaf name governed by target command or option
StateDirectory= | state-dir | Leaf name governed by target command or option
CacheDirectory= | cache-dir | Leaf name governed by target command or option
LogsDirectory= | log-dir | Leaf name governed by target command or option
OOMScoreAdjust= | oom
User= Group= | u | Check syntax. In particular, numeric ids begin with a colon.
User= ExecStart=+ ExecStart=! | U | In these modes, does not drop the user, expecting the application to do that, but instead uses the specified username for other options. In this case the environment variable setting by is not useful but other options like will use the right user.

  Resource limit option mapping
The table below shows how xchpst resource limit options correspond to those of other tools.
xchpst | chpst | softlimit | prlimit | ulimit | systemd
d | d | d | d | d | LimitDATA=
o | o | o | n | n | LimitNOFILE=
p | p | p | u | u | LimitNPROC=
f | f | f | f | f | LimitFSIZE=
c | c | c | c | c | LimitCORE=
t | t | t | t | t | LimitCPU=
m | m | m | d s l v | d s l v | LimitDATA= LimitSTACK= LimitAS= LimitMEMLOCK=
limit-as (or a) |  | a | v | v | LimitAS=
limit-rss (or r) |  | r | m | m | LimitRSS=
limit-stack (or s) |  | s | s | s | LimitSTACK=
limit-memlock |  | l | l | l | LimitMEMLOCK=
limit-msgqueue |  |  | q | q | LimitMSGQUEUE=
limit-nice |  |  | e | e | LimitNICE=
limit-rtprio |  |  | r | r | LimitRTPRIO=
limit-rttime |  |  | y | R | LimitRTTIME=
limit-sigpending |  |  | i | i | LimitSIGPENDING=
limit-locks |  |  | x | x | LimitLOCKS=

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), envdir(8), envuidgid(8), pgrphack(8), fghack(8), setlock(8), setuidgid(8), softlimit(8)

AUTHORS
-nosplit Andrew Bower <andrew@bower.uk>