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

REPORTING BUGS

303       The  official  bug  tracker  is  at <https://github.com/google/xsecure
304       lock/issues/>.
305
307       The code is released unser the Apache 2.0  license.   See  the  LICENSE
308       file for more details.
309

SEE ALSO

311       xss-lock (1), xautolock (1).
312
313       The  README.md  file included with XSecureLock contains full documenta‐
314       tion.
315
316       The XSecureLock source code and all documentation may be downloaded  on
317       <https://github.com/google/xsecurelock/>.
318

AUTHORS

320       Rudolf Polzer.
321
322
323
324XSecureLock User Manual         April 15, 2019                  XSECURELOCK(1)
Impressum