<?xml version='1.0'?> <!--*-nxml-*-->
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
    "http://www.oasis-open.org/docbook/xml/4.2/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>/run/user/$UID/flatpak-info</filename>.
        </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>
            <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.</para></listitem>
                </varlistentry>
                <varlistentry>
                    <term><option>command</option> (string)</term>
                    <listitem><para>The command to run. Only relevant for applications.</para></listitem>
                </varlistentry>
            </variablelist>
        </refsect2>
        <refsect2>
            <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>
            <para>
                All keys in this group (and the group itself) are optional.
            </para>
            <variablelist>
                <varlistentry>
                    <term><option>shared</option> (list)</term>
                    <listitem><para>
                        List of subsystems to share with the host system.
                        Possible subsystems: network, ipc.
                    </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, 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.
                    </para></listitem>
                </varlistentry>
                <varlistentry>
                    <term><option>devices</option> (list)</term>
                    <listitem><para>
                        List of devices to make available in the sandbox.
                        Possible values: dri, kvm, all.
                    </para></listitem>
                </varlistentry>
                <varlistentry>
                    <term><option>filesystems</option> (list)</term>
                    <listitem><para>
                        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).
                    </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.
                    </para></listitem>
                </varlistentry>
            </variablelist>
        </refsect2>
        <refsect2>
            <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 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.*).
            </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 [Session Bus Policy] 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 entry are, in increasing order or
                access:
            </para>
            <variablelist>
                <varlistentry>
                    <term><option>none</option></term>
                    <listitem><para>
                        The bus name or names in question is invisible to the application.
                    </para></listitem>
                </varlistentry>
                <varlistentry>
                    <term><option>see</option></term>
                    <listitem><para>
                        The bus name or names can be enumerated by the application.
                    </para></listitem>
                </varlistentry>
                <varlistentry>
                    <term><option>talk</option></term>
                    <listitem><para>
                        The application can send messages/ and receive replies and signals from the bus name or names.
                    </para></listitem>
                </varlistentry>
                <varlistentry>
                    <term><option>own</option></term>
                    <listitem><para>
                        The application can own the bus name or names (as well as all the above).
                    </para></listitem>
                </varlistentry>
            </variablelist>
        </refsect2>
        <refsect2>
            <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 [System Bus Policy] group is present
                and provides a policy for filtered access.
            </para>
            <para>
                Entries in this group have the same form as for the [Session Bus Policy] group.
                However, the app has no permissions by default.
            </para>
        </refsect2>
        <refsect2>
            <title>[Environment]</title>
            <para>
                The [Environment] group specifies environment variables to set
                when running the application.
            </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>
        </refsect2>
        <refsect2>
            <title>[Extension NAME]</title>
            <para>
                Runtimes and applications can define extensions, which are optional,
                additional runtimes to be mounted at a specified location inside
                the sandbox when they are present on the system. Typical uses for
                extensions include translations for applications, or debuginfo
                for sdks. The name of the extension is specified as part of the
                group heading.
            </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 is for an application, the
                        path is relative to <filename>/app</filename>, otherwise
                        it is relative to <filename>/usr</filename>. This key
                        is mandatory.
                    </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 is for.
                    </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 is for.
                    </para></listitem>
                </varlistentry>
                <varlistentry>
                    <term><option>add-ld-path</option> (string)</term>
                    <listitem><para>
                        A path relative to the extension directory that will be appended
                        to LD_LIBRARY_PATH.
                    </para></listitem>
                </varlistentry>
                <varlistentry>
                    <term><option>merge-dirs</option> (string)</term>
                    <listitem><para>
                        A list of relative paths of directories below the extension directory
                        that will be merged.
                    </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.
                        The only currently recognized value is active-gl-driver, which is true
                        if the name of the active GL driver matches the extension basename.
                    </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.
                        The only currently recognized value is active-gl-driver, which is true
                        if the name of the active GL driver matches the extension basename.
                    </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.
                    </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 name, and
                        mount them at the corresponding name below the subdirectory.
                    </para></listitem>
                </varlistentry>
                <varlistentry>
                    <term><option>no-autodownload</option> (boolean)</term>
                    <listitem><para>
                        Whether to automatically download this extension
                        when updating or installing a 'related' application
                        or runtime.
                    </para></listitem>
                </varlistentry>
                <varlistentry>
                    <term><option>autodelete</option> (boolean)</term>
                    <listitem><para>
                        Whether to automatically delete this extension
                        when deleting a 'related' application or runtime.
                    </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

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

[Extension org.gnome.Calculator.Debug]
directory=lib/debug
</programlisting>
    </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>
