flatpak-metadata man page

flatpak-metadata ā€” Information about an application or runtime

Description

Flatpak uses metadata files to describe applications and runtimes. The metadata file for a deployed application or runtime is placed in the toplevel deploy directory. For example, the metadata for the locally installed application org.gnome.Calculator is in ~/.local/share/flatpak/app/org.gnome.Calculator/current/active/metadata.

Most aspects of the metadata configuration can be overridden when launching applications, either temporarily via options of the flatpak run command, or permanently with the flatpak override command.

A metadata file describing the effective configuration is available inside the running sandbox at /.flatpak-info. For compatibility with older Flatpak versions, /run/user/$UID/flatpak-info is a symbolic link to the same file.

File Format

The metadata file is using the same .ini file format that is used for systemd unit files or application .desktop files.

[Application] or [Runtime]

Metadata for applications starts with an [Application] group, metadata for runtimes with a [Runtime] group.

The following keys can be present in these groups:

name (string)

The name of the application or runtime. This key is mandatory.

runtime (string)

The fully qualified name of the runtime that is used by the application. This key is mandatory for applications.

sdk (string)

The fully qualified name of the sdk that matches the runtime.

command (string)

The command to run. Only relevant for applications.

required-flatpak (string)

The required version of Flatpak to run this application or runtime.

tags (string list)

Tags to include in AppStream XML.

[Context]

This group determines various system resources that may be shared with the application when it is run in a flatpak sandbox.

All keys in this group (and the group itself) are optional.

shared (list)

List of subsystems to share with the host system. Possible subsystems: network, ipc.

sockets (list)

List of well-known sockets to make available in the sandbox. Possible sockets: x11, wayland, pulseaudio, session-bus, system-bus. When making a socket available, flatpak also sets well-known environment variables like DISPLAY or DBUS_SYSTEM_BUS_ADDRESS to let the application find sockets that are not in a fixed location.

devices (list)

List of devices to make available in the sandbox. Possible values: dri, kvm, all.

filesystems (list)

List of filesystem subsets to make available to the application. Possible values: home, host, xdg-desktop, xdg-documents, xdg-download xdg-music, xdg-pictures, xdg-public-share, xdg-templates, xdg-videos, xdg-run, xdg-config, xdg-cache, xdg-data, an absolute path, or a homedir-relative path like ~/dir or paths relative to the xdg dirs, like xdg-download/subdir. The xdg-* arguments can also specify a subdirectory, such as xdg-pictures/screenshots. Each entry can have a suffix of :ro, :rw or :create to indicate if the path should be shared read-only, read-write or read-write + create if needed (default is read-write).

persistent (list)

List of homedir-relative paths to make available at the corresponding path in the per-application home directory, allowing the locations to be used for persistent data when the application does not have access to the real homedir. For instance making ".myapp" persistent would make "~/.myapp" in the sandbox a bind mount to "~/.var/app/org.my.App/.myapp", thus allowing an unmodified application to save data in the per-application location.

features (list)

List of features available or unavailable to the application, currently from the following list: devel, multiarch. A feature can be prefixed with ! to indicate the absence of that feature, for example !devel if development and debugging are not allowed.

[Instance]

This group only appears in /.flatpak-info for a running app, and not in the metadata files written by application authors. It is filled in by Flatpak itself.

app-path (string)

The absolute path on the host system of the app's app files, as mounted at /app inside the container

branch (string)

The branch of the app, for example stable

flatpak-version (string)

The version number of the Flatpak version that ran this app

runtime-path (string)

The absolute path on the host system of the app's runtime files, as mounted at /usr inside the container

session-bus-proxy (boolean)

True if this app cannot access the D-Bus session bus directly (either it goes via a proxy, or it cannot access the session bus at all)

system-bus-proxy (boolean)

True if this app cannot access the D-Bus system bus directly (either it goes via a proxy, or it cannot access the system bus at all)

[Session Bus Policy]

If the sockets key is not allowing full access to the D-Bus session bus, then flatpak provides filtered access.

The default policy for the session bus only allows the application to own its own application ID and subnames. For instance if the app is called "org.my.App", it can only own "org.my.App" and "org.my.App.*". Its also only allowed to talk to the bus itself (org.freedesktop.DBus) and the portal APIs APIs (bus names of the form org.freedesktop.portal.*).

Additionally the app is always allowed to reply to messages sent to it, and emit broadcast signals (but these will not reach other sandboxed apps unless they are allowed to talk to your app.

If the [Session Bus Policy] group is present, it provides policy for session bus access.

Each key in this group has the form of a D-Bus bus name or prefix thereof, for example org.gnome.SessionManager or org.freedesktop.portal.*

The possible values for entry are, in increasing order or access:

none

The bus name or names in question is invisible to the application.

see

The bus name or names can be enumerated by the application.

talk

The application can send messages/ and receive replies and signals from the bus name or names.

own

The application can own the bus name or names (as well as all the above).

[System Bus Policy]

If the sockets key is not allowing full access to the D-Bus system bus, then flatpak does not make the system bus available unless the [System Bus Policy] group is present and provides a policy for filtered access.

Entries in this group have the same form as for the [Session Bus Policy] group. However, the app has no permissions by default.

[Environment]

The [Environment] group specifies environment variables to set when running the application.

Entries in this group have the form VAR=VALUE where VAR is the name of an environment variable to set.

[Extension NAME]

Runtimes and applications can define extension points, which allow optional, additional runtimes to be mounted at a specified location inside the sandbox when they are present on the system. Typical uses for extension points include translations for applications, or debuginfo for sdks. The name of the extension point is specified as part of the group heading.

directory (string)

The relative path at which the extension will be mounted in the sandbox. If the extension point is for an application, the path is relative to /app, otherwise it is relative to /usr. This key is mandatory.

version (string)

The branch to use when looking for the extension. If this is not specified, it defaults to the branch of the application or runtime that the extension point is for.

versions (string)

The branches to use when looking for the extension. If this is not specified, it defaults to the branch of the application or runtime that the extension point is for.

add-ld-path (string)

A path relative to the extension point directory that will be appended to LD_LIBRARY_PATH.

merge-dirs (string)

A list of relative paths of directories below the extension point directory that will be merged.

download-if (string)

A condition that must be true for the extension to be auto-downloaded. The only currently recognized value is active-gl-driver, which is true if the name of the active GL driver matches the extension point basename.

enable-if (string)

A condition that must be true for the extension to be enabled. The only currently recognized value is active-gl-driver, which is true if the name of the active GL driver matches the extension point basename.

subdirectory-suffix (string)

A suffix that gets appended to the directory name. This is very useful when the extension point naming scheme is "reversed". For example, an extension point for GTK+ themes would be /usr/share/themes/$NAME/gtk-3.0, which could be achieved using subdirectory-suffix=gtk-3.0.

subdirectories (boolean)

If this key is set to true, then flatpak will look for extensions whose name is a prefix of the extension point name, and mount them at the corresponding name below the subdirectory.

no-autodownload (boolean)

Whether to automatically download extensions matching this extension point when updating or installing a 'related' application or runtime.

autodelete (boolean)

Whether to automatically delete extensions matching this extension point when deleting a 'related' application or runtime.

[ExtensionOf]

This optional group may be present if the runtime is an extension.

ref (string)

The ref of the runtime or application that this extension belongs to.

priority (integer)

The priority to give this extension when looking for the best match. Default is 0.

[Extra Data]

This optional group may be present if the runtime or application uses extra data that gets downloaded separately. The data in this group gets merged into the repository summary, with the xa.extra-data-sources key.

If multiple extra data sources are present, their uri, size and checksum keys are grouped together by using the same suffix. If only one extra data source is present, the suffix can be omitted.

NoRuntime (boolean)

Whether to mount the runtime while running the /app/bin/apply_extra script. Defaults to true, i.e. not mounting the runtime.

uriX (string)

The uri for extra data source X. The only supported uri schemes are http and https.

sizeX (integer)

The size for extra data source X.

checksumX (string)

The sha256 sum for extra data source X.

[Policy SUBSYSTEM]

Subsystems can define their own policies to be placed in a group whose name has this form. Their values are treated as lists, in which items can have their meaning negated by prepending ! to the value. They are not otherwise parsed by Flatpak.

Example

[Application]
name=org.gnome.Calculator
runtime=org.gnome.Platform/x86_64/3.20
sdk=org.gnome.Sdk/x86_64/3.20
command=gnome-calculator

[Context]
shared=network;ipc;
sockets=x11;wayland;
filesystems=xdg-run/dconf;~/.config/dconf:ro;

[Session Bus Policy]
ca.desrt.dconf=talk

[Environment]
DCONF_USER_CONFIG_DIR=.config/dconf

[Extension org.gnome.Calculator.Locale]
directory=share/runtime/locale
subdirectories=true

[Extension org.gnome.Calculator.Debug]
directory=lib/debug

See Also

flatpak(1), flatpak-run(1), flatpak-override(1)

Info

flatpak metadata