pw-container

Create a new security context and print its socket address to stdout

$ pw-container

$ pw-container [command] [argument1 argument2 ...]

$ pw-container [[-r|--remote]] [remote_instance_name] [command]

$ pw-container [[-P|--properties]] '[{"key": "value"]}' [command]

$ pw-container [[-h|--help]]

pw-container [OPTIONS] [COMMAND [ARGUMENTS...]]

The COMMAND and its ARGUMENTS are typically the PipeWire daemon itself or a specific PipeWire module/tool to be run within the isolated environment.

-h, --help
    Display help options and exit.

--version
    Show program version information and exit.

--debug[=LEVEL]
    Enable debug messages, optionally specifying a debug level.

--verbose[=LEVEL]
    Enable verbose messages, optionally specifying a verbose level.

-p, --pipewire-binary=FILE
    Specify the path to the PipeWire binary.

-r, --runtime-dir=DIR
    Set the runtime directory for the container.

-c, --config-dir=DIR
    Set the configuration directory for the container.

-l, --library-dir=DIR
    Set the library directory for the container.

-C, --container-config=FILE
    Provide a path to a specific container configuration file.

-m, --module-dir=DIR
    Set the module directory for the container.

-S, --socket=PATH
    Specify the socket path for the container to use.

-u, --user=USER
    Run the container process as the specified user.

-g, --group=GROUP
    Run the container process as the specified group.

-e, --env=VAR=VALUE
    Set an environment variable for the container process.

--
    Separator; all subsequent arguments are passed directly to COMMAND.

pw-container is a utility within the PipeWire framework designed to run PipeWire modules or services in an isolated environment, often referred to as a container. This isolation is crucial for enhancing system stability and security by preventing a misbehaving module from affecting the entire PipeWire instance or other system components. It effectively creates a sandbox for specific audio or video processing tasks.

The command achieves this by setting up dedicated directories for runtime, configuration, and libraries, and by potentially running the contained process under a different user or group. This allows for a more robust and secure management of various PipeWire components, especially when dealing with third-party or experimental modules. It's particularly useful for debugging, testing new configurations, or deploying sensitive components without impacting the main PipeWire daemon.

pw-container provides process isolation and restricted file system access but is not a full system virtualization or containerization solution like Docker or Podman. It relies on PipeWire's internal sandboxing mechanisms and system capabilities (like user/group separation and directory isolation) to achieve its goals.

Configuration for the contained environment, especially paths for libraries and modules, must be carefully managed to ensure the container can function correctly while remaining isolated. Debugging issues within a container can sometimes be more complex due to the restricted environment.

pw-container is frequently used in systemd unit files to run specific PipeWire services or modules as dedicated system services. This allows for fine-grained control over their lifecycle, resource allocation, and security contexts, independent of the main PipeWire daemon. For example, a Bluetooth audio service or a media session manager might be run within its own pw-container instance to enhance stability and security.

The pw-container utility emerged as part of the broader PipeWire project, which was initiated to provide a unified framework for handling audio, video, and hardware streams on Linux. As PipeWire gained adoption as a replacement for PulseAudio and JACK, the need for robust sandboxing and isolation of modules became apparent.

It addresses concerns related to security, stability, and compatibility, allowing diverse audio/video components to coexist and operate without interfering with each other or the main system. Its development reflects PipeWire's commitment to building a modern, secure, and flexible multimedia framework for Linux.

pipewire(1), pw-cli(1), systemd.service(5)