Ubuntu Frame configuration options

This document provides a reference for the configuration options for Ubuntu Frame.

Contents:


Snap configuration options

There are three snap configuration options:

  • daemon=[true|false] enables the daemon (defaults to true on Ubuntu Core and false on classic systems)
  • config=<contents for frame.config>
  • display=<contents for frame.display>

daemon

This controls the ubuntu-frame.daemon process. If daemon=true then the daemon runs and takes control of the display on your computer, otherwise the daemon is disabled.

On a default installation daemon is only set to true on Ubuntu Core systems. But can be set to true either manually or from a gadget snap.

You can see the value of this using the following command:

$ snap get ubuntu-frame daemon

Or set it using

$ snap set ubuntu-frame daemon=true

config

This provides a way to modify the Frame configuration file. Every time the option is set the provided config is merged with the default config and written to the file. The default file looks like this:

$ cat /var/snap/ubuntu-frame/current/frame.config 
# DO NOT EDIT THIS FILE BY HAND -- YOUR CHANGES WILL BE OVERWRITTEN
# USE 'snap set ubuntu-frame config=...' INSTEAD

# ** Options supplied through config (begin) **
# (none)
# ** Options supplied through config (end) **

# Required to run as daemon
console-provider=vt

# Virtual terminal to use for display (0 to use current)
vt=4

# Mouse pointer to use (auto|null|software)
cursor=auto

# As frame HAS to run mesa-kms we can safely override the probe for KMS everywhere
env-hacks=MIR_MESA_KMS_DISABLE_MODESET_PROBE

By default config is unset, but you can, for instance, change the “wallpaper” color as follows:

$ snap set ubuntu-frame config="
wallpaper-top=0x92006a
wallpaper-bottom=0xdd4814
"

Another option that is useful for some applications (such as games) is to enable the Wayland extensions for cursor confinement as follows:

$ snap set ubuntu-frame config="
add-wayland-extensions=zwp_pointer_constraints_v1:zwp_relative_pointer_manager_v1
"

Each “set” command overwrites the previous content, so if you’re combining config options, put them all into the same “set” command:

$ snap set ubuntu-frame config="
wallpaper-top=0x92006a
wallpaper-bottom=0xdd4814
add-wayland-extensions=zwp_pointer_constraints_v1:zwp_relative_pointer_manager_v1
"

A full list of the current configuration options supported by ubuntu-frame can be obtained by --help:

$ ubuntu-frame --help
usage: /snap/ubuntu-frame/3926/usr/local/bin/frame [options]

Command-line options (e.g. "--wayland-host=wayland-0").

Environment variables capitalise long form with prefix "MIR_SERVER_" and "_" in place of "-".
(E.g. "MIR_SERVER_WAYLAND_HOST=wayland-0")

Config file entries are long form (e.g. "wayland-host=wayland-0").
The config file (frame.config) is located via the XDG Base Directory Specification.
($XDG_CONFIG_HOME or $HOME/.config followed by $XDG_CONFIG_DIRS)

user options:
  --arw-file                            Make socket filename globally rw 
                                        (equivalent to chmod a=rw)
  --platform-display-libs arg           Libraries to use for platform output 
                                        support (default: autodetect)
  --platform-rendering-libs arg         Libraries to use for platform rendering
                                        support (default: autodetect)
  --platform-input-lib arg              Library to use for platform input 
                                        support (default: input-stub.so)
  --platform-path arg (=/usr/lib/aarch64-linux-gnu/mir/server-platform)
                                        Directory to look for platform 
                                        libraries (default: /usr/lib/aarch64-li
                                        nux-gnu/mir/server-platform)
  -i [ --enable-input ] arg (=1)        Enable input.
  --compositor-report arg (=off)        Compositor reporting [{log,lttng,off}]
  --display-report arg (=off)           How to handle the Display report. 
                                        [{log,lttng,off}]
  --input-report arg (=off)             How to handle to Input report. 
                                        [{log,lttng,off}]
  --seat-report arg (=off)              How to handle to Seat report. 
                                        [{log,off}]
  --scene-report arg (=off)             How to handle the scene report. 
                                        [{log,lttng,off}]
  --shared-library-prober-report arg (=log)
                                        How to handle the SharedLibraryProber 
                                        report. [{log,lttng,off}]
  --shell-report arg (=off)             How to handle the Shell report. 
                                        [{log,off}]
  --composite-delay arg (=0)            Compositor frame delay in milliseconds 
                                        (how long to wait for new frames from 
                                        clients before compositing). Higher 
                                        values result in lower latency but risk
                                        causing frame skipping. Default: A 
                                        negative value means decide 
                                        automatically.
  --enable-touchspots                   Display visualization of touchspots 
                                        (e.g. for screencasting).
  --cursor arg (=auto)                  Cursor (mouse pointer) to use 
                                        [{auto,null,software}]
  --enable-key-repeat arg (=1)          Enable server generated key repeat
  --idle-timeout arg (=0)               Time (in seconds) Mir will remain idle 
                                        before turning off the display, or 0 to
                                        keep display on forever.
  --on-fatal-error-except               On "fatal error" conditions [e.g. 
                                        drivers behaving in unexpected ways] 
                                        throw an exception (instead of a core 
                                        dump)
  --debug                               Enable extra development debugging. 
                                        This is only interesting for people 
                                        doing Mir server or client development.
  --console-provider arg (=auto)        Console device handling
                                        How Mir handles console-related tasks 
                                        (device handling, VT switching, etc)
                                        Options:
                                        logind: use logind
                                        vt: use the Linux VT subsystem. 
                                        Requires root.
                                        none: support no console-related tasks.
                                        Useful for nested platforms which do 
                                        not need raw device access and which 
                                        don't have a VT concept
                                        auto: detect the appropriate provider.
  --vt arg (=0)                         [requires --console-provider=vt] VT to 
                                        run on or 0 to use current.
  --bypass arg (=0)                     [platform-specific] utilize the bypass 
                                        optimization for fullscreen surfaces.
  --driver-quirks arg                   [platform-specific] Driver quirks to 
                                        apply (may be specified multiple times;
                                        multiple quirks are combined)
  --x11-output arg (=1280x1024)         [mir-on-X specific] Colon separated 
                                        list of WIDTHxHEIGHT sizes for "output"
                                        windows. ^SCALE may also be appended to
                                        any output
  --x11-window-title arg (=Mir on X)    [mir-on-X specific] Title for the 
                                        banner of the generated X11 window
  --env-hacks arg                       Colon separated list of environment 
                                        variable settings
  --wayland-extensions arg              Colon-separated list of Wayland 
                                        extensions to enable. If used, default 
                                        extensions will NOT be enabled unless 
                                        specified. Default extensions:
                                          wl_shell
                                          xdg_wm_base
                                          zwp_text_input_manager_v1
                                          zwp_text_input_manager_v2
                                          zwp_text_input_manager_v3
                                          zxdg_output_manager_v1
                                          zxdg_shell_v6
                                        Additional supported extensions:
                                          zwlr_foreign_toplevel_manager_v1
                                          zwlr_layer_shell_v1
                                          zwlr_screencopy_manager_v1
                                          zwlr_virtual_pointer_manager_v1
                                          zwp_idle_inhibit_manager_v1
                                          zwp_input_method_manager_v2
                                          zwp_pointer_constraints_v1
                                          zwp_relative_pointer_manager_v1
                                          zwp_virtual_keyboard_manager_v1
  --add-wayland-extensions arg          Wayland extensions to enable in 
                                        addition to default extensions. Use 
                                        `all` to enable all supported 
                                        extensions.
  --drop-wayland-extensions arg         Wayland extensions to disable.
  --display-layout arg (=default)       Display configuration layout from 
                                        `frame.display'
                                        (Found in $XDG_CONFIG_HOME or 
                                        $HOME/.config, followed by 
                                        $XDG_CONFIG_DIRS)
  --wallpaper-top arg (=0x7f7f7f)       Colour of wallpaper RGB
  --wallpaper-bottom arg (=0x1f1f1f)    Colour of wallpaper RGB
  --diagnostic-background arg (=0x380c24)
                                        Colour of diagnostic screen background 
                                        RGB
  --diagnostic-text arg (=0xffffff)     Colour of diagnostic screen text RGB
  --diagnostic-path arg                 Path (including filename) of diagnostic
                                        file
  --authorise-without-apparmor arg (=0) Use /proc/<pid>/cmdline if AppArmor is 
                                        unavailable
  --window-management-trace             log trace message
  --keymap arg (=us)                    keymap <layout>[+<variant>[+<options>]]
                                        , e,g, "gb" or "cz+qwerty" or 
                                        "de++compose:caps"
  -h [ --help ]                         this help text

Version 79: All configuration options beginning with --diagnostic are only available from Ubuntu Frame 79 onward. As of the time of writing, this version is still in beta.

You might notice that the options are described as “command-line options”, and they can be supplied that way when running the snap from the command-line (and not as a daemon). That can be a convenient way of testing their effect. (See RUNNING_ON_YOUR_DESKTOP.md for an example).

display

One of the options in config is:

  --display-layout arg (=default)       Display configuration layout from 
                                        `frame.display'
                                        (Found in $XDG_CONFIG_HOME or 
                                        $HOME/.config, followed by 
                                        $XDG_CONFIG_DIRS)

The contents of this file describe the graphics cards and outputs on the system and, as such, vary between systems. You can get a template for your system by running ubuntu-frame and checking for an frame.display file. For example:

$ cat /var/snap/ubuntu-frame/current/frame.display
layouts:
# keys here are layout labels (used for atomically switching between them)
# when enabling displays, surfaces should be matched in reverse recency order

  default:                         # the default layout

    cards:
    # a list of cards (currently matched by card-id)

    - card-id: 0
      unknown-1:
        # This output supports the following modes: 1280x1024@60.0
        #
        # Uncomment the following to enforce the selected configuration.
        # Or amend as desired.
        #
        # state: enabled	# {enabled, disabled}, defaults to enabled
        # mode: 1280x1024@60.0	# Defaults to preferred mode
        # position: [0, 0]	# Defaults to [0, 0]
        # orientation: normal	# {normal, left, right, inverted}, defaults to normal
        # scale: 1
        # group: 0	# Outputs with the same non-zero value are treated as a single display

For an inverted display on this system, you would use:

$ snap set ubuntu-frame display="
layouts:
  default:
    cards:
    - card-id: 0
      unknown-1:
        orientation: inverted
"

It is possible to configure this file with multiple and switch between them with the display-layout option.

Last updated a month ago. Help improve this document in the forum.