Prompt for a Password Safely with systemd-ask-password

Pipe a secret through the wrong shell construct and it sits in your history file forever, which is what systemd-ask-password exists to prevent. You will finish with a repeatable way to ask for a system-wide password or passphrase, capture it for one command, and choose whether the request stays on the current terminal or goes through systemd's password-agent mechanism. The examples are based on systemd 255.4-1ubuntu8.17, installed here as systemd 255.

Allow about ten minutes. You need a shell and a terminal for the interactive examples. This command deals with secrets, so do not paste a real password into a shell history, a ticket, or a shared terminal. The examples use obvious test values only where a terminal smoke test needs input.

1. Check the installed command

Start with read-only checks. They need no elevated privileges:

$ command -v systemd-ask-password
/usr/bin/systemd-ask-password
$ systemd-ask-password --version
systemd 255 (255.4-1ubuntu8.17)
$ systemd-ask-password --help

The help text confirms the local option spelling. The command accepts one question message after its options, and it asks for a system password: a secret used by a service or system operation, rather than one belonging to a single login account.

2. Use the current TTY for a one-off prompt

With a usable TTY, the normal mode asks on that terminal and writes the acquired password to standard output. A minimal example:

$ systemd-ask-password 'Passphrase for the test operation:'
Passphrase for the test operation: ********
test-value

Replace test-value with the real secret only when you are testing interactively. The command's output is the password followed by a newline by default. That makes command substitution convenient, but it also makes careless logging easy:

$ password=$(systemd-ask-password 'Passphrase: ')
$ some-command --password "$password"
$ unset password

The variable is not a secure vault. It can leak through debugging, crash reporting, process inspection of a poorly designed child, or accidental shell tracing. Keep its lifetime short, never enable set -x around this code, and unset it the moment the child no longer needs it.

When the masked prompt is showing, pressing Tab hides the asterisks, and so does pressing Backspace before entering text. This only changes visual feedback; it does not make the secret any safer if the terminal or shell is already compromised.

3. Make output safer for a real script

If a program needs the password, keep it out of standard output and pass it through a short-lived variable or a file descriptor the program supports. Use --no-output when you want the query to fill a kernel keyring cache without printing the collected value at all:

$ sudo systemd-ask-password \
    --keyname=cryptsetup \
    --no-output \
    'Passphrase for the encrypted device:'

For ordinary output, use -n when a trailing newline would cause harm:

$ systemd-ask-password -n 'Token for the test operation:' > /run/user/1000/token.txt

Do not use a world-readable path for a secret. The example path is only illustrative, and redirecting to a file creates state that must be removed afterwards. If you created a test file, remove it with the narrow, explicit command below, after checking its path:

$ ls -l /run/user/1000/token.txt
$ rm -- /run/user/1000/token.txt

4. Choose TTY or password agents deliberately

Use --no-tty when a terminal must never receive the prompt:

$ systemd-ask-password --no-tty --timeout=30 \
    'Passphrase required by the service:'

Without a TTY, or with --no-tty, systemd falls back to its system-wide query mechanism. Active password agents may ask through Plymouth, the console service, a wall message, or another registered agent. A headless machine may have no agent able to answer at all, which is a normal failure rather than a reason to print the secret to a log.

The default timeout is 90 seconds. A timeout of zero waits indefinitely, usually a poor choice inside a service because it can leave a job stuck forever. Set a finite value that fits the operation's maintenance window, and handle a non-zero exit status.

$ systemd-ask-password --no-tty --timeout=1 'Agent-path smoke test'
Failed to query password: Permission denied
$ printf 'exit status: %s\n' "$?"
exit status: 1

The exact diagnostic depends on the available agents and permissions. What matters is the contract: success returns zero, a failed or expired query returns non-zero. Do not build automation around the wording of the diagnostic itself.

5. Make repeated unlocks less disruptive

--accept-cached lets a previously entered password satisfy a later query. It helps when several objects can be unlocked with the same secret:

$ sudo systemd-ask-password \
    --keyname=cryptsetup \
    --accept-cached \
    --timeout=30 \
    'Passphrase for the next encrypted device:'

A keyring cache is not permanent. With --keyname, systemd gives the cached key a 2.5 minute timeout, and more than one password can be stored under the same key name as a NUL-separated list. Treat the key name as part of your security design, not a convenient place to leave secrets sitting around. If you need to inspect or clear such a cache, use the keyring tooling and the exact key name your system's workflow defines.

The --multiple option only has meaning with --accept-cached. It asks for multiple cached values and writes one password per line, so avoid it if a password could itself contain a newline or your consumer cannot distinguish records safely.

6. Keep prompts identifiable

Set an identifier when several services may ask questions at once:

$ systemd-ask-password \
    --id=cryptsetup:/dev/mapper/data \
    --timeout=30 \
    'Passphrase for /dev/mapper/data:'

The identifier is freely chosen, but include the subsystem and object it refers to so agents can recognise related requests. Do not put the password in the identifier, question, unit name, or any other metadata that might get logged or displayed.

--icon=NAME supplies an XDG icon name to agents that support graphical display. --echo=yes is meant for non-protected input such as a username, not for passwords. The default --echo=masked shows asterisks, while --echo=no gives no typing feedback at all. The command's --emoji=auto default may add a lock and key symbol when the TTY permits it; do not treat that visual detail as a machine-readable signal.

7. Handle failures without weakening the boundary

A non-zero exit status means the query did not complete successfully. Check the status immediately, keep only a safe diagnostic, and decide whether the caller should retry:

if ! password=$(systemd-ask-password --timeout=30 'Passphrase: '); then
    printf '%s\n' 'Password query failed or timed out' >&2
    exit 1
fi

if ! some-command --password "$password"; then
    unset password
    exit 1
fi
unset password

Do not solve an agent failure by adding the password to a command line, writing it to a predictable temporary file, or switching on visible echo. If a service needs a password at boot, look into its configured password agent and unit ordering instead. If a TTY query works but --no-tty fails, that tells you about agent availability, not about the password itself.