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

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

--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, as per ionice(1).

--cpus START[-END[:STRIDE]][,...]

Set CPU affinity in the same format as taskset(1).

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