1weston.ini(5) File Formats Manual weston.ini(5)
2
6 weston.ini - configuration file for Weston - the reference Wayland com‐
7 positor
8
10 Weston obtains configuration from its command line parameters and the
11 configuration file described here.
12
14 Weston uses a configuration file called weston.ini for its setup. The
15 weston.ini configuration file is searched for in one of the following
16 places when the server is started:
17 $XDG_CONFIG_HOME/weston.ini (if $XDG_CONFIG_HOME is set)
19 $HOME/.config/weston.ini (if $HOME is set)
20 weston/weston.ini in each
21 $XDG_CONFIG_DIR (if $XDG_CONFIG_DIRS is set)
22 /etc/xdg/weston/weston.ini (if $XDG_CONFIG_DIRS is not set)
23 where environment variable $HOME is the user's home directory, and
25 $XDG_CONFIG_HOME is the user specific configuration directory, and
26 $XDG_CONFIG_DIRS is a colon ':' delimited listed of configuration base
27 directories, such as /etc/xdg-foo:/etc/xdg.
28 The weston.ini file is composed of a number of sections which may be
30 present in any order, or omitted to use default configuration values.
31 Each section has the form:
32 [SectionHeader]
34 Key1=Value1
35 Key2=Value2
36 ...
37 The spaces are significant. Comment lines are ignored:
39 #comment
41 The section headers are:
43 core The core modules and options
45 libinput Input device configuration
46 shell Desktop customization
47 launcher Add launcher to the panel
48 output Output configuration
49 input-method Onscreen keyboard input
50 keyboard Keyboard layouts
51 terminal Terminal application options
52 xwayland XWayland options
53 screen-share Screen sharing options
54 autolaunch Autolaunch options
55 Possible value types are string, signed and unsigned 32-bit integer,
57 and boolean. Strings must not be quoted, do not support any escape se‐
58 quences, and run till the end of the line. Integers can be given in
59 decimal (e.g. 123), octal (e.g. 0173), and hexadecimal (e.g. 0x7b)
60 form. Boolean values can be only 'true' or 'false'.
61
63 The core section is used to select the startup compositor modules and
64 general options.
65 shell=desktop
67 specifies a shell to load (string). This can be used to load
68 your own implemented shell or one with Weston as default. Avail‐
69 able shells in the /usr/lib64/weston directory are:
70 desktop
72 fullscreen
73 ivi
74 kiosk
75 xwayland=true
77 ask Weston to load the XWayland module (boolean).
78 modules=cms-colord.so,screen-share.so
80 specifies the modules to load (string). Available modules in the
81 /usr/lib64/weston directory are:
82 cms-colord.so
84 screen-share.so
85 backend=headless
87 overrides defaults backend. Available backends are:
88 drm
90 headless
91 rdp
92 pipewire
93 vnc
94 wayland
95 x11
96 repaint-window=N
98 Set the approximate length of the repaint window in millisec‐
99 onds. The repaint window is used to control and reduce the out‐
100 put latency for clients. If the window is longer than the output
101 refresh period, the repaint will be done immediately when the
102 previous repaint finishes, not processing client requests in be‐
103 tween. If the repaint window is too short, the compositor may
104 miss the target vertical blank, increasing output latency. The
105 default value is 7 milliseconds. The allowed range is from -10
106 to 1000 milliseconds. Using a negative value will force the com‐
107 positor to always miss the target vblank.
108 idle-time=seconds
110 sets Weston's idle timeout in seconds. This idle timeout is the
111 time after which Weston will enter an "inactive" mode and screen
112 will fade to black. A value of 0 disables the timeout.
113 Important : This option may also be set via Weston's '-i' com‐
115 mand line option and will take precedence over the current .ini
116 option. This means that if both weston.ini and command line de‐
117 fine this idle-timeout time, the one specified in the command-
118 line will be used. On the other hand, if none of these sets the
119 value, default idle timeout will be set to 300 seconds.
120 require-input=true
122 require an input device for launch
123 wait-for-debugger=true
125 Raises SIGSTOP before initializing the compositor. This allows
126 the user to attach with a debugger and continue execution by
127 sending SIGCONT. This is useful for debugging a crash on start-
128 up when it would be inconvenient to launch weston directly from
129 a debugger. Boolean, defaults to false. There is also a command
130 line option to do the same.
131 remoting=remoting-plugin.so
133 specifies a plugin for remote output to load (string). This can
134 be used to load your own implemented remoting plugin or one with
135 Weston as default. Available remoting plugins in the __libwe‐
136 ston_modules_dir__ directory are:
137 remoting-plugin.so
139 renderer=auto
141 Selects a renderer to use for internal composition when re‐
142 quired, or auto to select the most appropriate renderer. Avail‐
143 able renderers are:
144 auto
146 gl
147 noop
148 pixman
149 Not all backends support all renderers.
150 use-pixman=true
152 Deprecated in favour of the renderer= option. Enables pixman-
153 based rendering for all outputs on backends that support it.
154 Boolean, defaults to false. There is also a command line option
155 to do the same.
156 color-management=true
158 Enables color management and requires using GL-renderer. Bool‐
159 ean, defaults to false.
160 TENTATIVE, EXPERIMENTAL, WORK IN PROGRESS: Color management en‐
162 ables the use of ICC files to describe monitor color behavior,
163 Wayland protocol extensions for clients to describe their color
164 spaces and perform monitor profiling, and tone mapping required
165 to enable HDR video modes. This extended functionality comes at
166 the cost of heavier image processing and sometimes a loss of
167 some hardware off-loading features like composite-bypass.
168 output-decorations=true
170 For headless-backend with GL-renderer only: draws output window
171 decorations, similar to what wayland-backend does for floating
172 output windows. Boolean, defaults to false. These decorations
173 cannot normally be screenshot. This option is useful for the We‐
174 ston test suite only.
175
177 The libinput section is used to configure input devices when using the
178 libinput input device backend. The defaults are determined by libinput
179 and vary according to what is most sensible for any given device.
180 Available configuration are:
182 enable-tap=false
184 Enables tap to click on touchpad devices.
185 tap-and-drag=false
187 For touchpad devices with enable-tap enabled. If the user taps,
188 then taps a second time, this time holding, the virtual mouse
189 button stays down for as long as the user keeps their finger on
190 the touchpad, allowing the user to click and drag with taps
191 alone.
192 tap-and-drag-lock=false
194 For touchpad devices with enable-tap and tap-and-drag enabled.
195 In the middle of a tap-and-drag, if the user releases the touch‐
196 pad for less than a certain number of milliseconds, then touches
197 it again, the virtual mouse button will remain pressed and the
198 drag can continue.
199 disable-while-typing=true
201 For devices that may be accidentally triggered while typing on
202 the keyboard, causing a disruption of the typing. Disables them
203 while the keyboard is in use.
204 middle-button-emulation=false
206 For pointer devices with left and right buttons, but no middle
207 button. When enabled, a middle button event is emitted when the
208 left and right buttons are pressed simultaneously.
209 left-handed=false
211 Configures the device for use by left-handed people. Exactly
212 what this option does depends on the device. For pointers with
213 left and right buttons, the buttons are swapped. On tablets, the
214 tablet is logically turned upside down, because it will be phys‐
215 ically turned upside down.
216 rotation=n
218 Changes the direction of the logical north, rotating it n de‐
219 grees clockwise away from the default orientation, where n is a
220 whole number between 0 and 359 inclusive. Needed for trackballs,
221 mainly. Allows the user to orient the trackball sideways, for
222 example.
223 accel-profile={flat,adaptive}
225 Set the pointer acceleration profile. The pointer's screen speed
226 is proportional to the physical speed with a certain constant of
227 proportionality. Call that constant alpha. flat keeps alpha
228 fixed. See accel-speed. adaptive causes alpha to increase with
229 physical speed, giving the user more control when the speed is
230 slow, and more reach when the speed is high. adaptive is the
231 default.
232 accel-speed=v
234 If accel-profile is set to flat, it simply sets the value of al‐
235 pha. If accel-profile is set to adaptive, the effect is more
236 complicated, but generally speaking, it will change the
237 pointer's speed. v is normalised and must lie in the range [-1,
238 1]. The exact mapping between v and alpha is hardware-dependent,
239 but higher values cause higher cursor speeds.
240 natural-scroll=false
242 Enables natural scrolling, mimicking the behaviour of touch‐
243 screen scrolling. That is, if the wheel, finger, or fingers are
244 moved down, the surface is scrolled up instead of down, as if
245 the finger, or fingers were in contact with the surface being
246 scrolled.
247 scroll-method={two-finger,edge,button,none}
249 Sets the scroll method. two-finger scrolls with two fingers on a
250 touchpad. edge scrolls with one finger on the right edge of a
251 touchpad. button scrolls when the pointer is moved while a cer‐
252 tain button is pressed. See scroll-button. none disables
253 scrolling altogether.
254 scroll-button={BTN_LEFT,BTN_RIGHT,BTN_MIDDLE,...}
256 For devices with scroll-method set to button. Specifies the but‐
257 ton that will trigger scrolling. See /usr/include/linux/input-
258 event-codes.h for the complete list of possible values.
259 touchscreen_calibrator=true
261 Advertise the touchscreen calibrator interface to all clients.
262 This is a potential denial-of-service attack vector, so it
263 should only be enabled on trusted userspace. Boolean, defaults
264 to false.
265 The interface is required for running touchscreen calibrator ap‐
267 plications. It provides the application raw touch events, by‐
268 passing the normal touch handling. It also allows the applica‐
269 tion to upload a new calibration into the compositor.
270 Even though this option is listed in the libinput section, it
272 does affect all Weston configurations regardless of the used
273 backend. If the backend does not use libinput, the interface can
274 still be advertised, but it will not list any devices.
275 calibration_helper=/bin/echo
277 An optional calibration helper program to permanently save a new
278 touchscreen calibration. String, defaults to unset.
279 The given program will be executed with seven arguments when a
281 calibrator application requests the server to take a new cali‐
282 bration matrix into use. The program is executed synchronously
283 and will therefore block Weston for its duration. If the program
284 exit status is non-zero, Weston will not apply the new calibra‐
285 tion. If the helper is unset or the program exit status is zero,
286 Weston will use the new calibration immediately.
287 The program is invoked as:
289 calibration_helper syspath m1 m2 m3 m4 m5 m6
291 where syspath is the udev sys path for the device and m1
293 through m6 are the calibration matrix elements in libinput's LI‐
294 BINPUT_CALIBRATION_MATRIX udev property format. The sys path is
295 an absolute path and starts with the sys mount point.
296
298 The shell section is used to customize the compositor. Some keys may
299 not be handled by different shell plugins.
300 The entries that can appear in this section are:
302 client=/usr/libexec/weston-desktop-shell
304 specifies the path for the shell client to run. It is possible
305 to pass arguments and environment variables to the program, for
306 example, 'ENVFOO=bar ENVBAR=baz /path/to/program --arg another‐
307 arg', with entries that are space-separated but with no support
308 for quoting. If no client was specified then weston-desktop-
309 shell is launched (string).
310 background-image=file
312 sets the path for the background image file (string).
313 background-type=tile
315 determines how the background image is drawn (string). Can be
316 centered, scale, scale-crop or tile (default). Centered shows
317 the image once centered. If the image is smaller than the out‐
318 put, the rest of the surface will be in background color. If the
319 image size does fit the output it will be cropped left and
320 right, or top and bottom. Scale means scaled to fit the output
321 precisely, not preserving aspect ratio. Scale-crop preserves
322 aspect ratio, scales the background image just big enough to
323 cover the output, and centers it. The image ends up cropped from
324 left and right, or top and bottom, if the aspect ratio does not
325 match the output. Tile repeats the background image to fill the
326 output.
327 background-color=0xAARRGGBB
329 sets the color of the background (unsigned integer). The hexa‐
330 decimal digit pairs are in order alpha, red, green, and blue.
331 clock-format=format
333 sets the panel clock format (string). Can be none, minutes, sec‐
334 onds, minutes-24h, seconds-24h. By default, minutes format is
335 used.
336 panel-color=0xAARRGGBB
338 sets the color of the panel (unsigned integer). The hexadecimal
339 digit pairs are in order transparency, red, green, and blue. Ex‐
340 amples:
341 0xffff0000 Red
343 0xff00ff00 Green
344 0xff0000ff Blue
345 0x00ffffff Fully transparent
346 panel-position=top
348 sets the position of the panel (string). Can be top, bottom,
349 left, right, none.
350 locking=true
352 enables screen locking (boolean).
353 animation=zoom
355 sets the effect used for opening new windows (string). Can be
356 zoom, fade, none. By default, no animation is used.
357 close-animation=fade
359 sets the effect used when closing windows (string). Can be fade,
360 none. By default, the fade animation is used.
361 startup-animation=fade
363 sets the effect used by desktop-shell when starting up (string).
364 Can be fade, none. By default, the fade animation is used.
365 focus-animation=dim-layer
367 sets the effect used with the focused and unfocused windows. Can
368 be dim-layer, none. By default, no animation is used.
369 allow-zap=true
371 whether the shell should quit when the Ctrl-Alt-Backspace key
372 combination is pressed
373 binding-modifier=ctrl
375 sets the modifier key used for common bindings (string), such as
376 moving surfaces, resizing, rotating, switching, closing and set‐
377 ting the transparency for windows, controlling the backlight and
378 zooming the desktop. See weston-bindings(7). Possible values:
379 none, ctrl, alt, super (default)
380 cursor-theme=theme
382 sets the cursor theme (string).
383 cursor-size=24
385 sets the cursor size (unsigned integer).
386
388 There can be multiple launcher sections, one for each launcher.
389 icon=icon
391 sets the path to icon image (string). Svg images are not cur‐
392 rently supported.
393 displayname=displayname
395 sets the display name of the launcher that appears in the
396 tooltip.
397 path=program
399 sets the path to the program that is run by clicking on this
400 launcher (string). It is possible to pass arguments and envi‐
401 ronment variables to the program. For example:
402 path=GDK_BACKEND=wayland gnome-terminal --full-screen
404
406 There can be multiple output sections, each corresponding to one out‐
407 put. It is currently only recognized by the drm and x11 backends.
408 name=name
410 sets a name for the output (string). The backend uses the name
411 to identify the output. All X11 output names start with a letter
412 X. All Wayland output names start with the letters WL. Exam‐
413 ples of usage:
414 LVDS1 DRM backend, Laptop internal panel no.1
416 VGA1 DRM backend, VGA connector no.1
417 X1 X11 backend, X window no.1
418 WL1 Wayland backend, Wayland window no.1
419 See weston-drm(7) for more details.
421 mode=mode
423 sets the output mode (string). The mode parameter is handled
424 differently depending on the backend. On the X11 backend, it
425 just sets the WIDTHxHEIGHT of the weston window. The DRM back‐
426 end accepts different modes, along with an option of a modeline
427 string.
428 See weston-drm(7) for examples of modes-formats supported by DRM
430 backend.
431 transform=normal
433 How you have rotated your monitor from its normal orientation
434 (string). The transform key can be one of the following 8
435 strings:
436 normal Normal output.
438 rotate-90 90 degrees clockwise.
439 rotate-180 Upside down.
440 rotate-270 90 degrees counter clockwise.
441 flipped Horizontally flipped
442 flipped-rotate-90 Flipped and 90 degrees clockwise
443 flipped-rotate-180 Flipped and upside down
444 flipped-rotate-270 Flipped and 90 degrees counter clockwise
445 scale=factor
447 The scaling multiplier applied to the entire output, in support
448 of high resolution ("HiDPI" or "retina") displays, that roughly
449 corresponds to the pixel ratio of the display's physical resolu‐
450 tion to the logical resolution. Applications that do not sup‐
451 port high resolution displays typically appear tiny and unread‐
452 able. Weston will scale the output of such applications by this
453 multiplier, to make them readable. Applications that do support
454 their own output scaling can draw their content in high resolu‐
455 tion, in which case they avoid compositor scaling. Weston will
456 not scale the output of such applications, and they are not af‐
457 fected by this multiplier.
458 An integer, 1 by default, typically configured as 2 or higher
460 when needed, denoting the scaling multiplier for the output.
461 icc_profile=file
463 If option color-management is true, load the given ICC file as
464 the output color profile. This works only on DRM, headless, way‐
465 land, and x11 backends, and for remoting and pipewire outputs.
466 seat=name
468 The logical seat name that this output should be associated
469 with. If this is set then the seat's input will be confined to
470 the output that has the seat set on it. The expectation is that
471 this functionality will be used in a multiheaded environment
472 with a single compositor for multiple output and input configu‐
473 rations. The default seat is called "default" and will always be
474 present. This seat can be constrained like any other.
475 allow_hdcp=true
477 Allows HDCP support for this output. If set to true, HDCP can be
478 tried for the content-protection, provided by the backends, on
479 this output. By default, HDCP support is always allowed for an
480 output. The content-protection can actually be realized, only if
481 the hardware (source and sink) support HDCP, and the backend has
482 the implementation of content-protection protocol. Currently,
483 HDCP is supported by drm-backend.
484 content-type=content_type
486 The type of the content being primarily displayed to this out‐
487 put. Can be "no data" (default), "graphics", "photo", "cinema"
488 or "game".
489 app-ids=app-id[,app_id]*
491 A comma separated list of the IDs of applications to place on
492 this output. These IDs should match the application IDs as set
493 with the xdg_shell.set_app_id request. Currently, this option is
494 supported by kiosk-shell.
495 eotf-mode=sdr
497 Sets the EOTF mode on the output. This is used for choosing be‐
498 tween standard dynamic range (SDR) mode and the various high dy‐
499 namic range (HDR) modes. The display driver, the graphics card,
500 and the video sink (monitor) need to support the chosen mode,
501 otherwise the result is undefined. The mode can be one of the
502 following strings:
503 sdr traditional gamma, SDR
505 hdr-gamma traditional gamma, HDR
506 st2084 SMPTE ST 2084, a.k.a Perceptual Quantizer
507 hlg Hybrid Log-Gamma (ITU-R BT.2100)
508 Defaults to sdr. Non-SDR modes require color-management=true.
510 color_characteristics=name
512 Sets the basic output color characteristics by loading the pa‐
513 rameters from the color_characteristics section with the key
514 name=name . If an ICC profile is also set, the ICC profile takes
515 precedence.
516
518 path=/usr/libexec/weston-keyboard
519 sets the path of the on screen keyboard input method (string).
520 It is possible to pass arguments and environment variables to
521 the program, for example, 'ENVFOO=bar ENVBAR=baz /path/to/pro‐
522 gram --arg anotherarg', with entries that are space-separated
523 but with no support for quoting.
524 overlay-keyboard=false
527 sets weston-keyboard as overlay panel.
528
530 This section contains the following keys:
531 keymap_rules=evdev
533 sets the keymap rules file (string). Used to map layout and
534 model to input device.
535 keymap_model=pc105
537 sets the keymap model (string). See the Models section in xkey‐
538 board-config(7).
539 keymap_layout=us,de,gb
541 sets the comma separated list of keyboard layout codes (string).
542 See the Layouts section in xkeyboard-config(7).
543 keymap_variant=euro,,intl
545 sets the comma separated list of keyboard layout variants
546 (string). The number of variants must be the same as the number
547 of layouts above. See the Layouts section in xkeyboard-con‐
548 fig(7).
549 keymap_options=grp:alt_shift_toggle,grp_led:scroll
551 sets the keymap options (string). See the Options section in
552 xkeyboard-config(7).
553 repeat-rate=40
555 sets the rate of repeating keys in characters per second (un‐
556 signed integer)
557 repeat-delay=400
559 sets the delay in milliseconds since key down until repeating
560 starts (unsigned integer)
561 numlock-on=false
563 sets the default state of the numlock on weston startup for the
564 backends which support it.
565 vt-switching=true
567 Whether to allow the use of Ctrl+Alt+Fn key combinations to
568 switch away from the compositor's virtual console.
569
571 Contains settings for the weston terminal application (weston-termi‐
572 nal). It allows to customize the font and shell of the command line in‐
573 terface.
574 font=DejaVu Sans Mono
576 sets the font of the terminal (string). For a good experience it
577 is recommended to use monospace fonts. In case the font is not
578 found, the default one is used.
579 font-size=14
581 sets the size of the terminal font (unsigned integer).
582 term=xterm-256color
584 The terminal shell (string). Sets the $TERM variable.
585
587 path=/usr/bin/Xwayland
588 sets the path to the xserver to run (string).
589
591 command=/usr/bin/weston --backend=rdp --shell=fullscreen --no-clients-
592 resize --no-config
593 sets the command to start a fullscreen-shell server for screen
594 sharing (string).
595 start-on-startup=false
597 If set to true, start screen sharing of all outputs available on
598 Weston startup. Set to false by default. Set to false by de‐
599 fault. When using this option make sure you enable --no-config
600 to avoid re-loading the screen-share module and implictly trig‐
601 ger screen-sharing for the RDP output already performing the
602 screen share. Alternatively, you could also supply a different
603 configuration file, by using --config /path/to/config/file, and
604 make sure that the configuration file doesn't load the screen-
605 share module.
606
608 path=/usr/bin/echo
609 Path to an executable file to run after startup. This file is
610 executed in parallel to Weston, so it does not have to immedi‐
611 ately exit. Defaults to empty.
612 watch=false
614 If set to true, quit Weston after the auto-launched executable
615 exits. Set to false by default.
616
618 Each color_characteristics section records one set of basic display or
619 monitor color characterisation parameters. The parameters are defined
620 in CTA-861-H specification as Static Metadata Type 1, and they can also
621 be found in EDID. The parameters are divided into groups. Each group
622 must be given either fully or not at all.
623 Each section should be named with name key by which it can be refer‐
625 enced from other sections. A metadata section is just a collection of
626 parameter values and does nothing on its own. It has an effect only
627 when referenced from elsewhere.
628 See output section key color_characteristics.
630 name=name
632 An arbitrary name for this section. You can choose any name you
633 want as long as it does not contain the colon (:) character.
634 Names with at least one colon are reserved.
635 Primaries group
637 red_x=x
638 red_y=y
639 green_x=x
640 green_y=y
641 blue_x=x
642 blue_y=y
643 The CIE 1931 xy chromaticity coordinates of the display pri‐
644 maries. These floating point values must reside between 0.0 and
645 1.0, inclusive.
646 White point group
648 white_x=x
649 white_y=y
650 The CIE 1931 xy chromaticity coordinates of the display white
651 point. These floating point values must reside between 0.0 and
652 1.0, inclusive.
653 Independent parameters
655 Each parameter listed here has its own group and therefore can be given
656 alone.
657 max_L=L
659 Display's desired maximum content luminance (peak) L cd/m², a
660 floating point value in the range 0.0–100000.0.
661 min_L=L
663 Display's desired minimum content luminance L cd/m², a floating
664 point value in the range 0.0–100000.0.
665 maxFALL=L
667 Display's desired maximum frame-average light level L cd/m², a
668 floating point value in the range 0.0–100000.0.
669
671 weston(1), weston-bindings(7), weston-drm(7), xkeyboard-config(7)
672Weston 12.0.2 2019-03-26 weston.ini(5)