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

-@

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.

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.

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-service
run-dir
pid-ns
hardlimit
o 2048

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

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.

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: