1XSECURELOCK(1)                                                  XSECURELOCK(1)
2
3
4

NAME

6       XSecureLock - X11 screen lock utility
7

SYNPOSIS

9       [options] xsecurelock [– command-to-run-when-locked]
10

DESCRIPTION

12       XSecureLock  is  an  X11  screen lock utility designed with the primary
13       goal of security.
14
15       It locks the current X11 session, and only allows unlocking if the user
16       authenticates to it (typically with the login password).
17
18       While  locked,  it can launch a screen saver process and then waits for
19       input events.  Upon an input event, it displays a login dialog to allow
20       for unlocking.
21

OPTIONS

23       Options are set as environment variables prior to invoking XSecureLock;
24       the following variables are available:
25
26       • XSECURELOCK_AUTH: specifies the desired  authentication  module  (the
27         part that displays the authentication prompt).
28
29       • XSECURELOCK_AUTHPROTO:  specifies the desired authentication protocol
30         module (the part that talks to the system).
31
32       • XSECURELOCK_AUTH_BACKGROUND_COLOR: specifies the X11 color (see  man‐
33         page of XParseColor) for the background of the auth dialog.
34
35       • XSECURELOCK_AUTH_CURSOR_BLINK:  if  set, the cursor will blink in the
36         auth dialog.  Enabled by default, can be set to 0 to disable.
37
38       • XSECURELOCK_AUTH_SOUNDS: specifies whether to play sounds during  au‐
39         thentication to indicate status.  Sounds are defined as follows:
40
41         • High-pitch ascending: prompt for user input.
42
43         • High-pitch constant: an info message was displayed.
44
45         • Low-pitch descending: an error message was displayed.
46
47         • Medium-pitch ascending: authentication successful.
48
49       • XSECURELOCK_AUTH_FOREGROUND_COLOR:  specifies the X11 color (see man‐
50         page of XParseColor) for the foreground text of the auth dialog.
51
52       • XSECURELOCK_AUTH_TIMEOUT: specifies the time (in seconds) to wait for
53         response  to  a  prompt by auth_x11 before giving up and reverting to
54         the screen saver.
55
56       • XSECURELOCK_AUTH_WARNING_COLOR: specifies the X11 color (see  manpage
57         of XParseColor) for the warning text of the auth dialog.
58
59       • XSECURELOCK_BLANK_TIMEOUT:  specifies  the  time  (in seconds) before
60         telling X11 to fully blank the screen; a negative value disables  X11
61         blanking.   The time is measured since the closing of the auth window
62         or xsecurelock startup.  Setting this to 0 is rather nonsensical,  as
63         key-release  events (e.g. from the keystroke to launch xsecurelock or
64         from pressing escape to close the auth dialog)  always  wake  up  the
65         screen.
66
67       • XSECURELOCK_BLANK_DPMS_STATE:  specifies  which DPMS state to put the
68         screen in when blanking (one of standby, suspend, off and  on,  where
69         “on” means to not invoke DPMS at all).
70
71       • XSECURELOCK_BURNIN_MITIGATION:  specifies  the  number  of pixels the
72         prompt of auth_x11 may be moved at startup to mitigate possible burn-
73         in  effects  due  to  the  auth  dialog  being displayed all the time
74         (e.g. when spurious mouse events wake up the screen all the time).
75
76       • XSECURELOCK_BURNIN_MITIGATION_DYNAMIC: if set to  a  non-zero  value,
77         auth_x11  will  move the prompt while it is being displayed, but stay
78         within the bounds of  XSECURELOCK_BURNIN_MITIGATION.   The  value  of
79         this  variable is the maximum allowed shift per screen refresh.  This
80         mitigates short-term burn-in effects but is probably annoying to most
81         users, and thus disabled by default.
82
83       • XSECURELOCK_COMPOSITE_OBSCURER: create a second full-screen window to
84         obscure window content in case a running compositor  unmaps  its  own
85         window.   Helps  with some instances of bad compositor behavior (such
86         as compositor crashes/restarts, but also compton has been  caught  at
87         drawing notification icons above the screen locker when not using the
88         GLX backend), should prevent compositors from unredirecting as it’s 1
89         pixel  smaller  than the screen from every side, and should otherwise
90         be harmless, so it’s enabled by default.
91
92       • XSECURELOCK_DATETIME_FORMAT: the date format to  show.   Defaults  to
93         the locale settings.
94
95       • XSECURELOCK_DEBUG_ALLOW_LOCKING_IF_INEFFECTIVE: Normally we don’t al‐
96         low locking sessions that are likely not any useful to lock, such  as
97         the X11 part of a Wayland session (one could still use Wayland appli‐
98         catione when locked) or VNC sessions (as it’d only  lock  the  server
99         side  session  while  users will likely think they locked the client,
100         allowing for an easy escape).  These checks can be bypassed  by  set‐
101         ting  this  variable  to 1.  Not recommended other than for debugging
102         XSecureLock itself via such connections.
103
104       • XSECURELOCK_DEBUG_WINDOW_INFO: When complaining about another  window
105         misbehaving,  print  not  just the window ID but also some info about
106         it.  Uses the xwininfo and xprop tools.
107
108       • XSECURELOCK_DIM_ALPHA: Linear-space opacity to fade the screen to.
109
110       • XSECURELOCK_DIM_COLOR: X11 color to fade the screen to.
111
112       • XSECURELOCK_DIM_FPS: Target framerate to attain  during  the  dimming
113         effect of dimmer.  Ideally matches the display refresh rate.
114
115       • XSECURELOCK_DIM_MAX_FILL_SIZE:  Maximum  size (in width or height) to
116         fill at once using an XFillRectangle call.  Low values may cause per‐
117         formance  loss  or noticeable tearing during dimming; high values may
118         cause crashes or hangs with some graphics drivers  or  a  temporarily
119         unresponsive X server.
120
121       • XSECURELOCK_DIM_OVERRIDE_COMPOSITOR_DETECTION:  When set to 1, always
122         try to use transparency for dimming; when set  to  0,  always  use  a
123         dither  pattern.   Default is to autodetect whether transparency will
124         likely work.
125
126       • XSECURELOCK_DIM_TIME_MS: Milliseconds to dim for when above  xss-lock
127         command  line  with dimmer is used; also used by wait_nonidle to know
128         when to assume dimming and waiting has finished and exit.
129
130       • XSECURELOCK_DISCARD_FIRST_KEYPRESS: If set to 0, the key  pressed  to
131         stop  the  screen  saver and spawn the auth child is sent to the auth
132         child (and thus becomes part of the password entry).  By  default  we
133         always discard the key press that started the authentication flow, to
134         prevent users from getting used to type their  password  on  a  blank
135         screen (which could be just powered off and have a chat client behind
136         or similar).
137
138       • XSECURELOCK_FONT: X11 or FontConfig font name to  use  for  auth_x11.
139         You  can  get  a list of supported font names by running xlsfonts and
140         fc-list.
141
142       • XSECURELOCK_FORCE_GRAB: When grabbing fails, try  stealing  the  grab
143         from  other  windows (a value of 2 steals from all descendants of the
144         root window, while a value of 1 only  steals  from  client  windows).
145         This  works  only sometimes and is incompatible with many window man‐
146         agers, so use with care.  See the “Forcing Grabs” section  below  for
147         details.
148
149       • XSECURELOCK_GLOBAL_SAVER:  specifies  the desired global screen saver
150         module (by default this is a multiplexer that runs  XSECURELOCK_SAVER
151         on each screen).
152
153       • XSECURELOCK_IDLE_TIMERS:  comma-separated  list of idle time counters
154         used by until_nonidle.  Typical values are either  empty  (relies  on
155         the X Screen Saver extension instead), “IDLETIME” and “DEVICEIDLETIME
156         ” where n is an XInput device index (run xinput  to  see  them).   If
157         multiple time counters are specified, the idle time is the minimum of
158         them all.  All listed timers must have the same unit.
159
160       • XSECURELOCK_IMAGE_DURATION_SECONDS: how long to show each still image
161         played by saver_mpv.  Defaults to 1.
162
163       • XSECURELOCK_KEY_%s_COMMAND  where  %s  is  the  name of an X11 keysym
164         (find using xev): a shell command to execute when the  specified  key
165         is  pressed.   Useful e.g. for media player control.  Beware: be cau‐
166         tious about what you run with this, as it may yield attackers control
167         over your computer.
168
169       • XSECURELOCK_LIST_VIDEOS_COMMAND:  shell  command  to  list  all video
170         files to potentially play by saver_mpv or saver_mplayer.  Defaults to
171         find ~/Videos -type f.
172
173       • XSECURELOCK_NO_COMPOSITE:  disables  covering  the  composite overlay
174         window.  This switches to a more traditional way of locking, but  may
175         allow  desktop notifications to be visible on top of the screen lock.
176         Not recommended.
177
178       • XSECURELOCK_NO_PAM_RHOST: do not set PAM_RHOST to localhost,  despite
179         recommendation (http://www.linux-pam.org/Linux-PAM-html/adg-security-
180         user-identity.html) to do so by the Linux-PAM Application Developers’
181         Guide.   This  may work around bugs in third-party PAM authentication
182         modules.  If this solves a problem  for  you,  please  report  a  bug
183         against said PAM module.
184
185       • XSECURELOCK_NO_XRANDR: disables multi monitor support using XRandR.
186
187       • XSECURELOCK_NO_XRANDR15:  disables multi monitor support using XRandR
188         1.5 and fall back to XRandR 1.2.  Not recommended.
189
190       • XSECURELOCK_PAM_SERVICE: pam service name.  You should  have  a  file
191         with that name in /etc/pam.d.
192
193       • XSECURELOCK_PASSWORD_PROMPT: Choose password prompt mode:
194
195         • asterisks: shows asterisks, like classic password prompts.  This is
196           the least secure option because password length is visible.
197
198                  ***_
199                  *******_
200
201         • cursor: shows a cursor that jumps around on each key  press.   This
202           is the default.
203
204                  ________|_______________________
205                  ___________________|____________
206
207         • disco:  shows  dancers,  which dance around on each key press.  Re‐
208           quires a font that can handle Unicode line drawing characters,  and
209           FontConfig.
210
211                  ┏(・o・)┛ ♪ ┗(・o・)┓ ♪ ┏(・o・)┛ ♪ ┗(・o・)┓ ♪ ┏(・o・)┛
212                  ┗(・o・)┓ ♪ ┏(・o・)┛ ♪ ┏(・o・)┛ ♪ ┏(・o・)┛ ♪ ┏(・o・)┛
213
214         • emoji:  shows  an emoji, changing which one on each key press.  Re‐
215           quires a font that can handle emoji, and FontConfig.
216
217                  👍
218                  🎶
219                  💕
220
221         • emoticon: shows an ascii emoticon, changing which one on  each  key
222           press.
223
224                  :-O
225                  d-X
226                  X-\
227
228         • hidden:  completely hides the password, and there’s no feedback for
229           keypresses.  This would almost be most secure - however as it gives
230           no  feedback to input whatsoever, you may not be able to notice ac‐
231           cidentally typing to another computer and sending your password  to
232           some chatroom.
233
234         • kaomoji: shows a kaomoji (Japanese emoticon), changing which one on
235           each key press.  Requires a Japanese font, and FontConfig.
236
237                  (͡°͜ʖ͡°)
238                  (^u^)
239                  ¯\_(ツ)_/¯
240
241         • time: shows the current time since the  epoch  on  each  keystroke.
242           This may be the most secure mode, as it gives feedback to keystroke
243           based exclusively on public information, and does  not  carry  over
244           any  state  between  keystrokes  whatsoever - not even some form of
245           randomness.
246
247                  1559655410.922329
248
249         • time_hex: same as time, but in microseconds and hexadecimal.   “Be‐
250           cause we can”.
251
252                  0x58a7f92bd7359
253
254       • XSECURELOCK_SAVER: specifies the desired screen saver module.
255
256       • XSECURELOCK_SAVER_RESET_ON_AUTH_CLOSE: specifies whether to reset the
257         saver module when the auth dialog closes.  Resetting is done by send‐
258         ing  SIGUSR1 to the saver, which may either just terminate, or handle
259         this specifically to do a cheaper reset.
260
261       • XSECURELOCK_SHOW_DATETIME: whether to show local date and time on the
262         login.  Disabled by default.
263
264       • XSECURELOCK_SHOW_HOSTNAME:  whether to show the hostname on the login
265         screen of auth_x11.  Possible values are 0 for not showing the  host‐
266         name, 1 for showing the short form, and 2 for showing the long form.
267
268       • XSECURELOCK_SHOW_USERNAME:  whether to show the username on the login
269         screen of auth_x11.
270
271       • XSECURELOCK_SINGLE_AUTH_WINDOW: whether to show only  a  single  auth
272         window from auth_x11, as opposed to one per screen.
273
274       • XSECURELOCK_SWITCH_USER_COMMAND:  shell command to execute when Win-O
275         or Ctrl-Alt-O are pressed (think “other user”).  Typical values could
276         be  lxdm -c USER_SWITCH, dm-tool switch-to-greeter, gdmflexiserver or
277         kdmctl reserve, depending on your desktop environment.
278
279       • XSECURELOCK_WAIT_TIME_MS: Milliseconds to wait after dimming (and be‐
280         fore locking) when above xss-lock command line is used.  Should be at
281         least as large as the period time set using “xset s”.  Also  used  by
282         wait_nonidle  to know when to assume dimming and waiting has finished
283         and exit.
284
285       • XSECURELOCK_XSCREENSAVER_PATH: Location where XScreenSaver hacks  are
286         installed for use by saver_xscreensaver.
287
288       • XSECURELOCK_XSCREENSAVER_PATH:  Location where XScreenSaver hacks are
289         installed for use by saver_xscreensaver.
290
291       Additionally, XSecureLock spawns  the  command-to-run-when-locked  once
292       locking  is  complete;  this can be used as a notification mechanism if
293       desired.
294

REPORTING BUGS

296       The official  bug  tracker  is  at  <https://github.com/google/xsecure
297       lock/issues/>.
298
300       The  code  is  released  unser the Apache 2.0 license.  See the LICENSE
301       file for more details.
302

SEE ALSO

304       xss-lock (1), xautolock (1).
305
306       The README.md file included with XSecureLock contains  full  documenta‐
307       tion.
308
309       The  XSecureLock source code and all documentation may be downloaded on
310       <https://github.com/google/xsecurelock/>.
311

AUTHORS

313       Rudolf Polzer.
314
315
316
317XSecureLock User Manual         April 15, 2019                  XSECURELOCK(1)
Impressum