Ubuntu Frame configuration options¶

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

Snap configuration options¶

There are four snap configuration options:

daemon=[true|false] enables the daemon (defaults to true on Ubuntu Core and false on classic systems)
launcher=[true|false] enables a side bar application switcher if your solution calls for that
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

`launcher`¶

Tip

This feature is only available on Intel, AMD and ARM64 systems

Tip

This feature is only available from Frame version 187 onward

This controls whether a side bar application switcher (“Launcher” from Unity Desktop design) is displayed. If your solution requires multiple applications that the user needs to be able to switch between, this will enable that - displaying a side bar with clickable application icons.

# Until https://github.com/canonical/snapd/pull/14331 gets released
$ snap refresh snapd --channel edge/ubuntu-core-desktop

# Give Frame access to application metadata and icons
$ snap connect ubuntu-frame:desktop-launch

# Enable the launcher
$ snap set ubuntu-frame launcher=true

Make sure that the applications you want to run are annotated with metadata and icons appropriately, see Snapcraft’s Configure package information documentation to get your app icons to display.

Tip

Since version 211, you can use Mir or UbuntuFrame in OnlyShowIn= and NotShowIn= to control visibility of the icon on different environments. This is useful to hide the daemon app in snaps that are also useful outside of the Frame ecosystem.

`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, see Options reference below.

`display`¶

This option provides a way to modify the display configuration for Ubuntu Frame, which is used to set the properties of the outputs and the placement of applications.

The current display configuration can be read using snap get ubuntu-frame display. If no display configuration was previously set an automatically generated configuration is used. This may be a useful starting point for writing new configuration.

If invalid configuration is provided Ubuntu Frame will fail to start with an error message.

If you need to reset this configuration (because your hardware changes, or you make a mistake) then simply unset it and restart Ubuntu Frame:

$ snap unset ubuntu-frame display
$ snap restart ubuntu-frame
$ snap get ubuntu-frame display
...

Layouts¶

Display configuration is made up of one of more named layout. Each layout contains their own set of configuration that is applied when that layout is active. The first layout is used by default and can be changed using the display-layout configuration option (see below).

A system could be configured to show different application during the day and night using two layouts:

layouts:
  day:
    cards:
    - card-id: 0
      eDP-1:
        # ...
      HDMI-A-1:
        # ...

  night:
    cards:
    - card-id: 0
      eDP-1:
        # ...
      HDMI-A-1:
        # ...

Output Configuration¶

Each output can be configured by setting properties keyed by the card ID and output name. All properties are optional. Each output is configured by name and index of the graphics card providing it.

Configuration for the eDP-1 output on the first graphics card is specified using:

layouts:
  default:
    cards:
    - card-id: 0
      eDP-1:
        # Configuration options

The output resolution, frame rate, orientation and pixel scaling can be overridden from the default values:

layouts:
  default:
    cards:
    - card-id: 0
      eDP-1:
        mode: 1920x1080@60.0 # Resolution and frame rate, defaults to preferred mode.
        orientation: normal  # {normal, left, right, inverted}, defaults to normal.
        scale: 1             # Pixel scaling, defaults to 1.

Setting an output position changes the default behavior of applications showing on all outputs to instead show different content on each output:

layouts:
  default:
    cards:
    - card-id: 0
      eDP-1:
        position: [0, 0] # Note this is the default position and could be omitted.
      HDMI-A-1:
        position: [1920, 0] # Placed to the right of eDP-1

A non-zero group value is used to join outputs together so applications can span them:

layouts:
  default:
    cards:
    - card-id: 0
      eDP-1:
        position: [0, 0]
        group: 1
      HDMI-A-1:
        position: [1920, 0]
        group: 1  # Joins eDP-1 to make a 3840x1080 display.

Applications can be assigned to show on a particular output using either the snap name or surface title:

layouts:
  default:
    cards:
    - card-id: 0
      eDP-1:
        surface-title: Some App
      HDMI-A-1:
        snap-name: wpe-webkit-mir-kiosk

Applications can also be positioned in any location by adding them to applications. Each application is then provided with a position and size:

layouts:
  default:
    cards:
    - card-id: 0
      eDP-1:
        mode: 1920x1080@60.0

    applications:
    - surface-title: Some App
      # Use left half of output
      position: [0, 0]
      size: [960, 1080]
    - snap-name: wpe-webkit-mir-kiosk
      # Use bottom right quarter of output
      position: [960, 540]
      size: [960, 540]

If the output should not be used by frame it can be disabled by setting state to either enabled or disabled:

layouts:
  default:
    cards:
    - card-id: 0
      eDP-1:
        state: disabled  # Output not used
      HDMI-A-1:
        # Output in use, state defaults to enabled

`display-layout`¶

Controls the layout in use.

Change the layout to night:

snap set ubuntu-frame display-layout=night

Get the current layout:

$ snap get ubuntu-frame display-layout
night

Options reference¶

`add-wayland-extensions`¶

Colon separated list of Wayland extensions to enable in addition to default extensions. Use all to enable all supported extensions.

`arw-file`¶

Make server Wayland socket readable and writeable by all users. For debugging purposes only.

`authorise-without-apparmor`¶

Use /proc/<pid>/cmdline if AppArmor is unavailable

Defaults to 0.

`composite-delay`¶

Number of milliseconds to wait for new frames from clients before compositing. Higher values result in lower latency but risk causing frame skipping.

Defaults to 0.

`compositor-report`¶

Configure compositor reporting. [{off,log,lttng}]

Defaults to off.

`console-provider`¶

Method used to handle console-related tasks (device handling, VT switching, etc):

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.

Defaults to auto.

`cursor`¶

Cursor type:

auto: use hardware if available, or fallback to software.
null: cursor disabled.
software: always use software cursor.

Defaults to auto.

`debug`¶

Enable debugging information. Useful when developing Mir servers.

`diagnostic-background`¶

Colour of diagnostic screen background RGB

Defaults to 0x380c24.

`diagnostic-delay`¶

Delay time (in seconds) before displaying diagnostic screen

Defaults to 0.

`diagnostic-path`¶

Path (including filename) of diagnostic file

`diagnostic-text`¶

Colour of diagnostic screen text RGB

Defaults to 0xffffff.

`display-layout`¶

Display configuration layout from frame.display (Found in $XDG_CONFIG_HOME or $HOME/.config, followed by $XDG_CONFIG_DIRS)

Defaults to default.

`display-report`¶

Configure display reporting. [{off,log,lttng}]

Defaults to off.

`drop-wayland-extensions`¶

Colon separated list of Wayland extensions to disable.

`enable-input`¶

Enable input.

Defaults to 1.

`enable-key-repeat`¶

Enable server generated key repeat.

Defaults to 1.

`enable-touchspots`¶

Enable visual feedback of touch events. Useful for screencasting.

`env-hacks`¶

Colon separated list of environment variable settings.

`help`¶

Show command line help.

`help-markdown`¶

Show command line options in markdown format suitable for including into a document.

`idle-timeout`¶

Number of seconds Mir will remain idle before turning off the display when the session is not locked, or 0 to keep display on forever.

Defaults to 0.

`idle-timeout-when-locked`¶

Number of seconds Mir will remain idle before turning off the display when the session is locked, or 0 to keep the display on forever.

Defaults to 0.

`input-report`¶

Configure input reporting. [{off,log,lttng}]

Defaults to off.

`key-repeat-delay`¶

Number of milliseconds to hold down a key before generating repeat events.

Defaults to 600.

`key-repeat-rate`¶

Number of milliseconds between generated key repeat events.

Defaults to 25.

`keymap`¶

Keymap to use. Specified in the form <layout>[+<variant>[+<options>]], e.g. gb or cz+qwerty or de++compose:caps

Defaults to us.

`mouse-cursor-acceleration`¶

Acceleration profile for mice and trackballs:

none: no acceleration.
adaptive: cursor is accelerated.

`mouse-cursor-acceleration-bias`¶

Pointer acceleration speed of mice. Must be within range of [-1.0, 1.0].

`mouse-handedness`¶

Mouse laterality:

right: left button is primary.
left: right button is primary.

`mouse-horizontal-scroll-speed-override`¶

Mouse horizontal scroll speed scaling factor. Use negative values for natural scrolling.

`mouse-scroll-speed`¶

Mouse scroll speed scaling factor. Use negative values for natural scrolling.

`mouse-vertical-scroll-speed-override`¶

Mouse vertical scroll speed scaling factor. Use negative values for natural scrolling.

`on-fatal-error-except`¶

Throw an exception when a fatal error condition occurs. This replaces the default behaviour of dumping core and can make it easier to diagnose issues.

`platform-display-libs`¶

Comma separated list of libraries to use for platform output support, e.g. mir:x11,mir:wayland. If not provided the libraries are autodetected.

`platform-input-lib`¶

Library to use for platform input support, e.g. mir:stub-input. If not provided this is autodetected.

`platform-path`¶

Directory to look for platform libraries.

Defaults to /usr/lib/x86_64-linux-gnu/mir/server-platform.

`platform-rendering-libs`¶

Comma separated list of libraries to use for platform rendering support, e.g. mir:egl-generic. If not provided the libraries are autodetected.

`scene-report`¶

Configure scene reporting. [{off,log,lttng}]

Defaults to off.

`seat-report`¶

Configure seat reporting. [{off,log}]

Defaults to off.

`shared-library-prober-report`¶

Configure shared library prober reporting. [{log,off,lttng}]

Defaults to log.

`shell-report`¶

Configure shell reporting. [{off,log}]

Defaults to off.

`touchpad-click-mode`¶

Click mode for touchpad. Left, middle and right button click events generated when:

none: no events generated.
area: single finger tap on left, middle or right area.
clickfinger: one, two or three fingers present when touchpad pushed down.

`touchpad-cursor-acceleration`¶

Acceleration profile for touchpads:

none: no acceleration.
adaptive: cursor accelerates.

`touchpad-cursor-acceleration-bias`¶

Pointer acceleration speed scaling factor for touchpads. Must be within range of [-1.0, 1.0].

`touchpad-disable-while-typing`¶

Disable touchpad while typing on keyboard. [true, false]

`touchpad-disable-with-external-mouse`¶

Disable touchpad if an external pointer device is plugged in. [true, false]

`touchpad-horizontal-scroll-speed-override`¶

Touchpad horizontal scroll scaling factor. Use negative values for natural scrolling.

`touchpad-middle-mouse-button-emulation`¶

Generate middle mouse button click from a simultaneous left and right button click.

`touchpad-scroll-mode`¶

Scroll mode for touchpads. Generates scroll events when:

edge: single finger moves on right or bottom edges of touchpad.
two-finger: two fingers move horizontally or vertically.
button-down: mouse button held down.

`touchpad-scroll-speed`¶

Touchpad scroll scaling factor. Use negative values for natural scrolling.

`touchpad-tap-to-click`¶

Enable or disable tap-to-click on this device. If enabled 1, 2, and 3 finger taps are mapped to left, right, middle click events. [true, false]

`touchpad-vertical-scroll-speed-override`¶

Touchpad vertical scroll scaling factor. Use negative values for natural scrolling.

`version`¶

Display Mir version and exit.

`vt`¶

VT to run on or 0 to use current. Only used when --console-provider=vt.

Defaults to 0.

`vt-switching`¶

Enable VT switching on Ctrl+Alt+F*. Only used when --console-provider=vt|logind.

Defaults to 1.

`wallpaper`¶

Specifies whether or not the wallpaper is enabled

Defaults to 1.

`wallpaper-bottom`¶

Colour of wallpaper RGB

Defaults to 0x1f1f1f.

`wallpaper-top`¶

Colour of wallpaper RGB

Defaults to 0x7f7f7f.

`wayland-extensions`¶

Colon separated list of Wayland extensions to enable. If used, default extensions will NOT be enabled unless specified. Default extensions:

mir_shell_v1
wl_shell
wp_fractional_scale_manager_v1
xdg_activation_v1
xdg_wm_base
zwp_text_input_manager_v1
zwp_text_input_manager_v2
zwp_text_input_manager_v3
zxdg_decoration_manager_v1
zxdg_output_manager_v1
zxdg_shell_v6 Additional supported extensions:
ext_data_control_manager_v1
ext_foreign_toplevel_list_v1
ext_image_copy_capture_manager_v1
ext_input_trigger_action_manager_v1
ext_input_trigger_registration_manager_v1
ext_output_image_capture_source_manager_v1
ext_session_lock_manager_v1
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_input_method_v1
zwp_input_panel_v1
zwp_pointer_constraints_v1
zwp_primary_selection_device_manager_v1
zwp_relative_pointer_manager_v1
zwp_virtual_keyboard_manager_v1

`window-management-trace`¶

Log trace message

Options for mir:atomic-kms platform¶

`bypass`¶

Enable bypass optimization for fullscreen surfaces.

Defaults to 0.

`driver-quirks`¶

Driver quirks to apply. May be specified multiple times; multiple quirks are combined.

Options for mir:gbm-kms platform¶

`bypass`¶

Enable bypass optimization for fullscreen surfaces.

Defaults to 0.

`driver-quirks`¶

Driver quirks to apply. May be specified multiple times; multiple quirks are combined.

Options for mir:x11 platform¶

`x11-output`¶

Colon separated list of outputs to use. Dimensions are in the form WIDTHxHEIGHT[^SCALE], e.g. 1920x1080:3840x2160^2.

Defaults to 1280x1024.

`x11-window-title`¶

Title of the window containing the Mir output.

Defaults to Mir on X.

You might notice that the options are described as “command-line options”, and they also 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 Run Ubuntu Frame in your desktop environment for an example).

Ubuntu Frame configuration options¶

Snap configuration options¶

daemon¶

launcher¶

config¶

display¶

Layouts¶

Output Configuration¶

display-layout¶

Options reference¶

add-wayland-extensions¶

arw-file¶

authorise-without-apparmor¶

composite-delay¶

compositor-report¶

console-provider¶

cursor¶

debug¶

diagnostic-background¶

diagnostic-delay¶

diagnostic-path¶

diagnostic-text¶

display-layout¶

display-report¶

drop-wayland-extensions¶

enable-input¶

enable-key-repeat¶

enable-touchspots¶

env-hacks¶

help¶

help-markdown¶

idle-timeout¶

idle-timeout-when-locked¶

input-report¶

key-repeat-delay¶

key-repeat-rate¶

keymap¶

mouse-cursor-acceleration¶

mouse-cursor-acceleration-bias¶

mouse-handedness¶

mouse-horizontal-scroll-speed-override¶

mouse-scroll-speed¶

mouse-vertical-scroll-speed-override¶

on-fatal-error-except¶

platform-display-libs¶

platform-input-lib¶

platform-path¶

platform-rendering-libs¶

scene-report¶

seat-report¶

shared-library-prober-report¶

shell-report¶

touchpad-click-mode¶

touchpad-cursor-acceleration¶

touchpad-cursor-acceleration-bias¶

touchpad-disable-while-typing¶

touchpad-disable-with-external-mouse¶

touchpad-horizontal-scroll-speed-override¶

touchpad-middle-mouse-button-emulation¶

touchpad-scroll-mode¶

touchpad-scroll-speed¶

touchpad-tap-to-click¶

touchpad-vertical-scroll-speed-override¶

version¶

vt¶

vt-switching¶

wallpaper¶

wallpaper-bottom¶

wallpaper-top¶

wayland-extensions¶

window-management-trace¶

Options for mir:atomic-kms platform¶

bypass¶

driver-quirks¶

Options for mir:gbm-kms platform¶

bypass¶

driver-quirks¶

Options for mir:x11 platform¶

x11-output¶

x11-window-title¶

`daemon`¶

`launcher`¶

`config`¶

`display`¶

`display-layout`¶

`add-wayland-extensions`¶

`arw-file`¶

`authorise-without-apparmor`¶

`composite-delay`¶

`compositor-report`¶

`console-provider`¶

`cursor`¶

`debug`¶

`diagnostic-background`¶

`diagnostic-delay`¶

`diagnostic-path`¶

`diagnostic-text`¶

`display-layout`¶

`display-report`¶

`drop-wayland-extensions`¶

`enable-input`¶

`enable-key-repeat`¶

`enable-touchspots`¶

`env-hacks`¶

`help`¶

`help-markdown`¶

`idle-timeout`¶

`idle-timeout-when-locked`¶

`input-report`¶

`key-repeat-delay`¶

`key-repeat-rate`¶

`keymap`¶

`mouse-cursor-acceleration`¶

`mouse-cursor-acceleration-bias`¶

`mouse-handedness`¶

`mouse-horizontal-scroll-speed-override`¶

`mouse-scroll-speed`¶

`mouse-vertical-scroll-speed-override`¶

`on-fatal-error-except`¶

`platform-display-libs`¶

`platform-input-lib`¶

`platform-path`¶

`platform-rendering-libs`¶

`scene-report`¶

`seat-report`¶

`shared-library-prober-report`¶

`shell-report`¶

`touchpad-click-mode`¶

`touchpad-cursor-acceleration`¶

`touchpad-cursor-acceleration-bias`¶

`touchpad-disable-while-typing`¶

`touchpad-disable-with-external-mouse`¶

`touchpad-horizontal-scroll-speed-override`¶

`touchpad-middle-mouse-button-emulation`¶

`touchpad-scroll-mode`¶

`touchpad-scroll-speed`¶

`touchpad-tap-to-click`¶

`touchpad-vertical-scroll-speed-override`¶

`version`¶

`vt`¶

`vt-switching`¶

`wallpaper`¶

`wallpaper-bottom`¶

`wallpaper-top`¶

`wayland-extensions`¶

`window-management-trace`¶

`bypass`¶

`driver-quirks`¶

`bypass`¶

`driver-quirks`¶

`x11-output`¶

`x11-window-title`¶