portals.conf

PORTALS.CONF(5) File Formats Manual PORTALS.CONF(5)

NAME

   portals.conf - XDG desktop portal configuration

SYNOPSIS

   $XDG_CONFIG_HOME/xdg-desktop-portal/{*-}portals.conf

   $XDG_CONFIG_DIRS/xdg-desktop-portal/{*-}portals.conf

   /etc/xdg-desktop-portal/{*-}portals.conf

   $XDG_DATA_HOME/xdg-desktop-portal/{*-}portals.conf

   $XDG_DATA_DIRS/xdg-desktop-portal/{*-}portals.conf

   /usr/share/xdg-desktop-portal/{*-}portals.conf

DESCRIPTION

   xdg-desktop-portal  uses a configuration file to determine which portal backend should be used to provide the implementation for the requested interface.  This mechanism is very simi
   lar to the freedesktop.org specification for "Association between MIME types and applications" (mime-apps).

   Desktop environments and OS vendors should provide a default configuration for their chosen portal backends in /usr/share/xdg-desktop-portal/DESKTOP-portals.conf, where DESKTOP is the
   desktop environment name as it would appear in the XDG_CURRENT_DESKTOP environment variable, after case-folding ASCII upper case to  lower  case.   For  example,  KDE  should  provide
   /usr/share/xdg-desktop-portal/kde-portals.conf.

   Users  can  override  those  defaults, or provide configuration for an otherwise unsupported desktop environment, by writing a file ~/.config/xdg-desktop-portal/portals.conf. Users of
   more than one desktop environment can use desktop-specific filenames such as kde-portals.conf which will only be used in the appropriate desktop environment.

   Similarly, system administrators can provide a default configuration for all users in /etc/xdg-desktop-portal/DESKTOP-portals.conf or /etc/xdg-desktop-portal/portals.conf.

   The following locations are searched for configuration, highest precedence first:

    $XDG_CONFIG_HOME, defaulting to ~/.config

    each directory in $XDG_CONFIG_DIRS, defaulting to /etc/xdg

    the build-time sysconfdir for xdg-desktop-portal, usually /etc

    $XDG_DATA_HOME, defaulting to ~/.local/share (searched only for consistency with other specifications, writing configuration here is not recommended)

    each directory in $XDG_DATA_DIRS, defaulting to /usr/local/share:/usr/share

    the build-time datadir for xdg-desktop-portal, usually /usr/share

   In each of those locations, for each desktop environment name listed in the XDG_CURRENT_DESKTOP environment variable,  xdg-desktop-portal  checks  for  xdg-desktop-portal/DESKTOP-por
   tals.conf, where DESKTOP is the desktop environment name in lower-case. If a desktop-environment-specific configuration file is not found, a non-desktop-specific file xdg-desktop-por
   tal/portals.conf  will  be  read.   For example, if XDG_CURRENT_DESKTOP is set to Budgie:GNOME, then xdg-desktop-portal will look for xdg-desktop-portal/budgie-portals.conf, xdg-desk
   top-portal/gnome-portals.conf and xdg-desktop-portal/portals.conf in that order.

   Only the first configuration file found is read, and lower-precedence configuration files are ignored. All possible configuration files within one directory are tried before moving on
   to the next directory, so for example ~/.config/xdg-desktop-portal/portals.conf is higher-precedence than /usr/share/xdg-desktop-portal/kde-portals.conf.

FILE FORMAT

   The format of the portals configuration file is the same .ini format used by systemd unit files or application desktop files.

   [preferred]
      The main configuration group for preferred portals.

   The following keys can be present in the preferred group:

   default (string)
      The default portal backend to use for every interface, unless the interface is listed explicitly.

   org.freedesktop.impl.portal.* (string)
      One of the valid portal interface implementations exposed by xdg-desktop-portal.

   Each key in the group contains a semi-colon separated list of portal backend implementation, to be searched for an implementation of the requested interface,  in  the  same  order  as
   specified in the configuration file. Additionally, the special values none and * can be used:

   none
      Do not provide a portal implementation for this interface.

   *
      Use the first portal implementation found, in lexicographical order.

EXAMPLE

      [preferred]
      # Use xdg-desktop-portal-gtk for every portal interface...
      default=gtk
      # ... except for the ScreenCast interface
      org.freedesktop.impl.portal.ScreenCast=gnome

ENVIRONMENT

   XDG_CURRENT_DESKTOP
      A colon-separated list of desktop environments, most specific first, used to choose a desktop-specific portal configuration.  The default is an empty list.

   XDG_CONFIG_HOME
      The per-user portals.conf file is located in this directory. The default is $HOME/.config.

   XDG_CONFIG_DIRS
      A colon-separated list of system configuration directories and secondary per-user configuration directories. The default is /etc/xdg.

   XDG_DATA_HOME
      A per-user data directory, searched for consistency with other specifications. The default is $HOME/.local/share.

   XDG_DATA_DIRS
      A colon-separated list of system data directories and secondary per-user data directories. The default is /usr/local/share:/usr/share.

SEE ALSO

    XDG Base Directory Specification <https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html>

    XDG Desktop Entry specification <https://specifications.freedesktop.org/desktop-entry-spec/desktop-entry-spec-latest.html>

    XDG Association between MIME type and applications specification <https://specifications.freedesktop.org/mime-apps-spec/mime-apps-spec-latest.html>

                                                                                                                                                                           PORTALS.CONF(5)