Test saslauthd Authentication Safely with testsaslauthd

Mail stops accepting logins, and testsaslauthd tells you whether saslauthd or the credentials are to blame. It checks that the socket is reachable and that a given username and password are accepted by the configured backend, without touching any configuration. Examples use testsaslauthd from Ubuntu package sasl2-bin 2.1.28+dfsg1-5ubuntu3.1; allow about ten minutes once you know the socket path and a test account.

1. Check the installed command

Start with these ordinary, read-only commands:

$ command -v testsaslauthd
/usr/sbin/testsaslauthd
$ dpkg-query -W -f='${Package} ${Version}\n' sasl2-bin
sasl2-bin 2.1.28+dfsg1-5ubuntu3.1
$ testsaslauthd -h
testsaslauthd: invalid option -- 'h'
testsaslauthd: usage: testsaslauthd -u username -p password
              [-r realm] [-s servicename]
              [-f socket path] [-R repeatnum]

That usage text is the actual help here; the manpage does not document a long help option, so do not reach for --help or borrow an option from a different SASL utility.

2. Find the daemon socket

testsaslauthd talks to the daemon over a Unix socket, and -f supplies its path. That path belongs to this daemon's deployment: do not guess it from a different host, and do not silently rely on a compiled-in default.

Ask the service configuration and filesystem which socket actually exists. Reading configuration is usually fine; listing a directory can need elevated privileges on a locked-down host:

$ systemctl cat saslauthd 2>/dev/null | grep -E -- '-m[ =]|--socket|saslauthd'
$ find /run /var/run /var/spool -maxdepth 5 -type s -name mux -print 2>/dev/null
/var/spool/postfix/var/run/saslauthd/mux

Use the exact path your service reports. On this machine, saslauthd sits under the Postfix spool tree, not the more familiar /run/saslauthd/mux, and that mismatch is a common reason an authentication test looks broken when it is not.

$ SOCKET='/var/spool/postfix/var/run/saslauthd/mux'
$ test -S "$SOCKET" && printf 'socket exists: %s\n' "$SOCKET"
socket exists: /var/spool/postfix/var/run/saslauthd/mux

If test -S fails, stop here. The daemon may be stopped, configured elsewhere, or exposing a socket your account cannot see. Do not create a replacement socket by hand.

3. Run a safe connectivity and authentication test

-u and -p are mandatory; add service name and realm when your SASL setup expects them. Start with a deliberately invalid password:

$ testsaslauthd \
    -u GUIDE_INVALID_USER \
    -p GUIDE_INVALID_PASSWORD \
    -s smtp \
    -f "$SOCKET"
0: NO "authentication failed"

That response proves the client reached the socket and got an answer back. This build returns status 255 for a failed authentication, so capture it right away if a script needs to tell the difference:

$ printf 'exit status: %s\n' "$?"
exit status: 255

That status belongs to the command directly before printf. For a real check, swap in the real account and password at the last possible moment. A successful credential check returns OK and status 0; verify the account through the service that owns it, because an SMTP account, a system account and a SASL identity are not automatically the same thing.

4. Separate a bad password from a bad socket

Point at a path that definitely does not exist to see what a connection failure looks like, without touching anything on the host:

$ testsaslauthd \
    -u GUIDE_INVALID_USER \
    -p GUIDE_INVALID_PASSWORD \
    -f /tmp/testsaslauthd-guide-no-socket
0: connect() : No such file or directory
$ printf 'exit status: %s\n' "$?"
exit status: 255

Both cases return a non-zero status, but they point at different problems. NO "authentication failed" means the daemon answered and rejected the credentials. connect() : No such file or directory means the client never reached the socket. Check the daemon's -m setting, socket permissions and service state before you even look at the password.

Do not fix a socket error by loosening permissions broadly. If the socket belongs to a service group, run the test as an account that legitimately belongs to that group, or hand the check to whoever administers it. Elevated privileges are for inspecting or correcting the deployment, not for making an unknown password suddenly valid.

5. Include realm and service when the deployment needs them

Some backends distinguish identities by realm, and SASL clients commonly select a service name. Pass both explicitly when your daemon or application configuration specifies them:

$ testsaslauthd \
    -u 'USER_NAME' \
    -p 'PASSWORD_FROM_SECURE_INPUT' \
    -r 'AUTH_REALM' \
    -s 'smtp' \
    -f "$SOCKET"
0: OK "Success."

Those are illustrative placeholders, not defaults: the manpage documents the options but does not define a universal realm or service value. Copy the real values from the client configuration you are testing, and keep passwords out of scripts and process listings where you can. The command line is visible to other local process observers on many systems, and shell history may keep it long after you are done.

6. Repeat a check only when you need to

-R repeats the test the given number of times, which is handy for chasing an intermittent socket or backend response, but it also means repeated authentication attempts and log lines. Keep the count small:

$ testsaslauthd \
    -u GUIDE_INVALID_USER \
    -p GUIDE_INVALID_PASSWORD \
    -s smtp \
    -f "$SOCKET" \
    -R 2
0: NO "authentication failed"
1: NO "authentication failed"
$ printf 'exit status: %s\n' "$?"
exit status: 255

Do not use a large repeat count against a production account or while chasing a rate limit. There is nothing to clean up after this example since it only sends test requests, but the authentication logs it generates may still need retaining or clearing under your normal operational policy.