Test Cyrus SASL Mechanisms with sasl-sample-server

sasl-sample-server is a diagnostic tool, not a network daemon. It reads the sample protocol from standard input, writes its base64-encoded exchange to standard output, and lets you see exactly which mechanisms it advertises. Allow about fifteen minutes if the SASL plugins are already installed.

The examples were checked on Ubuntu with sasl2-bin version 2.1.28+dfsg1-5ubuntu3.1. Other package builds can have different plugins, configuration paths or output. The installed manpage is brief, so treat the command's own usage output as the final word for this particular binary.

1. Check the installed program

Run these ordinary, read-only checks as your normal user. No elevated privileges are needed:

$ command -v sasl-sample-server
/usr/sbin/sasl-sample-server
$ dpkg-query -W -f='${Package} ${Version}\n' sasl2-bin
sasl2-bin 2.1.28+dfsg1-5ubuntu3.1
$ sasl-sample-server --help
sasl-sample-server: invalid option -- '-'
sasl-sample-server: Usage: sasl-sample-server [-b min=N,max=N] [-e ssf=N,id=ID] [-m MECH] [-f FLAGS] [-i local=IP,remote=IP] [-p PATH] [-d DOM] [-u DOM] [-s NAME]
        -l      enable server-send-last

The last command deliberately uses an unsupported long option. It still prints the useful usage summary and exits non-zero. This program documents short options rather than providing a conventional --help interface. Do not copy the usage line as a complete test: the server waits for a client exchange on standard input.

Checkpoint: Confirm that the package and executable are the ones you intend to test. If command -v finds nothing, stop and install or repair the package through your normal change process.

2. Start a harmless mechanism-list test

Feed an empty input stream to the server with a timeout. This changes no files, opens no listening socket and does not authenticate anyone:

$ timeout 2s sasl-sample-server </dev/null
sasl-sample-server: Unable to parse input
Generating client mechanism list...
Sending list of 11 mechanism(s)
S: U0NSQU1tU0hBLTUxMiBTQ1JBTS1TSEEtMzg0IFNDUkFNLVNIQS0yNTYgU0NSQU1tU0hBLTIyNCBTQ1JBTS1TSEEtMSBESUdFU1QtTUQ1IENSQU0tTUQ1IE5UTE0gUExBSU4gTE9HSU4gQU5PTllNT1VT
Waiting for client mechanism...

The exact mechanism count and base64 line depend on the installed plugins. The useful signs are Sending list of followed by a count, an S: line, and a wait for the next client message. The non-zero status is expected here because an empty stream is not a valid sample-protocol exchange. Capture the output if you are comparing plugin changes:

$ timeout 2s sasl-sample-server </dev/null > /tmp/sasl-sample-server.out 2>&1
$ sed -n '1,12p' /tmp/sasl-sample-server.out

The temporary file is disposable. Remove it after inspection with rm -- /tmp/sasl-sample-server.out; that is the only deletion in this workflow and is safe because it is an explicitly named temporary file.

3. Understand the server's input and output

sasl-sample-server is the server half of Cyrus SASL's sample client/server pair. It does not accept a TCP port option. The upstream sample implementation exchanges protocol data through standard input and output, and the exchange is base64 encoded for display. Use sasl-sample-client or another program that implements the matching sample protocol when you want to exercise a complete authentication conversation.

Do not interpret the displayed mechanism list as proof that authentication works. It only shows what the current library can advertise after loading its plugins. A mechanism can still fail because its credentials, key material, helper daemon or policy are absent.

The SASL application configuration is separate from this command line. Cyrus documentation identifies the sample application's default configuration name as /usr/lib/sasl2/sample.conf. This file is not present on the checked machine, so do not assume that a package has created it. Before adding one, inspect the package contents and your distribution's configuration policy:

$ dpkg -L sasl2-bin | grep -E '/(sample\.conf|sasl2)/'
$ find /usr/lib/sasl2 /etc/sasl2 -maxdepth 1 -type f -print 2>/dev/null

If you create a configuration file, record the change and its permissions, test it with a disposable account, and remove or restore it using your change-control process. The sample server may read settings such as pwcheck_method from the SASL configuration, but the manpage does not define a complete configuration file. Do not invent one from a copied example.

4. Select a mechanism and service identity

Use -m MECH when you need to force one mechanism for a reproducible test. The value must be a mechanism that the server advertises. For example, first capture the list, then use the exact name supplied by your own output:

$ sasl-sample-server -m SCRAM-SHA-256 -s sample < sample-input.txt
sasl-sample-server: mechanism-specific output appears here

The input file in that example is a placeholder, not a file supplied by the package. A complete exchange must come from sasl-sample-client or a protocol fixture made for the same mechanism. Do not put real passwords or production credentials in a fixture. A failed forced-mechanism test is useful: it tells you that the selected mechanism or its required support is not available, but it does not identify which dependency is missing by itself.

-s NAME supplies the service name passed to the SASL mechanisms. Use the service name expected by the mechanism or test fixture, such as sample for an isolated test. -d DOM supplies the local server domain and -u DOM supplies the user domain. These are identity inputs to SASL; neither option creates a domain, user, password or account.

5. Add addresses only when the mechanism needs them

Some mechanisms require local and remote addresses even though this sample program is not opening a network connection. Pass them with -i in the form shown by the installed usage output:

$ sasl-sample-server -i 'local=127.0.0.1;4555,remote=127.0.0.1;4556' -m SCRAM-SHA-256 -s sample < sample-input.txt

The manpage shows the semicolon between an address and port, while the option's two assignments are comma-separated. Keep the whole value quoted so the shell cannot split it. These values describe the SASL connection context; they do not make the program bind to either port. Use addresses that match the test fixture rather than guessing.

6. Set security properties deliberately

The -b min=N,max=N option sets the acceptable security-layer strength in bits. The manpage notes that min=1 means integrity. The -f option accepts comma-separated security flags as supported by the binary, including noplain, noactive, nodict, forwardsec, maximum and passcred. For example:

$ sasl-sample-server -f noplain,noactive -m SCRAM-SHA-256 -s sample < sample-input.txt

Use the strictest properties your test actually needs. maximum requests all listed security flags and can reject mechanisms that would otherwise authenticate. passcred asks the server to attempt to pass client credentials, which is a security-sensitive test and should stay in an isolated environment.

-e ssf=N,id=ID tells SASL to assume that an external layer already supplies encryption strength N and authentication identity ID. It does not create TLS, encrypt standard input or verify that an external channel exists. Only use it when a surrounding test harness has actually established that context.

7. Diagnose failures without weakening the test

A usage error usually means the option spelling or suboption syntax is wrong. Compare it with the installed usage output rather than adding undocumented flags. If the mechanism list is empty or unexpectedly short, inspect the installed plugin directory and the SASL configuration path, then check that the package's mechanism plugins are readable.

If a forced mechanism fails, remove -m once and confirm the server can still produce its list. Then test one advertised mechanism with a known-safe fixture. If authentication reaches a password check, remember that the sample server uses the SASL library's configured authentication back end. It does not create users and it does not turn a local password database into a safe production store.

Stop the process with its timeout or end-of-file. Do not run it as root merely because the binary is under /usr/sbin. Elevated privileges can expose credential stores and configuration files to the test, making a diagnostic run riskier without making SASL more correct. If you changed a configuration file, restore the previous copy or remove the new file only after recording the intended recovery.

Done means