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-shell.so
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-shell.so
72 xwayland=true
74 ask Weston to load the XWayland module (boolean).
75 modules=cms-colord.so,screen-share.so
77 specifies the modules to load (string). Available modules in the
78 /usr/lib64/weston directory are:
79 cms-colord.so
81 screen-share.so
82 backend=headless-backend.so
84 overrides defaults backend. Available backend modules in the
85 /usr/lib64/libweston-11 directory are:
86 drm-backend.so
88 headless-backend.so
89 rdp-backend.so
90 wayland-backend.so
91 x11-backend.so
92 repaint-window=N
94 Set the approximate length of the repaint window in millisec‐
95 onds. The repaint window is used to control and reduce the out‐
96 put latency for clients. If the window is longer than the output
97 refresh period, the repaint will be done immediately when the
98 previous repaint finishes, not processing client requests in be‐
99 tween. If the repaint window is too short, the compositor may
100 miss the target vertical blank, increasing output latency. The
101 default value is 7 milliseconds. The allowed range is from -10
102 to 1000 milliseconds. Using a negative value will force the com‐
103 positor to always miss the target vblank.
104 idle-time=seconds
106 sets Weston's idle timeout in seconds. This idle timeout is the
107 time after which Weston will enter an "inactive" mode and screen
108 will fade to black. A value of 0 disables the timeout.
109 Important : This option may also be set via Weston's '-i' com‐
111 mand line option and will take precedence over the current .ini
112 option. This means that if both weston.ini and command line de‐
113 fine this idle-timeout time, the one specified in the command-
114 line will be used. On the other hand, if none of these sets the
115 value, default idle timeout will be set to 300 seconds.
116 require-input=true
118 require an input device for launch
119 wait-for-debugger=true
121 Raises SIGSTOP before initializing the compositor. This allows
122 the user to attach with a debugger and continue execution by
123 sending SIGCONT. This is useful for debugging a crash on start-
124 up when it would be inconvenient to launch weston directly from
125 a debugger. Boolean, defaults to false. There is also a command
126 line option to do the same.
127 remoting=remoting-plugin.so
129 specifies a plugin for remote output to load (string). This can
130 be used to load your own implemented remoting plugin or one with
131 Weston as default. Available remoting plugins in the __libwe‐
132 ston_modules_dir__ directory are:
133 remoting-plugin.so
135 use-pixman=true
137 Enables pixman-based rendering for all outputs on backends that
138 support it. Boolean, defaults to false. There is also a com‐
139 mand line option to do the same.
140 color-management=true
142 Enables color management and requires using GL-renderer. Bool‐
143 ean, defaults to false.
144 TENTATIVE, EXPERIMENTAL, WORK IN PROGRESS: Color management en‐
146 ables the use of ICC files to describe monitor color behavior,
147 Wayland protocol extensions for clients to describe their color
148 spaces and perform monitor profiling, and tone mapping required
149 to enable HDR video modes. This extended functionality comes at
150 the cost of heavier image processing and sometimes a loss of
151 some hardware off-loading features like composite-bypass.
152
154 The libinput section is used to configure input devices when using the
155 libinput input device backend. The defaults are determined by libinput
156 and vary according to what is most sensible for any given device.
157 Available configuration are:
159 enable-tap=false
161 Enables tap to click on touchpad devices.
162 tap-and-drag=false
164 For touchpad devices with enable-tap enabled. If the user taps,
165 then taps a second time, this time holding, the virtual mouse
166 button stays down for as long as the user keeps their finger on
167 the touchpad, allowing the user to click and drag with taps
168 alone.
169 tap-and-drag-lock=false
171 For touchpad devices with enable-tap and tap-and-drag enabled.
172 In the middle of a tap-and-drag, if the user releases the touch‐
173 pad for less than a certain number of milliseconds, then touches
174 it again, the virtual mouse button will remain pressed and the
175 drag can continue.
176 disable-while-typing=true
178 For devices that may be accidentally triggered while typing on
179 the keyboard, causing a disruption of the typing. Disables them
180 while the keyboard is in use.
181 middle-button-emulation=false
183 For pointer devices with left and right buttons, but no middle
184 button. When enabled, a middle button event is emitted when the
185 left and right buttons are pressed simultaneously.
186 left-handed=false
188 Configures the device for use by left-handed people. Exactly
189 what this option does depends on the device. For pointers with
190 left and right buttons, the buttons are swapped. On tablets, the
191 tablet is logically turned upside down, because it will be phys‐
192 ically turned upside down.
193 rotation=n
195 Changes the direction of the logical north, rotating it n de‐
196 grees clockwise away from the default orientation, where n is a
197 whole number between 0 and 359 inclusive. Needed for trackballs,
198 mainly. Allows the user to orient the trackball sideways, for
199 example.
200 accel-profile={flat,adaptive}
202 Set the pointer acceleration profile. The pointer's screen speed
203 is proportional to the physical speed with a certain constant of
204 proportionality. Call that constant alpha. flat keeps alpha
205 fixed. See accel-speed. adaptive causes alpha to increase with
206 physical speed, giving the user more control when the speed is
207 slow, and more reach when the speed is high. adaptive is the
208 default.
209 accel-speed=v
211 If accel-profile is set to flat, it simply sets the value of al‐
212 pha. If accel-profile is set to adaptive, the effect is more
213 complicated, but generally speaking, it will change the
214 pointer's speed. v is normalised and must lie in the range [-1,
215 1]. The exact mapping between v and alpha is hardware-dependent,
216 but higher values cause higher cursor speeds.
217 natural-scroll=false
219 Enables natural scrolling, mimicking the behaviour of touch‐
220 screen scrolling. That is, if the wheel, finger, or fingers are
221 moved down, the surface is scrolled up instead of down, as if
222 the finger, or fingers were in contact with the surface being
223 scrolled.
224 scroll-method={two-finger,edge,button,none}
226 Sets the scroll method. two-finger scrolls with two fingers on a
227 touchpad. edge scrolls with one finger on the right edge of a
228 touchpad. button scrolls when the pointer is moved while a cer‐
229 tain button is pressed. See scroll-button. none disables
230 scrolling altogether.
231 scroll-button={BTN_LEFT,BTN_RIGHT,BTN_MIDDLE,...}
233 For devices with scroll-method set to button. Specifies the but‐
234 ton that will trigger scrolling. See /usr/include/linux/input-
235 event-codes.h for the complete list of possible values.
236 touchscreen_calibrator=true
238 Advertise the touchscreen calibrator interface to all clients.
239 This is a potential denial-of-service attack vector, so it
240 should only be enabled on trusted userspace. Boolean, defaults
241 to false.
242 The interface is required for running touchscreen calibrator ap‐
244 plications. It provides the application raw touch events, by‐
245 passing the normal touch handling. It also allows the applica‐
246 tion to upload a new calibration into the compositor.
247 Even though this option is listed in the libinput section, it
249 does affect all Weston configurations regardless of the used
250 backend. If the backend does not use libinput, the interface can
251 still be advertised, but it will not list any devices.
252 calibration_helper=/bin/echo
254 An optional calibration helper program to permanently save a new
255 touchscreen calibration. String, defaults to unset.
256 The given program will be executed with seven arguments when a
258 calibrator application requests the server to take a new cali‐
259 bration matrix into use. The program is executed synchronously
260 and will therefore block Weston for its duration. If the program
261 exit status is non-zero, Weston will not apply the new calibra‐
262 tion. If the helper is unset or the program exit status is zero,
263 Weston will use the new calibration immediately.
264 The program is invoked as:
266 calibration_helper syspath m1 m2 m3 m4 m5 m6
268 where syspath is the udev sys path for the device and m1
270 through m6 are the calibration matrix elements in libinput's LI‐
271 BINPUT_CALIBRATION_MATRIX udev property format. The sys path is
272 an absolute path and starts with the sys mount point.
273
275 The shell section is used to customize the compositor. Some keys may
276 not be handled by different shell plugins.
277 The entries that can appear in this section are:
279 client=file
281 sets the path for the shell client to run. If not specified we‐
282 ston-desktop-shell is launched (string).
283 background-image=file
285 sets the path for the background image file (string).
286 background-type=tile
288 determines how the background image is drawn (string). Can be
289 centered, scale, scale-crop or tile (default). Centered shows
290 the image once centered. If the image is smaller than the out‐
291 put, the rest of the surface will be in background color. If the
292 image size does fit the output it will be cropped left and
293 right, or top and bottom. Scale means scaled to fit the output
294 precisely, not preserving aspect ratio. Scale-crop preserves
295 aspect ratio, scales the background image just big enough to
296 cover the output, and centers it. The image ends up cropped from
297 left and right, or top and bottom, if the aspect ratio does not
298 match the output. Tile repeats the background image to fill the
299 output.
300 background-color=0xAARRGGBB
302 sets the color of the background (unsigned integer). The hexa‐
303 decimal digit pairs are in order alpha, red, green, and blue.
304 clock-format=format
306 sets the panel clock format (string). Can be none, minutes, sec‐
307 onds, minutes-24h, seconds-24h. By default, minutes format is
308 used.
309 panel-color=0xAARRGGBB
311 sets the color of the panel (unsigned integer). The hexadecimal
312 digit pairs are in order transparency, red, green, and blue. Ex‐
313 amples:
314 0xffff0000 Red
316 0xff00ff00 Green
317 0xff0000ff Blue
318 0x00ffffff Fully transparent
319 panel-position=top
321 sets the position of the panel (string). Can be top, bottom,
322 left, right, none.
323 locking=true
325 enables screen locking (boolean).
326 animation=zoom
328 sets the effect used for opening new windows (string). Can be
329 zoom, fade, none. By default, no animation is used.
330 close-animation=fade
332 sets the effect used when closing windows (string). Can be fade,
333 none. By default, the fade animation is used.
334 startup-animation=fade
336 sets the effect used by desktop-shell when starting up (string).
337 Can be fade, none. By default, the fade animation is used.
338 focus-animation=dim-layer
340 sets the effect used with the focused and unfocused windows. Can
341 be dim-layer, none. By default, no animation is used.
342 allow-zap=true
344 whether the shell should quit when the Ctrl-Alt-Backspace key
345 combination is pressed
346 binding-modifier=ctrl
348 sets the modifier key used for common bindings (string), such as
349 moving surfaces, resizing, rotating, switching, closing and set‐
350 ting the transparency for windows, controlling the backlight and
351 zooming the desktop. See weston-bindings(7). Possible values:
352 none, ctrl, alt, super (default)
353 cursor-theme=theme
355 sets the cursor theme (string).
356 cursor-size=24
358 sets the cursor size (unsigned integer).
359
361 There can be multiple launcher sections, one for each launcher.
362 icon=icon
364 sets the path to icon image (string). Svg images are not cur‐
365 rently supported.
366 displayname=displayname
368 sets the display name of the launcher that appears in the
369 tooltip.
370 path=program
372 sets the path to the program that is run by clicking on this
373 launcher (string). It is possible to pass arguments and envi‐
374 ronment variables to the program. For example:
375 path=GDK_BACKEND=wayland gnome-terminal --full-screen
377
379 There can be multiple output sections, each corresponding to one out‐
380 put. It is currently only recognized by the drm and x11 backends.
381 name=name
383 sets a name for the output (string). The backend uses the name
384 to identify the output. All X11 output names start with a letter
385 X. All Wayland output names start with the letters WL. Exam‐
386 ples of usage:
387 LVDS1 DRM backend, Laptop internal panel no.1
389 VGA1 DRM backend, VGA connector no.1
390 X1 X11 backend, X window no.1
391 WL1 Wayland backend, Wayland window no.1
392 See weston-drm(7) for more details.
394 mode=mode
396 sets the output mode (string). The mode parameter is handled
397 differently depending on the backend. On the X11 backend, it
398 just sets the WIDTHxHEIGHT of the weston window. The DRM back‐
399 end accepts different modes, along with an option of a modeline
400 string.
401 See weston-drm(7) for examples of modes-formats supported by DRM
403 backend.
404 transform=normal
406 How you have rotated your monitor from its normal orientation
407 (string). The transform key can be one of the following 8
408 strings:
409 normal Normal output.
411 rotate-90 90 degrees clockwise.
412 rotate-180 Upside down.
413 rotate-270 90 degrees counter clockwise.
414 flipped Horizontally flipped
415 flipped-rotate-90 Flipped and 90 degrees clockwise
416 flipped-rotate-180 Flipped and upside down
417 flipped-rotate-270 Flipped and 90 degrees counter clockwise
418 scale=factor
420 The scaling multiplier applied to the entire output, in support
421 of high resolution ("HiDPI" or "retina") displays, that roughly
422 corresponds to the pixel ratio of the display's physical resolu‐
423 tion to the logical resolution. Applications that do not sup‐
424 port high resolution displays typically appear tiny and unread‐
425 able. Weston will scale the output of such applications by this
426 multiplier, to make them readable. Applications that do support
427 their own output scaling can draw their content in high resolu‐
428 tion, in which case they avoid compositor scaling. Weston will
429 not scale the output of such applications, and they are not af‐
430 fected by this multiplier.
431 An integer, 1 by default, typically configured as 2 or higher
433 when needed, denoting the scaling multiplier for the output.
434 icc_profile=file
436 If option color-management is true, load the given ICC file as
437 the output color profile. This works only on DRM, headless, way‐
438 land, and x11 backends, and for remoting and pipewire outputs.
439 seat=name
441 The logical seat name that this output should be associated
442 with. If this is set then the seat's input will be confined to
443 the output that has the seat set on it. The expectation is that
444 this functionality will be used in a multiheaded environment
445 with a single compositor for multiple output and input configu‐
446 rations. The default seat is called "default" and will always be
447 present. This seat can be constrained like any other.
448 allow_hdcp=true
450 Allows HDCP support for this output. If set to true, HDCP can be
451 tried for the content-protection, provided by the backends, on
452 this output. By default, HDCP support is always allowed for an
453 output. The content-protection can actually be realized, only if
454 the hardware (source and sink) support HDCP, and the backend has
455 the implementation of content-protection protocol. Currently,
456 HDCP is supported by drm-backend.
457 app-ids=app-id[,app_id]*
459 A comma separated list of the IDs of applications to place on
460 this output. These IDs should match the application IDs as set
461 with the xdg_shell.set_app_id request. Currently, this option is
462 supported by kiosk-shell.
463 eotf-mode=sdr
465 Sets the EOTF mode on the output. This is used for choosing be‐
466 tween standard dynamic range (SDR) mode and the various high dy‐
467 namic range (HDR) modes. The display driver, the graphics card,
468 and the video sink (monitor) need to support the chosen mode,
469 otherwise the result is undefined. The mode can be one of the
470 following strings:
471 sdr traditional gamma, SDR
473 hdr-gamma traditional gamma, HDR
474 st2084 SMPTE ST 2084, a.k.a Perceptual Quantizer
475 hlg Hybrid Log-Gamma (ITU-R BT.2100)
476 Defaults to sdr. Non-SDR modes require color-management=true.
478 color_characteristics=name
480 Sets the basic output color characteristics by loading the pa‐
481 rameters from the color_characteristics section with the key
482 name=name . If an ICC profile is also set, the ICC profile takes
483 precedence.
484
486 path=/usr/libexec/weston-keyboard
487 sets the path of the on screen keyboard input method (string).
488 overlay-keyboard=false
490 sets weston-keyboard as overlay panel.
491
493 This section contains the following keys:
494 keymap_rules=evdev
496 sets the keymap rules file (string). Used to map layout and
497 model to input device.
498 keymap_model=pc105
500 sets the keymap model (string). See the Models section in xkey‐
501 board-config(7).
502 keymap_layout=us,de,gb
504 sets the comma separated list of keyboard layout codes (string).
505 See the Layouts section in xkeyboard-config(7).
506 keymap_variant=euro,,intl
508 sets the comma separated list of keyboard layout variants
509 (string). The number of variants must be the same as the number
510 of layouts above. See the Layouts section in xkeyboard-con‐
511 fig(7).
512 keymap_options=grp:alt_shift_toggle,grp_led:scroll
514 sets the keymap options (string). See the Options section in
515 xkeyboard-config(7).
516 repeat-rate=40
518 sets the rate of repeating keys in characters per second (un‐
519 signed integer)
520 repeat-delay=400
522 sets the delay in milliseconds since key down until repeating
523 starts (unsigned integer)
524 numlock-on=false
526 sets the default state of the numlock on weston startup for the
527 backends which support it.
528 vt-switching=true
530 Whether to allow the use of Ctrl+Alt+Fn key combinations to
531 switch away from the compositor's virtual console.
532
534 Contains settings for the weston terminal application (weston-termi‐
535 nal). It allows to customize the font and shell of the command line in‐
536 terface.
537 font=DejaVu Sans Mono
539 sets the font of the terminal (string). For a good experience it
540 is recommended to use monospace fonts. In case the font is not
541 found, the default one is used.
542 font-size=14
544 sets the size of the terminal font (unsigned integer).
545 term=xterm-256color
547 The terminal shell (string). Sets the $TERM variable.
548
550 path=/usr/bin/Xwayland
551 sets the path to the xserver to run (string).
552
554 command=/usr/bin/weston --backend=rdp-backend.so --shell=fullscreen-
555 shell.so --no-clients-resize --no-config
556 sets the command to start a fullscreen-shell server for screen
557 sharing (string).
558 start-on-startup=false
560 If set to true, start screen sharing of all outputs available on
561 Weston startup. Set to false by default. Set to false by de‐
562 fault. When using this option make sure you enable --no-config
563 to avoid re-loading the screen-share module and implictly trig‐
564 ger screen-sharing for the RDP output already performing the
565 screen share. Alternatively, you could also supply a different
566 configuration file, by using --config /path/to/config/file, and
567 make sure that the configuration file doesn't load the screen-
568 share module.
569
571 path=/usr/bin/echo
572 Path to an executable file to run after startup. This file is
573 executed in parallel to Weston, so it does not have to immedi‐
574 ately exit. Defaults to empty.
575 watch=false
577 If set to true, quit Weston after the auto-launched executable
578 exits. Set to false by default.
579
581 Each color_characteristics section records one set of basic display or
582 monitor color characterisation parameters. The parameters are defined
583 in CTA-861-H specification as Static Metadata Type 1, and they can also
584 be found in EDID. The parameters are divided into groups. Each group
585 must be given either fully or not at all.
586 Each section should be named with name key by which it can be refer‐
588 enced from other sections. A metadata section is just a collection of
589 parameter values and does nothing on its own. It has an effect only
590 when referenced from elsewhere.
591 See output section key color_characteristics.
593 name=name
595 An arbitrary name for this section. You can choose any name you
596 want as long as it does not contain the colon (:) character.
597 Names with at least one colon are reserved.
598 Primaries group
600 red_x=x
601 red_y=y
602 green_x=x
603 green_y=y
604 blue_x=x
605 blue_y=y
606 The CIE 1931 xy chromaticity coordinates of the display pri‐
607 maries. These floating point values must reside between 0.0 and
608 1.0, inclusive.
609 White point group
611 white_x=x
612 white_y=y
613 The CIE 1931 xy chromaticity coordinates of the display white
614 point. These floating point values must reside between 0.0 and
615 1.0, inclusive.
616 Independent parameters
618 Each parameter listed here has its own group and therefore can be given
619 alone.
620 max_L=L
622 Display's desired maximum content luminance (peak) L cd/m², a
623 floating point value in the range 0.0–100000.0.
624 min_L=L
626 Display's desired minimum content luminance L cd/m², a floating
627 point value in the range 0.0–100000.0.
628 maxFALL=L
630 Display's desired maximum frame-average light level L cd/m², a
631 floating point value in the range 0.0–100000.0.
632
634 weston(1), weston-bindings(7), weston-drm(7), xkeyboard-config(7)
635Weston 11.0.1 2019-03-26 weston.ini(5)