1XSECURELOCK(1) XSECURELOCK(1)
2
6 XSecureLock - X11 screen lock utility
7
9 [options] xsecurelock [– command-to-run-when-locked]
10
12 XSecureLock is an X11 screen lock utility designed with the primary
13 goal of security.
14 It locks the current X11 session, and only allows unlocking if the user
16 authenticates to it (typically with the login password).
17 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
23 Options are set as environment variables prior to invoking XSecureLock;
24 the following variables are available:
25 • XSECURELOCK_AUTH: specifies the desired authentication module (the
27 part that displays the authentication prompt).
28 • XSECURELOCK_AUTHPROTO: specifies the desired authentication protocol
30 module (the part that talks to the system).
31 • XSECURELOCK_AUTH_BACKGROUND_COLOR: specifies the X11 color (see man‐
33 page of XParseColor) for the background of the auth dialog.
34 • 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 • XSECURELOCK_AUTH_SOUNDS: specifies whether to play sounds during au‐
39 thentication to indicate status. Sounds are defined as follows:
40 • High-pitch ascending: prompt for user input.
42 • High-pitch constant: an info message was displayed.
44 • Low-pitch descending: an error message was displayed.
46 • Medium-pitch ascending: authentication successful.
48 • XSECURELOCK_AUTH_FOREGROUND_COLOR: specifies the X11 color (see man‐
50 page of XParseColor) for the foreground text of the auth dialog.
51 • 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 • XSECURELOCK_AUTH_WARNING_COLOR: specifies the X11 color (see manpage
57 of XParseColor) for the warning text of the auth dialog.
58 • XSECURELOCK_BACKGROUND_COLOR: specifies the X11 color (see manpage of
60 XParseColor) for the background of the main and saver windows.
61 • XSECURELOCK_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 • XSECURELOCK_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 • XSECURELOCK_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 • XSECURELOCK_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 • XSECURELOCK_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 • XSECURELOCK_DATETIME_FORMAT: the date format to show. Defaults to
96 the locale settings. (see man date for possible formats)
97 • XSECURELOCK_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 • XSECURELOCK_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 • XSECURELOCK_DIM_ALPHA: Linear-space opacity to fade the screen to.
112 • XSECURELOCK_DIM_COLOR: X11 color to fade the screen to.
114 • XSECURELOCK_DIM_FPS: Target framerate to attain during the dimming
116 effect of dimmer. Ideally matches the display refresh rate.
117 • XSECURELOCK_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 • XSECURELOCK_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 • XSECURELOCK_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 • XSECURELOCK_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 • XSECURELOCK_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 • XSECURELOCK_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 • XSECURELOCK_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 • XSECURELOCK_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 • XSECURELOCK_IMAGE_DURATION_SECONDS: how long to show each still image
164 played by saver_mpv. Defaults to 1.
165 • XSECURELOCK_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 • XSECURELOCK_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 • XSECURELOCK_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 • XSECURELOCK_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 • XSECURELOCK_NO_XRANDR: disables multi monitor support using XRandR.
189 • XSECURELOCK_NO_XRANDR15: disables multi monitor support using XRandR
191 1.5 and fall back to XRandR 1.2. Not recommended.
192 • XSECURELOCK_PAM_SERVICE: pam service name. You should have a file
194 with that name in /etc/pam.d.
195 • XSECURELOCK_PASSWORD_PROMPT: Choose password prompt mode:
197 • asterisks: shows asterisks, like classic password prompts. This is
199 the least secure option because password length is visible.
200 ***_
202 *******_
203 • cursor: shows a cursor that jumps around on each key press. This
205 is the default.
206 ________|_______________________
208 ___________________|____________
209 • disco: 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 ┏(･o･)┛ ♪ ┗(･o･)┓ ♪ ┏(･o･)┛ ♪ ┗(･o･)┓ ♪ ┏(･o･)┛
215 ┗(･o･)┓ ♪ ┏(･o･)┛ ♪ ┏(･o･)┛ ♪ ┏(･o･)┛ ♪ ┏(･o･)┛
216 • emoji: shows an emoji, changing which one on each key press. Re‐
218 quires a font that can handle emoji, and FontConfig.
219 👍
221 🎶
222 💕
223 • emoticon: shows an ascii emoticon, changing which one on each key
225 press.
226 :-O
228 d-X
229 X-\
230 • hidden: 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 • kaomoji: shows a kaomoji (Japanese emoticon), changing which one on
238 each key press. Requires a Japanese font, and FontConfig.
239 (͡°͜ʖ͡°)
241 (＾ｕ＾)
242 ¯\_(ツ)_/¯
243 • time: 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 1559655410.922329
251 • time_hex: same as time, but in microseconds and hexadecimal. “Be‐
253 cause we can”.
254 0x58a7f92bd7359
256 • XSECURELOCK_SAVER: specifies the desired screen saver module.
258 • XSECURELOCK_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 • XSECURELOCK_SHOW_DATETIME: whether to show local date and time on the
265 login. Disabled by default.
266 • XSECURELOCK_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 • XSECURELOCK_SHOW_USERNAME: whether to show the username on the login
272 screen of auth_x11.
273 • XSECURELOCK_SINGLE_AUTH_WINDOW: whether to show only a single auth
275 window from auth_x11, as opposed to one per screen.
276 • XSECURELOCK_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 • XSECURELOCK_VIDEOS_FLAGS: flags to append when invoking mpv/mplayer
283 with saver_mpv or saver_mplayer. Defaults to empty.
284 • XSECURELOCK_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 • XSECURELOCK_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 • XSECURELOCK_XSCREENSAVER_PATH: Location where XScreenSaver hacks are
296 installed for use by saver_xscreensaver.
297 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
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
311 xss-lock (1), xautolock (1).
312 The README.md file included with XSecureLock contains full documenta‐
314 tion.
315 The XSecureLock source code and all documentation may be downloaded on
317 <https://github.com/google/xsecurelock/>.
318
320 Rudolf Polzer.
321XSecureLock User Manual April 15, 2019 XSECURELOCK(1)