Safely add and remove Cyrus SASL users with saslpasswd2

This guide creates a user in the Cyrus SASL secrets database, confirms the entry, and shows how to remove it when necessary. Allow about 10 minutes if the application already uses the standard sasldb database. You need the sasl2-bin package and administrative access to the database file, which is normally a root-owned resource.

Before you change anything

saslpasswd2 manages credentials for server programs and SASL mechanisms that use the standard libsasl database. It is not a general Linux account tool: it does not create a Unix user, grant shell access or configure an SMTP, IMAP or other service.

This machine has sasl2-bin version 2.1.28+dfsg1-5ubuntu3.1. The binary reports Cyrus SASL and libsasl version 2.1.28. Check the executable and version on the host you are changing:

$ command -v saslpasswd2
/usr/sbin/saslpasswd2
$ saslpasswd2 -v
Built against SASL API version 2.1.28
LibSasl version 2.1.28 by "Cyrus SASL"

The exact version matters when comparing behaviour between distributions. The examples below use a separate database path so that the workflow is easy to test. A production path such as /etc/sasldb2 should be changed only with the service owner's procedure and permissions in mind.

1. Choose the database, user and realm

Set shell variables for the values you intend to use. The user name is an application identity, not necessarily a local login. If you omit a realm, Cyrus SASL normally uses the server's fully qualified domain name. Use -u when the service expects a particular realm.

SASLDB='/etc/sasldb2'
SASL_USER='smtp-relay'
SASL_REALM='auth.example.test'

Do not put a real password in a shell variable. Shell history, process inspection and logs are poor places for credentials. The database itself is security-sensitive: Cyrus SASL documentation warns that sasldb stores plaintext password values, so only the services that need to verify them should be able to read the file.

2. Create or update the entry

For an interactive change, run this as root or as the account that owns the database. The command prompts for the password twice and writes the entry to the file supplied with -f:

$ sudo saslpasswd2 -c -f "$SASLDB" -u "$SASL_REALM" "$SASL_USER"
Password:
Again (for verification):

-c asks the mechanisms to create the account and cannot be combined with -d. For a new entry, keep the normal plaintext userPassword property unless you have confirmed that the application's mechanism-specific secret is sufficient. The -n option suppresses that property and stores only mechanism-specific secrets, such as those used by OTP, SCRAM or SRP.

For automation, -p enables pipe mode. It disables prompting and password verification, so feed the password through standard input and protect the surrounding job and logs. This example is deliberately a placeholder, not a production secret:

$ printf '%s\n' 'REPLACE-WITH-A-ROTATED-SECRET' | sudo saslpasswd2 -c -p -f "$SASLDB" -u "$SASL_REALM" "$SASL_USER"

Pipe mode is also the default when standard input is not a terminal. Supplying -p explicitly makes scripts clearer. On an existing entry, omit -c when changing its password, and keep the same -f, user and realm values.

3. Verify the entry without printing its secret

Use sasldblistusers2 to list identities and properties in the same file. It does not display the password:

$ sudo sasldblistusers2 -f "$SASLDB"
[email protected]: userPassword

The output should contain the expected user and realm. If it is empty, check that the verification command names exactly the same file and realm as the write command. A successful list proves that the record exists, not that the consuming service accepts it. The service must also be configured to use the sasldb-backed auxprop plugin and a compatible SASL mechanism.

4. Check the file before handing it to a service

Inspect ownership and mode without opening the database contents:

$ sudo stat -c '%A %U:%G %n' "$SASLDB"
-rw-r----- root mail /etc/sasldb2

The displayed owner and group are examples only. Use the account that your service actually runs as, and keep ordinary shell users out. Do not paste the database into tickets or backup excerpts. If the file has unexpectedly broad permissions, stop and fix access through your platform's normal administration process before starting or reloading the service.

5. Remove an entry deliberately

$ sudo saslpasswd2 -d -f "$SASLDB" -u "$SASL_REALM" "$SASL_USER"
$ sudo sasldblistusers2 -f "$SASLDB"

-d deletes the entry and is mutually exclusive with -c. An empty listing, or a listing without the target identity, confirms that the record is gone from that file. To undo an accidental deletion, recreate the entry with -c and a newly supplied password, then verify the service with its normal authentication test. Do not try to recover a password from sasldb or invent a copy of the old secret.

Common traps

• Wrong file: omitting -f, or using a different path during verification, can make a correct change appear missing. Copy the path into both commands.
• Wrong realm: [email protected] and the same user in another realm are different identities. Confirm the application's realm handling before adding a second record.
• Unexpected prompt: a terminal normally triggers interactive prompting. Use -p only when your input contains the intended password and the automation channel is protected.
• Option conflict: -c and -d cannot be combined. Choose creation or deletion, then run the list command.
• Service still rejects the user: the database record is only one part of SASL authentication. Check the service's application name, mechanism, auxprop configuration, file permissions and service logs.