DOCSEARCHbyAlgolia
Submit Docs

swaylock

repository·master·Indexed 22 days ago

https://github.com/swaywm/swaylock

A screen locking utility for Wayland compositors that implement the ext-session-lock-v1 protocol. It features customizable appearance via CLI flags or configuration files, including support for background images, colors, and indicator styling.

Tokens
2K
Snippets
3
Records
7
Agent score
29%

What's inside swaylock

  3. Compile swaylock from source

    master

    To build swaylock from source, ensure you have the necessary dependencies installed and then use meson and ninja to build and install the binary.

    Dependencies

    • meson (Compile-time)
    • wayland
    • wayland-protocols (Compile-time)
    • libxkbcommon
    • cairo
    • gdk-pixbuf2 (Optional: required for background images other than PNG)
    • pam (Optional)
    • scdoc (Optional: for man pages) (Compile-time)
    • git (Compile-time)

    Build and Install Steps

    meson build
ninja -C build
sudo ninja -C build install

  4. Configure swaylock permissions on systems without PAM

    master

    On systems without PAM, swaylock uses shadow.h. If your system stores user passwords in /etc/shadow (and does not use a tcb-like setup via musl or glibc+[tcb]), you must set specific permissions for swaylock to function correctly.

    Option 1: Set SUID

    Set the binary to be SUID so it can read /etc/shadow:

    sudo chmod a+s /usr/local/bin/swaylock

    Option 2: Set SGID (If /etc/shadow is owned by the shadow group)

    If /etc/shadow is owned by the shadow group, you can use SGID instead:

    sudo chgrp shadow /usr/local/bin/swaylock
sudo chmod g+s /usr/local/bin/swaylock

    Note: swaylock will drop root permissions shortly after startup.

  5. Configure swaylock via a config file

    master

    swaylock searches for configuration files in the following order:

    1. The path specified by the -C, --config <config_file> flag.
    2. $HOME/.swaylock/config (with shell expansion applied).
    3. $XDG_CONFIG_HOME/swaylock/config (or $HOME/.config/swaylock/config if $XDG_CONFIG_HOME is not set).
    4. SYSCONFDIR/swaylock/config.

    Config files use a one-option-per-line format where each line is treated as a command-line flag (e.g., a line containing color ff0000 is interpreted as --color ff0000).

  6. Reference: swaylock CLI flags

    master

    The following flags are available for swaylock:

    FlagLong FlagDescription
    -C--config <file>Path to the config file
    -c--color <color>Turn the screen into the given color instead of light gray
    -d--debugEnable debugging output
    -e--ignore-empty-passwordWhen an empty password is provided, do not validate it
    -F--show-failed-attemptsShow current count of failed authentication attempts
    -f--daemonizeDetach from the controlling terminal after locking
    -R--ready-fd <fd>File descriptor to send readiness notifications to
    -h--helpShow help message and quit
    -i--image [[<output>]:]<path>Display the given image, optionally only on the given output
    -k--show-keyboard-layoutDisplay the current xkb layout while typing
    -K--hide-keyboard-layoutHide the current xkb layout while typing
    -L--disable-caps-lock-textDisable the Caps Lock text
    -l--indicator-caps-lockShow the current Caps Lock state also on the indicator
    -n--line-uses-insideUse the inside color for the line between the inside and ring
    -r--line-uses-ringUse the ring color for the line between the inside and ring
    -s--scaling <mode>Image scaling mode: stretch, fill, fit, center, tile, solid_color
    -t--tilingSame as --scaling=tile
    -u--no-unlock-indicatorDisable the unlock indicator
    -v--versionShow the version number and quit
    --bs-hl-color <color>Sets the color of backspace highlight segments
    --caps-lock-bs-hl-color <color>Sets the color of backspace highlight segments when Caps Lock is active
    --caps-lock-key-hl-color <color>Sets the color of the key press highlight segments when Caps Lock is active
    --font <font>Sets the font of the text
    --font-size <size>Sets a fixed font size for the indicator text
    --indicator-idle-visibleSets the indicator to show even if idle
    --indicator-radius <radius>Sets the indicator radius
    --indicator-thickness <thick>Sets the indicator thickness
    --indicator-x-position <x>Sets the horizontal position of the indicator
    --indicator-y-position <y>Sets the vertical position of the indicator
    --inside-color <color>Sets the color of the inside of the indicator
    --inside-clear-color <color>Sets the color of the inside of the indicator when cleared
    --inside-caps-lock-color <color>Sets the color of the inside of the indicator when Caps Lock is active
    --inside-ver-color <color>Sets the color of the inside of the indicator when verifying
    --inside-wrong-color <color>Sets the color of the inside of the indicator when invalid
    --key-hl-color <color>Sets the color of the key press highlight segments
    --layout-bg-color <color>Sets the background color of the box containing the layout text
    --layout-border-color <color>Sets the color of the border of the box containing the layout text
    --layout-text-color <color>Sets the color of the layout text
    --line-color <color>Sets the color of the line between the inside and ring
    --line-clear-color <color>Sets the color of the line between the inside and ring when cleared
    --line-caps-lock-color <color>Sets the color of the line between the inside and ring when Caps Lock is active
    --line-ver-color <color>Sets the color of the line between the inside and ring when verifying
    --line-wrong-color <color>Sets the color of the line between the inside and ring when invalid
    --ring-color <color>Sets the color of the ring of the indicator
    --ring-clear-color <color>Sets the color of the ring of the indicator when cleared
    --ring-caps-lock-color <color>Sets the color of the ring of the indicator when Caps Lock is active
    --ring-ver-color <color>Sets the color of the ring of the indicator when verifying
    --ring-wrong-color <color>Sets the color of the ring of the indicator when invalid
    --separator-color <color>Sets the color of the lines that separate highlight segments
    --text-color <color>Sets the color of the text
    --text-clear-color <color>Sets the color of the text when cleared
    --text-caps-lock-color <color>Sets the color of the text when Caps Lock is active
    --text-ver-color <color>Sets the color of the text when verifying
    --text-wrong-color <color>Sets the color of the text when invalid

  7. Use swaylock CLI options

    master

    swaylock can be configured via command-line arguments to customize the appearance and behavior of the lockscreen. Options include setting background colors, images, fonts, indicator dimensions, and visibility of UI elements like the keyboard layout or failed attempt counts.

    All color options follow the <rrggbb[aa]> format (e.g., FF0000 for red, FF0000AA for semi-transparent red).

    # Example: Set a solid blue background and a specific image for an output
swaylock -c 0000FF -i output_name:/path/to/image.png

# Example: Customize indicator appearance
swaylock --indicator-radius 80 --indicator-thickness 15 --font "Fira Code"