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_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 • 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 • 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 • 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 • 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 • XSECURELOCK_DATETIME_FORMAT: the date format to show. Defaults to
93 the locale settings.
94 • 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 • 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 • XSECURELOCK_DIM_ALPHA: Linear-space opacity to fade the screen to.
109 • XSECURELOCK_DIM_COLOR: X11 color to fade the screen to.
111 • XSECURELOCK_DIM_FPS: Target framerate to attain during the dimming
113 effect of dimmer. Ideally matches the display refresh rate.
114 • 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 • 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 • 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 • 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 • 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 • 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 • 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 • 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 • XSECURELOCK_IMAGE_DURATION_SECONDS: how long to show each still image
161 played by saver_mpv. Defaults to 1.
162 • 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 • 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 • 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 • 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 • XSECURELOCK_NO_XRANDR: disables multi monitor support using XRandR.
186 • XSECURELOCK_NO_XRANDR15: disables multi monitor support using XRandR
188 1.5 and fall back to XRandR 1.2. Not recommended.
189 • XSECURELOCK_PAM_SERVICE: pam service name. You should have a file
191 with that name in /etc/pam.d.
192 • XSECURELOCK_PASSWORD_PROMPT: Choose password prompt mode:
194 • asterisks: shows asterisks, like classic password prompts. This is
196 the least secure option because password length is visible.
197 ***_
199 *******_
200 • cursor: shows a cursor that jumps around on each key press. This
202 is the default.
203 ________|_______________________
205 ___________________|____________
206 • 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 ┏(･o･)┛ ♪ ┗(･o･)┓ ♪ ┏(･o･)┛ ♪ ┗(･o･)┓ ♪ ┏(･o･)┛
212 ┗(･o･)┓ ♪ ┏(･o･)┛ ♪ ┏(･o･)┛ ♪ ┏(･o･)┛ ♪ ┏(･o･)┛
213 • emoji: shows an emoji, changing which one on each key press. Re‐
215 quires a font that can handle emoji, and FontConfig.
216 👍
218 🎶
219 💕
220 • emoticon: shows an ascii emoticon, changing which one on each key
222 press.
223 :-O
225 d-X
226 X-\
227 • 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 • kaomoji: shows a kaomoji (Japanese emoticon), changing which one on
235 each key press. Requires a Japanese font, and FontConfig.
236 (͡°͜ʖ͡°)
238 (＾ｕ＾)
239 ¯\_(ツ)_/¯
240 • 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 1559655410.922329
248 • time_hex: same as time, but in microseconds and hexadecimal. “Be‐
250 cause we can”.
251 0x58a7f92bd7359
253 • XSECURELOCK_SAVER: specifies the desired screen saver module.
255 • 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 • XSECURELOCK_SHOW_DATETIME: whether to show local date and time on the
262 login. Disabled by default.
263 • 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 • XSECURELOCK_SHOW_USERNAME: whether to show the username on the login
269 screen of auth_x11.
270 • XSECURELOCK_SINGLE_AUTH_WINDOW: whether to show only a single auth
272 window from auth_x11, as opposed to one per screen.
273 • 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 • 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 • XSECURELOCK_XSCREENSAVER_PATH: Location where XScreenSaver hacks are
286 installed for use by saver_xscreensaver.
287 • XSECURELOCK_XSCREENSAVER_PATH: Location where XScreenSaver hacks are
289 installed for use by saver_xscreensaver.
290 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
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
304 xss-lock (1), xautolock (1).
305 The README.md file included with XSecureLock contains full documenta‐
307 tion.
308 The XSecureLock source code and all documentation may be downloaded on
310 <https://github.com/google/xsecurelock/>.
311
313 Rudolf Polzer.
314XSecureLock User Manual April 15, 2019 XSECURELOCK(1)