mutter/doc/monitor-configuration.md

Monitor configuration

File locations

Monitor configurations are stored as XML files called monitors.xml on the file system. There are two types of locations for the XML file: the system level and the user level.

The directories for system level configuration is defined in accordance to the $XDG_CONFIG_DIRS environment variable defined in the XDG Base Directory Specification. The default is /etc/xdg/monitors.xml.

The directory for the user level configuration is defined in accordance to the $XDG_CONFIG_HOME environment variable defined in the XDG Base Directory Specification. The default is ~/.config/monitors.xml

File contents

A configuration file consists of an XML document with the root element <monitors version="2">. In this document multiple configurations are stored as individual <configuration/> elements containing all the details of the monitor setup. The version attribute must be set to "2".

Each configuration corresponds to a specific hardware setup, where a given set of monitors are connected to the computer. There can only be one configuration per hardware setup.

Writing configuration

Monitor configurations are managed by Mutter via the Display panel in Settings, which uses a D-Bus API to communicate with Mutter. Each time a new configuration is applied and accepted, the user level configuration file is replaced with updated content.

Previously defined monitor configurations for hardware state other than the current are left intact.

Configuration policy

The monitor configuration policy determines how Mutter configures monitors. This can mean for example in what order configuration files should be preferred, or whether configuration via Settings (i.e. D-Bus) should be allowed.

The default policy is to prioritize configurations defined in the user level configuration file, and to allow configuring via D-Bus.

Changing the policy is possible by manually adding a <policy/> element inside the <monitors version="2"/> element in the monitors.xml file. Note that there may only be one <policy/> element in each configuration file.

Changing configuration file priority policy

To change the order of configuration file priority, or to disable configuration files completely, add a <stores/> element inside the <policy/> element described above.

In this element, the file policy is defined by a <stores/> element, which lists stores with the order according to prioritization. Each store is specified using a <store/> element with either system or user as the content.

Example of only reading monitor configuration from the system level file:

<monitors version="2">
  <policy>
    <stores>
      <store>system</store>
    </stores>
  </policy>
</monitors>

Example of reversing the priority of monitor configuration:

<monitors version="2">
  <policy>
    <stores>
      <store>user</store>
      <store>system</store>
    </stores>
  </policy>
</monitors>

Changing D-Bus configuration policy

D-Bus configureability can be configured using a <dbus/> element in the <policy/> element. It's content should either be yes or no depending on whether monitor configuration via D-Bus should be enabled or disable.

Example of how to disable monitor configuration via D-Bus:

<monitors version="2">
  <policy>
    <dbus>no</dbus>
  </policy>
</monitors>