Cyrus SASL sql auxprop plugin

sql 5
sql auxiliary property plugin

Cyrus SASL auxprop plugin to access sql authentication backends.

## Description

This document describes configuration options for the Cyrus SASL auxiliary property plugin `sql`.

`sql` is a generic plugin for various SQL backends. Currently it provides access to either MySQL, PostgreSQL or SQLite databases.

The plugin requires that passwords in the database are stored in plaintext format in order to use shared-secret mechanisms.

## Configuration Syntax

The following syntax is mandatory for `sql` plugin configuration:

- SQL statements specified with sql_select, sql_select and sql_select must not be enclosed in quotes.

- Macros, e.g. `%u`, `%r` and `%v`, specified within SQL statements must be quoted individually.

See for a valid configuration example.

## Options

The following configuration parameters are applicable in the context of the `sql` plugin:

sql_engine (default: `mysql`)

  Specifies the type of SQL engine to use for connections to the SQL backend. The following types are available:

  `mysql`

    Enables the mysql driver for connections to a MySQL server.

  `pgsql`

    Enables the pgsql driver for connections to a PostgreSQL server.

  `sqlite`

    Enables the sqlite driver for connections to a SQLite server.

sql_hostnames (default: empty)

  A comma-separated list of one or more SQL servers the plugin should try to connect to and query from. Specify servers separated in `hostname[:port]` format.

  Specify localhost when using the MySQL engine to communicate over a UNIX domain socket and 127.0.0.1 to attempt a connection that uses a TCP socket.

sql_user (default empty)

  Configures the username the plugin will send when it authenticates to the SQL server.

sql_passwd (defaults: empty)

  Configures the password the plugin will send when it authenticates to the SQL server.

sql_database (default: empty)

  Specifies the name of the database which contains auxiliary properties (e.g. username, realm, password etc.)

sql_select (default: empty)

  Mandatory `SELECT` statement used to fetch properties from the SQL database.

sql_insert (default: empty)

  Optional `INSERT` statement used to create properties for new users in the SQL database.

sql_update (default: empty)

  Optional `UPDATE` statement used to modify properties in the SQL database.

sql_usessl (default: `no`)

  Specify either `yes`, `on`, `1` or `true`, and the plugin will try to establish a secure connection to the SQL server.

  Does this really work? I remember it doesn't ...

### Macros

The sql plugin provides macros to build sql_select, sql_select and sql_select statements. They will be replaced with arguments sent from the client. The following macros exist:

%u

  The name of the user whose properties are being selected, inserted or updated.

%p

  The name of the property being selected, inserted or updated. While this could technically be anything, Cyrus SASL will try userPassword and cmusaslsecretMECHNAME (where MECHNAME is the name of a SASL mechanism).

%r

  Name of the realm to which the user belongs. This could be the KERBEROS realm, the FQDN of the computer the SASL application is running on or whatever is after the @ on a username.

%v

  Value of the property being stored during insert or update operations. While this could technically be anything depending on the property itself, it generally is a userPassword.

## Example

The following example shows a typical `sql` configuration:

    pwcheck_method: auxprop
    auxprop_plugin: sql
    mech_list: plain login cram-md5 digest-md5
    sql_engine: pgsql
    sql_hostnames: 127.0.0.1, 192.0.2.1
    sql_user: username
    sql_passwd: secret
    sql_database: company
    sql_select: SELECT password FROM users WHERE user = '%u'@'%r'

## See also

authdaemond 5 , ldapdb 5 , libsasl 5 , saslauthd 8 , saslauthd.conf 5 , saslpasswd2 5 , sasldblistusers2 5 , sasldb 5 , sql 5

## Readme files

`README.Debian`

## Author

This manual was written for the Debian distribution because the original program does not have a manual page. Parts of the documentation have been taken from the Cyrus SASL's `options.html`.

    Patrick Ben Koetter
    p@state-of-mind.de