Ubuntu Manpage: XSecureLock - X11 screen lock utility

NAME

       XSecureLock - X11 screen lock utility

SYNPOSIS

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

DESCRIPTION

       XSecureLock is an X11 screen lock utility designed with the primary goal of security.

       It  locks  the  current X11 session, and only allows unlocking if the user authenticates to it (typically
       with the login password).

       While locked, it can launch a screen saver process and then waits for input events.  Upon an input event,
       it displays a login dialog to allow for unlocking.

OPTIONS

Options are set as environment variables prior to invoking XSecureLock; the following variables are
available:

• XSECURELOCK_AUTH: specifies the desired authentication module (the part that displays the
authentication prompt).

• XSECURELOCK_AUTHPROTO: specifies the desired authentication protocol module (the part that talks to the
system).

• XSECURELOCK_AUTH_BACKGROUND_COLOR: specifies the X11 color (see manpage of XParseColor) for the
background of the auth dialog.

• XSECURELOCK_AUTH_CURSOR_BLINK: if set, the cursor will blink in the auth dialog. Enabled by default,
can be set to 0 to disable.

• XSECURELOCK_AUTH_SOUNDS: specifies whether to play sounds during authentication to indicate status.
Sounds are defined as follows:

• High-pitch ascending: prompt for user input.

• High-pitch constant: an info message was displayed.

• Low-pitch descending: an error message was displayed.

• Medium-pitch ascending: authentication successful.

• XSECURELOCK_AUTH_FOREGROUND_COLOR: specifies the X11 color (see manpage of XParseColor) for the
foreground text of the auth dialog.

• XSECURELOCK_AUTH_TIMEOUT: specifies the time (in seconds) to wait for response to a prompt by auth_x11
before giving up and reverting to the screen saver.

• XSECURELOCK_AUTH_WARNING_COLOR: specifies the X11 color (see manpage of XParseColor) for the warning
text of the auth dialog.

• XSECURELOCK_BACKGROUND_COLOR: specifies the X11 color (see manpage of XParseColor) for the background
of the main and saver windows.

• XSECURELOCK_BLANK_TIMEOUT: specifies the time (in seconds) before telling X11 to fully blank the
screen; a negative value disables X11 blanking. The time is measured since the closing of the auth
window or xsecurelock startup. Setting this to 0 is rather nonsensical, as key-release events
(e.g. from the keystroke to launch xsecurelock or from pressing escape to close the auth dialog) always
wake up the screen.

• XSECURELOCK_BLANK_DPMS_STATE: specifies which DPMS state to put the screen in when blanking (one of
standby, suspend, off and on, where “on” means to not invoke DPMS at all).

• XSECURELOCK_BURNIN_MITIGATION: specifies the number of pixels the prompt of auth_x11 may be moved at
startup to mitigate possible burn-in effects due to the auth dialog being displayed all the time
(e.g. when spurious mouse events wake up the screen all the time).

• XSECURELOCK_BURNIN_MITIGATION_DYNAMIC: if set to a non-zero value, auth_x11 will move the prompt while
it is being displayed, but stay within the bounds of XSECURELOCK_BURNIN_MITIGATION. The value of this
variable is the maximum allowed shift per screen refresh. This mitigates short-term burn-in effects
but is probably annoying to most users, and thus disabled by default.

• XSECURELOCK_COMPOSITE_OBSCURER: create a second full-screen window to obscure window content in case a
running compositor unmaps its own window. Helps with some instances of bad compositor behavior (such
as compositor crashes/restarts, but also compton has been caught at drawing notification icons above
the screen locker when not using the GLX backend), should prevent compositors from unredirecting as
it’s 1 pixel smaller than the screen from every side, and should otherwise be harmless, so it’s enabled
by default.

• XSECURELOCK_DATETIME_FORMAT: the date format to show. Defaults to the locale settings. (see man date
for possible formats)

• XSECURELOCK_DEBUG_ALLOW_LOCKING_IF_INEFFECTIVE: Normally we don’t allow locking sessions that are
likely not any useful to lock, such as the X11 part of a Wayland session (one could still use Wayland
applicatione when locked) or VNC sessions (as it’d only lock the server side session while users will
likely think they locked the client, allowing for an easy escape). These checks can be bypassed by
setting this variable to 1. Not recommended other than for debugging XSecureLock itself via such
connections.

• XSECURELOCK_DEBUG_WINDOW_INFO: When complaining about another window misbehaving, print not just the
window ID but also some info about it. Uses the xwininfo and xprop tools.

• XSECURELOCK_DIM_ALPHA: Linear-space opacity to fade the screen to.

• XSECURELOCK_DIM_COLOR: X11 color to fade the screen to.

• XSECURELOCK_DIM_FPS: Target framerate to attain during the dimming effect of dimmer. Ideally matches
the display refresh rate.

• XSECURELOCK_DIM_MAX_FILL_SIZE: Maximum size (in width or height) to fill at once using an
XFillRectangle call. Low values may cause performance loss or noticeable tearing during dimming; high
values may cause crashes or hangs with some graphics drivers or a temporarily unresponsive X server.

• XSECURELOCK_DIM_OVERRIDE_COMPOSITOR_DETECTION: When set to 1, always try to use transparency for
dimming; when set to 0, always use a dither pattern. Default is to autodetect whether transparency
will likely work.

• XSECURELOCK_DIM_TIME_MS: Milliseconds to dim for when above xss-lock command line with dimmer is used;
also used by wait_nonidle to know when to assume dimming and waiting has finished and exit.

• XSECURELOCK_DISCARD_FIRST_KEYPRESS: If set to 0, the key pressed to stop the screen saver and spawn the
auth child is sent to the auth child (and thus becomes part of the password entry). By default we
always discard the key press that started the authentication flow, to prevent users from getting used
to type their password on a blank screen (which could be just powered off and have a chat client behind
or similar).

• XSECURELOCK_FONT: X11 or FontConfig font name to use for auth_x11. You can get a list of supported
font names by running xlsfonts and fc-list.

• XSECURELOCK_FORCE_GRAB: When grabbing fails, try stealing the grab from other windows (a value of 2
steals from all descendants of the root window, while a value of 1 only steals from client windows).
This works only sometimes and is incompatible with many window managers, so use with care. See the
“Forcing Grabs” section below for details.

• XSECURELOCK_GLOBAL_SAVER: specifies the desired global screen saver module (by default this is a
multiplexer that runs XSECURELOCK_SAVER on each screen).

• XSECURELOCK_IDLE_TIMERS: comma-separated list of idle time counters used by until_nonidle. Typical
values are either empty (relies on the X Screen Saver extension instead), “IDLETIME” and
“DEVICEIDLETIME ” where n is an XInput device index (run xinput to see them). If multiple time
counters are specified, the idle time is the minimum of them all. All listed timers must have the same
unit.

• XSECURELOCK_IMAGE_DURATION_SECONDS: how long to show each still image played by saver_mpv. Defaults to
1.

• XSECURELOCK_KEY_%s_COMMAND where %s is the name of an X11 keysym (find using xev): a shell command to
execute when the specified key is pressed. Useful e.g. for media player control. Beware: be cautious
about what you run with this, as it may yield attackers control over your computer.

• XSECURELOCK_LIST_VIDEOS_COMMAND: shell command to list all video files to potentially play by saver_mpv
or saver_mplayer. Defaults to find ~/Videos -type f.

• XSECURELOCK_NO_COMPOSITE: disables covering the composite overlay window. This switches to a more
traditional way of locking, but may allow desktop notifications to be visible on top of the screen
lock. Not recommended.

• XSECURELOCK_NO_PAM_RHOST: do not set PAM_RHOST to localhost, despite http://www.linux-pam.org/Linux-
PAM-html/adg-security-user-identity.html recommendation to do so by the Linux-PAM Application
Developers’ Guide. This may work around bugs in third-party PAM authentication modules. If this
solves a problem for you, please report a bug against said PAM module.

• XSECURELOCK_NO_XRANDR: disables multi monitor support using XRandR.

• XSECURELOCK_NO_XRANDR15: disables multi monitor support using XRandR 1.5 and fall back to XRandR 1.2.
Not recommended.

• XSECURELOCK_PAM_SERVICE: pam service name. You should have a file with that name in /etc/pam.d.

• XSECURELOCK_PASSWORD_PROMPT: Choose password prompt mode:

• asterisks: shows asterisks, like classic password prompts. This is the least secure option because
password length is visible.

***_
*******_

• cursor: shows a cursor that jumps around on each key press. This is the default.

________|_______________________
___________________|____________

• disco: shows dancers, which dance around on each key press. Requires a font that can handle Unicode
line drawing characters, and FontConfig.

┏(･o･)┛ ♪ ┗(･o･)┓ ♪ ┏(･o･)┛ ♪ ┗(･o･)┓ ♪ ┏(･o･)┛
┗(･o･)┓ ♪ ┏(･o･)┛ ♪ ┏(･o･)┛ ♪ ┏(･o･)┛ ♪ ┏(･o･)┛

• emoji: shows an emoji, changing which one on each key press. Requires a font that can handle emoji,
and FontConfig.

👍
🎶
💕

• emoticon: shows an ascii emoticon, changing which one on each key press.

:-O
d-X
X-\

• hidden: completely hides the password, and there’s no feedback for keypresses. This would almost be
most secure - however as it gives no feedback to input whatsoever, you may not be able to notice
accidentally typing to another computer and sending your password to some chatroom.

• kaomoji: shows a kaomoji (Japanese emoticon), changing which one on each key press. Requires a
Japanese font, and FontConfig.

(͡°͜ʖ͡°)
(＾ｕ＾)
¯\_(ツ)_/¯

• time: shows the current time since the epoch on each keystroke. This may be the most secure mode, as
it gives feedback to keystroke based exclusively on public information, and does not carry over any
state between keystrokes whatsoever - not even some form of randomness.

1559655410.922329

• time_hex: same as time, but in microseconds and hexadecimal. “Because we can”.

0x58a7f92bd7359

• XSECURELOCK_SAVER: specifies the desired screen saver module.

• XSECURELOCK_SAVER_RESET_ON_AUTH_CLOSE: specifies whether to reset the saver module when the auth dialog
closes. Resetting is done by sending SIGUSR1 to the saver, which may either just terminate, or handle
this specifically to do a cheaper reset.

• XSECURELOCK_SHOW_DATETIME: whether to show local date and time on the login. Disabled by default.

• XSECURELOCK_SHOW_HOSTNAME: whether to show the hostname on the login screen of auth_x11. Possible
values are 0 for not showing the hostname, 1 for showing the short form, and 2 for showing the long
form.

• XSECURELOCK_SHOW_KEYBOARD_LAYOUT: whether to show the name of the current keyboard layout. Enabled by
default.

• XSECURELOCK_SHOW_USERNAME: whether to show the username on the login screen of auth_x11.

• XSECURELOCK_SINGLE_AUTH_WINDOW: whether to show only a single auth window from auth_x11, as opposed to
one per screen.

• XSECURELOCK_SWITCH_USER_COMMAND: shell command to execute when Win-O or Ctrl-Alt-O are pressed (think
“other user”). Typical values could be lxdm -c USER_SWITCH, dm-tool switch-to-greeter, gdmflexiserver
or kdmctl reserve, depending on your desktop environment.

• XSECURELOCK_VIDEOS_FLAGS: flags to append when invoking mpv/mplayer with saver_mpv or saver_mplayer.
Defaults to empty.

• XSECURELOCK_WAIT_TIME_MS: Milliseconds to wait after dimming (and before locking) when above xss-lock
command line is used. Should be at least as large as the period time set using “xset s”. Also used by
wait_nonidle to know when to assume dimming and waiting has finished and exit.

• XSECURELOCK_SAVER_DELAY_MS: Milliseconds to wait after starting children process and before mapping
windows to let children be ready to display and reduce the black flash.

• XSECURELOCK_SAVER_STOP_ON_BLANK: specifies if saver is stopped when screen is blanked (DPMS or XSS) to
save power.

• XSECURELOCK_XSCREENSAVER_PATH: Location where XScreenSaver hacks are installed for use by
saver_xscreensaver.

Additionally, XSecureLock spawns the command-to-run-when-locked once locking is complete; this can be
used as a notification mechanism if desired.

REPORTING BUGS

       The official bug tracker is at https://github.com/google/xsecurelock/issues/.

COPYRIGHT

       The code is released unser the Apache 2.0 license.  See the LICENSE file for more details.

AUTHORS

       Rudolf Polzer.

XSecureLock User Manual                          April 15, 2019                                   XSECURELOCK(1)