.\" Automatically generated by Pandoc 2.5
.\"
.TH "XSECURELOCK" "1" "April 15, 2019" "XSecureLock User Manual" ""
.hy
.SH NAME
.PP
XSecureLock \- X11 screen lock utility
.SH SYNPOSIS
.PP
[\f[I]options\f[R]] xsecurelock [\[en]
\f[I]command\-to\-run\-when\-locked\f[R]]
.SH DESCRIPTION
.PP
XSecureLock is an X11 screen lock utility designed with the primary goal
of security.
.PP
It locks the current X11 session, and only allows unlocking if the user
authenticates to it (typically with the login password).
.PP
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.
.SH OPTIONS
.PP
Options are set as environment variables prior to invoking XSecureLock;
the following variables are available:
.IP \[bu] 2
\f[C]XSECURELOCK_AUTH\f[R]: specifies the desired authentication module
(the part that displays the authentication prompt).
.IP \[bu] 2
\f[C]XSECURELOCK_AUTHPROTO\f[R]: specifies the desired authentication
protocol module (the part that talks to the system).
.IP \[bu] 2
\f[C]XSECURELOCK_AUTH_BACKGROUND_COLOR\f[R]: specifies the X11 color
(see manpage of XParseColor) for the background of the auth dialog.
.IP \[bu] 2
\f[C]XSECURELOCK_AUTH_SOUNDS\f[R]: specifies whether to play sounds
during authentication to indicate status.
Sounds are defined as follows:
.RS 2
.IP \[bu] 2
High\-pitch ascending: prompt for user input.
.IP \[bu] 2
High\-pitch constant: an info message was displayed.
.IP \[bu] 2
Low\-pitch descending: an error message was displayed.
.IP \[bu] 2
Medium\-pitch ascending: authentication successful.
.RE
.IP \[bu] 2
\f[C]XSECURELOCK_AUTH_FOREGROUND_COLOR\f[R]: specifies the X11 color
(see manpage of XParseColor) for the foreground text of the auth dialog.
.IP \[bu] 2
\f[C]XSECURELOCK_AUTH_TIMEOUT\f[R]: specifies the time (in seconds) to
wait for response to a prompt by \f[C]auth_x11\f[R] before giving up and
reverting to the screen saver.
.IP \[bu] 2
\f[C]XSECURELOCK_AUTH_WARNING_COLOR\f[R]: specifies the X11 color (see
manpage of XParseColor) for the warning text of the auth dialog.
.IP \[bu] 2
\f[C]XSECURELOCK_BLANK_TIMEOUT\f[R]: 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.
.IP \[bu] 2
\f[C]XSECURELOCK_BLANK_DPMS_STATE\f[R]: specifies which DPMS state to
put the screen in when blanking (one of standby, suspend, off and on,
where \[lq]on\[rq] means to not invoke DPMS at all).
.IP \[bu] 2
\f[C]XSECURELOCK_BURNIN_MITIGATION\f[R]: specifies the number of pixels
the prompt of \f[C]auth_x11\f[R] 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).
.IP \[bu] 2
\f[C]XSECURELOCK_BURNIN_MITIGATION_DYNAMIC\f[R]: if set to a non\-zero
value, \f[C]auth_x11\f[R] will move the prompt while it is being
displayed, but stay within the bounds of
\f[C]XSECURELOCK_BURNIN_MITIGATION\f[R].
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.
.IP \[bu] 2
\f[C]XSECURELOCK_COMPOSITE_OBSCURER\f[R]: 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\[cq]s 1
pixel smaller than the screen from every side, and should otherwise be
harmless, so it\[cq]s enabled by default.
.IP \[bu] 2
\f[C]XSECURELOCK_DATETIME_FORMAT\f[R]: the date format to show.
Defaults to the locale settings.
.IP \[bu] 2
\f[C]XSECURELOCK_DEBUG_ALLOW_LOCKING_IF_INEFFECTIVE\f[R]: Normally we
don\[cq]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\[cq]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.
.IP \[bu] 2
\f[C]XSECURELOCK_DEBUG_WINDOW_INFO\f[R]: When complaining about another
window misbehaving, print not just the window ID but also some info
about it.
Uses the \f[C]xwininfo\f[R] and \f[C]xprop\f[R] tools.
.IP \[bu] 2
\f[C]XSECURELOCK_DIM_ALPHA\f[R]: Linear\-space opacity to fade the
screen to.
.IP \[bu] 2
\f[C]XSECURELOCK_DIM_COLOR\f[R]: X11 color to fade the screen to.
.IP \[bu] 2
\f[C]XSECURELOCK_DIM_FPS\f[R]: Target framerate to attain during the
dimming effect of \f[C]dimmer\f[R].
Ideally matches the display refresh rate.
.IP \[bu] 2
\f[C]XSECURELOCK_DIM_OVERRIDE_COMPOSITOR_DETECTION\f[R]: 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.
.IP \[bu] 2
\f[C]XSECURELOCK_DIM_TIME_MS\f[R]: Milliseconds to dim for when above
xss\-lock command line with \f[C]dimmer\f[R] is used; also used by
\f[C]wait_nonidle\f[R] to know when to assume dimming and waiting has
finished and exit.
.IP \[bu] 2
\f[C]XSECURELOCK_DISCARD_FIRST_KEYPRESS\f[R]: 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).
.IP \[bu] 2
\f[C]XSECURELOCK_FONT\f[R]: X11 or FontConfig font name to use for
\f[C]auth_x11\f[R].
You can get a list of supported font names by running \f[C]xlsfonts\f[R]
and \f[C]fc\-list\f[R].
.IP \[bu] 2
\f[C]XSECURELOCK_FORCE_GRAB\f[R]: When grabbing fails, try stealing the
grab from other windows (a value of \f[C]2\f[R] steals from all
descendants of the root window, while a value of \f[C]1\f[R] only steals
from client windows).
This works only sometimes and is incompatible with many window managers,
so use with care.
See the \[lq]Forcing Grabs\[rq] section below for details.
.IP \[bu] 2
\f[C]XSECURELOCK_GLOBAL_SAVER\f[R]: specifies the desired global screen
saver module (by default this is a multiplexer that runs
\f[C]XSECURELOCK_SAVER\f[R] on each screen).
.IP \[bu] 2
\f[C]XSECURELOCK_IDLE_TIMERS\f[R]: comma\-separated list of idle time
counters used by \f[C]until_nonidle\f[R].
Typical values are either empty (relies on the X Screen Saver extension
instead), \[lq]IDLETIME\[rq] and \[lq]DEVICEIDLETIME \[rq] where n is an
XInput device index (run \f[C]xinput\f[R] 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.
.IP \[bu] 2
\f[C]XSECURELOCK_IMAGE_DURATION_SECONDS\f[R]: how long to show each
still image played by \f[C]saver_mpv\f[R].
Defaults to 1.
.IP \[bu] 2
\f[C]XSECURELOCK_KEY_%s_COMMAND\f[R] where \f[C]%s\f[R] is the name of
an X11 keysym (find using \f[C]xev\f[R]): a shell command to execute
when the specified key is pressed.
Useful e.g.\ for media player control.
Beware: be cautiuous about what you run with this, as it may yield
attackers control over your computer.
.IP \[bu] 2
\f[C]XSECURELOCK_LIST_VIDEOS_COMMAND\f[R]: shell command to list all
video files to potentially play by \f[C]saver_mpv\f[R] or
\f[C]saver_mplayer\f[R].
Defaults to \f[C]find \[ti]/Videos \-type f\f[R].
.IP \[bu] 2
\f[C]XSECURELOCK_NO_COMPOSITE\f[R]: 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.
.IP \[bu] 2
\f[C]XSECURELOCK_NO_PAM_RHOST\f[R]: do not set \f[C]PAM_RHOST\f[R] to
\f[C]localhost\f[R], despite
recommendation (http://www.linux-pam.org/Linux-PAM-html/adg-security-user-identity.html)
to do so by the Linux\-PAM Application Developers\[cq] 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.
.IP \[bu] 2
\f[C]XSECURELOCK_NO_XRANDR\f[R]: disables multi monitor support using
XRandR.
.IP \[bu] 2
\f[C]XSECURELOCK_NO_XRANDR15\f[R]: disables multi monitor support using
XRandR 1.5 and fall back to XRandR 1.2.
Not recommended.
.IP \[bu] 2
\f[C]XSECURELOCK_PAM_SERVICE\f[R]: pam service name.
You should have a file with that name in \f[C]/etc/pam.d\f[R].
.IP \[bu] 2
\f[C]XSECURELOCK_PASSWORD_PROMPT\f[R]: Choose password prompt mode:
.RS 2
.IP \[bu] 2
\f[C]asterisks\f[R]: shows asterisks, like classic password prompts.
This is the least secure option because password length is visible.
.RS 2
.IP
.nf
\f[C]
***_
*******_
\f[R]
.fi
.RE
.IP \[bu] 2
\f[C]cursor\f[R]: shows a cursor that jumps around on each key press.
This is the default.
.RS 2
.IP
.nf
\f[C]
________|_______________________
___________________|____________
\f[R]
.fi
.RE
.IP \[bu] 2
\f[C]disco\f[R]: shows dancers, which dance around on each key press.
Requires a font that can handle Unicode line drawing characters, and
FontConfig.
.RS 2
.IP
.nf
\f[C]
\[u250F](\[uFF65]o\[uFF65])\[u251B] \[u266A] \[u2517](\[uFF65]o\[uFF65])\[u2513] \[u266A] \[u250F](\[uFF65]o\[uFF65])\[u251B] \[u266A] \[u2517](\[uFF65]o\[uFF65])\[u2513] \[u266A] \[u250F](\[uFF65]o\[uFF65])\[u251B]
\[u2517](\[uFF65]o\[uFF65])\[u2513] \[u266A] \[u250F](\[uFF65]o\[uFF65])\[u251B] \[u266A] \[u250F](\[uFF65]o\[uFF65])\[u251B] \[u266A] \[u250F](\[uFF65]o\[uFF65])\[u251B] \[u266A] \[u250F](\[uFF65]o\[uFF65])\[u251B]
\f[R]
.fi
.RE
.IP \[bu] 2
\f[C]emoji\f[R]: shows an emoji, changing which one on each key press.
Requires a font that can handle emoji, and FontConfig.
.RS 2
.IP
.nf
\f[C]
\[u1F44D]
\[u1F3B6]
\[u1F495]
\f[R]
.fi
.RE
.IP \[bu] 2
\f[C]emoticon\f[R]: shows an ascii emoticon, changing which one on each
key press.
.RS 2
.IP
.nf
\f[C]
:\-O
d\-X
X\-\[rs]
\f[R]
.fi
.RE
.IP \[bu] 2
\f[C]hidden\f[R]: completely hides the password, and there\[cq]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.
.RS 2
.IP
.nf
\f[C]
\f[R]
.fi
.RE
.IP \[bu] 2
\f[C]kaomoji\f[R]: shows a kaomoji (Japanese emoticon), changing which
one on each key press.
Requires a Japanese font, and FontConfig.
.RS 2
.IP
.nf
\f[C]
(\[u0361]\[de]\[u035C]\[u0296]\[u0361]\[de])
(\[uFF3E]\[uFF55]\[uFF3E])
\[a-]\[rs]_(\[u30C4])_/\[a-]
\f[R]
.fi
.RE
.IP \[bu] 2
\f[C]time\f[R]: 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.
.RS 2
.IP
.nf
\f[C]
1559655410.922329
\f[R]
.fi
.RE
.IP \[bu] 2
\f[C]time_hex\f[R]: same as \f[C]time\f[R], but in microseconds and
hexadecimal.
\[lq]Because we can\[rq].
.RS 2
.IP
.nf
\f[C]
0x58a7f92bd7359
\f[R]
.fi
.RE
.RE
.IP \[bu] 2
\f[C]XSECURELOCK_SAVER\f[R]: specifies the desired screen saver module.
.IP \[bu] 2
\f[C]XSECURELOCK_SAVER_RESET_ON_AUTH_CLOSE\f[R]: specifies whether to
reset the saver module when the auth dialog closes.
Resetting is done by sending \f[C]SIGUSR1\f[R] to the saver, which may
either just terminate, or handle this specifically to do a cheaper
reset.
.IP \[bu] 2
\f[C]XSECURELOCK_SHOW_DATETIME\f[R]: whether to show local date and time
on the login.
Disabled by default.
.IP \[bu] 2
\f[C]XSECURELOCK_SHOW_HOSTNAME\f[R]: whether to show the hostname on the
login screen of \f[C]auth_x11\f[R].
Possible values are 0 for not showing the hostname, 1 for showing the
short form, and 2 for showing the long form.
.IP \[bu] 2
\f[C]XSECURELOCK_SHOW_USERNAME\f[R]: whether to show the username on the
login screen of \f[C]auth_x11\f[R].
.IP \[bu] 2
\f[C]XSECURELOCK_SINGLE_AUTH_WINDOW\f[R]: whether to show only a single
auth window from \f[C]auth_x11\f[R], as opposed to one per screen.
.IP \[bu] 2
\f[C]XSECURELOCK_SWITCH_USER_COMMAND\f[R]: shell command to execute when
\f[C]Win\-O\f[R] or \f[C]Ctrl\-Alt\-O\f[R] are pressed (think
\[lq]\f[I]other\f[R] user\[rq]).
Typical values could be \f[C]lxdm \-c USER_SWITCH\f[R],
\f[C]dm\-tool switch\-to\-greeter\f[R], \f[C]gdmflexiserver\f[R] or
\f[C]kdmctl reserve\f[R], depending on your desktop environment.
.IP \[bu] 2
\f[C]XSECURELOCK_WAIT_TIME_MS\f[R]: 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 \[lq]xset
s\[rq].
Also used by \f[C]wait_nonidle\f[R] to know when to assume dimming and
waiting has finished and exit.
.IP \[bu] 2
\f[C]XSECURELOCK_XSCREENSAVER_PATH\f[R]: Location where XScreenSaver
hacks are installed for use by \f[C]saver_xscreensaver\f[R].
.IP \[bu] 2
\f[C]XSECURELOCK_XSCREENSAVER_PATH\f[R]: Location where XScreenSaver
hacks are installed for use by \f[C]saver_xscreensaver\f[R].
.PP
Additionally, XSecureLock spawns the
\f[I]command\-to\-run\-when\-locked\f[R] once locking is complete; this
can be used as a notification mechanism if desired.
.SH REPORTING BUGS
.PP
The official bug tracker is at
.
.SH COPYRIGHT
.PP
The code is released unser the Apache 2.0 license.
See the LICENSE file for more details.
.SH SEE ALSO
.PP
\f[C]xss\-lock\f[R] (1), \f[C]xautolock\f[R] (1).
.PP
The \f[I]README.md\f[R] file included with XSecureLock contains full
documentation.
.PP
The XSecureLock source code and all documentation may be downloaded on
.
.SH AUTHORS
Rudolf Polzer.