3.3 Database URL

Anubis database is identified by its URL, or Universal Resource Locator. A URL consists of following elements (square brackets enclose optional ones):

proto://[[user[:password]@]host]/path[params]

where:

proto

Specifies the database protocol. The protocol describes how to access the database. In a way, it may be regarded as specifying the database type. Currently, GNU Anubis supports the following database protocols:

‘text’	A plain text file with users’ credentials.
‘gdbm’	GDBM database
‘mysql’	MySQL database
‘pgsql’	PostgreSQL database
‘postgres’	Alias for ‘pgsql’.

These protocols are described in detail below.

user

The name of the user authorized to access the database.

password

Password for the above user.

host

Domain name or IP address of a machine running the database.

path

A path to the database. The exact meaning of this element depends on the database protocol. It is described in detail when discussing particular protocols.

params

A list of protocol-dependent parameters. Each parameter consists of the parameter name, or keyword and its value separated by a equals sign:

keyword=name

Multiple parameters are separated by semicolons.

3.3.1 Plain text databases

A simplest database is a plain text file, with lines representing records. Empty lines and lines beginning with ‘#’ (comments) sign are ignored. A record consists of fields, separated by colons (‘:’, ASCII 58). If ‘:’ character occurs as a part of a field, it must be escaped by a single backslash character (‘\\’, ASCII 92). Each record must contain at least two and no more than four fields:

1. SMTP ‘AUTHID’.
2. SMTP password.
3. Account name.
4. Pathname of the user configuration file.

URL syntax

The URL syntax for this type of databases is quite simple:

text:path

where path specifies absolute file name of the database file.

3.3.2 Databases in GDBM format

The protocol value ‘gdbm’ specifies a GDBM database. For the detailed description of GDBM system Introduction in The GNU DBM Manual.

Technically speaking, each GDBM record consists of a key and content. Its key holds the value of SMTP ‘AUTHID’, whereas its content holds SMTP password, system account name and path to user configuration file, separated by commas. As it was with ‘text’ databases, the two last fields are optional.

The URL syntax for GDBM databases is:

gdbm:path

where path specifies absolute file name of the database file.

3.3.3 MySQL and PostgreSQL

This is the most flexible database format. GNU Anubis 4.3 supports MySQL(3) and PostgreSQL(4) interfaces. No matter which of them you use, the implementation details are hidden behind a single consistent Anubis interface.

GNU Anubis supposes that all user data are kept in a single database table. This table must have at least four columns for storing SMTP ‘AUTHID’, SMTP password, system account name and path to user configuration file. Among those, only the last two may have NULL values. There is no restriction on the name of the database or the authentication table, nor on its column names. This information may be specified in URL as discussed below.

URL syntax

proto://[[user[:password]@]host/]dbname[params]

Proto describes the database type to use. Use ‘mysql’ for MySQL databases and ‘pgsql’ or ‘postgres’ for PostgreSQL databases.

Optional user and password specify authentication credentials for accessing the database.

Host sets the domain name or IP address of the machine running the database. It may be omitted if the database resides on ‘localhost’.

The database name is specified by the dbname element.

Further details needed for connecting to the database are given by URL parameters. All of them have reasonable default values, so you’ll have to specify only those parameters that differ from the default. The following parameters are defined:

‘port=number’

Specifies port number the database server is listening on. If it is not given, the behavior depends on the value of the ‘socket’ parameter (see below). If ‘socket’ is not present, the program will use the default port number for the given protocol (i.e. 3306 for ‘mysql’ and 5432 for ‘pgsql’.

‘socket=string’

Specifies the UNIX file name of the socket to connect to. This parameter cannot be used together with ‘port’ (see above).

‘bufsize=number’

Sets length of the buffer for storing SQL queries. Default is 1024 bytes.

‘table=string’

Specifies name of the database table with the authentication data. Default is ‘users’.

‘authid=string’

Specifies the name of a column in ‘table’ which holds ‘AUTHID’ value. Default is ‘authid’.

‘passwd=string’

Specifies the name of a column in ‘table’ which holds the user password. Default is ‘passwd’.

‘account=string’

Specifies the name of a column in ‘table’ which holds the name of system account to be used for this ‘AUTHID’. Default is ‘account’.

‘rcfile=string’

Specifies the name of a column in ‘table’ which holds the path to the user’s configuration file. Default is ‘rcfile’.

When using a MySQL database (‘mysql://’), database parameters and access credentials are first read from the file ‘/etc/my.cnf’, if it exists. This file called option file in ‘MySQL’ parlance (see option files). is organized in groups, each group beginning with the group name in square brackets on a separate line. Within a group, each non-empty line consists of a MySQL option name, optionally followed by an equals sign and the value. By default, settings from the group named ‘anubis’ are read.

Two additional parameters are provided to fine-tune this behavior:

‘options-file=file’

Read options from file instead of ‘/etc/my.cnf’. An empty value (‘options-file=’), disables using the options file.

‘options-group=name’

Set the name of the group in the MySQL configuration file, from which to read configuration options.

This document was generated on January 6, 2024 using texi2html 5.0.