Skip to main content
Version: 2.2 (dev)

Lock, idle and DPMS somewm-only

The awesome global exposes session locking, idle timeouts, and display power controls. An idle callback can lock the session or turn displays off. User activity wakes displays and resets idle timers.

Lock API​

Methods​

MethodArgumentsReturnDescription
awesome.lock()nonebooleanLock the session. Returns true on success or if already Lua-locked. Returns false without a registered surface or while ext-session-lock is active
awesome.unlock()nonebooleanUnlock the session. Returns true if already unlocked. While Lua-locked, requires a successful awesome.authenticate() call since locking
awesome.authenticate(password)stringbooleanSynchronously verify the current user’s password via PAM. Return success. On failure, emit lock::auth_failed
awesome.set_lock_surface(wibox)wiboxnoneRegister the interactive lock surface (receives keyboard input when locked)
awesome.clear_lock_surface()nonenoneUnregister the lock surface. Does not unlock the session
awesome.add_lock_cover(wibox)wiboxnoneRegister a cover surface for multi-monitor support (max 16). Idempotent
awesome.remove_lock_cover(wibox)wiboxnoneUnregister a specific cover surface
awesome.clear_lock_covers()nonenoneUnregister all cover surfaces

Properties​

PropertyTypeDescription
awesome.lockedboolean (read-only)True if session is locked via the Lua lock API
awesome.lock_surfacedrawin or nil (read-only)Registered drawin, when retrievable. In 2.1 this can be nil even after registering a wibox, so retain your own reference
awesome.lock_mechanismstring or nil (read-only)"lua" for Lua locking, "ext" for ext-session-lock, otherwise nil

Signals​

SignalArgumentsDescription
lock::activatesource (string)Session locked. Source is "user"
lock::deactivatenoneSession unlocked
lock::auth_failednonePassword authentication failed

Security Model​

awesome.unlock() checks an authentication flag set by PAM verification. Starting a new lock resets the flag. While locked, input is restricted to the registered lock surfaces.

Destroying the registered interactive surface or reloading the configuration forces a Lua unlock. awesome.clear_lock_surface() only unregisters it, so a custom lock must register a replacement before returning control to the user.

The PAM helper clears its temporary password buffer. This does not erase the caller’s Lua string.

Example​

For password entry and surface setup, see the lockscreen guide. The bundled lockscreen module supplies both.

Idle API​

Methods​

MethodArgumentsReturnDescription
awesome.set_idle_timeout(name, seconds, callback)string, positive integer, functionnoneCreate or update a named idle timeout (max 32). Callback fires once after seconds of inactivity, then rearms on user activity
awesome.clear_idle_timeout(name)stringnoneRemove a named idle timeout. No-op if not found
awesome.clear_all_idle_timeouts()nonenoneRemove all active idle timeouts

Properties​

PropertyTypeDescription
awesome.idleboolean (read-only)True when the user has been idle long enough to fire at least one timeout
awesome.idle_inhibitboolean (read/write)Set to true to suppress idle timeouts from Lua. OR-ed with protocol-level inhibitors
awesome.idle_inhibitedboolean (read-only)True if idle is inhibited by any source (protocol inhibitors OR idle_inhibit)
awesome.inhibitorstable (read-only)Array of {client = <client or nil>, visible = bool} for each active Wayland protocol inhibitor
awesome.inhibitor_countinteger (read-only)Number of active Wayland protocol idle inhibitors
awesome.idle_timeoutstable (read-only)Table of {name = {seconds = N, fired = bool}, ...} for all active timeouts

Signals​

SignalArgumentsDescription
idle::startnoneUser became idle (first timeout fired)
idle::stopnoneUser activity detected after being idle
property::idle_inhibitednoneCombined idle inhibition state changed (read awesome.idle_inhibited for new value)

Example​

awesome.set_idle_timeout("display-off", 120, function()
awesome.dpms_off()
end)

awesome.set_idle_timeout("lock", 300, function()
awesome.lock()
end)

The lock callback requires a registered lock surface. Turning displays off does not lock the session.

DPMS API​

Methods​

MethodArgumentsReturnDescription
awesome.dpms_off()nonenoneTurn off all displays (sleep mode)
awesome.dpms_on()nonenoneWake all displays

Properties​

PropertyTypeDescription
awesome.dpms_statetable (read-only)Table of {output_name = "on"/"off", ...} showing power state per output

Signals​

SignalArgumentsDescription
dpms::offnoneAt least one display entered sleep mode
dpms::onnoneAt least one display woke up

Displays automatically wake on user activity (keyboard/mouse input).

See Also​