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-10 directory are:
86 drm-backend.so
88 fbdev-backend.so
89 headless-backend.so
90 rdp-backend.so
91 wayland-backend.so
92 x11-backend.so
93 repaint-window=N
95 Set the approximate length of the repaint window in millisec‐
96 onds. The repaint window is used to control and reduce the out‐
97 put latency for clients. If the window is longer than the output
98 refresh period, the repaint will be done immediately when the
99 previous repaint finishes, not processing client requests in be‐
100 tween. If the repaint window is too short, the compositor may
101 miss the target vertical blank, increasing output latency. The
102 default value is 7 milliseconds. The allowed range is from -10
103 to 1000 milliseconds. Using a negative value will force the com‐
104 positor to always miss the target vblank.
105 gbm-format=format
107 sets the GBM format used for the framebuffer for the GBM back‐
108 end. Can be xrgb8888, xrgb2101010, rgb565. By default, xrgb8888
109 is used.
110 idle-time=seconds
112 sets Weston's idle timeout in seconds. This idle timeout is the
113 time after which Weston will enter an "inactive" mode and screen
114 will fade to black. A value of 0 disables the timeout.
115 Important : This option may also be set via Weston's '-i' com‐
117 mand line option and will take precedence over the current .ini
118 option. This means that if both weston.ini and command line de‐
119 fine this idle-timeout time, the one specified in the command-
120 line will be used. On the other hand, if none of these sets the
121 value, default idle timeout will be set to 300 seconds.
122 require-input=true
124 require an input device for launch
125 pageflip-timeout=milliseconds
127 sets Weston's pageflip timeout in milliseconds. This sets a
128 timer to exit gracefully with a log message and an exit code of
129 1 in case the DRM driver is non-responsive. Setting it to 0
130 disables this feature.
131 wait-for-debugger=true
133 Raises SIGSTOP before initializing the compositor. This allows
134 the user to attach with a debugger and continue execution by
135 sending SIGCONT. This is useful for debugging a crash on start-
136 up when it would be inconvenient to launch weston directly from
137 a debugger. Boolean, defaults to false. There is also a command
138 line option to do the same.
139 remoting=remoting-plugin.so
141 specifies a plugin for remote output to load (string). This can
142 be used to load your own implemented remoting plugin or one with
143 Weston as default. Available remoting plugins in the __libwe‐
144 ston_modules_dir__ directory are:
145 remoting-plugin.so
147 use-pixman=true
149 Enables pixman-based rendering for all outputs on backends that
150 support it. Boolean, defaults to false. There is also a com‐
151 mand line option to do the same.
152 color-management=true
154 Enables color management and requires using GL-renderer. Bool‐
155 ean, defaults to false.
156 TENTATIVE, EXPERIMENTAL, WORK IN PROGRESS: Color management en‐
158 ables the use of ICC files to describe monitor color behavior,
159 Wayland protocol extensions for clients to describe their color
160 spaces and perform monitor profiling, and tone mapping required
161 to enable HDR video modes. This extended functionality comes at
162 the cost of heavier image processing and sometimes a loss of
163 some hardware off-loading features like composite-bypass.
164
167 The libinput section is used to configure input devices when using the
168 libinput input device backend. The defaults are determined by libinput
169 and vary according to what is most sensible for any given device.
170 Available configuration are:
172 enable-tap=false
174 Enables tap to click on touchpad devices.
175 tap-and-drag=false
177 For touchpad devices with enable-tap enabled. If the user taps,
178 then taps a second time, this time holding, the virtual mouse
179 button stays down for as long as the user keeps their finger on
180 the touchpad, allowing the user to click and drag with taps
181 alone.
182 tap-and-drag-lock=false
184 For touchpad devices with enable-tap and tap-and-drag enabled.
185 In the middle of a tap-and-drag, if the user releases the touch‐
186 pad for less than a certain number of milliseconds, then touches
187 it again, the virtual mouse button will remain pressed and the
188 drag can continue.
189 disable-while-typing=true
191 For devices that may be accidentally triggered while typing on
192 the keyboard, causing a disruption of the typing. Disables them
193 while the keyboard is in use.
194 middle-button-emulation=false
196 For pointer devices with left and right buttons, but no middle
197 button. When enabled, a middle button event is emitted when the
198 left and right buttons are pressed simultaneously.
199 left-handed=false
201 Configures the device for use by left-handed people. Exactly
202 what this option does depends on the device. For pointers with
203 left and right buttons, the buttons are swapped. On tablets, the
204 tablet is logically turned upside down, because it will be phys‐
205 ically turned upside down.
206 rotation=n
208 Changes the direction of the logical north, rotating it n de‐
209 grees clockwise away from the default orientation, where n is a
210 whole number between 0 and 359 inclusive. Needed for trackballs,
211 mainly. Allows the user to orient the trackball sideways, for
212 example.
213 accel-profile={flat,adaptive}
215 Set the pointer acceleration profile. The pointer's screen speed
216 is proportional to the physical speed with a certain constant of
217 proportionality. Call that constant alpha. flat keeps alpha
218 fixed. See accel-speed. adaptive causes alpha to increase with
219 physical speed, giving the user more control when the speed is
220 slow, and more reach when the speed is high. adaptive is the
221 default.
222 accel-speed=v
224 If accel-profile is set to flat, it simply sets the value of al‐
225 pha. If accel-profile is set to adaptive, the effect is more
226 complicated, but generally speaking, it will change the
227 pointer's speed. v is normalised and must lie in the range [-1,
228 1]. The exact mapping between v and alpha is hardware-dependent,
229 but higher values cause higher cursor speeds.
230 natural-scroll=false
232 Enables natural scrolling, mimicking the behaviour of touch‐
233 screen scrolling. That is, if the wheel, finger, or fingers are
234 moved down, the surface is scrolled up instead of down, as if
235 the finger, or fingers were in contact with the surface being
236 scrolled.
237 scroll-method={two-finger,edge,button,none}
239 Sets the scroll method. two-finger scrolls with two fingers on a
240 touchpad. edge scrolls with one finger on the right edge of a
241 touchpad. button scrolls when the pointer is moved while a cer‐
242 tain button is pressed. See scroll-button. none disables
243 scrolling altogether.
244 scroll-button={BTN_LEFT,BTN_RIGHT,BTN_MIDDLE,...}
246 For devices with scroll-method set to button. Specifies the but‐
247 ton that will trigger scrolling. See /usr/include/linux/input-
248 event-codes.h for the complete list of possible values.
249 touchscreen_calibrator=true
251 Advertise the touchscreen calibrator interface to all clients.
252 This is a potential denial-of-service attack vector, so it
253 should only be enabled on trusted userspace. Boolean, defaults
254 to false.
255 The interface is required for running touchscreen calibrator ap‐
257 plications. It provides the application raw touch events, by‐
258 passing the normal touch handling. It also allows the applica‐
259 tion to upload a new calibration into the compositor.
260 Even though this option is listed in the libinput section, it
262 does affect all Weston configurations regardless of the used
263 backend. If the backend does not use libinput, the interface can
264 still be advertised, but it will not list any devices.
265 calibration_helper=/bin/echo
267 An optional calibration helper program to permanently save a new
268 touchscreen calibration. String, defaults to unset.
269 The given program will be executed with seven arguments when a
271 calibrator application requests the server to take a new cali‐
272 bration matrix into use. The program is executed synchronously
273 and will therefore block Weston for its duration. If the program
274 exit status is non-zero, Weston will not apply the new calibra‐
275 tion. If the helper is unset or the program exit status is zero,
276 Weston will use the new calibration immediately.
277 The program is invoked as:
279 calibration_helper syspath m1 m2 m3 m4 m5 m6
281 where syspath is the udev sys path for the device and m1
283 through m6 are the calibration matrix elements in libinput's LI‐
284 BINPUT_CALIBRATION_MATRIX udev property format. The sys path is
285 an absolute path and starts with the sys mount point.
286
289 The shell section is used to customize the compositor. Some keys may
290 not be handled by different shell plugins.
291 The entries that can appear in this section are:
293 client=file
295 sets the path for the shell client to run. If not specified we‐
296 ston-desktop-shell is launched (string).
297 background-image=file
299 sets the path for the background image file (string).
300 background-type=tile
302 determines how the background image is drawn (string). Can be
303 centered, scale, scale-crop or tile (default). Centered shows
304 the image once centered. If the image is smaller than the out‐
305 put, the rest of the surface will be in background color. If the
306 image size does fit the output it will be cropped left and
307 right, or top and bottom. Scale means scaled to fit the output
308 precisely, not preserving aspect ratio. Scale-crop preserves
309 aspect ratio, scales the background image just big enough to
310 cover the output, and centers it. The image ends up cropped from
311 left and right, or top and bottom, if the aspect ratio does not
312 match the output. Tile repeats the background image to fill the
313 output.
314 background-color=0xAARRGGBB
316 sets the color of the background (unsigned integer). The hexa‐
317 decimal digit pairs are in order alpha, red, green, and blue.
318 clock-format=format
320 sets the panel clock format (string). Can be none, minutes, sec‐
321 onds, minutes-24h, seconds-24h. By default, minutes format is
322 used.
323 panel-color=0xAARRGGBB
325 sets the color of the panel (unsigned integer). The hexadecimal
326 digit pairs are in order transparency, red, green, and blue. Ex‐
327 amples:
328 0xffff0000 Red
330 0xff00ff00 Green
331 0xff0000ff Blue
332 0x00ffffff Fully transparent
333 panel-position=top
335 sets the position of the panel (string). Can be top, bottom,
336 left, right, none.
337 locking=true
339 enables screen locking (boolean).
340 animation=zoom
342 sets the effect used for opening new windows (string). Can be
343 zoom, fade, none. By default, no animation is used.
344 close-animation=fade
346 sets the effect used when closing windows (string). Can be fade,
347 none. By default, the fade animation is used.
348 startup-animation=fade
350 sets the effect used for opening new windows (string). Can be
351 fade, none. By default, the fade animation is used.
352 focus-animation=dim-layer
354 sets the effect used with the focused and unfocused windows. Can
355 be dim-layer, none. By default, no animation is used.
356 allow-zap=true
358 whether the shell should quit when the Ctrl-Alt-Backspace key
359 combination is pressed
360 binding-modifier=ctrl
362 sets the modifier key used for common bindings (string), such as
363 moving surfaces, resizing, rotating, switching, closing and set‐
364 ting the transparency for windows, controlling the backlight and
365 zooming the desktop. See weston-bindings(7). Possible values:
366 none, ctrl, alt, super (default)
367 num-workspaces=6
369 defines the number of workspaces (unsigned integer). The user
370 can switch workspaces by using the binding+F1, F2 keys. If this
371 key is not set, fall back to one workspace.
372 cursor-theme=theme
374 sets the cursor theme (string).
375 cursor-size=24
377 sets the cursor size (unsigned integer).
378
380 There can be multiple launcher sections, one for each launcher.
381 icon=icon
383 sets the path to icon image (string). Svg images are not cur‐
384 rently supported.
385 path=program
387 sets the path to the program that is run by clicking on this
388 launcher (string). It is possible to pass arguments and envi‐
389 ronment variables to the program. For example:
390 path=GDK_BACKEND=wayland gnome-terminal --full-screen
392
394 There can be multiple output sections, each corresponding to one out‐
395 put. It is currently only recognized by the drm and x11 backends.
396 name=name
398 sets a name for the output (string). The backend uses the name
399 to identify the output. All X11 output names start with a letter
400 X. All Wayland output names start with the letters WL. The
401 available output names for DRM backend are listed in the weston-
402 launch(1) output. Examples of usage:
403 LVDS1 DRM backend, Laptop internal panel no.1
405 VGA1 DRM backend, VGA connector no.1
406 X1 X11 backend, X window no.1
407 WL1 Wayland backend, Wayland window no.1
408 See weston-drm(7) for more details.
410 mode=mode
412 sets the output mode (string). The mode parameter is handled
413 differently depending on the backend. On the X11 backend, it
414 just sets the WIDTHxHEIGHT of the weston window. The DRM back‐
415 end accepts different modes, along with an option of a modeline
416 string.
417 See weston-drm(7) for examples of modes-formats supported by DRM
419 backend.
420 transform=normal
422 How you have rotated your monitor from its normal orientation
423 (string). The transform key can be one of the following 8
424 strings:
425 normal Normal output.
427 rotate-90 90 degrees clockwise.
428 rotate-180 Upside down.
429 rotate-270 90 degrees counter clockwise.
430 flipped Horizontally flipped
431 flipped-rotate-90 Flipped and 90 degrees clockwise
432 flipped-rotate-180 Flipped and upside down
433 flipped-rotate-270 Flipped and 90 degrees counter clockwise
434 scale=factor
436 The scaling multiplier applied to the entire output, in support
437 of high resolution ("HiDPI" or "retina") displays, that roughly
438 corresponds to the pixel ratio of the display's physical resolu‐
439 tion to the logical resolution. Applications that do not sup‐
440 port high resolution displays typically appear tiny and unread‐
441 able. Weston will scale the output of such applications by this
442 multiplier, to make them readable. Applications that do support
443 their own output scaling can draw their content in high resolu‐
444 tion, in which case they avoid compositor scaling. Weston will
445 not scale the output of such applications, and they are not af‐
446 fected by this multiplier.
447 An integer, 1 by default, typically configured as 2 or higher
449 when needed, denoting the scaling multiplier for the output.
450 icc_profile=file
452 If option color-management is true, load the given ICC file as
453 the output color profile. This works only on DRM, headless, way‐
454 land, and x11 backends, and for remoting and pipewire outputs.
455 seat=name
457 The logical seat name that this output should be associated
458 with. If this is set then the seat's input will be confined to
459 the output that has the seat set on it. The expectation is that
460 this functionality will be used in a multiheaded environment
461 with a single compositor for multiple output and input configu‐
462 rations. The default seat is called "default" and will always be
463 present. This seat can be constrained like any other.
464 allow_hdcp=true
466 Allows HDCP support for this output. If set to true, HDCP can be
467 tried for the content-protection, provided by the backends, on
468 this output. By default, HDCP support is always allowed for an
469 output. The content-protection can actually be realized, only if
470 the hardware (source and sink) support HDCP, and the backend has
471 the implementation of content-protection protocol. Currently,
472 HDCP is supported by drm-backend.
473 app-ids=app-id[,app_id]*
475 A comma separated list of the IDs of applications to place on
476 this output. These IDs should match the application IDs as set
477 with the xdg_shell.set_app_id request. Currently, this option is
478 supported by kiosk-shell.
479
481 path=/usr/libexec/weston-keyboard
482 sets the path of the on screen keyboard input method (string).
483 overlay-keyboard=false
485 sets weston-keyboard as overlay panel.
486
488 This section contains the following keys:
489 keymap_rules=evdev
491 sets the keymap rules file (string). Used to map layout and
492 model to input device.
493 keymap_model=pc105
495 sets the keymap model (string). See the Models section in xkey‐
496 board-config(7).
497 keymap_layout=us,de,gb
499 sets the comma separated list of keyboard layout codes (string).
500 See the Layouts section in xkeyboard-config(7).
501 keymap_variant=euro,,intl
503 sets the comma separated list of keyboard layout variants
504 (string). The number of variants must be the same as the number
505 of layouts above. See the Layouts section in xkeyboard-con‐
506 fig(7).
507 keymap_options=grp:alt_shift_toggle,grp_led:scroll
509 sets the keymap options (string). See the Options section in
510 xkeyboard-config(7).
511 repeat-rate=40
513 sets the rate of repeating keys in characters per second (un‐
514 signed integer)
515 repeat-delay=400
517 sets the delay in milliseconds since key down until repeating
518 starts (unsigned integer)
519 numlock-on=false
521 sets the default state of the numlock on weston startup for the
522 backends which support it.
523 vt-switching=true
525 Whether to allow the use of Ctrl+Alt+Fn key combinations to
526 switch away from the compositor's virtual console.
527
529 Contains settings for the weston terminal application (weston-termi‐
530 nal). It allows to customize the font and shell of the command line in‐
531 terface.
532 font=DejaVu Sans Mono
534 sets the font of the terminal (string). For a good experience it
535 is recommended to use monospace fonts. In case the font is not
536 found, the default one is used.
537 font-size=14
539 sets the size of the terminal font (unsigned integer).
540 term=xterm-256color
542 The terminal shell (string). Sets the $TERM variable.
543
545 path=/usr/bin/Xwayland
546 sets the path to the xserver to run (string).
547
549 command=/usr/bin/weston --backend=rdp-backend.so --shell=fullscreen-
550 shell.so --no-clients-resize
551 sets the command to start a fullscreen-shell server for screen
552 sharing (string).
553 start-on-startup=false
555 If set to true, start screen sharing of all outputs available on
556 Weston startup. Set to false by default.
557
559 path=/usr/bin/echo
560 Path to an executable file to run after startup. This file is
561 executed in parallel to Weston, so it does not have to immedi‐
562 ately exit. Defaults to empty.
563 watch=false
565 If set to true, quit Weston after the auto-launched executable
566 exits. Set to false by default.
567
569 weston(1), weston-bindings(7), weston-drm(7), xkeyboard-config(7)
570Weston 10.0.1 2019-03-26 weston.ini(5)