Convert a Legacy SASL Database Safely with sasldbconverter2

sasldbconverter2 converts an old Cyrus SASL database into the newer sasldb format, while you keep a restorable copy of the input. Allow about 20 minutes, plus a short maintenance window if a mail or IMAP service reads the database during the conversion.

This guide uses sasldbconverter2 from Debian's sasl2-bin package, version 2.1.28+dfsg1-5ubuntu3.1. The installed manual documents one important boundary: the converter works only with sasldb files that use the gdbm library. It does not convert an arbitrary database format.

1. Confirm the installed program

Run these ordinary, read-only checks as your normal account:

$ command -v sasldbconverter2
/usr/sbin/sasldbconverter2
$ dpkg-query -W -f='${Package} ${Version}\n' sasl2-bin
sasl2-bin 2.1.28+dfsg1-5ubuntu3.1

Your package version can differ. The command has no useful conversion flags documented in its manual. Its interface is positional:

sasldbconverter2 [old_sasldb_file [new_sasldb_file]]

The first path is the old database. The second is an optional destination. If you omit it, the program writes to its default location, usually /etc/sasldb2. Treat that default as a real system change, not as a harmless temporary output.

2. Identify the input and check its format

Set an obvious placeholder for the old file. Replace it with the path from your system; do not guess from a service name:

$ OLD_SASLDB='/path/to/old/sasldb'
$ ls -l -- "$OLD_SASLDB"
$ file -- "$OLD_SASLDB"
/path/to/old/sasldb: GNU dbm 1.x or 1.8.x database

The wording from file varies by version. You need a readable existing file, and the converter's documented compatibility is gdbm. A different file description is a stop sign, not a reason to try the command repeatedly. Find how the database was created or restore a known gdbm-backed copy first.

Checkpoint: do not continue until ls shows the intended input and you have confirmed that no service is writing it. If an authentication service uses this database, arrange a maintenance window or stop that service according to its own documentation. This guide does not prescribe a service name or unit.

3. Make and verify a backup

Conversion changes authentication data and can overwrite the default destination. Make a separate backup before starting. This command normally needs no privilege if the input is in a directory you can read and the backup directory is writable:

$ BACKUP='/secure/backup/old-sasldb.before-conversion'
$ cp --preserve=all -- "$OLD_SASLDB" "$BACKUP"
$ cmp -- "$OLD_SASLDB" "$BACKUP"
$ ls -l -- "$BACKUP"

cmp prints nothing and returns status 0 when the backup matches the input. Keep this copy until the converted database has been tested by the application. Store it with permissions appropriate for an authentication database; it may contain password data. If the backup path is protected, use sudo cp only for that copy and check its ownership and mode afterwards.

Do not use shell redirection to create a backup, and do not delete the old file after conversion. The backup is your rollback path:

$ cmp -- "$OLD_SASLDB" "$BACKUP"
$ printf 'backup verified\n'
backup verified

4. Convert to an explicit destination first

Using an explicit destination makes the first run easier to review and avoids accidentally targeting /etc/sasldb2. Choose a new path on the same host with enough space:

$ NEW_SASLDB='/var/lib/sasl2/sasldb2.converted'
$ sasldbconverter2 "$OLD_SASLDB" "$NEW_SASLDB"

The program may pause and ask you to press return before it proceeds. Read the paths it prints. Continue only when the old input and new output are exactly the ones you selected. A successful run should return to the shell without an error; the manual does not promise a particular success message.

The output directory may require elevated privileges. If the unprivileged command reports a permissions error, stop and inspect the directory rather than changing its permissions broadly:

$ ls -ld -- "${NEW_SASLDB%/*}"
$ test -w -- "${NEW_SASLDB%/*}" && echo writable

If the destination is a protected system directory, repeat only the conversion with sudo after reviewing the complete command and both paths:

$ sudo sasldbconverter2 "$OLD_SASLDB" "$NEW_SASLDB"

That command writes authentication data as root. Do not put passwords or other secrets in the command line. Do not use sudo merely to compensate for an incorrect path.

5. Check the result before switching a service

Verify that the destination exists, is non-empty, and is the database type you expected:

$ test -s -- "$NEW_SASLDB"
$ file -- "$NEW_SASLDB"
/var/lib/sasl2/sasldb2.converted: GNU dbm 1.x or 1.8.x database
$ ls -l -- "$NEW_SASLDB"

The exact file wording and permissions are host-specific. The useful checks are a successful test -s, a gdbm description, and ownership that permits the SASL-using service to read the file without making it world-readable.

Use the service's own safe authentication test against the converted file before replacing its configured database. There is no universal test command in the sasldbconverter2 manual, so do not invent one. If the service cannot authenticate a test account, restore its previous configuration or point it back to the old file, then investigate while the backup remains available.

6. Install the converted file only after testing

When the application test passes, install the new database at the path your SASL configuration expects. Make a second backup of any existing destination before replacing it:

$ sudo cp --preserve=all -- /etc/sasldb2 /etc/sasldb2.before-conversion
$ sudo cp --preserve=all -- "$NEW_SASLDB" /etc/sasldb2
$ sudo ls -l -- /etc/sasldb2

The first copy fails if /etc/sasldb2 does not exist, which is useful: do not replace that line with a blind command. If the installed service needs a reload or restart, use its documented operation during the maintenance window and then repeat the harmless authentication test.

To undo this final replacement, stop or isolate the affected service as its documentation requires, then restore the pre-conversion destination and its permissions:

$ sudo cp --preserve=all -- /etc/sasldb2.before-conversion /etc/sasldb2
$ sudo ls -l -- /etc/sasldb2

Keep both backups until users can authenticate normally and logs show no conversion-related failures. Remove old copies only under your normal retention policy.