org.freedesktop.Flatpak.Development: Flatpak Library Reference Manual

org.freedesktop.Flatpak.Development

org.freedesktop.Flatpak.Development — Flatpak development interface

Methods

HostCommand       (IN  ay    cwd_path,
                   IN  aay   argv,
                   IN  a{uh} fds,
                   IN  a{ss} envs,
                   IN  u     flags,
                   OUT u     pid);
HostCommandSignal (IN  u     pid,
                   IN  u     signal,
                   IN  b     to_process_group);

Signals

HostCommandExited (u pid,
                   u exit_status);

Properties

version  readable   u

Description

The Development interface lets any client, possibly in a sandbox if it has access to the session helper, spawn a process on the host, outside any sandbox.

Clearly this is not something you typically want a sandboxed app to do: it is a sandbox escape allowing arbitrary code execution, and must not be allowed for applications where sandboxing is intended to be a security boundary.

However, it is very useful when using Flatpak for distribution and choice of runtime library stack, without intending to create a security boundary. For instance, if an IDE like GNOME Builder is distributed as a trusted Flatpak app and will be used to build other Flatpak apps, it needs to use this facility to launch a Flatpak build operation inside the sandbox, because otherwise recursive calls to flatpak will not work.

This interface is provided on the D-Bus session bus by the well-known D-Bus name org.freedesktop.Flatpak, at the object path /org/freedesktop/Flatpak/Development.

This documentation describes version 1 of this interface.

Method Details

The HostCommand() method

HostCommand (IN  ay    cwd_path,
             IN  aay   argv,
             IN  a{uh} fds,
             IN  a{ss} envs,
             IN  u     flags,
             OUT u     pid);

This method lets trusted applications (insider or outside a sandbox) run arbitrary commands in the user's session, outside any sandbox.

The following flags values are supported:

1 (FLATPAK_HOST_COMMAND_FLAGS_CLEAR_ENV)	Clear the environment.
2 (FLATPAK_HOST_COMMAND_FLAGS_WATCH_BUS)	Kill the sandbox when the caller disappears from the session bus.

Unknown (unsupported) flags are an error and will cause HostCommand() to fail.

Note that unlike org.freedesktop.portal.Flatpak.Spawn(), there is no options parameter here.

`IN ay cwd_path`:	the working directory for the new process
`IN aay argv`:	the argv for the new process, starting with the executable to launch
`IN a{uh} fds`:	an array of file descriptors to pass to the new process
`IN a{ss} envs`:	an array of variable/value pairs for the environment of the new process
`IN u flags`:	flags
`OUT u pid`:	the PID of the new process

The HostCommandSignal() method

HostCommandSignal (IN  u pid,
                   IN  u signal,
                   IN  b to_process_group);

This method lets you send a Unix signal to a process that was started with HostCommand(). The pid argument here must be a PID that was returned by a call to HostCommand() from the same sender: terminating unrelated processes is not allowed.

`IN u pid`:	the process ID on the host system
`IN u signal`:	the signal to send (see signal(7))
`IN b to_process_group`:	whether to send the signal to the process group

Signal Details

The "HostCommandExited" signal

HostCommandExited (u pid,
                   u exit_status);

Emitted when a process started by HostCommand() exits. Use g_spawn_check_exit_status(), or the macros such as WIFEXITED documented in waitpid(2), to interpret the exit_status.

This signal is not emitted for processes that were not launched directly by HostCommand(), for example if a process launched by HostCommand() runs foreground or background child processes.

`u pid`:	the PID of the process that has ended
`u exit_status`:	the wait status (see waitpid(2))

Property Details

The "version" property

version  readable   u

The API version number. This documentation describes version 1 of this interface.