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 Possible value types are string, signed and unsigned 32-bit integer,
56 and boolean. Strings must not be quoted, do not support any escape
57 sequences, and run till the end of the line. Integers can be given in
58 decimal (e.g. 123), octal (e.g. 0173), and hexadecimal (e.g. 0x7b)
59 form. Boolean values can be only 'true' or 'false'.
60
62 The core section is used to select the startup compositor modules and
63 general options.
64 shell=desktop-shell.so
66 specifies a shell to load (string). This can be used to load
67 your own implemented shell or one with Weston as default. Avail‐
68 able shells in the /usr/lib64/weston directory are:
69 desktop-shell.so
71 xwayland=true
73 ask Weston to load the XWayland module (boolean).
74 modules=cms-colord.so,screen-share.so
76 specifies the modules to load (string). Available modules in the
77 /usr/lib64/weston directory are:
78 cms-colord.so
80 screen-share.so
81 backend=headless-backend.so
83 overrides defaults backend. Available backend modules in the
84 /usr/lib64/libweston-8 directory are:
85 drm-backend.so
87 fbdev-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
99 between. 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 gbm-format=format
106 sets the GBM format used for the framebuffer for the GBM back‐
107 end. Can be xrgb8888, xrgb2101010, rgb565. By default, xrgb8888
108 is used.
109 idle-time=seconds
111 sets Weston's idle timeout in seconds. This idle timeout is the
112 time after which Weston will enter an "inactive" mode and screen
113 will fade to black. A value of 0 disables the timeout.
114 Important : This option may also be set via Weston's '-i' com‐
116 mand line option and will take precedence over the current .ini
117 option. This means that if both weston.ini and command line
118 define this idle-timeout time, the one specified in the command-
119 line will be used. On the other hand, if none of these sets the
120 value, default idle timeout will be set to 300 seconds.
121 require-input=true
123 require an input device for launch
124 pageflip-timeout=milliseconds
126 sets Weston's pageflip timeout in milliseconds. This sets a
127 timer to exit gracefully with a log message and an exit code of
128 1 in case the DRM driver is non-responsive. Setting it to 0
129 disables this feature.
130 wait-for-debugger=true
132 Raises SIGSTOP before initializing the compositor. This allows
133 the user to attach with a debugger and continue execution by
134 sending SIGCONT. This is useful for debugging a crash on start-
135 up when it would be inconvenient to launch weston directly from
136 a debugger. Boolean, defaults to false. There is also a command
137 line option to do the same.
138 remoting=remoting-plugin.so
140 specifies a plugin for remote output to load (string). This can
141 be used to load your own implemented remoting plugin or one with
142 Weston as default. Available remoting plugins in the __libwe‐
143 ston_modules_dir__ directory are:
144 remoting-plugin.so
146 use-pixman=true
148 Enables pixman-based rendering for all outputs on backends that
149 support it. Boolean, defaults to false. There is also a com‐
150 mand line option to do the same.
151
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
196 degrees clockwise away from the default orientation, where n is
197 a whole number between 0 and 359 inclusive. Needed for track‐
198 balls, mainly. Allows the user to orient the trackball sideways,
199 for 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
212 alpha. 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
244 applications. It provides the application raw touch events,
245 bypassing the normal touch handling. It also allows the appli‐
246 cation 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
271 LIBINPUT_CALIBRATION_MATRIX udev property format. The sys path
272 is an absolute path and starts with the sys mount point.
273
276 The shell section is used to customize the compositor. Some keys may
277 not be handled by different shell plugins.
278 The entries that can appear in this section are:
280 client=file
282 sets the path for the shell client to run. If not specified
283 weston-desktop-shell is launched (string).
284 background-image=file
286 sets the path for the background image file (string).
287 background-type=tile
289 determines how the background image is drawn (string). Can be
290 centered, scale, scale-crop or tile (default). Centered shows
291 the image once centered. If the image is smaller than the out‐
292 put, the rest of the surface will be in background color. If the
293 image size does fit the output it will be cropped left and
294 right, or top and bottom. Scale means scaled to fit the output
295 precisely, not preserving aspect ratio. Scale-crop preserves
296 aspect ratio, scales the background image just big enough to
297 cover the output, and centers it. The image ends up cropped from
298 left and right, or top and bottom, if the aspect ratio does not
299 match the output. Tile repeats the background image to fill the
300 output.
301 background-color=0xAARRGGBB
303 sets the color of the background (unsigned integer). The hexa‐
304 decimal digit pairs are in order alpha, red, green, and blue.
305 clock-format=format
307 sets the panel clock format (string). Can be none, minutes, sec‐
308 onds. By default, minutes format is 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.
313 Examples:
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 for opening new windows (string). Can be
337 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 num-workspaces=6
355 defines the number of workspaces (unsigned integer). The user
356 can switch workspaces by using the binding+F1, F2 keys. If this
357 key is not set, fall back to one workspace.
358 cursor-theme=theme
360 sets the cursor theme (string).
361 cursor-size=24
363 sets the cursor size (unsigned integer).
364 lockscreen-icon=path
366 sets the path to lock screen icon image (string). (tablet shell
367 only)
368 lockscreen=path
370 sets the path to lock screen background image (string). (tablet
371 shell only)
372 homescreen=path
374 sets the path to home screen background image (string). (tablet
375 shell only)
376
378 There can be multiple launcher sections, one for each launcher.
379 icon=icon
381 sets the path to icon image (string). Svg images are not cur‐
382 rently supported.
383 path=program
385 sets the path to the program that is run by clicking on this
386 launcher (string). It is possible to pass arguments and envi‐
387 ronment variables to the program. For example:
388 path=GDK_BACKEND=wayland gnome-terminal --full-screen
390
392 There can be multiple output sections, each corresponding to one out‐
393 put. It is currently only recognized by the drm and x11 backends.
394 name=name
396 sets a name for the output (string). The backend uses the name
397 to identify the output. All X11 output names start with a letter
398 X. All Wayland output names start with the letters WL. The
399 available output names for DRM backend are listed in the weston-
400 launch(1) output. Examples of usage:
401 LVDS1 DRM backend, Laptop internal panel no.1
403 VGA1 DRM backend, VGA connector no.1
404 X1 X11 backend, X window no.1
405 WL1 Wayland backend, Wayland window no.1
406 See weston-drm(7) for more details.
408 mode=mode
410 sets the output mode (string). The mode parameter is handled
411 differently depending on the backend. On the X11 backend, it
412 just sets the WIDTHxHEIGHT of the weston window. The DRM back‐
413 end accepts different modes, along with an option of a modeline
414 string.
415 See weston-drm(7) for examples of modes-formats supported by DRM
417 backend.
418 transform=normal
420 The transformation applied to screen output (string). The trans‐
421 form key can be one of the following 8 strings:
422 normal Normal output.
424 90 90 degrees clockwise.
425 180 Upside down.
426 270 90 degrees counter clockwise.
427 flipped Horizontally flipped
428 flipped-90 Flipped and 90 degrees clockwise
429 flipped-180 Flipped upside down
430 flipped-270 Flipped and 90 degrees counter clockwise
431 scale=factor
433 The scaling multiplier applied to the entire output, in support
434 of high resolution ("HiDPI" or "retina") displays, that roughly
435 corresponds to the pixel ratio of the display's physical resolu‐
436 tion to the logical resolution. Applications that do not sup‐
437 port high resolution displays typically appear tiny and unread‐
438 able. Weston will scale the output of such applications by this
439 multiplier, to make them readable. Applications that do support
440 their own output scaling can draw their content in high resolu‐
441 tion, in which case they avoid compositor scaling. Weston will
442 not scale the output of such applications, and they are not
443 affected by this multiplier.
444 An integer, 1 by default, typically configured as 2 or higher
446 when needed, denoting the scaling multiplier for the output.
447 seat=name
449 The logical seat name that this output should be associated
450 with. If this is set then the seat's input will be confined to
451 the output that has the seat set on it. The expectation is that
452 this functionality will be used in a multiheaded environment
453 with a single compositor for multiple output and input configu‐
454 rations. The default seat is called "default" and will always be
455 present. This seat can be constrained like any other.
456 allow_hdcp=true
458 Allows HDCP support for this output. If set to true, HDCP can be
459 tried for the content-protection, provided by the backends, on
460 this output. By default, HDCP support is always allowed for an
461 output. The content-protection can actually be realized, only if
462 the hardware (source and sink) support HDCP, and the backend has
463 the implementation of content-protection protocol. Currently,
464 HDCP is supported by drm-backend.
465
467 path=/usr/libexec/weston-keyboard
468 sets the path of the on screen keyboard input method (string).
469
471 This section contains the following keys:
472 keymap_rules=evdev
474 sets the keymap rules file (string). Used to map layout and
475 model to input device.
476 keymap_model=pc105
478 sets the keymap model (string). See the Models section in xkey‐
479 board-config(7).
480 keymap_layout=us,de,gb
482 sets the comma separated list of keyboard layout codes (string).
483 See the Layouts section in xkeyboard-config(7).
484 keymap_variant=euro,,intl
486 sets the comma separated list of keyboard layout variants
487 (string). The number of variants must be the same as the number
488 of layouts above. See the Layouts section in xkeyboard-con‐
489 fig(7).
490 keymap_options=grp:alt_shift_toggle,grp_led:scroll
492 sets the keymap options (string). See the Options section in
493 xkeyboard-config(7).
494 repeat-rate=40
496 sets the rate of repeating keys in characters per second
497 (unsigned integer)
498 repeat-delay=400
500 sets the delay in milliseconds since key down until repeating
501 starts (unsigned integer)
502 numlock-on=false
504 sets the default state of the numlock on weston startup for the
505 backends which support it.
506 vt-switching=true
508 Whether to allow the use of Ctrl+Alt+Fn key combinations to
509 switch away from the compositor's virtual console.
510
512 Contains settings for the weston terminal application (weston-termi‐
513 nal). It allows to customize the font and shell of the command line
514 interface.
515 font=DejaVu Sans Mono
517 sets the font of the terminal (string). For a good experience it
518 is recommended to use monospace fonts. In case the font is not
519 found, the default one is used.
520 font-size=14
522 sets the size of the terminal font (unsigned integer).
523 term=xterm-256color
525 The terminal shell (string). Sets the $TERM variable.
526
528 path=/usr/bin/Xwayland
529 sets the path to the xserver to run (string).
530
532 command=/usr/bin/weston --backend=rdp-backend.so --shell=fullscreen-
533 shell.so --no-clients-resize
534 sets the command to start a fullscreen-shell server for screen
535 sharing (string).
536
538 weston(1), weston-bindings(7), weston-drm(7), xkeyboard-config(7)
539Weston 8.0.0 2019-03-26 weston.ini(5)