3.2 Database URL

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

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

The detailed description of each URL part follows:

proto

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

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

These protocols are described in detail below.

user

User name necessary to access the database.

password

User password necessary to access the database.

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 database protocols.

params

A list of protocol-dependent parameters. Each parameter is of the form keyword=name, parameters are separated by semicolons.

3.2.1 Plain text databases

This is the simplest database possible. It is kept in a plain text file. Each line in this file represents a single record, empty lines and lines beginning with ‘#’ (comments) sign are ignored. Records consist of fields, each field being a sequence of characters. Fields are separated by colons (‘:’, ASCII 58). If ‘:’ character occurs in a field, it is preceeded by a single backslash character (‘\\’, ASCII 92). A record must contain at least two fields.

1. SMTP ‘AUTHID’.
2. SMTP password.
3. Account name.
4. Path to 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.2.2 Databases in GDBM format

The protocol value ‘gdbm’ specifies a GDBM database. For the detailed description of GDBM system (gdbm)Top section `Introduction' in The GNU DBM Manual.

URL syntax for GDBM databases is:

gdbm:path

where path specifies absolute file name of the database file.

3.2.3 MySQL and PostgreSQL

This is the most flexible database format. GNU Anubis 4.1.1 supports MySQL(2) and PostgreSQL(3) 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 exact database type to use. Use ‘mysql’ for MySQL databases and ‘pgsql’ or ‘postgres’ for PostgreSQL databases.

Optional user and password specify authentication credentials used to access the database.

Host sets 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 dbname element.

Finally, further details needed for connecting to the database may be given by URL parameters. All of them have reasonable default values, so you'll have to specify only those parameters that does not match the default values. Known parameters are:

port=number

Specifies the port number to be used when connecting to the database. If it is not specified, the behavior depends on the value of socket parameter: 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 UNIX name of the socket to connect to. This parameter cannot be used together with port (see above).

bufsize=number

Sets the length of the buffer used to create SQL queries. Default is 1024 bytes.

table=string

Specifies the name of database table keeping where the authentication data are stored. 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 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 path to the user's configuration file. Default is ‘rcfile’.

This document was generated by Sergey Poznyakoff on December, 20 2008 using texi2html 1.78.