SYSTEMD-ASK-PASSWORD(1)

📦
version 262.1 · 15 versions
, in arch rolling

💖 SYSTEMD-ASK-PASSWORD — bestie, it's the manual ✨

okay so this is the page for systemd-ask-password from the systemd manual set, and honestly? she's serving "ask the human for a password" and she's good at it. let's get into it 🫶

🌸 NAME 🌸

systemd-ask-password — literally just: ask the user for a system password. that's the whole job. 💅

✨ SYNOPSIS ✨

systemd-ask-password [OPTIONS...] [MESSAGE]

🦋 DESCRIPTION 🦋

so systemd-ask-password is the lil tool you use to ask a password or passphrase out of a human, interactively, with a question prompt that you pass on the command line. the way it works:

  • if you run it from a TTY, it asks for the password right there on the TTY and prints it to standard output. simple. iconic.
  • if you run it with no TTY at all, or with --no-tty, it switches to a whole system-wide / per-user agent-based query mechanism — which is fancy speak for "several agents can pop the question instead, and any active user can answer". the agents are listed below, keep reading bestie 👇

what's the point of this thing? it queries system-wide or per-user passwords — and yes, "system-wide" includes passwords that might not even belong to a specific user account. examples, since you're gonna ask:

  • unlocking encrypted hard disks when they get plugged in, or at boot 🔐
  • entering an SSL certificate passphrase for web and VPN servers

the existing system-level agents are:

⚠️ answering system-wide password queries is a privileged operation, no cap. that's why literally all the agents above — except the last one — run as privileged system services. and the last one still needs elevated privileges too, so run it through run0(1) or something similar. don't be out here raw-dogging privileges, bestie 😭

more password agents can be implemented according to the systemd Password Agent Specification (link is down in NOTES, we got u).

oh and one more thing — if a password is being queried on a TTY, the user can hit TAB to hide the asterisks that normally show up for each character typed. pressing Backspace as the first key does the same thing. cute lil privacy toggle, obsessed. 🙈

💅 OPTIONS 💅

here's everything she understands, bestie. no skipping, we're doing all of them:

  • --icon= — give an icon name to go with the password query. all the agents that support graphical display can use it. and pls follow the XDG Icon Naming Specification for the name (link in NOTES 💖).
  • --id= — sets an identifier for this specific password query. it's freely choosable, and it lets the agents involved actually recognize which query is which. pro move: include the subsystem doing the query and the specific object it's for. example: "--id=cryptsetup:/dev/sda5".
Added in version 227.
  • --keyname= — configures a kernel keyring key name to use as a cache for the password. if you set it, the tool tries to push any passwords it collects into the kernel keyring of the root user, as a key with the name you gave. and if you combine it with --accept-cached, it'll also try to pull those cached passwords back out of the kernel keyring instead of bothering the user right away. the point? the kernel keyring becomes an effective cache so you're not repeatedly asking the user for passwords when multiple objects can be unlocked with the same one. the cached key gets a timeout of 2.5min, after which it's purged from the kernel keyring. note that you can cache multiple passwords under the same keyname — they'll be stored as a NUL-separated list of passwords. use keyctl(1) to access the cached key via the kernel keyring directly. example: "--keyname=cryptsetup".
Added in version 227.
  • --credential= — configure a credential to read the password from — if it exists. this pairs nicely with the ImportCredential=, LoadCredential= and SetCredential= settings in unit files; see systemd.exec(5) for the details. if you don't specify it, it defaults to "password". heads up: this option does nothing if no credentials directory is passed to the program (i.e. $CREDENTIALS_DIRECTORY isn't set) or if no credential with the specified name exists.
Added in version 249.
  • --timeout= — the query timeout, in seconds. defaults to 90s. a timeout of 0 waits indefinitely (main character energy, no rush 🧚).
  • --echo=yes|no|masked — controls whether user input gets echoed. takes a boolean or the special string "masked", and "masked" is the default. if enabled, typed characters are echoed literally — great for prompting for usernames and other non-protected data. if disabled, typed characters aren't echoed in any form and the user gets zero feedback on their input. if set to "masked", an asterisk ("*") is echoed for each character typed. in that mode, if the user hits the tabulator key ("↹"), echo gets turned off. (alternatively, if the user hits the backspace key ("⌫") while no data has been entered otherwise, echo gets turned off too.)
Added in version 249.
  • --echo, -e — same thing as --echo=yes, see above. 💫
Added in version 217.
  • --emoji=yes|no|auto — controls whether the query gets prefixed with a lock and key emoji (🔐) or not, if the TTY settings allow it. default is "auto", which itself defaults to "yes" — unless --echo=yes was given.
Added in version 249.
  • --no-tty — never ask for the password on the current TTY, even if there is one available. always use the agent system instead. periodt.
  • --accept-cached — if passed, accept cached passwords, i.e. passwords that were previously entered.
  • --multiple — when used alongside --accept-cached, accept multiple passwords. outputs one password per line.
  • --no-output — do not print passwords to standard output. useful when you want to stash a password in the kernel keyring with --keyname= but do not want it showing up on screen or in logs. stealth mode fr fr. 🤫
Added in version 230.
  • -n — by default, when the acquired password is written to standard output it gets a newline character tacked on the end. this switch turns that off, just like the switch of the same name in the echo(1) command.
Added in version 249.
  • --user, --system — controls whether you query the system-wide password agents or the per-user ones. by default, if invoked privileged it's the system-wide agents; otherwise it's the per-user ones. these options let you override that automatic behaviour yourself.
Added in version 257.
  • -h, --help — print a short help text and exit. the classic. 👑

🌈 EXIT STATUS 🌈

on success, 0 comes back. anything non-zero means it failed. that's it, that's the whole vibe check.

🎀 SEE ALSO 🎀

systemd(1), systemd-ask-password-console.service(8), systemd-tty-ask-password-agent(1), keyctl(1), plymouth(8), wall(1)

⭐ NOTES ⭐

  1. systemd Password Agent Specification — https://systemd.io/PASSWORD_AGENTS/
  2. XDG Icon Naming Specification — https://standards.freedesktop.org/icon-naming-spec/icon-naming-spec-latest.html

and that's the whole page, bestie!! this was systemd 262.1, you've been reading SYSTEMD-ASK-PASSWORD(1), and it's giving "go forth and query passwords responsibly" 💖✨🦋 mwah, ily, go read the SEE ALSO list, iykyk 🫶

📦 where this page comes from
  • arch rolling: systemd 262.1-1 · LGPL-2.1-or-later AND CC0-1.0 AND GPL-2.0-or-later AND MIT-0
  • 💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on : a language model's rewrite of the original, under its terms