Configure Cyrus SASL Without Guessing Which File It Reads

You will build a defensible Cyrus SASL configuration: the right file name, valid syntax and an intentional password check. Along the way you will settle on valid parameter: value lines and a verification plan. The examples match libsasl(5) from Debian package libsasl2-2 version 2.1.28+dfsg1-5ubuntu3.1.

Allow about twenty minutes for a configuration-only check. You need a shell, the application using SASL, and its documentation. You do not need elevated privileges for inspection. Writing a system configuration or restarting an authentication service normally does require sudo, and can interrupt logins, so this guide starts with a temporary file and a read-only review.

1. Identify the application name first

libsasl does not choose a universal file such as libsasl.conf. The application passes an app_name to the library. The library then looks for a file named app_name.conf in its configuration directories. Find the value in the application's manual or package documentation before creating anything:

$ command -v YOUR_SASL_APPLICATION
/usr/sbin/YOUR_SASL_APPLICATION
$ man YOUR_SASL_APPLICATION

Replace YOUR_SASL_APPLICATION with the real program. The name in the file is the library's app_name, not necessarily the executable name, service name, or protocol. The manual for the application is the authority here. For example, this host's Postfix SASL file is /etc/postfix/sasl/smtpd.conf; that path is supplied by Postfix's configuration layout, not by a generic rule in libsasl(5).

Checkpoint: Write down both values before editing: the application's app_name and the exact configuration directory it searches. If either is unknown, stop. A perfectly formatted file in the wrong directory has no effect.

2. Inspect the installed contract and available plugins

Confirm the library package and inspect the mechanism plugins without changing service state:

$ dpkg-query -W -f='${Package} ${Version}\\n' libsasl2-2:amd64
libsasl2-2 2.1.28+dfsg1-5ubuntu3.1
$ test -e /usr/lib/x86_64-linux-gnu/sasl2/libplain.so && echo 'libplain.so is present'
libplain.so is present
$ saslpluginviewer -s

The last command lists server authentication plugins when the viewer is installed. Do not infer that a plugin is usable merely because its shared object exists: the application, its credentials, and the selected verification service must agree. Debian also documents that a libsasl2-modules* package is required for server programs to authenticate, so check the installed package set when the mechanism list is unexpectedly empty.

3. Build a temporary configuration with exact syntax

Every setting occupies one physical line. Separate the parameter and value with a colon and one whitespace character. Blank lines and lines whose first non-whitespace character is # are ignored. The easy-to-miss rule is that the value must not have trailing whitespace.

$ tmp_sasl_conf=$(mktemp)
$ cat >"$tmp_sasl_conf" <<'EOF'
# Review example only; this file is not read by your service.
log_level: 1
mech_list: plain login
pwcheck_method: saslauthd
saslauthd_path: /run/saslauthd/mux
EOF
$ sed -n 'l' "$tmp_sasl_conf"
# Review example only; this file is not read by your service.$
log_level: 1$
mech_list: plain login$
pwcheck_method: saslauthd$
saslauthd_path: /run/saslauthd/mux$

The $ at the end of each line is the output from sed -n 'l', not part of the file. It makes trailing spaces visible. This temporary file changes nothing in the running system and can be removed with rm -- "$tmp_sasl_conf" when you finish the review.

4. Choose one password verification path

pwcheck_method defaults to auxprop. That method uses the SASL auxiliary-property plugins, selected with auxprop_plugin. If you choose it, make the backend explicit rather than relying on every available plugin being queried:

pwcheck_method: auxprop
auxprop_plugin: sasldb

Other documented choices are saslauthd, authdaemond, pwcheck, and alwaystrue. The last one makes password verification succeed always and is not a production authentication policy. The pwcheck daemon is deprecated; use saslauthd instead when a password-verification service is the intended design.

For saslauthd, saslauthd_path must name the run directory including its mux named pipe. Check the service's actual socket before changing the application file:

$ stat /run/saslauthd/mux
  File: /run/saslauthd/mux
$ systemctl is-active saslauthd
active

Your path and service state may differ. Do not start or restart a password service merely to make this check pass. If the socket is absent, investigate the saslauthd deployment and its permissions first.

5. Limit mechanisms deliberately

mech_list is optional and defaults to empty, meaning the application is not being restricted by this setting. When you set it, use a whitespace-separated list of mechanisms that the application and clients genuinely support:

mech_list: plain login

This example permits mechanisms that commonly carry a password. It does not provide transport encryption. Only use plain or login where the surrounding protocol already provides suitable TLS or another protected channel. An authentication success is not proof that credentials were protected in transit.

Keep log_level at its default of 1 unless you have a specific diagnostic reason. Levels 2 through 6 add progressively more authentication and protocol detail. Level 7 includes passwords and is a serious credential exposure risk; never enable it on a normal host or collect its output in a shared log.

6. Install the file only after matching the application

Once the temporary content is correct, place equivalent lines in the application-specific file identified in step 1. This is the first state-changing step. Back up the current file and preserve its owner and mode before editing:

$ sudo cp -a /PATH/TO/app_name.conf /PATH/TO/app_name.conf.bak
$ sudoedit /PATH/TO/app_name.conf

Replace both placeholders with real paths. Do not copy this command unchanged. If the file does not exist, confirm the application's documented configuration directory before creating it. Avoid adding a second conflicting setting elsewhere: the application may pass options directly to libsasl, which can override or supplement file-based values.

Restarting the application is service-disrupting and is not a generic libsasl operation. Follow that application's reload or restart procedure, preferably in a maintenance window. If authentication fails after the change, restore the backup and use the application's logs to identify whether the problem is the file name, plugin, socket, credentials, or mechanism negotiation:

$ sudo cp -a /PATH/TO/app_name.conf.bak /PATH/TO/app_name.conf
$ sudo systemctl restart YOUR_SERVICE

Only run the rollback restart if you actually changed the live file and the service needs restarting to reread it. A backup restores the previous text; it does not undo other changes made while diagnosing the incident.

7. Verify the result without trusting a successful login

First confirm that the live file contains the intended lines and no trailing whitespace:

$ sudo sed -n 'l' /PATH/TO/app_name.conf
$ sudo systemctl status YOUR_SERVICE --no-pager
$ sudo journalctl -u YOUR_SERVICE -n 50 --no-pager

Then perform the application's supported authentication test with a test account, not a real user's password. A successful login verifies the whole path only for that test: application file selection, plugin loading, password backend, mechanism negotiation, and service permissions. It does not prove that every client will use the same mechanism or that a plaintext mechanism is safe without transport protection.

If the test fails, return to the checkpoint rather than adding random options. Recheck app_name, the exact file name, pwcheck_method, the selected auxprop_plugin or saslauthd_path, and the service log. Keep log_level below 7 while doing so.

Done means