weston.ini - configuration file for Weston
- the reference Wayland
obtains configuration from its command line parameters and the
configuration file described here.
uses a configuration file called weston.ini
for its setup.
configuration file is searched for in one of the
following places when the server is started:
$XDG_CONFIG_HOME/weston.ini (if $XDG_CONFIG_HOME is set)
$HOME/.config/weston.ini (if $HOME is set)
weston/weston.ini in each
$XDG_CONFIG_DIR (if $XDG_CONFIG_DIRS is set)
/etc/xdg/weston/weston.ini (if $XDG_CONFIG_DIRS is not set)
<current dir>/weston.ini (if no variables were set)
where environment variable $HOME
is the user's home directory, and
is the user specific configuration directory, and
is a colon ':'
delimited listed of
configuration base directories, such as /etc/xdg-foo:/etc/xdg
file is composed of a number of sections which may be
present in any order, or omitted to use default configuration values. Each
section has the form:
The spaces are significant. Comment lines are ignored:
The section headers are:
core The core modules and options
libinput Input device configuration
shell Desktop customization
launcher Add launcher to the panel
output Output configuration
input-method Onscreen keyboard input
keyboard Keyboard layouts
terminal Terminal application options
xwayland XWayland options
screen-share Screen sharing options
Possible value types are string, signed and unsigned 32-bit integer, and
boolean. Strings must not be quoted, do not support any escape sequences, and
run till the end of the line. Integers can be given in decimal (e.g. 123),
octal (e.g. 0173), and hexadecimal (e.g. 0x7b) form. Boolean values can be
only 'true' or 'false'.
section is used to select the startup compositor modules and
- specifies a shell to load (string). This can be used to
load your own implemented shell or one with Weston as default. Available
shells in the /usr/lib/mips-linux-gnu/weston directory are:
- ask Weston to load the XWayland module (boolean).
- specifies the modules to load (string). Available modules
in the /usr/lib/mips-linux-gnu/weston directory are:
- overrides defaults backend. Available backend modules in
the /usr/lib/mips-linux-gnu/weston directory are:
- Set the approximate length of the repaint window in
milliseconds. The repaint window is used to control and reduce the output
latency for clients. If the window is longer than the output refresh
period, the repaint will be done immediately when the previous repaint
finishes, not processing client requests in between. If the repaint window
is too short, the compositor may miss the target vertical blank,
increasing output latency. The default value is 7 milliseconds. The
allowed range is from -10 to 1000 milliseconds. Using a negative value
will force the compositor to always miss the target vblank.
- sets the GBM format used for the framebuffer for the GBM
backend. Can be xrgb8888, xrgb2101010, rgb565. By
default, xrgb8888 is used.
- sets Weston's idle timeout in seconds. This idle timeout is
the time after which Weston will enter an "inactive" mode and
screen will fade to black. A value of 0 disables the timeout.
Important : This option may also be set via Weston's '-i' command
line option and will take precedence over the current .ini option. This
means that if both weston.ini and command line define this idle-timeout
time, the one specified in the command-line will be used. On the other
hand, if none of these sets the value, default idle timeout will be set to
- require an input device for launch
- sets Weston's pageflip timeout in milliseconds. This sets a
timer to exit gracefully with a log message and an exit code of 1 in case
the DRM driver is non-responsive. Setting it to 0 disables this feature.
section is used to configure input devices when using the
libinput input device backend.
Available configuration are:
- enables tap to click on touchpad devices
section is used to customize the compositor. Some keys may not
be handled by different shell plugins.
The entries that can appear in this section are:
- sets the path for the shell client to run. If not specified
weston-desktop-shell is launched (string).
- sets the path for the background image file (string).
- determines how the background image is drawn (string). Can
be scale, scale-crop or tile (default). Scale means
scaled to fit the output precisely, not preserving aspect ratio.
Scale-crop preserves aspect ratio, scales the background image just big
enough to cover the output, and centers it. The image ends up cropped from
left and right, or top and bottom, if the aspect ratio does not match the
output. Tile repeats the background image to fill the output.
- sets the color of the background (unsigned integer). The
hexadecimal digit pairs are in order alpha, red, green, and blue.
- sets the panel clock format (string). Can be none,
minutes, seconds. By default, minutes format is used.
- sets the color of the panel (unsigned integer). The
hexadecimal digit pairs are in order transparency, red, green, and blue.
0x00ffffff Fully transparent
- sets the position of the panel (string). Can be top,
bottom, left, right, none.
- enables screen locking (boolean).
- sets the effect used for opening new windows (string). Can
be zoom, fade, none. By default, no animation is
- sets the effect used when closing windows (string). Can be
fade, none. By default, the fade animation is used.
- sets the effect used for opening new windows (string). Can
be fade, none. By default, the fade animation is used.
- sets the effect used with the focused and unfocused
windows. Can be dim-layer, none. By default, no animation is
- whether the shell should quit when the Ctrl-Alt-Backspace
key combination is pressed
- sets the modifier key used for common bindings (string),
such as moving surfaces, resizing, rotating, switching, closing and
setting the transparency for windows, controlling the backlight and
zooming the desktop. Possible values: none, ctrl, alt, super
- defines the number of workspaces (unsigned integer). The
user can switch workspaces by using the binding+F1, F2 keys. If this key
is not set, fall back to one workspace.
- sets the cursor theme (string).
- sets the cursor size (unsigned integer).
- sets the path to lock screen icon image (string). (tablet
- sets the path to lock screen background image (string).
(tablet shell only)
- sets the path to home screen background image (string).
(tablet shell only)
There can be multiple launcher sections, one for each launcher.
- sets the path to icon image (string). Svg images are not
- sets the path to the program that is run by clicking on
this launcher (string). It is possible to pass arguments and environment
variables to the program. For example:
path=GDK_BACKEND=wayland gnome-terminal --full-screen
There can be multiple output sections, each corresponding to one output. It is
currently only recognized by the drm and x11 backends.
- sets a name for the output (string). The backend uses the
name to identify the output. All X11 output names start with a letter X.
All Wayland output names start with the letters WL. The available output
names for DRM backend are listed in the weston-launch(1) output.
Examples of usage:
LVDS1 DRM backend, Laptop internal panel no.1
VGA1 DRM backend, VGA connector no.1
X1 X11 backend, X window no.1
WL1 Wayland backend, Wayland window no.1
for more details.
- sets the output mode (string). The mode parameter is
handled differently depending on the backend. On the X11 backend, it just
sets the WIDTHxHEIGHT of the weston window. The DRM backend accepts
WIDTHxHEIGHT Resolution size width and height in pixels
preferred Uses the preferred mode
current Uses the current crt controller mode
off Disables the output
Optionally, a user may specify a modeline, such as:
173.00 1920 2048 2248 2576 1080 1083 1088 1120 -hsync +vsync
It consists of the refresh rate in Hz, horizontal and vertical resolution,
options for horizontal and vertical synchronisation. The program cvt(1)
can provide suitable modeline string.
- The transformation applied to screen output (string). The
transform key can be one of the following 8 strings:
normal Normal output.
90 90 degrees clockwise.
180 Upside down.
270 90 degrees counter clockwise.
flipped Horizontally flipped
flipped-90 Flipped and 90 degrees clockwise
flipped-180 Flipped upside down
flipped-270 Flipped and 90 degrees counter clockwise
- The scaling multiplier applied to the entire output, in
support of high resolution ("HiDPI" or "retina")
displays, that roughly corresponds to the pixel ratio of the display's
physical resolution to the logical resolution. Applications that do not
support high resolution displays typically appear tiny and unreadable.
Weston will scale the output of such applications by this multiplier, to
make them readable. Applications that do support their own output scaling
can draw their content in high resolution, in which case they avoid
compositor scaling. Weston will not scale the output of such applications,
and they are not affected by this multiplier.
An integer, 1 by default, typically configured as 2 or higher when needed,
denoting the scaling multiplier for the output.
- The logical seat name that that this output should be
associated with. If this is set then the seat's input will be confined to
the output that has the seat set on it. The expectation is that this
functionality will be used in a multiheaded environment with a single
compositor for multiple output and input configurations. The default seat
is called "default" and will always be present. This seat can be
constrained like any other.
- sets the path of the on screen keyboard input method
This section contains the following keys:
- sets the keymap rules file (string). Used to map layout and
model to input device.
- sets the keymap model (string). See the Models section in
- sets the comma separated list of keyboard layout codes
(string). See the Layouts section in xkeyboard-config(7).
- sets the comma separated list of keyboard layout variants
(string). The number of variants must be the same as the number of layouts
above. See the Layouts section in xkeyboard-config(7).
- sets the keymap options (string). See the Options section
- sets the rate of repeating keys in characters per second
- sets the delay in milliseconds since key down until
repeating starts (unsigned integer)
- sets the default state of the numlock on weston startup for
the backends which support it.
- Whether to allow the use of Ctrl+Alt+Fn key combinations to
switch away from the compositor's virtual console.
Contains settings for the weston terminal application (weston-terminal). It
allows to customize the font and shell of the command line interface.
- font=DejaVu Sans Mono
- sets the font of the terminal (string). For a good
experience it is recommended to use monospace fonts. In case the font is
not found, the default one is used.
- sets the size of the terminal font (unsigned integer).
- The terminal shell (string). Sets the $TERM variable.
- sets the path to the xserver to run (string).
- command=/usr/bin/weston --backend=rdp-backend.so
- sets the command to start a fullscreen-shell server for
screen sharing (string).