Version: 2.0

Dux Greeter

Configuration

Custom Compositor Configuration

tip

Custom compositor configurations allow you to configure displays (resolution, refresh rate, position, etc.) specifically for the greeter.

niri

Create a baseline configuration file at /etc/greetd/niri.kdl:

sudo tee /etc/greetd/niri.kdl > /dev/null << 'EOF'
hotkey-overlay {
    skip-at-startup
}

environment {
    DMS_RUN_GREETER "1"
}

gestures {
  hot-corners {
    off
  }
}

layout {
  background-color "#000000"
}
EOF

Update the command in `/etc/greetd/config.toml to use this configuration

#...existing configuration
command = "dms-greeter --command niri -C /etc/greetd/niri.kdl"
#...existing configuration

Edit /etc/greetd/niri.kdl however you see fit, the greeter will run under this compositor configuration

Hyprland

Create a baseline configuration file at /etc/greetd/hypr.lua:

sudo tee /etc/greetd/hypr.lua > /dev/null << 'EOF'
hl.env("DMS_RUN_GREETER", "1")

hl.config({
    misc = {
        disable_hyprland_logo = true
    }
})
EOF

Update the command in `/etc/greetd/config.toml to use this configuration

#...existing configuration
command = "dms-greeter --command hyprland -C /etc/greetd/hypr.lua"
#...existing configuration

Edit /etc/greetd/hypr.lua however you see fit, the greeter will run under this compositor configuration

Sway

Create a baseline configuration file at /etc/greetd/sway:

sudo tee /etc/greetd/sway > /dev/null << 'EOF'
# Sway greeter configuration
# The exec command to launch the greeter is automatically appended by dms-greeter
EOF

Update the command in `/etc/greetd/config.toml to use this configuration

#...existing configuration
command = "dms-greeter --command sway -C /etc/greetd/sway"
#...existing configuration

Edit /etc/greetd/sway however you see fit, the greeter will run under this compositor configuration

Mango

Create a baseline configuration file at /etc/greetd/mango.conf:

sudo tee /etc/greetd/mango.conf > /dev/null << 'EOF'
# Mango greeter configuration
EOF

Update the command in `/etc/greetd/config.toml to use this configuration

#...existing configuration
command = "dms-greeter --command mango -C /etc/greetd/mango.conf"
#...existing configuration

Edit /etc/greetd/mango.conf however you see fit, the greeter will run under this compositor configuration

Miracle WM

Create a baseline configuration file at /etc/greetd/miracle-wm.yaml:

sudo tee /etc/greetd/miracle-wm.yaml > /dev/null << 'EOF'
# Miracle WM greeter configuration
EOF

Update the command in `/etc/greetd/config.toml to use this configuration

#...existing configuration
command = "dms-greeter --command miracle-wm -C /etc/greetd/miracle-wm.yaml"
#...existing configuration

Edit /etc/greetd/miracle-wm.yaml however you see fit, the greeter will run under this compositor configuration

Syncing with DMS

You can automatically sync the system greeter with the logged in user's wallpaper, themes, fonts, etc.

Automatic Sync

You can use dms-greeter sync to automatically set up theme syncing. This command is available anywhere the dms-greeter package is installed.

note

NixOS users: The dms-greeter sync command is not available on NixOS. Please follow the manual sync steps below.

dms-greeter sync

This will:

Add your user to the greeter group (if needed)
Set up ACL permissions on parent directories for greeter access
Configure group permissions on DMS config directories
Create symlinks to sync settings, wallpapers, and color themes
Link your per-user theme slot at /var/cache/dms-greeter/users/<username>/ to your live DMS state (for the multi-account picker)

note

After running dms-greeter sync, you will need to log out and log back in for group membership changes to take effect. After logging back in, your greeter will automatically reflect your current DMS theme, wallpaper, and settings.

Multi-user systems

On a shared PC, each account can have its own greeter theme and profile photo on the login screen. DMS shows a user picker (avatar + inline list) when more than one local account exists.

Recommended workflow: One main admin runs dms-greeter sync once (system setup). Every other account - including other sudo admins - uses dms-greeter sync --profile only. Full sync from multiple accounts repoints root cache symlinks and greetd; --profile updates only that user's login-screen slot.

Roles

Who	Command	Needs sudo?
Main admin (first setup)	`dms-greeter sync`	Yes
All other users (including other admins)	`dms-greeter sync --profile`	No
Add users to greeter group	Settings → Users (toggle) or `sudo usermod -aG greeter <user>`	Yes (Polkit or sudo)

Full dms-greeter sync only adds the user running the command to the greeter group. You must add other accounts explicitly.

Adding users to the greeter group (admin)

GUI (recommended): In DMS, open Settings → Users. Use the greeter access toggle (login icon) on each account, or enable Allow greeter login access when creating a user. DMS runs usermod -aG for granting administrator access to the user.

note

After you add someone to the greeter group, they must log out and back in before group membership applies, then run dms-greeter sync --profile on their account.

CLI alternative:

sudo usermod -aG greeter otheruser1 otheruser2

Each added user must log out and back in, then sync their own slot:

dms-greeter sync --profile

One-time setup (main admin)

# Configure greetd, ACLs, and your own theme slot
dms-greeter sync

Then add every other account - either in Settings → Users (greeter toggle) or from a terminal:

sudo usermod -aG greeter alice bob charlie

Per-user setup (everyone except the main admin)

After logging out and back in (so the greeter group applies):

dms-greeter sync --profile

This writes only to /var/cache/dms-greeter/users/<your-username>/ and grants the greeter group read access to your DMS state and wallpaper folders, without changing greetd or system configuration. The slot links to your live settings, so later wallpaper and theme changes show up at the login screen without re-running sync. Re-run only if you move wallpapers to a new folder the greeter cannot read yet.

What gets stored per user

Under /var/cache/dms-greeter/users/<username>/:

settings.json - symlink to ~/.config/dms/settings.json (theme, clock, weather, fonts)
session.json - symlink to ~/.local/state/dms/session.json (wallpaper configuration)
colors.json - symlink to the DMS color scheme

The greeter reads the same keys as the DMS lock screen. lockScreenWallpaperPath, lockScreenWallpaperFillMode, lockScreenFontFamily, and lockScreenShowWeather in settings.json apply to the login screen, and fall back to the desktop wallpaper, fill mode, and font when unset. Sync grants the greeter read access to those files alongside the session wallpapers.

The profile photo is read directly from ~/.face, ~/.face.icon, or AccountsService. If setfacl is unavailable or the greeter cannot be granted read access, sync falls back to a point-in-time snapshot (copied files) and dms-greeter status reports the slot as snapshot; re-run sync after installing the acl package to link it live.

The root cache (/var/cache/dms-greeter/settings.json, etc.) remains the default fallback when no per-user slot exists or no user is selected yet.

Developer note: `--local`

When developing from a dank-greeter checkout, only the primary admin should use:

dms-greeter sync --local

All other accounts use dms-greeter sync --profile. If greetd is already configured with a -p path to a shared checkout, the main admin can refresh that path with --local; other users should not need it.

Not the same as Switch User

DMS Switch User in the running session (dms switch-user) switches between active Wayland sessions. The greeter user picker lists local login accounts from the system password database for signing in after logout or reboot.

Manual Sync

If you prefer to set up syncing manually:

Add your user to the greeter group:

sudo usermod -aG greeter <username>

Set up ACL permissions on parent directories:

setfacl -m u:greeter:x ~
setfacl -m u:greeter:x ~/.config
setfacl -m u:greeter:x ~/.local
setfacl -m u:greeter:x ~/.cache
setfacl -m u:greeter:x ~/.local/state

Set group permissions on DMS config directories:

sudo chgrp -R greeter ~/.config/dms
sudo chmod -R g+rX ~/.config/dms

sudo chgrp -R greeter ~/.local/state/dms
sudo chmod -R g+rX ~/.local/state/dms

sudo chgrp -R greeter ~/.cache/quickshell
sudo chmod -R g+rX ~/.cache/quickshell

Create configuration symlinks:

sudo mkdir -p /var/cache/dms-greeter
sudo ln -sf ~/.config/dms/settings.json /var/cache/dms-greeter/settings.json
sudo ln -sf ~/.local/state/dms/session.json /var/cache/dms-greeter/session.json
sudo ln -sf ~/.cache/quickshell/dankshell/dms-colors.json /var/cache/dms-greeter/colors.json

note

You will have to logout or reboot for group change to take effect.

tip

For the complete setup and policy-owner guide, see Dux Greeter authentication. Lock-screen factors are configured separately in Lock Screen authentication.

Dux Greeter can use fingerprint readers and security keys through the system PAM stack. Enable the corresponding toggle in Settings → Greeter and run Sync to apply the PAM entries; nothing installs the driver, enrolls a fingerprint, or registers a security key for you.

Authentication interaction

Dux Greeter follows greetd PAM independently of the lock screen's Auto, Custom, and OR/AND choices. With DMS-managed greetd PAM, selecting a user automatically starts an enabled and available fingerprint or security-key factor. With Use system PAM authentication, the system stack controls the prompts and may require Enter on an empty password field to begin the login attempt.

Fingerprints

Install your distribution's fingerprint service/client and PAM integration, then enroll at least one finger. Package names vary by distribution. For example, Fedora's native stack is:

sudo dnf install fprintd fprintd-pam
fprintd-enroll

The distro fprintd package normally pulls in libfprint automatically; you do not usually need to install libfprint separately.

Confirm that enrollment succeeded with:

fprintd-list "$USER"

To choose a specific finger instead of the default, pass its token, for example fprintd-enroll -f right-thumb.

Then enable Fingerprint at login in Settings → Greeter and hit the Sync button (or run dms-greeter sync) to apply the PAM configuration.

If fprintd-enroll reports No devices available, the reader may not be supported by the installed libfprint driver. Check the libfprint supported devices list first.

Unsupported Validity/Synaptics readers

Some laptops have a compatible Validity/Synaptics sensor that is not supported by the native libfprint stack, regardless of distribution. In that case, the open-fprintd service with the python-validity driver may work instead. Follow that project's installation and firmware instructions; package names and setup steps vary by distribution and release.

An alternate driver replaces the stock fprintd service, so do not run both daemon implementations at the same time.

Vendor-specific drivers may require firmware extraction and additional system services. Install only the driver stack intended for your reader.

Security keys

Install and configure pam_u2f, register the key with your distribution's PAM tooling, then enable Security key at login in Settings → Greeter. The key must be registered before it can authenticate.

Externally managed greetd PAM

If you manage /etc/pam.d/greetd on your own with authselect, pam-auth-update, NixOS modules, or a hand-written stack, turn on Use system PAM authentication in Settings → Greeter. With the toggle on, /etc/pam.d/greetd is never written: the next greeter sync removes any existing managed block and then leaves the file untouched. The fingerprint and security-key toggles are disabled in this mode, since your own PAM configuration decides which authentication methods the greeter offers.

Lock screen authentication source

The lock screen has separate primary and security-key PAM sources, plus a choice between DMS-managed factors and system-PAM policy. See Lock Screen authentication for the complete setup.

Inspecting PAM services

Two read-only commands back the lock screen source picker and are useful for troubleshooting. Neither writes any file or requires root.

List the candidate PAM services found on the system:

dms auth list-services --json

Validate a PAM service file for lock screen use, it reports whether the resolved stack contains auth directives, whether pam_fprintd/pam_u2f appear inline, and any modules referenced but not installed:

dms auth validate --path /etc/pam.d/system-auth
dms auth validate --service system-auth

validate exits 0 when the file is usable and 1 otherwise (with --json the result is printed either way).

Repairing authentication configuration

Use dms-greeter sync --auth when you need to repair or manually re-apply the managed greetd PAM configuration (for example, after editing PAM files or restoring a backup):

dms-greeter sync --auth

Lock screen PAM is separate and repaired with dms auth sync.

Checking Sync Status

To verify that your greeter is properly configured and syncing with your user settings, run:

dms-greeter status

This command is available for all users and will check:

✓ Group membership (whether your user is in the greeter group)
✓ Cache directory existence
✓ Configuration symlinks (settings, wallpaper, colors)
✓ Whether source files exist and are readable

Example Output

=== DMS Greeter Status ===

Group Membership:
  ✓ User is in greeter group

Greeter Cache Directory:
  ✓ /var/cache/dms-greeter exists

Configuration Symlinks:
  ✓ Settings: synced correctly
  ✓ Session state: synced correctly
  ✓ Color theme: synced correctly

Per-user slots (multi-account):
  ✓ users/alice/ - live (linked to DMS state)
  ⚠ users/bob/ - snapshot (wallpaper and theme changes need a re-sync)
    Run 'dms-greeter sync --profile' as bob to link it live

✓ All checks passed! Greeter is properly configured.

Troubleshooting

If dms-greeter status shows issues:

User not in greeter group:

dms-greeter sync
# Then log out and log back in

Symlinks missing or broken:

dms-greeter sync

Secondary user cannot run full sync (not in sudoers):

# Admin: Settings → Users → enable greeter access for that account
# Or: sudo usermod -aG greeter <username>
# User logs out/in, then:
dms-greeter sync --profile

Per-user theme not showing in picker:

# Run on that user's account after group membership is active:
dms-greeter sync --profile
# Log out to see the updated theme on the login screen

ACL permission issues (themes/wallpapers not appearing):

# Check if ACLs are set
getfacl ~ ~/.config ~/.local ~/.cache ~/.local/state | grep "group:greeter"

# If not, run sync again
dms-greeter sync

Greeter shows an old wallpaper after changing it in DMS:

# A slot reported as "snapshot" is a point-in-time copy; link it live:
dms-greeter status
dms-greeter sync --profile
# If the slot is already live, grant access to the new wallpaper folder by re-running the same command

Auto-login skips the greeter password after boot - similar to the auto-login option in SDDM or GDM - until you sign out. It uses greetd's native [initial_session], so:

After a reboot you land straight in your session without entering a password at the greeter.
Signing out returns you to the normal greeter, where a password is required.
Your lock screen is unaffected - unlocking always requires your password.

warning

Auto-login reduces physical security: anyone who powers on or reboots the machine reaches your session without a password. Only enable it on machines you physically trust, ideally with full-disk encryption.

Requirements

Auto-login needs to know which user and session to start, so it requires Remember last user and Remember last session (both enabled by default). The first login is always interactive - DMS remembers the user and session you pick, then auto-logs in on subsequent boots.

Enabling and disabling

From Settings (recommended): open Settings → Greeter and toggle Sign in automatically on startup. DMS updates greetd in the background and shows a confirmation; the change takes effect on your next reboot. Turn the same toggle off to require a password again.

From the login screen: on the password screen, tap the Auto-login chip before signing in. Auto-login is enabled once you reach your desktop.

If administrator access is needed and passwordless sudo isn't configured, DMS opens a terminal so you can enter your sudo password; it closes automatically when finished.

CLI

The toggles run a focused sync under the hood. You can also apply just the auto-login state from a terminal:

dms-greeter sync --autologin

Unlike a full dms-greeter sync, this updates only greetd's [initial_session] block - adding it (with your remembered user and session) when enabled, or removing it when disabled - and skips the theme, ACL, and permission steps. It reads the greeterAutoLogin setting from your DMS configuration, so run it after changing that setting if you ever need to re-apply greetd manually.

Manual Configuration

The greeter uses three main configuration files located in /var/cache/dms-greeter/. If you defined a custom directory, it will be in DMS_GREET_CFG_DIR. For NixOS users it is under /var/lib/dms-greeter/:

settings.json - Appearance, behavior, and widget settings
session.json - Wallpaper configuration
colors.json - Color scheme configuration

On multi-user systems, each account may also have a copied slot under /var/cache/dms-greeter/users/<username>/ with the same file names plus localized wallpapers and a profile.* image for the user picker. See Multi-user systems above.

note

These files are read-only by the greeter, not written or updated.

note

The greeter does not read config.d/*.json files.

Colors

Colors can be configured in the exact same way described in Dux Shell Custom Themes

Settings

The settings.json file controls the greeter's appearance and behavior. Here's a complete reference:

Clock & Time

{
  "use24HourClock": true,
  "showSeconds": false,
  "lockDateFormat": ""
}

use24HourClock: Use 24-hour format (true) or 12-hour format (false)
showSeconds: Display seconds in the clock
lockDateFormat: Custom Qt date format string (empty = Locale.LongFormat)

Weather

{
  "weatherEnabled": true,
  "weatherLocation": "New York, NY",
  "weatherCoordinates": "40.7128,-74.0060",
  "useAutoLocation": false,
  "useFahrenheit": false
}

weatherEnabled: Show weather widget in top-right
weatherLocation: Display name for location
weatherCoordinates: "latitude,longitude" string
useAutoLocation: Auto-detect location via IP geolocation
useFahrenheit: Use Fahrenheit (true) or Celsius (false)

Appearance

{
  "currentThemeName": "blue",
  "customThemeFile": "",
  "matugenScheme": "scheme-tonal-spot",
  "iconTheme": "System Default",
  "fontFamily": "Inter Variable",
  "fontWeight": 400,
  "fontScale": 1.0,
  "cornerRadius": 12,
  "widgetBackgroundColor": "sch",
  "surfaceBase": "s",
  "animationSpeed": 2
}

currentThemeName: Built-in theme name ("blue", "red", "green", etc.)
customThemeFile: Path to custom matugen JSON theme file
matugenScheme: Matugen color scheme variant
iconTheme: Icon theme name for DankIcon fallbacks
fontFamily: Primary font family
fontWeight: Font weight (400 = normal, 700 = bold)
fontScale: Font size multiplier (1.0 = default)
cornerRadius: Corner radius in pixels for UI elements
widgetBackgroundColor: Widget background scheme ("sch", "s", "sv")
surfaceBase: Surface base color scheme ("s", "sv", "sb")
animationSpeed: Animation speed (0 = fastest, 4 = slowest, 2 = default)

Complete Example

/var/cache/dms-greeter/settings.json:

{
  "use24HourClock": true,
  "showSeconds": false,
  "lockDateFormat": "",
  "lockScreenShowPowerActions": true,
  "useFahrenheit": false,
  "weatherLocation": "New York, NY",
  "weatherCoordinates": "40.7128,-74.0060",
  "useAutoLocation": false,
  "weatherEnabled": true,
  "currentThemeName": "blue",
  "customThemeFile": "",
  "matugenScheme": "scheme-tonal-spot",
  "nightModeEnabled": false,
  "iconTheme": "System Default",
  "fontFamily": "Inter Variable",
  "fontWeight": 400,
  "fontScale": 1.0,
  "cornerRadius": 12,
  "widgetBackgroundColor": "sch",
  "surfaceBase": "s",
  "animationSpeed": 2
}

Wallpapers

The session.json file controls wallpaper settings.

Basic Configuration

{
  "wallpaperPath": "/path/to/wallpaper.jpg",
  "wallpaperFillMode": "PreserveAspectCrop"
}

wallpaperPath: Default wallpaper for all monitors
wallpaperFillMode: Qt fill mode
- "PreserveAspectCrop" - Crop to fill (default)
- "PreserveAspectFit" - Fit within bounds
- "Stretch" - Stretch to fill

Per-Monitor Wallpapers

{
  "wallpaperPath": "/path/to/default.jpg",
  "wallpaperFillMode": "PreserveAspectCrop",
  "monitorWallpapers": {
    "DP-1": "/path/to/monitor1-wallpaper.jpg",
    "DP-2": "/path/to/monitor2-wallpaper.jpg",
    "HDMI-A-1": "#1a1a1a"
  }
}

monitorWallpapers: Per-monitor wallpaper overrides
- Key: Monitor name from niri msg outputs or hyprctl monitors
- Value formats:
  - File paths: /path/to/image.jpg
  - Solid colors: #RRGGBB format
  - Wallpaper Engine: we:workshop_id format

Complete Example

/var/cache/dms-greeter/session.json:

{
  "wallpaperPath": "/usr/share/backgrounds/default.jpg",
  "wallpaperFillMode": "PreserveAspectCrop",
  "monitorWallpapers": {
    "DP-1": "/home/user/Pictures/wallpaper-main.png",
    "DP-2": "#2e3440",
    "HDMI-A-1": "/home/user/Pictures/wallpaper-side.jpg"
  }
}

Configuration

Custom Compositor Configuration​

niri​

Hyprland​

Sway​

Mango​

Miracle WM​

Syncing with DMS​

Automatic Sync​

Multi-user systems​

Roles​

Adding users to the greeter group (admin)​

One-time setup (main admin)​

Per-user setup (everyone except the main admin)​

What gets stored per user​

Developer note: --local​

Not the same as Switch User​

Manual Sync​

Login authentication​

Fingerprints​

Security keys​

Externally managed greetd PAM​

Lock screen authentication source​

Inspecting PAM services​

Repairing authentication configuration​

Checking Sync Status​

Example Output​

Troubleshooting​

Auto-login on startup​

Requirements​

Enabling and disabling​

CLI​

Manual Configuration​

Colors​

Settings​

Clock & Time​

Weather​

Appearance​

Complete Example​

Wallpapers​

Basic Configuration​

Per-Monitor Wallpapers​

Complete Example​

Custom Compositor Configuration

niri

Hyprland

Sway

Mango

Miracle WM

Syncing with DMS

Automatic Sync

Multi-user systems

Roles

Adding users to the greeter group (admin)

One-time setup (main admin)

Per-user setup (everyone except the main admin)

What gets stored per user

Developer note: `--local`

Not the same as Switch User

Manual Sync

Login authentication

Fingerprints

Security keys

Externally managed greetd PAM

Lock screen authentication source

Inspecting PAM services

Repairing authentication configuration

Checking Sync Status

Example Output

Troubleshooting

Auto-login on startup

Requirements

Enabling and disabling

CLI

Manual Configuration

Colors

Settings

Clock & Time

Weather

Appearance

Complete Example

Wallpapers

Basic Configuration

Per-Monitor Wallpapers

Complete Example