1weston.ini(5)                 File Formats Manual                weston.ini(5)
2
3
4

NAME

6       weston.ini - configuration file for Weston - the reference Wayland com‐
7       positor
8

INTRODUCTION

10       Weston obtains configuration from its command line parameters  and  the
11       configuration file described here.
12

DESCRIPTION

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
18           $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
24       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
29       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
33           [SectionHeader]
34           Key1=Value1
35           Key2=Value2
36               ...
37
38       The spaces are significant.  Comment lines are ignored:
39
40           #comment
41
42       The section headers are:
43
44           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
56       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

CORE SECTION

63       The core section is used to select the startup compositor  modules  and
64       general options.
65
66       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
71                 desktop-shell.so
72
73       xwayland=true
74              ask Weston to load the XWayland module (boolean).
75
76       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
80                 cms-colord.so
81                 screen-share.so
82
83       backend=headless-backend.so
84              overrides defaults backend. Available  backend  modules  in  the
85              /usr/lib64/libweston-10 directory are:
86
87                 drm-backend.so
88                 fbdev-backend.so
89                 headless-backend.so
90                 rdp-backend.so
91                 wayland-backend.so
92                 x11-backend.so
93
94       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
106       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
111       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
116              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
123       require-input=true
124              require an input device for launch
125
126       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
132       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
140       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
146                 remoting-plugin.so
147
148       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
153       color-management=true
154              Enables color management and requires using GL-renderer.   Bool‐
155              ean, defaults to false.
156
157              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
165

LIBINPUT SECTION

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
171       Available configuration are:
172
173       enable-tap=false
174              Enables tap to click on touchpad devices.
175
176       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
183       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
190       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
195       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
200       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
207       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
214       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
223       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
231       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
238       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
245       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
250       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
256              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
261              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
266       calibration_helper=/bin/echo
267              An optional calibration helper program to permanently save a new
268              touchscreen calibration. String, defaults to unset.
269
270              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
278              The program is invoked as:
279
280                 calibration_helper syspath m1 m2 m3 m4 m5 m6
281
282              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
287

SHELL SECTION

289       The  shell  section  is used to customize the compositor. Some keys may
290       not be handled by different shell plugins.
291
292       The entries that can appear in this section are:
293
294       client=file
295              sets the path for the shell client to run. If not specified  we‐
296              ston-desktop-shell is launched (string).
297
298       background-image=file
299              sets the path for the background image file (string).
300
301       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
315       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
319       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
324       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
329                 0xffff0000    Red
330                 0xff00ff00    Green
331                 0xff0000ff    Blue
332                 0x00ffffff    Fully transparent
333
334       panel-position=top
335              sets  the  position  of  the panel (string). Can be top, bottom,
336              left, right, none.
337
338       locking=true
339              enables screen locking (boolean).
340
341       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
345       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
349       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
353       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
357       allow-zap=true
358              whether the shell should quit when  the  Ctrl-Alt-Backspace  key
359              combination is pressed
360
361       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
368       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
373       cursor-theme=theme
374              sets the cursor theme (string).
375
376       cursor-size=24
377              sets the cursor size (unsigned integer).
378

LAUNCHER SECTION

380       There can be multiple launcher sections, one for each launcher.
381
382       icon=icon
383              sets  the  path  to icon image (string). Svg images are not cur‐
384              rently supported.
385
386       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
391                  path=GDK_BACKEND=wayland gnome-terminal --full-screen
392

OUTPUT SECTION

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
397       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
404                 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
409              See weston-drm(7) for more details.
410
411       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
418              See weston-drm(7) for examples of modes-formats supported by DRM
419              backend.
420
421       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
426                 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
435       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
448              An integer, 1 by default, typically configured as  2  or  higher
449              when needed, denoting the scaling multiplier for the output.
450
451       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
456       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
465       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
474       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

INPUT-METHOD SECTION

481       path=/usr/libexec/weston-keyboard
482              sets the path of the on screen keyboard input method (string).
483
484       overlay-keyboard=false
485              sets weston-keyboard as overlay panel.
486

KEYBOARD SECTION

488       This section contains the following keys:
489
490       keymap_rules=evdev
491              sets the keymap rules file (string).  Used  to  map  layout  and
492              model to input device.
493
494       keymap_model=pc105
495              sets  the keymap model (string). See the Models section in xkey‐
496              board-config(7).
497
498       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
502       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
508       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
512       repeat-rate=40
513              sets  the  rate  of repeating keys in characters per second (un‐
514              signed integer)
515
516       repeat-delay=400
517              sets the delay in milliseconds since key  down  until  repeating
518              starts (unsigned integer)
519
520       numlock-on=false
521              sets  the default state of the numlock on weston startup for the
522              backends which support it.
523
524       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

TERMINAL SECTION

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
533       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
538       font-size=14
539              sets the size of the terminal font (unsigned integer).
540
541       term=xterm-256color
542              The terminal shell (string). Sets the $TERM variable.
543

XWAYLAND SECTION

545       path=/usr/bin/Xwayland
546              sets the path to the xserver to run (string).
547

SCREEN-SHARE SECTION

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
554       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

AUTOLAUNCH SECTION

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
564       watch=false
565              If set to true, quit Weston after the  auto-launched  executable
566              exits. Set to false by default.
567

SEE ALSO

569       weston(1), weston-bindings(7), weston-drm(7), xkeyboard-config(7)
570
571
572
573Weston 10.0.1                     2019-03-26                     weston.ini(5)
Impressum