-
Simon McVittie authored
These are the client side for <https://github.com/flatpak/flatpak/pull/4018 >. We'll use them to put the Steam Runtime on /usr and an empty directory on /app. Because the corresponding Flatpak change has not been merged, make it fail unless an undocumented environment variable has been set. Signed-off-by:
Simon McVittie <smcv@collabora.com>
Simon McVittie authoredThese are the client side for <https://github.com/flatpak/flatpak/pull/4018 >. We'll use them to put the Steam Runtime on /usr and an empty directory on /app. Because the corresponding Flatpak change has not been merged, make it fail unless an undocumented environment variable has been set. Signed-off-by:
Simon McVittie <smcv@collabora.com>
title: pressure-vessel-launch
section: 1
NAME
pressure-vessel-launch - client to launch processes in a container
SYNOPSIS
pressure-vessel-launch [--clear-env] [--directory DIR] [--env VAR=VALUE] [--forward-fd FD] [--pass-env VAR] [--pass-env-matching WILDCARD] [--unset-env VAR] [--verbose] {--bus-name NAME|--dbus-address ADDRESS|--socket SOCKET} [--] COMMAND [ARGUMENTS...]
pressure-vessel-launch [--verbose] {--bus-name NAME|--dbus-address ADDRESS|--socket SOCKET} --terminate
DESCRIPTION
pressure-vessel-launch connects to an AF_UNIX
socket established
by pressure-vessel-launcher(1), and executes an arbitrary command
as a subprocess of pressure-vessel-launcher.
OPTIONS
- --socket PATH, --socket @ABSTRACT
- Connect to the given
AF_UNIX
socket, which can either be an absolute path, or@
followed by an arbitrary string. An absolute path indicates a filesystem-based socket, which is associated with the filesystem and can be shared between filesystem namespaces by bind-mounting.@
indicates an an abstract socket, which is associated with a network namespace, is shared between all containers that are in the same network namespace, and cannot be shared across network namespace boundaries. - --dbus-address ADDRESS
- The same as --socket, but the socket is specified in the form of a D-Bus address.
- --bus-name NAME
- Connect to the well-known D-Bus session bus and send commands to the given NAME, which is normally assumed to be owned by pressure-vessel-launcher.As a special case, if the NAME is org.freedesktop.Flatpak, then it is assumed to be owned by the flatpak-session-helper per-user service, and the COMMAND is launched on the host system, similar to the --host option of flatpak-spawn(1). The --terminate option is not allowed in this mode.As another special case, if the NAME is org.freedesktop.portal.Flatpak, then it is assumed to be owned by the flatpak-portal per-user service, and the COMMAND is launched in a Flatpak sub-sandbox, similar to flatpak-spawn(1) without the --host option. Most options that alter how the sub-sandbox is created, such as --sandbox-flag, are not currently supported. As with org.freedesktop.Flatpak, the --terminate option is not allowed in this mode.
- --app-path PATH, --app-path=
- When creating a Flatpak subsandbox, mount PATH as the
/app
in the new subsandbox. If PATH is specified as the empty string, place an empty directory at/app
.This experimental option is only valid when used with --bus-name=org.freedesktop.portal.Flatpak, and requires a Flatpak branch that has not yet been merged. - --clear-env
- The COMMAND runs in an empty environment, apart from any environment variables set by --env and similar options. By default, it inherits environment variables from pressure-vessel-launcher, with --env and similar options overriding or unsetting individual variables.
- --directory DIR
- Arrange for the COMMAND to run in DIR. By default, it inherits the current working directory from pressure-vessel-launcher.
- --forward-fd FD
- Arrange for the COMMAND to receive file descriptor number FD from outside the container. File descriptors 0, 1 and 2 (standard input, standard output and standard error) are always forwarded.
- --share-pids
- If used with --bus-name=org.freedesktop.portal.Flatpak, use the same process ID namespace for the new subsandbox as for the calling process. This requires Flatpak 1.10 or later, running on a host operating system where bwrap(1) is not and does not need to be setuid root.When communicating with a different API, this option is ignored.
- --terminate
- Instead of running a COMMAND, terminate the Launcher server.
- --usr-path PATH
- When creating a Flatpak subsandbox, mount PATH as the
/usr
in the new subsandbox.This experimental option is only valid when used with --bus-name=org.freedesktop.portal.Flatpak, and requires a Flatpak branch that has not yet been merged. - --verbose
- Be more verbose.
ENVIRONMENT OPTIONS
Options from this group are processed in order, with each option taking precedence over any earlier options that affect the same environment variable. For example, --pass-env-matching="FO*" --env=FOO=bar --unset-env=FOCUS will set FOO to bar, unset FOCUS even if the caller has it set, and pass through FONTS from the caller.
- --env VAR=VALUE
- Set environment variable VAR to VALUE. This is mostly equivalent to using env VAR=VALUE COMMAND ARGUMENTS... as the command.
- --pass-env VAR
- If the environment variable VAR is set, pass its current value into the container as if via --env. Otherwise, unset it as if via --unset-env.
- --pass-env-matching WILDCARD
- For each environment variable that is set and has a name matching the fnmatch(3) pattern WILDCARD, pass its current value into the container as if via --env. For example, --pass-env-matching=Steam* copies Steam-related environment variables. If this command is run from a shell, the wildcard will usually need to be quoted, for example --pass-env-matching="Steam*".
- --unset-env VAR
- Unset VAR when running the command. This is mostly equivalent to using env -u VAR COMMAND ARGUMENTS... as the command.
ENVIRONMENT
PWD
- pressure-vessel-launcher(1) sets this to the current working directory (as specified by --directory, or inherited from the launcher) for each command executed inside the container, overriding the environment options shown above.
-
PRESSURE_VESSEL_LOG_INFO
(boolean) - If set to
1
, increase the log verbosity up to the info level. If set to0
, no effect. -
PRESSURE_VESSEL_LOG_WITH_TIMESTAMP
(boolean) - If set to
1
, prepend the log entries with a timestamp. If set to0
, no effect.
OUTPUT
The standard output from COMMAND is printed on standard output.
The standard error from COMMAND is printed on standard error. Diagnostic messages from pressure-vessel-launch may also be printed on standard error.
EXIT STATUS
The exit status is similar to env(1):
- 0
- The COMMAND exited successfully with status 0, or --terminate succeeded.
- 125
- Invalid arguments were given, or pressure-vessel-launch failed to start.
- 126
- Reserved to indicate inability to launch the COMMAND. This is not currently distinguished from exit status 125.
- 127
- Reserved to indicate that the COMMAND was not found. This is not currently distinguished from exit status 125.
- 128
- The COMMAND was launched, but its exit status could not be determined. This happens if the wait-status was neither normal exit nor termination by a signal. It also happens if pressure-vessel-launch was disconnected from the D-Bus session bus or the --socket before the exit status could be determined.
- Any value less than 128
- The COMMAND exited unsuccessfully with the status indicated.
- 128 + n
- The COMMAND was killed by signal n. (This is the same encoding used by bash(1), bwrap(1) and env(1).)
EXAMPLES
See pressure-vessel-launcher(1).