The ubuntu-core-kiosk snap provides the foundation for any graphical kiosk implementation. It provides a shell handling multiple displays, touch, mouse and keyboard input, letting you run any application you want, instantly turning it into a kiosk application. Although primarily intended for use on Ubuntu Core it can be used on Classic linux systems and even run as an application within a traditional desktop environment.
There are three snap configuration options:
daemon=[true|false]enables the daemon (defaults to true on Ubuntu Core and false on classic systems)kiosk-config=<contents for ubuntu_core_kiosk.config>kiosk-display=<contents for ubuntu_core_kiosk.display>
This controls the ubuntu-core-kiosk.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-core-kiosk daemonOr set it using
$ snap set ubuntu-core-kiosk daemon=trueThis provides a way to modify the kiosk 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-core-kiosk/current/ubuntu_core_kiosk.config
# DO NOT EDIT THIS FILE BY HAND -- YOUR CHANGES WILL BE OVERWRITTEN
# USE 'snap set ubuntu-core-kiosk kiosk-config=...' INSTEAD
# ** Options supplied through kiosk-config (begin) **
# (none)
# ** Options supplied through kiosk-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|none|software)
cursor=auto
# As kiosk HAS to run mesa-kms we can safely override the probe for KMS everywhere
env-hacks=MIR_MESA_KMS_DISABLE_MODESET_PROBEBy default kiosk-config is unset, but you can, for instance, change the "wallpaper" color as follows:
$ snap set ubuntu-core-kiosk kiosk-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-core-kiosk kiosk-config="
add-wayland-extensions=zwp_pointer_constraints_v1:zwp_relative_pointer_manager_v1
"A full list of the current configuration options supported by ubuntu-core-kiosk can be obtained by --help:
$ ubuntu-core-kiosk --help
usage: /snap/ubuntu-core-kiosk/117/usr/local/bin/ubuntu_core_kiosk [options]
Command-line options (e.g. "--host-socket=/tmp/mir_socket").
Environment variables capitalise long form with prefix "MIR_SERVER_" and "_" in place of "-".
(E.g. "MIR_SERVER_HOST_SOCKET=/tmp/mir_socket")
Config file entries are long form (e.g. "host-socket=/tmp/mir_socket").
The config file (ubuntu_core_kiosk.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/x86_64-linux-gnu/mir/server-platform)
Directory to look for platform
libraries (default: /usr/lib/x86_64-lin
ux-gnu/mir/server-platform)
-i [ --enable-input ] arg (=1) Enable input.
--compositor-report arg (=off) Compositor reporting [{log,lttng,off}]
--connector-report arg (=off) How to handle the Connector report.
[{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}]
--legacy-input-report arg (=off) How to handle the Legacy Input report.
[{log,off}]
--seat-report arg (=off) How to handle to Seat report.
[{log,off}]
--session-mediator-report arg (=off) How to handle the SessionMediator
report. [{log,lttng,off}]
--msg-processor-report arg (=off) How to handle the MessageProcessor
report. [{log,lttng,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
--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
--env-hacks arg Colon separated list of environment
variable settings
--wayland-extensions arg Exhaustive list of all Wayland
extensions to enable.
[wl_shell:xdg_wm_base:zwlr_foreign_topl
evel_manager_v1:zwlr_layer_shell_v1:zwp
_pointer_constraints_v1:zwp_relative_po
inter_manager_v1:zxdg_output_manager_v1
:zxdg_shell_v6]
--add-wayland-extensions arg Additional Wayland extensions to
enable. [zwlr_foreign_toplevel_manager_
v1:zwlr_layer_shell_v1:zwp_pointer_cons
traints_v1:zwp_relative_pointer_manager
_v1]
--drop-wayland-extensions arg Wayland extensions to disable.
[wl_shell:xdg_wm_base:zxdg_output_manag
er_v1:zxdg_shell_v6]
--display-layout arg (=default) Display configuration layout from
`ubuntu_core_kiosk.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
--window-management-trace log trace message
--keymap arg (=gb) keymap <layout>[+<variant>[+<options>]]
, e,g, "gb" or "cz+qwerty" or
"de++compose:caps"
-h [ --help ] this help text
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).
One of the options in kiosk-config is:
--display-layout arg (=default) Display configuration layout from
`ubuntu_core_kiosk.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-core-kiosk and checking for an ubuntu_core_kiosk.display file. For example:
$ cat /var/snap/ubuntu-core-kiosk/current/ubuntu_core_kiosk.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: [email protected]
#
# Uncomment the following to enforce the selected configuration.
# Or amend as desired.
#
# state: enabled # {enabled, disabled}, defaults to enabled
# mode: [email protected] # 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 displayFor an inverted display on this system, you would use:
$ snap set ubuntu-core-kiosk kiosk-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.
The snapcraft documentation describes gadgets snaps in detail. The only additional thing we'll show here is an example showing how to set the above configuration options for ubuntu-core-kiosk:
defaults:
Ip2mw7v1TbELd6IvCG6srr70rWlV7io7:
display-config: |
layouts:
default:
cards:
- card-id: 0
unknown-1:
orientation: inverted
kiosk-config: |
wallpaper-top=0x92006a
wallpaper-bottom=0xdd4814
add-wayland-extensions=zwp_pointer_constraints_v1:zwp_relative_pointer_manager_v1
daemon: trueDevelopers working with Ubuntu Core Kiosk may also find the following useful:
The following tutorials for building kiosk snaps currently refer to mir-kiosk but you can use ubuntu-core-kiosk instead as it is a more flexible replacement.
- Make a secure Ubuntu kiosk
- Make a Wayland-native Kiosk snap
- Make a X11-based Kiosk Snap
- Make a HTML5/Electron-based Kiosk Snap
Similarly, the following article describes some useful debugging techniques that can be applied when using ubuntu-core-kiosk as well as mir-kiosk.