mirror of
https://github.com/flatpak/flatpak.git
synced 2026-01-01 04:18:05 -05:00
6667e1d361
This gives us conditionals for shares and features. So far we have no use case for this, but the system already exists, it makes the code simpler, and when we need this in the future, we don't have to wait for it to roll out.
1361 lines
70 KiB
XML
1361 lines
70 KiB
XML
<?xml version='1.0'?> <!--*-nxml-*-->
|
|
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
|
|
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
|
|
|
|
<refentry id="flatpak-metadata">
|
|
|
|
<refentryinfo>
|
|
<title>flatpak metadata</title>
|
|
<productname>flatpak</productname>
|
|
|
|
<authorgroup>
|
|
<author>
|
|
<contrib>Developer</contrib>
|
|
<firstname>Alexander</firstname>
|
|
<surname>Larsson</surname>
|
|
<email>alexl@redhat.com</email>
|
|
</author>
|
|
</authorgroup>
|
|
</refentryinfo>
|
|
|
|
<refmeta>
|
|
<refentrytitle>flatpak metadata</refentrytitle>
|
|
<manvolnum>5</manvolnum>
|
|
</refmeta>
|
|
|
|
<refnamediv>
|
|
<refname>flatpak-metadata</refname>
|
|
<refpurpose>Information about an application or runtime</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsect1>
|
|
<title>Description</title>
|
|
|
|
<para>
|
|
Flatpak uses metadata files to describe applications and runtimes.
|
|
The <filename>metadata</filename> 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
|
|
<filename>~/.local/share/flatpak/app/org.gnome.Calculator/current/active/metadata</filename>.
|
|
</para>
|
|
|
|
<para>
|
|
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.
|
|
</para>
|
|
|
|
<para>
|
|
A metadata file describing the effective configuration is available
|
|
inside the running sandbox at <filename>/.flatpak-info</filename>.
|
|
For compatibility with older Flatpak versions,
|
|
<filename>/run/user/$UID/flatpak-info</filename> is a symbolic
|
|
link to the same file.
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>File format</title>
|
|
|
|
<para>
|
|
The metadata file is using the same .ini file format that is used for
|
|
systemd unit files or application .desktop files.
|
|
</para>
|
|
|
|
<refsect2 id="application-runtime-metadata">
|
|
<title>[Application] or [Runtime]</title>
|
|
|
|
<para>
|
|
Metadata for applications starts with an [Application] group,
|
|
metadata for runtimes with a [Runtime] group.
|
|
</para>
|
|
<para>
|
|
The following keys can be present in these groups:
|
|
</para>
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><option>name</option> (string)</term>
|
|
<listitem><para>The name of the application or runtime. This key is mandatory.</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>runtime</option> (string)</term>
|
|
<listitem><para>The fully qualified name of the runtime that is used by the application. This key is mandatory for applications.</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>sdk</option> (string)</term>
|
|
<listitem>
|
|
<para>
|
|
The fully qualified name of the sdk that matches the
|
|
runtime. Available since 0.1.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>command</option> (string)</term>
|
|
<listitem>
|
|
<para>
|
|
The command to run. Only relevant for applications.
|
|
Available since 0.1.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>required-flatpak</option> (string list)</term>
|
|
<listitem><para>
|
|
The required version of Flatpak to run this application
|
|
or runtime. For applications, this was available since
|
|
0.8.0. For runtimes, this was available since 0.9.1,
|
|
and backported to 0.8.3 for the 0.8.x branch.
|
|
</para><para>
|
|
Flatpak after version 1.4.3 and 1.2.5 support multiple versions here.
|
|
This can be useful if you need to support features that are backported
|
|
to a previous stable series. For example if you want to use a feature
|
|
added in 1.6.0 that was also backported to 1.4.4 you would use
|
|
<literal>1.6.0;1.4.4;</literal>. Note that older versions of flatpak will
|
|
just use the first element in the list, so make that the largest version.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>tags</option> (string list)</term>
|
|
<listitem><para>
|
|
Tags to include in AppStream XML. Typical values
|
|
in use on Flathub include
|
|
<option>beta</option>, <option>stable</option>,
|
|
<option>proprietary</option>
|
|
and <option>upstream-maintained</option>.
|
|
Available since 0.4.12.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</refsect2>
|
|
<refsect2 id="context-metadata">
|
|
<title>[Context]</title>
|
|
<para>
|
|
This group determines various system resources that may be shared
|
|
with the application when it is run in a flatpak sandbox.
|
|
</para>
|
|
<refsect3 id="conditional-permissions">
|
|
<title>Conditional Permissions</title>
|
|
<para>
|
|
Some permissions (such as <option>sockets</option> and
|
|
<option>devices</option>) support conditional grants,
|
|
where access is only provided when specific runtime
|
|
conditions are met. This allows applications to adapt
|
|
to different system capabilities and session types.
|
|
Available since 1.17.
|
|
</para>
|
|
<para>
|
|
Conditional permissions use the syntax
|
|
<literal>if:PERMISSION:CONDITION</literal> in the
|
|
metadata file. For example,
|
|
<literal>if:wayland:has-wayland</literal> grants
|
|
Wayland socket access only when running in a Wayland session.
|
|
</para>
|
|
<para>
|
|
The following conditions are supported:
|
|
</para>
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><option>true</option></term>
|
|
<listitem><para>
|
|
Always evaluates to true.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>false</option></term>
|
|
<listitem><para>
|
|
Always evaluates to false.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>has-input-device</option></term>
|
|
<listitem><para>
|
|
True if this version of Flatpak supports the
|
|
<option>input</option> device permission.
|
|
This is always true in Flatpak 1.15.6 and later,
|
|
and can be used to provide fallback behavior for
|
|
older Flatpak versions.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>has-wayland</option></term>
|
|
<listitem><para>
|
|
True if the current desktop session supports
|
|
Wayland.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<para>
|
|
Conditions can be negated by prefixing with
|
|
<literal>!</literal>. For example,
|
|
<literal>if:x11:!has-wayland</literal> grants
|
|
X11 socket access only when NOT running in a Wayland session.
|
|
</para>
|
|
<para>
|
|
Multiple conditional permissions can be specified for
|
|
the same resource. If any condition matches, the
|
|
permission is granted (OR logic). For example:
|
|
<programlisting>
|
|
sockets=wayland;if:x11:!has-wayland;if:x11:false
|
|
</programlisting>
|
|
</para>
|
|
<para>
|
|
For backward compatibility with older Flatpak versions,
|
|
conditional permissions can be combined with unconditional
|
|
grants:
|
|
<programlisting>
|
|
sockets=x11;if:x11:!has-wayland;
|
|
</programlisting>
|
|
Older Flatpak versions will grant X11 access unconditionally
|
|
(seeing only <literal>x11</literal>), while newer
|
|
versions recognize the conditional syntax and grant
|
|
X11 access only when not in Wayland sessions.
|
|
</para>
|
|
<para>
|
|
To explicitly deny a permission that might be granted at
|
|
a lower layer (such as from the runtime or a global override),
|
|
prefix the permission name with <literal>!</literal>:
|
|
<programlisting>
|
|
sockets=!x11;
|
|
</programlisting>
|
|
This denial can be combined with conditional grants to
|
|
remove unconditional access while allowing conditional access:
|
|
<programlisting>
|
|
sockets=!x11;x11;if:x11:!has-wayland;
|
|
</programlisting>
|
|
This denies unconditional X11 access, but allows X11
|
|
access conditionally when not running in a Wayland session.
|
|
The seemingly contradictory <literal>!x11</literal> and
|
|
<literal>x11</literal> ensures backward compatibility:
|
|
older Flatpak versions see the final <literal>x11</literal>
|
|
grant, while newer versions understand the conditional logic.
|
|
</para>
|
|
</refsect3>
|
|
<para>
|
|
All keys in this group (and the group itself) are optional.
|
|
</para>
|
|
<para>
|
|
The keys supported in this group are:
|
|
</para>
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><option>shared</option> (list)</term>
|
|
<listitem><para>
|
|
List of subsystems to share with the host system.
|
|
Possible subsystems: network, ipc.
|
|
Available since 0.3.
|
|
</para><para>
|
|
This option supports conditional permissions.
|
|
See <link linkend="conditional-permissions">Conditional Permissions</link>
|
|
for details on how to share subsystem access conditionally
|
|
based on runtime conditions.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>sockets</option> (list)</term>
|
|
<listitem><para>
|
|
List of well-known sockets to make available in the sandbox.
|
|
Possible sockets: x11, wayland, fallback-x11, pulseaudio, session-bus, system-bus,
|
|
ssh-auth, pcsc, cups, gpg-agent, inherit-wayland-socket.
|
|
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.
|
|
Available since 0.3.
|
|
</para><para>
|
|
This option supports conditional permissions.
|
|
See <link linkend="conditional-permissions">Conditional Permissions</link>
|
|
for details on how to grant socket access conditionally
|
|
based on runtime conditions.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>devices</option> (list)</term>
|
|
<listitem><para>
|
|
List of devices to make available in the sandbox. This
|
|
just expose the devices nodes, it doesn't grant any
|
|
permission that the user doesn't already have.
|
|
Possible values:
|
|
<variablelist>
|
|
|
|
<varlistentry><term><option>dri</option></term>
|
|
<listitem><para>
|
|
Graphics direct rendering
|
|
(<filename>/dev/dri</filename>).
|
|
Available since 0.3.
|
|
</para></listitem></varlistentry>
|
|
|
|
<varlistentry><term><option>input</option></term>
|
|
<listitem><para>
|
|
Input devices
|
|
(<filename>/dev/input</filename>).
|
|
Available since 1.15.6.
|
|
</para></listitem></varlistentry>
|
|
|
|
<varlistentry><term><option>usb</option></term>
|
|
<listitem><para>
|
|
USB device bus
|
|
(all device nodes below
|
|
<filename>/dev/bus/usb</filename>).
|
|
Available since 1.15.11.
|
|
</para></listitem></varlistentry>
|
|
|
|
<varlistentry><term><option>kvm</option></term>
|
|
<listitem><para>
|
|
Virtualization
|
|
(<filename>/dev/kvm</filename>).
|
|
Available since 0.6.12.
|
|
</para></listitem></varlistentry>
|
|
|
|
<varlistentry><term><option>all</option></term>
|
|
<listitem><para>
|
|
All device nodes in <filename>/dev</filename>, but not /dev/shm (which is separately specified).
|
|
Available since 0.6.6.
|
|
</para></listitem></varlistentry>
|
|
|
|
<varlistentry><term><option>shm</option></term>
|
|
<listitem><para>
|
|
Access to the host /dev/shm
|
|
(<filename>/dev/shm</filename>).
|
|
Available since 1.6.1.
|
|
</para></listitem></varlistentry>
|
|
|
|
</variablelist>
|
|
</para><para>
|
|
This option supports conditional permissions.
|
|
See <link linkend="conditional-permissions">Conditional Permissions</link>
|
|
for details on how to grant device access conditionally
|
|
based on runtime conditions.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>filesystems</option> (list)</term>
|
|
<listitem><para>
|
|
List of filesystem subsets to make available to the
|
|
application. Possible values:
|
|
<variablelist>
|
|
|
|
<varlistentry><term><option>home</option></term>
|
|
<listitem><para>
|
|
The entire home directory.
|
|
Available since 0.3.
|
|
</para></listitem></varlistentry>
|
|
|
|
<varlistentry><term><option>home/<replaceable>path</replaceable></option></term><listitem><para>
|
|
Alias for <filename>~/path</filename>
|
|
Available since 1.10.
|
|
For better compatibility with older
|
|
Flatpak versions, prefer to write this
|
|
as <filename>~/path</filename>.
|
|
</para></listitem></varlistentry>
|
|
|
|
<varlistentry><term><option>host</option></term>
|
|
<listitem><para>
|
|
The entire host file system, except for
|
|
directories that are handled specially by
|
|
Flatpak.
|
|
In particular, this shares
|
|
<filename>/home</filename>,
|
|
<filename>/media</filename>,
|
|
<filename>/opt</filename>,
|
|
<filename>/run/media</filename> and
|
|
<filename>/srv</filename> if they exist.
|
|
</para>
|
|
<para>
|
|
<filename>/dev</filename> is not shared:
|
|
use <option>devices=all;</option> instead.
|
|
</para>
|
|
<para>
|
|
Parts of <filename>/sys</filename> are always
|
|
shared. This option does not make additional
|
|
files in /sys available.
|
|
</para>
|
|
<para>
|
|
Additionally, this keyword provides all of the
|
|
same directories in
|
|
<filename>/run/host</filename> as the
|
|
<option>host-os</option> and
|
|
<option>host-etc</option> keywords.
|
|
If this keyword is used in conjunction
|
|
with one of the <option>host-</option>
|
|
keywords, whichever access level is higher
|
|
(more permissive) will be used for the
|
|
directories in <filename>/run/host</filename>:
|
|
for example,
|
|
<code>host:rw;host-os:ro;</code> is
|
|
equivalent to <code>host:rw;</code>.
|
|
</para>
|
|
<para>
|
|
These other reserved directories are
|
|
currently excluded:
|
|
<filename>/app</filename>,
|
|
<filename>/bin</filename>,
|
|
<filename>/boot</filename>,
|
|
<filename>/efi</filename>,
|
|
<filename>/etc</filename>,
|
|
<filename>/lib</filename>,
|
|
<filename>/lib32</filename>,
|
|
<filename>/lib64</filename>,
|
|
<filename>/proc</filename>,
|
|
<filename>/root</filename>,
|
|
<filename>/run</filename>,
|
|
<filename>/sbin</filename>,
|
|
<filename>/tmp</filename>,
|
|
<filename>/usr</filename>,
|
|
<filename>/var</filename>.
|
|
</para>
|
|
<para>
|
|
Available since 0.3.
|
|
</para></listitem></varlistentry>
|
|
|
|
<varlistentry><term><option>host-os</option></term>
|
|
<listitem><para>
|
|
The host operating system's libraries,
|
|
executables and static data from
|
|
<filename>/usr</filename>
|
|
and the related directories
|
|
<filename>/bin</filename>,
|
|
<filename>/lib</filename>,
|
|
<filename>/lib32</filename>,
|
|
<filename>/lib64</filename>,
|
|
<filename>/sbin</filename>.
|
|
Additionally, this keyword provides access
|
|
to a subset of <filename>/etc</filename> that
|
|
is associated with packaged libraries and
|
|
executables, even if the
|
|
<option>host-etc</option> keyword
|
|
was not used:
|
|
<filename>/etc/ld.so.cache</filename>,
|
|
(used by the dynamic linker) and
|
|
<filename>/etc/alternatives</filename>
|
|
(on operating systems that use it, such as
|
|
Debian).
|
|
</para>
|
|
<para>
|
|
To avoid conflicting with the Flatpak
|
|
runtime, these are mounted in the sandbox
|
|
at <filename>/run/host/usr</filename>,
|
|
<filename>/run/host/etc/ld.so.cache</filename>
|
|
and so on.
|
|
</para>
|
|
<para>
|
|
Available since 1.7.
|
|
</para></listitem></varlistentry>
|
|
|
|
<varlistentry><term><option>host-etc</option></term>
|
|
<listitem><para>
|
|
The host operating system's configuration from
|
|
<filename>/etc</filename>.
|
|
</para>
|
|
<para>
|
|
To avoid conflicting with the Flatpak
|
|
runtime, this is mounted in the sandbox
|
|
at <filename>/run/host/etc</filename>.
|
|
</para>
|
|
<para>
|
|
Available since 1.7.
|
|
</para></listitem></varlistentry>
|
|
|
|
<varlistentry><term><option>host-root</option></term>
|
|
<listitem><para>
|
|
The complete host operating system.
|
|
</para>
|
|
<para>
|
|
To avoid conflicting with the Flatpak
|
|
runtime, this is mounted in the sandbox
|
|
at <filename>/run/host/root</filename>.
|
|
</para>
|
|
<para>
|
|
This permission is only intended to be used
|
|
as a last resort when there is no possible
|
|
alternative with other filesystem
|
|
permissions for applications that need the
|
|
entire root filesystem of the host.
|
|
</para>
|
|
<para>
|
|
Please note that following symlinks under
|
|
<filename>/run/host/root</filename> naively
|
|
will result in a wrong path. For example,
|
|
using <literal>realpath()</literal> is wrong.
|
|
Instead, applications will have to implement
|
|
some way of following symlinks in a way that
|
|
behaves as if it were chroot'd into
|
|
<filename>/run/host/root</filename>.
|
|
</para>
|
|
<para>
|
|
There are a few ways to do this. Modern
|
|
kernels support the <ulink url="https://man7.org/linux/man-pages/man2/openat2.2.html">openat2()</ulink>
|
|
call with <literal>RESOLVE_IN_ROOT</literal>.
|
|
For a more portable solution with support for
|
|
older kernels, see the implementation from
|
|
the <ulink url="https://gitlab.steamos.cloud/steamrt/steam-runtime-tools/-/blob/65adfdd5fc812aeb5f33986755f6ff72c9612afa/steam-runtime-tools/resolve-in-sysroot.c">steam-runtime-tools</ulink>
|
|
as an example.
|
|
</para>
|
|
<para>
|
|
Available since 1.17.
|
|
</para></listitem></varlistentry>
|
|
|
|
<varlistentry><term><option>xdg-desktop</option>,
|
|
<option>xdg-documents</option>,
|
|
<option>xdg-download</option>,
|
|
<option>xdg-music</option>,
|
|
<option>xdg-pictures</option>,
|
|
<option>xdg-public-share</option>,
|
|
<option>xdg-videos</option>,
|
|
<option>xdg-templates</option>
|
|
</term><listitem><para>
|
|
<ulink url="https://www.freedesktop.org/wiki/Software/xdg-user-dirs/"
|
|
>freedesktop.org special directories</ulink>.
|
|
Available since 0.3.
|
|
</para></listitem></varlistentry>
|
|
|
|
<varlistentry><term><option>xdg-desktop/<replaceable>path</replaceable></option>,
|
|
<option>xdg-documents/<replaceable>path</replaceable></option>,
|
|
etc.
|
|
</term><listitem><para>
|
|
Subdirectories of freedesktop.org special
|
|
directories. Available since 0.4.13.
|
|
</para></listitem></varlistentry>
|
|
|
|
<varlistentry><term>
|
|
<option>xdg-cache</option>,
|
|
<option>xdg-config</option>,
|
|
<option>xdg-data</option>
|
|
</term><listitem><para>
|
|
Directories defined by the
|
|
<ulink url="https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html"
|
|
>freedesktop.org Base Directory Specification</ulink>.
|
|
Available since 0.6.14.
|
|
</para></listitem></varlistentry>
|
|
|
|
<varlistentry><term>
|
|
<option>xdg-cache/<replaceable>path</replaceable></option>,
|
|
<option>xdg-config/<replaceable>path</replaceable></option>,
|
|
<option>xdg-data/<replaceable>path</replaceable></option>
|
|
</term><listitem><para>
|
|
Subdirectories of directories defined by the
|
|
freedesktop.org Base Directory Specification.
|
|
Available since 0.6.14.
|
|
</para></listitem></varlistentry>
|
|
|
|
<varlistentry><term>
|
|
<option>xdg-run/<replaceable>path</replaceable></option>
|
|
</term><listitem><para>
|
|
Subdirectories of the
|
|
<envar>XDG_RUNTIME_DIR</envar> defined by the
|
|
freedesktop.org Base Directory Specification.
|
|
Note that <option>xdg-run</option> on its own
|
|
is not supported. Available since 0.4.13.
|
|
</para></listitem></varlistentry>
|
|
|
|
<varlistentry><term>
|
|
<option>/<replaceable>path</replaceable></option>
|
|
</term><listitem><para>
|
|
An arbitrary absolute path. Available since 0.3.
|
|
</para></listitem></varlistentry>
|
|
|
|
<varlistentry><term>
|
|
<option>~/<replaceable>path</replaceable></option>
|
|
</term><listitem><para>
|
|
An arbitrary path relative to the home
|
|
directory. Available since 0.3.
|
|
</para></listitem></varlistentry>
|
|
|
|
<varlistentry><term><option>~</option></term>
|
|
<listitem><para>
|
|
The same as <option>home</option>.
|
|
Available since 1.10.
|
|
For better compatibility with older
|
|
Flatpak versions, prefer to write this
|
|
as <option>home</option>.
|
|
</para></listitem></varlistentry>
|
|
|
|
<varlistentry><term>
|
|
One of the above followed by
|
|
<option>:ro</option>
|
|
</term><listitem><para>
|
|
Make the given directory available read-only.
|
|
</para></listitem></varlistentry>
|
|
|
|
<varlistentry><term>
|
|
One of the above followed by
|
|
<option>:rw</option>
|
|
</term><listitem><para>
|
|
Make the given directory available read/write.
|
|
This is the default.
|
|
</para></listitem></varlistentry>
|
|
|
|
<varlistentry><term>
|
|
One of the above followed by
|
|
<option>:create</option>
|
|
</term><listitem><para>
|
|
Make the given directory available read/write,
|
|
and create it if it does not already exist.
|
|
</para></listitem></varlistentry>
|
|
|
|
</variablelist>
|
|
</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>persistent</option> (list)</term>
|
|
<listitem><para>
|
|
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. Available since 0.3.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>features</option> (list)</term>
|
|
<listitem><para>
|
|
List of features available or unavailable to the
|
|
application, currently from the following list:
|
|
<variablelist>
|
|
|
|
<varlistentry><term><option>devel</option></term>
|
|
<listitem><para>
|
|
Allow system calls used by development-oriented
|
|
tools such as <command>perf</command>,
|
|
<command>strace</command> and
|
|
<command>gdb</command>.
|
|
Available since 0.6.10.
|
|
</para></listitem></varlistentry>
|
|
|
|
<varlistentry><term><option>multiarch</option></term>
|
|
<listitem><para>
|
|
Allow running multilib/multiarch binaries, for
|
|
example <literal>i386</literal> binaries in an
|
|
<literal>x86_64</literal> environment.
|
|
Available since 0.6.12.
|
|
</para></listitem></varlistentry>
|
|
|
|
<varlistentry><term><option>bluetooth</option></term>
|
|
<listitem><para>
|
|
Allow the application to use bluetooth (AF_BLUETOOTH) sockets.
|
|
Note, for bluetooth to fully work you must also have network access.
|
|
Available since 0.11.8.
|
|
</para></listitem></varlistentry>
|
|
|
|
<varlistentry><term><option>canbus</option></term>
|
|
<listitem><para>
|
|
Allow the application to use canbus (AF_CAN) sockets.
|
|
Note, for this work you must also have network access.
|
|
Available since 1.0.3.
|
|
</para></listitem></varlistentry>
|
|
|
|
<varlistentry><term><option>per-app-dev-shm</option></term>
|
|
<listitem><para>
|
|
Share a single instance of
|
|
<filename>/dev/shm</filename> between all
|
|
instances of this application run by the same
|
|
user ID, including sub-sandboxes.
|
|
If the application has the
|
|
<option>shm</option> device permission in its
|
|
<option>devices</option> list, then this
|
|
feature flag is ignored.
|
|
Available since 1.12.0.
|
|
</para></listitem></varlistentry>
|
|
|
|
</variablelist>
|
|
A feature can be prefixed with <option>!</option> to
|
|
indicate the absence of that feature, for example
|
|
<option>!devel</option> if development and debugging
|
|
are not allowed.
|
|
</para><para>
|
|
This option supports conditional permissions.
|
|
See <link linkend="conditional-permissions">Conditional Permissions</link>
|
|
for details on how to allow features based
|
|
conditionally on runtime conditions.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>unset-environment</option> (list)</term>
|
|
<listitem><para>
|
|
A list of names of environment variables to unset.
|
|
Note that environment variables to set to a value
|
|
(possibly empty) appear in the [Environment]
|
|
group instead.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</refsect2>
|
|
<refsect2 id="instance-metadata">
|
|
<title>[Instance]</title>
|
|
<para>
|
|
This group only appears in <filename>/.flatpak-info</filename>
|
|
for a running app, and not in the metadata files written by
|
|
application authors. It is filled in by Flatpak itself.
|
|
</para>
|
|
<!-- In versions prior to 0.6.10 some of this information was
|
|
in [Application], but for simplicity that isn't documented
|
|
here. -->
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><option>instance-id</option> (string)</term>
|
|
<listitem><para>
|
|
The ID of the running instance. This number is
|
|
used as the name of the directory in
|
|
<filename><envar>XDG_RUNTIME_DIR</envar>/.flatpak</filename>
|
|
where Flatpak stores information about this instance.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>instance-path</option> (string)</term>
|
|
<listitem><para>
|
|
The absolute path on the host system of the app's
|
|
persistent storage area in <filename>$HOME/.var</filename>.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>app-path</option> (string)</term>
|
|
<listitem><para>
|
|
The absolute path on the host system of the app's
|
|
app files, as mounted at <filename>/app</filename>
|
|
inside the container. Available since 0.6.10.
|
|
</para><para>
|
|
Since 1.12.0, if <command>flatpak run</command>
|
|
was run with the <option>--app-path</option> option,
|
|
this key gives the absolute path of whatever files
|
|
were mounted on <filename>/app</filename>, even if
|
|
that differs from the app's normal app files.
|
|
</para><para>
|
|
If <command>flatpak run</command> was run with
|
|
<option>--app-path=</option> (resulting in an
|
|
empty directory being mounted on
|
|
<filename>/app</filename>), the value is set to
|
|
the empty string.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>original-app-path</option> (string)</term>
|
|
<listitem><para>
|
|
If <command>flatpak run</command> was run with the
|
|
<option>--app-path</option> option, this key gives
|
|
the absolute path of the app's original files,
|
|
as mounted at <filename>/run/parent/app</filename>
|
|
inside the container. Available since 1.12.0.
|
|
</para><para>
|
|
If this key is missing, the app files are given
|
|
by <option>app-path</option>.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>app-commit</option> (string)</term>
|
|
<listitem><para>
|
|
The commit ID of the application that is running.
|
|
The filename of a deployment of this commit can
|
|
be found in <option>original-app-path</option>
|
|
if present, or <option>app-path</option> otherwise.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>app-extensions</option> (list of strings)</term>
|
|
<listitem><para>
|
|
A list of app extensions that are mounted into
|
|
the running instance. The format for each list item is
|
|
<option>EXTENSION_ID=COMMIT</option>.
|
|
If <option>original-app-path</option> is present,
|
|
the extensions are mounted below
|
|
<filename>/run/parent/app</filename>; otherwise,
|
|
they are mounted below <filename>/app</filename>.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>branch</option> (string)</term>
|
|
<listitem><para>
|
|
The branch of the app, for example
|
|
<literal>stable</literal>. Available since
|
|
0.6.10.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>arch</option> (string)</term>
|
|
<listitem><para>
|
|
The architecture of the running instance.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>flatpak-version</option> (string)</term>
|
|
<listitem><para>
|
|
The version number of the Flatpak version that ran
|
|
this app. Available since 0.6.11.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>runtime-path</option> (string)</term>
|
|
<listitem><para>
|
|
The absolute path on the host system of the app's
|
|
runtime files, as mounted at <filename>/usr</filename>
|
|
inside the container. Available since 0.6.10.
|
|
</para><para>
|
|
Since 1.12.0, if <command>flatpak run</command>
|
|
was run with the <option>--usr-path</option> option,
|
|
this key gives the absolute path of whatever files
|
|
were mounted on <filename>/usr</filename>, even if
|
|
that differs from the app's normal runtime files.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>original-runtime-path</option> (string)</term>
|
|
<listitem><para>
|
|
If <command>flatpak run</command> was run with the
|
|
<option>--runtime-path</option> option, this key gives
|
|
the absolute path of the app's original runtime,
|
|
as mounted at <filename>/run/parent/usr</filename>
|
|
inside the container. Available since 1.12.0.
|
|
</para><para>
|
|
If this key is missing, the runtime files are given
|
|
by <option>runtime-path</option>.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>runtime-commit</option> (string)</term>
|
|
<listitem><para>
|
|
The commit ID of the runtime that is used.
|
|
The filename of a deployment of this commit can be
|
|
found in <option>original-runtime-path</option>
|
|
if present, or <option>runtime-path</option>
|
|
otherwise.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>runtime-extensions</option> (list of strings)</term>
|
|
<listitem><para>
|
|
A list of runtime extensions that are mounted into
|
|
the running instance. The format for each list item is
|
|
<option>EXTENSION_ID=COMMIT</option>.
|
|
If <option>original-app-path</option> is present,
|
|
the extensions are mounted below
|
|
<filename>/run/parent/usr</filename>; otherwise,
|
|
they are mounted below <filename>/usr</filename>.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>extra-args</option> (string)</term>
|
|
<listitem><para>
|
|
Extra arguments that were passed to flatpak run.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>sandbox</option> (boolean)</term>
|
|
<listitem><para>
|
|
Whether the <option>--sandbox</option> option was passed
|
|
to flatpak run.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>build</option> (boolean)</term>
|
|
<listitem><para>
|
|
Whether this instance was created by flatpak build.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>session-bus-proxy</option> (boolean)</term>
|
|
<listitem><para>
|
|
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). Available since 0.8.0.
|
|
<!-- TODO: Those semantics are weird, are they
|
|
intended? -->
|
|
</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>system-bus-proxy</option> (boolean)</term>
|
|
<listitem><para>
|
|
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). Available since 0.8.0.
|
|
<!-- TODO: Those semantics are weird, are they
|
|
intended? -->
|
|
</para></listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</refsect2>
|
|
<refsect2 id="session-bus-policy-metadata">
|
|
<title>[Session Bus Policy]</title>
|
|
<para>
|
|
If the <option>sockets</option> key is not allowing full access
|
|
to the D-Bus session bus, then flatpak provides filtered access.
|
|
</para>
|
|
<para>
|
|
The default policy for the session bus only allows the
|
|
application to own its own application ID, its
|
|
subnames and its own application ID as a subname of
|
|
<option>org.mpris.MediaPlayer2</option>. For instance if the app is called
|
|
<option>org.my.App</option>, it can only own <option>org.my.App</option>,
|
|
<option>org.my.App.*</option>
|
|
and <option>org.mpris.MediaPlayer2.org.my.App</option>.
|
|
It is only allowed to talk to names matching those patterns, plus
|
|
the bus itself (<option>org.freedesktop.DBus</option>)
|
|
and the portal APIs (bus names of the form <option>org.freedesktop.portal.*</option>).
|
|
</para>
|
|
<para>
|
|
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.
|
|
</para>
|
|
<para>
|
|
If the <option>[Session Bus Policy]</option> group is present, it provides
|
|
policy for session bus access.
|
|
</para>
|
|
<para>
|
|
Each key in this group has the form of a D-Bus bus name or
|
|
prefix thereof, for example <option>org.gnome.SessionManager</option>
|
|
or <option>org.freedesktop.portal.*</option>.
|
|
</para>
|
|
<para>
|
|
The possible values for an entry are the following, in increasing order of
|
|
access. Each value implies all the access from any lower values:
|
|
</para>
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><option>none</option></term>
|
|
<listitem><para>
|
|
The bus name is invisible to the application.
|
|
Available since 0.2.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>see</option></term>
|
|
<listitem><para>
|
|
The bus name can be enumerated by the application.
|
|
Available since 0.2.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>talk</option></term>
|
|
<listitem><para>
|
|
The application can send messages to, and receive replies and signals from, the bus name.
|
|
Available since 0.2.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>own</option></term>
|
|
<listitem><para>
|
|
The application can own the bus name.
|
|
Available since 0.2.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</refsect2>
|
|
<refsect2 id="system-bus-policy-metadata">
|
|
<title>[System Bus Policy]</title>
|
|
<para>
|
|
If the <option>sockets</option> key is not allowing full access
|
|
to the D-Bus system bus, then flatpak does not make the system
|
|
bus available unless the <option>[System Bus Policy]</option> group is present
|
|
and provides a policy for filtered access. Available since 0.2.
|
|
</para>
|
|
<para>
|
|
Entries in this group have the same form as for the
|
|
<option>[Session Bus Policy]</option> group.
|
|
However, the app has no permissions by default.
|
|
</para>
|
|
</refsect2>
|
|
<refsect2 id="environment-metadata">
|
|
<title>[Environment]</title>
|
|
<para>
|
|
The [Environment] group specifies environment variables to set
|
|
when running the application. Available since 0.3.
|
|
</para>
|
|
<para>
|
|
Entries in this group have the form <option>VAR=VALUE</option>
|
|
where <option>VAR</option> is the name of an environment variable
|
|
to set.
|
|
</para>
|
|
<para>
|
|
Note that environment variables can also be unset (removed
|
|
from the environment) by listing them in the
|
|
<option>unset-environment</option> entry of the
|
|
[Context] group.
|
|
</para>
|
|
</refsect2>
|
|
<refsect2 id="extension-metadata">
|
|
<title>[Extension NAME]</title>
|
|
<para>
|
|
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. Since 0.11.4, the name may optionally include a tag
|
|
in the NAME in the name@tag ref syntax if you wish to use different
|
|
configurations (eg, versions) of the same extension concurrently.
|
|
The "tag" is effectively ignored, but is necessary in order to allow
|
|
the same extension name to be specified more than once.
|
|
</para>
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><option>directory</option> (string)</term>
|
|
<listitem><para>
|
|
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 <filename>/app</filename>, otherwise
|
|
it is relative to <filename>/usr</filename>. This key
|
|
is mandatory. Available since 0.1.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>version</option> (string)</term>
|
|
<listitem><para>
|
|
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.
|
|
Available since 0.4.1.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>versions</option> (string)</term>
|
|
<listitem><para>
|
|
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. Available since
|
|
0.9.1, and backported to the 0.8.x branch in 0.8.4.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>add-ld-path</option> (string)</term>
|
|
<listitem><para>
|
|
A path relative to the extension point directory that will be appended
|
|
to LD_LIBRARY_PATH. Available since 0.9.1, and
|
|
backported to the 0.8.x branch in 0.8.3.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>merge-dirs</option> (string)</term>
|
|
<listitem><para>
|
|
A list of relative paths of directories below the extension point directory
|
|
that will be merged. Available since 0.9.1, and
|
|
backported to the 0.8.x branch in 0.8.3.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>download-if</option> (string)</term>
|
|
<listitem>
|
|
<para>
|
|
A condition that must be true for the extension to be auto-downloaded.
|
|
As of 1.1.1 this supports multiple conditions separated by semi-colons.
|
|
</para>
|
|
<para>
|
|
These are the supported conditions:
|
|
</para>
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><option>active-gl-driver</option></term>
|
|
<listitem><para>
|
|
Is true if the name of the active GL driver matches the
|
|
extension point basename. Available since 0.9.1, and backported to
|
|
the 0.8.x branch in 0.8.3.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>active-gtk-theme</option></term>
|
|
<listitem><para>
|
|
Is true if the name of the current GTK theme
|
|
(via org.gnome.desktop.interface GSetting) matches the extension point
|
|
basename. Added 0.10.1.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>have-intel-gpu</option></term>
|
|
<listitem><para>Is true if the i915 kernel module is loaded. Added 0.10.1.</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>have-kernel-module-*</option></term>
|
|
<listitem><para>
|
|
Is true if the suffix (case-sensitive) is found in <literal>/proc/modules</literal>.
|
|
For example <literal>have-kernel-module-nvidia</literal>.
|
|
Added 1.13.1.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>on-xdg-desktop-*</option></term>
|
|
<listitem><para>
|
|
Is true if the suffix (case-insensitively) is in the
|
|
<literal>XDG_CURRENT_DESKTOP</literal> env var.
|
|
For example <literal>on-xdg-desktop-GNOME-classic</literal>.
|
|
Added 1.1.1.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>autoprune-unless</option> (string)</term>
|
|
<listitem><para>
|
|
A condition that must be false for the extension to be considered unused when
|
|
pruning. For example, <command>flatpak uninstall --unused</command> and
|
|
<command>flatpak update</command> use this information. 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. Available since 0.11.8.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>enable-if</option> (string)</term>
|
|
<listitem><para>
|
|
A condition that must be true for the extension to be enabled.
|
|
As of 1.1.1 this supports multiple conditions separated by semi-colons.
|
|
See <option>download-if</option> for available conditions.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>subdirectory-suffix</option> (string)</term>
|
|
<listitem><para>
|
|
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.
|
|
Available since 0.9.1, and backported to the 0.8.x
|
|
branch in 0.8.3.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>subdirectories</option> (boolean)</term>
|
|
<listitem><para>
|
|
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.
|
|
Available since 0.1.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>no-autodownload</option> (boolean)</term>
|
|
<listitem><para>
|
|
Whether to automatically download extensions matching this extension
|
|
point when updating or installing a 'related' application or runtime.
|
|
Available since 0.6.7.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>locale-subset</option> (boolean)</term>
|
|
<listitem><para>
|
|
If set, then the extensions are partially downloaded by default,
|
|
based on the currently configured locales. This means that the extension
|
|
contents should be a set of directories with the language code as name.
|
|
Available since 0.9.13 (and 0.6.6 for any extensions called *.Locale)
|
|
</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>autodelete</option> (boolean)</term>
|
|
<listitem><para>
|
|
Whether to automatically delete extensions matching this extension
|
|
point when deleting a 'related' application or runtime.
|
|
Available since 0.6.7.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>collection-id</option> (string)</term>
|
|
<listitem><para>
|
|
The ID of the collection that this extension point belongs to. If this
|
|
is unspecified, it defaults to the collection ID of the application
|
|
or runtime that the extension point is for.
|
|
Currently, extension points must be in the same collection as the
|
|
application or runtime that they are for.
|
|
Available since 0.99.1.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</refsect2>
|
|
<refsect2 id="extension-of-metadata">
|
|
<title>[ExtensionOf]</title>
|
|
<para>
|
|
This optional group may be present if the runtime is an extension.
|
|
</para>
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><option>ref</option> (string)</term>
|
|
<listitem><para>
|
|
The ref of the runtime or application that this extension
|
|
belongs to. Available since 0.9.1.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>runtime</option> (string)</term>
|
|
<listitem><para>
|
|
The runtime this extension will be inside of. If it is an
|
|
app extension, this is the app's runtime; otherwise, this
|
|
is identical to ref, without the runtime/ prefix.
|
|
Available since 1.5.0.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>priority</option> (integer)</term>
|
|
<listitem><para>
|
|
The priority to give this extension when looking for the
|
|
best match. Default is 0. Available since 0.9.1, and
|
|
backported to the 0.8.x branch in 0.8.3.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>tag</option> (string)</term>
|
|
<listitem><para>
|
|
The tag name to use when searching for this extension's mount
|
|
point in the parent flatpak. Available since 0.11.4.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</refsect2>
|
|
<refsect2 id="extra-data-metadata">
|
|
<title>[Extra Data]</title>
|
|
<para>
|
|
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.
|
|
</para>
|
|
<para>
|
|
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.
|
|
</para>
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><option>NoRuntime</option> (boolean)</term>
|
|
<listitem><para>
|
|
Whether to mount the runtime while running the /app/bin/apply_extra
|
|
script. Defaults to true, i.e. not mounting the runtime.
|
|
Available since 0.9.1, and backported to the 0.8.x
|
|
branch in 0.8.4.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>uri<replaceable>X</replaceable></option> (string)</term>
|
|
<listitem><para>
|
|
The uri for extra data source
|
|
<replaceable>X</replaceable>. The only supported uri
|
|
schemes are http and https. Available since 0.6.13.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>size<replaceable>X</replaceable></option> (integer)</term>
|
|
<listitem><para>
|
|
The size for extra data source
|
|
<replaceable>X</replaceable>. Available since 0.6.13.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>checksum<replaceable>X</replaceable></option> (string)</term>
|
|
<listitem><para>
|
|
The sha256 sum for extra data source
|
|
<replaceable>X</replaceable>. Available since 0.6.13.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</refsect2>
|
|
<refsect2 id="policy-metadata">
|
|
<title>[Policy SUBSYSTEM]</title>
|
|
<para>
|
|
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.
|
|
Available since 0.6.13.
|
|
<!-- TODO: More information would be nice -->
|
|
</para>
|
|
</refsect2>
|
|
<refsect2 id="usb-devices">
|
|
<title>[USB Devices]</title>
|
|
<para>
|
|
USB devices can be enumerable or hidden by the USB portal as specified
|
|
by the keys in this group. The vendor and product ids are validated
|
|
by Flatpak, but aren't otherwise used or parsed.
|
|
This merely grant the permission to enumerate USB device for use by the
|
|
portal. This does give access to the devices.
|
|
Available since 1.15.11.
|
|
</para>
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><option>enumerable-devices</option> (string list)</term>
|
|
<listitem><para>
|
|
List of enumerable USB devices. Each element is the same
|
|
syntax the arguments to `--usb`.
|
|
Available since 1.15.11.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><option>hidden-devices</option> (string list)</term>
|
|
<listitem><para>
|
|
List of hidden USB devices, i.e. to remove the enumarable
|
|
devices list. Each element is the same syntax the arguments
|
|
to `--nousb`. Hidden devices take precedence over enumerable
|
|
devices. Available since 1.15.11.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</refsect2>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Example</title>
|
|
<programlisting>
|
|
[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
|
|
|
|
[USB Devices]
|
|
enumerable-devices=0fd9:*;
|
|
hidden-devices=0fd9:0063;
|
|
|
|
[Extension org.gnome.Calculator.Locale]
|
|
directory=share/runtime/locale
|
|
subdirectories=true
|
|
|
|
[Extension org.gnome.Calculator.Debug]
|
|
directory=lib/debug
|
|
</programlisting>
|
|
<para>
|
|
Example using conditional permissions to support fallback
|
|
from Wayland to X11:
|
|
</para>
|
|
<programlisting>
|
|
[Application]
|
|
name=org.example.App
|
|
runtime=org.gnome.Platform/x86_64/3.20
|
|
sdk=org.gnome.Sdk/x86_64/3.20
|
|
|
|
[Context]
|
|
shared=network;ipc;
|
|
sockets=wayland;x11;if:x11:!has-wayland;
|
|
</programlisting>
|
|
<para>
|
|
In this example, the application will always have access to
|
|
the Wayland socket if there the app runs in a Wayland session.
|
|
The X11 socket only is available if the app does not run in
|
|
a wayland session (<option>!has-wayland</option>).
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>See also</title>
|
|
|
|
<para>
|
|
<citerefentry><refentrytitle>flatpak</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
|
|
<citerefentry><refentrytitle>flatpak-run</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
|
|
<citerefentry><refentrytitle>flatpak-override</refentrytitle><manvolnum>1</manvolnum></citerefentry>
|
|
</para>
|
|
|
|
</refsect1>
|
|
|
|
</refentry>
|