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

CORE SECTION

62       The core section is used to select the startup compositor  modules  and
63       general options.
64
65       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
70                 desktop-shell.so
71
72       xwayland=true
73              ask Weston to load the XWayland module (boolean).
74
75       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
79                 cms-colord.so
80                 screen-share.so
81
82       backend=headless-backend.so
83              overrides defaults backend. Available  backend  modules  in  the
84              /usr/lib64/libweston-8 directory are:
85
86                 drm-backend.so
87                 fbdev-backend.so
88                 headless-backend.so
89                 rdp-backend.so
90                 wayland-backend.so
91                 x11-backend.so
92
93       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
105       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
110       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
115              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
122       require-input=true
123              require an input device for launch
124
125       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
131       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
139       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
145                 remoting-plugin.so
146
147       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
152

LIBINPUT SECTION

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
158       Available configuration are:
159
160       enable-tap=false
161              Enables tap to click on touchpad devices.
162
163       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
170       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
177       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
182       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
187       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
194       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
201       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
210       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
218       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
225       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
232       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
237       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
243              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
248              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
253       calibration_helper=/bin/echo
254              An optional calibration helper program to permanently save a new
255              touchscreen calibration. String, defaults to unset.
256
257              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
265              The program is invoked as:
266
267                 calibration_helper syspath m1 m2 m3 m4 m5 m6
268
269              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
274

SHELL SECTION

276       The shell section is used to customize the compositor.  Some  keys  may
277       not be handled by different shell plugins.
278
279       The entries that can appear in this section are:
280
281       client=file
282              sets  the  path  for  the  shell client to run. If not specified
283              weston-desktop-shell is launched (string).
284
285       background-image=file
286              sets the path for the background image file (string).
287
288       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
302       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
306       clock-format=format
307              sets the panel clock format (string). Can be none, minutes, sec‐
308              onds.  By default, minutes format is used.
309
310       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
315                 0xffff0000    Red
316                 0xff00ff00    Green
317                 0xff0000ff    Blue
318                 0x00ffffff    Fully transparent
319
320       panel-position=top
321              sets  the  position  of  the panel (string). Can be top, bottom,
322              left, right, none.
323
324       locking=true
325              enables screen locking (boolean).
326
327       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
331       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
335       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
339       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
343       allow-zap=true
344              whether the shell should quit when  the  Ctrl-Alt-Backspace  key
345              combination is pressed
346
347       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
354       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
359       cursor-theme=theme
360              sets the cursor theme (string).
361
362       cursor-size=24
363              sets the cursor size (unsigned integer).
364
365       lockscreen-icon=path
366              sets  the path to lock screen icon image (string). (tablet shell
367              only)
368
369       lockscreen=path
370              sets the path to lock screen background image (string).  (tablet
371              shell only)
372
373       homescreen=path
374              sets  the path to home screen background image (string). (tablet
375              shell only)
376

LAUNCHER SECTION

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

OUTPUT SECTION

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
395       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
402                 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
407              See weston-drm(7) for more details.
408
409       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
416              See weston-drm(7) for examples of modes-formats supported by DRM
417              backend.
418
419       transform=normal
420              The transformation applied to screen output (string). The trans‐
421              form key can be one of the following 8 strings:
422
423                 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
432       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
445              An integer, 1 by default, typically configured as  2  or  higher
446              when needed, denoting the scaling multiplier for the output.
447
448       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
457       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

INPUT-METHOD SECTION

467       path=/usr/libexec/weston-keyboard
468              sets the path of the on screen keyboard input method (string).
469

KEYBOARD SECTION

471       This section contains the following keys:
472
473       keymap_rules=evdev
474              sets  the  keymap  rules  file  (string). Used to map layout and
475              model to input device.
476
477       keymap_model=pc105
478              sets the keymap model (string). See the Models section in  xkey‐
479              board-config(7).
480
481       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
485       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
491       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
495       repeat-rate=40
496              sets the  rate  of  repeating  keys  in  characters  per  second
497              (unsigned integer)
498
499       repeat-delay=400
500              sets  the  delay  in milliseconds since key down until repeating
501              starts (unsigned integer)
502
503       numlock-on=false
504              sets the default state of the numlock on weston startup for  the
505              backends which support it.
506
507       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

TERMINAL SECTION

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
516       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
521       font-size=14
522              sets the size of the terminal font (unsigned integer).
523
524       term=xterm-256color
525              The terminal shell (string). Sets the $TERM variable.
526

XWAYLAND SECTION

528       path=/usr/bin/Xwayland
529              sets the path to the xserver to run (string).
530

SCREEN-SHARE SECTION

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

SEE ALSO

538       weston(1), weston-bindings(7), weston-drm(7), xkeyboard-config(7)
539
540
541
542Weston 8.0.0                      2019-03-26                     weston.ini(5)
Impressum