3. Authentication

When GNU Anubis accepts an incoming connection, it first has to identify the remote party, i.e. determine whether it has the right to use Anubis resources and, if so, what configuration settings should be used during the session. We call this process authentication. The exact method of authentication depends on Anubis operation mode. Currently there are two modes:

transparent

This is the default mode. It is compatible with versions of GNU Anubis up to 3.6.2. In this mode, Anubis relies on AUTH service (identd) to authenticate users.

auth

This mode uses SMTP AUTH mechanism to authenticate incoming connections. See section Pixie & Dixie, this is the first draft description of this mode.

Both modes have their advantages and deficiencies, which you have to weigh carefully before choosing which one to use. These are discussed below:

Transparent (‘traditional’) mode.

Deficiencies:

1. The user must have identd installed on his machine.
2. Each user must have a system account on the machine where GNU Anubis runs (though the system administrator may relax this limitation using user name translation, see section TRANSLATION Section).

Advantages:

1. Relative simplicity. You don't have to create your users database.
2. Authentication is performed immediately after the connection.

Auth mode.

Deficiencies:

1. You have to maintain your users database
2. User's MUA must be able to perform ESMTP AUTH.(1)

Advantages:

1. Better reliability.
2. Users do not have to run identd on their machines.
3. Users are not required to have accounts on the machine where Anubis runs.
4. Users can remotely modify their configuration files.

3.1 User Database

User Database is a place where GNU Anubis uses keeps user credentials, i.e. data used to authenticate and authorize users. The exact way of storing these data does not matter here, it will be addressed further in this manual. In this section we treat user database as an abstraction layer.

The user database consists of records. Each record keeps information about a particular user. A record consists of four fields. A field may contain some value, or be empty, in which case we say that the field has null value.

The record fields are:

SMTP AUTHID

SMTP authentication ID of the user.

AUTH PASSWORD

SMTP password.

ACCOUNT

System user name to be used.

CONFIG

Path to the configuration file.

The first two fields are mandatory and must always have non-null values. No two records in the database may have the same value of SMTP AUTHID field. When anubis is trying to authenticate a user, it first looks up in the database a record with the value of SMTP AUTHID field matching AUTHID given by the user. If no such entry is found, authentication fails. Otherwise, anubis goes on and compares the password supplied by the user with that from AUTH PASSWORD column. If these match, authentication succeeds and anubis passes to authorization state.

In this state, it first determines the user ID (UID) to switch to. If the ACCOUNT field is not null, its value is used as a login name of the system account to use. If it is null, anubis switches to the privilege level of a default not privileged user, specified by user-notprivileged statement in the global configuration file (see section user-notprivileged).

The final step is to parse user configuration file. If CONFIG field is not null, its value is used as absolute path to the configuration file. Otherwise, anubis searches for file ‘~/.anubisrc’ (where ‘~’ denotes home directory for the system account obtained on the previous step) and if such a file exists, loads it.

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’.

3.3 Managing the Database

Managing the user database is a complex task, which looks differently from administrator's and user's point of view. The administrator have full rights on the database, it can add new records and delete or modify existing ones. A user, of course, does not have such ample rights. The only thing he is able to do is to maintain his own record in the database, provided that he already has one. If he does not, he should contact the system administrator and arrange for the creation of his record.

3.3.1 Administrators

All administrative tasks are done using anubisadm command — a multipurpose tool for Anubis administrator.

The command usage syntax is:

anubisadm command [options] database-url

where command specifies the operation to be performed on the database, options give additional operation-specific parameters, and database-url specifies the database to operate upon.

All administrative tasks can be subdivided into the following five categories:

• Creating the Database
• Listing Database Records
• Adding New Records
• Removing Existing Records
• Modifying Existing Records

These operations are described in detail in the following subsections .

3.3.1.1 Creating the Database

To create a database use anubisadm --create (or anubisadm -c) command. Anubisadm will read database entries from the standard input and write them to the database. The standard input is supposed to be formatted as text database (see section Plain text databases).

Thus to create a GDBM database from plain text file ‘userlist’, use the following command

anubisadm --create gdbm:/etc/anubis.db < userlist

Similarly, to create an initially empty database, type

anubisadm --create gdbm:/etc/anubis.db < /dev/null

Notice, that if you use SQL database format, ‘--create’ command does not imply creating the database structure! So, before running

anubisadm --create mysql://localhost/dbname < userlist

make sure you create the underlying database structure (including granting privileges to the anubis user), via the usual procedure. Please refer to corresponding database manual for the detailed instructions on this.

It is sometimes necessary to convert the existing user database from one format (protocol) to another. For example, suppose you have been running GDBM database (text:/etc/anubis.db) for some time, but now it has grown considerably and you decided to switch to PostgreSQL database to improve performance. To do so, first create the database using postgres utilities. Then run

anubisadm --list text:/etc/anubis.db | \
 anubisadm --create pgsql://localhost/dbname

That's all there is to it!

3.3.1.2 Listing Database Records

The command ‘--list’ (or ‘-l’) lists the existing database. When run without additional options, it will display all records from the database, e.g.:

anubisadm --list gdbm:/etc/anubis.db

Among its other uses, such invocation is handy for converting user database to another format (see section Creating the Database).

If you wish to list only a particular record, specify the AUTHID using ‘--authid’ (‘-i’) option. For example, to list record of the user with AUTHID ‘test’, type:

example$ anubisadm --list --authid test gdbm:/etc/anubis.db

3.3.1.3 Adding New Records

To add a new record use command ‘--add’ (‘-a’). Additional data are specified via the following options:

‘-i string’

‘--authid=string’

Specify the user SMTP AUTHID.

‘-p string’

‘--password=string’

Specify user password password.

‘-u string’

‘--user=string’

Specify system user name corresponding to the given AUTHID.

‘-f string’

‘--rcfile=string’

Specify configuration file to be used for this user.

For example, the following command adds a record with SMTP AUTHID ‘test’, password ‘guessme’ and maps it to the system account ‘gray’:

anubisadm --add --authid test --password guessme \
          --user gray gdbm:/etc/anubis.db

3.3.1.4 Removing Existing Records

Removing a record is quite straightforward: use ‘--remove’ (‘-r’) command and specify AUTHID using ‘--authid’ option. For example, to remove the record created in the previous subsection, run:

anubisadm --remove --authid test gdbm:/etc/anubis.db

3.3.1.5 Modifying Existing Records

To modify an existing record use command ‘--modify’ (‘-m’). The record is identified via ‘--authid’ option. The fields to be changed are given with the following options:

‘-p string’

‘--password=string’

Specify user password password.

‘-u string’

‘--user=string’

Specify system user name corresponding to the given AUTHID.

‘-f string’

‘--rcfile=string’

Specify configuration file to be used for this user.

For example, the following command sets new configuration file name for the user ‘smith’:

anubisadm --authid smith \
          --rcfile=/var/spool/anubis/common gdbm:/etc/anubis.db

3.3.1.6 Summary of All Administrative Commands

• Usage

  anubisadm command [options] database-url

• Commands:

  ‘-c’

  ‘--create’

  Create the database.

  ‘-l’

  ‘--list’

  List the contents of an existing database.

  ‘-a’

  ‘--add’

  Add a new record.

  ‘-m’

  ‘--modify’

  Modify an existing record.

  ‘-r’

  ‘--remove’

  Remove an existing record.

  ‘--version’

  Display program version number and exit.

  ‘--help’

  Display short usage summary and exit.

• Options:

  ‘-i string’

  ‘--authid=string’

  Specify the authid to operate upon. This option is mandatory for ‘--add’, ‘--modify’ and ‘--remove’ commands. It may also be used with ‘--list’ command.

  ‘-p string’

  ‘--password=string’

  Specify the password for the authid. This option is mandatory for ‘--add’, ‘--modify’ and ‘--remove’ commands.

  ‘-u string’

  ‘--user=string’

  Specify the system user name corresponding to the given authid. It may be used with ‘--add’, ‘--modify’, and ‘--remove’ commands.

  ‘-f string’

  ‘--rcfile=string’

  Specify the rc file to be used for this authid. The option may be used with ‘--add’, ‘--modify’, and ‘--remove’ commands.

3.3.2 Users

Users maintain their database records using anubisusr command. Main purpose of this command is to keep the copy of your configuration on GNU Anubis server up to date. . We recommend to invoke anubisusr from your ‘~/.profile’, which will make sure that your configuration file is up to date when you log in. (4).

Usage

anubisusr [options] [smtp-url]

where smtp-url is a URL of your GNU Anubis server. Notice that if it lacks user name and password, then anubisusr will first try to retrieve them from your ‘~/.netrc’ file (See netrc(5) for more info), and if not found it will prompt you to supply them.

Options

‘-m mech’

‘--mechanism mech’

Only use SASL mechanism mech. Use this option several times to set a list of allowed mechanisms.

‘-v’

‘--verbose’

Verbose output. Multiple options increase the verbosity. Maximum verbosity level is 3.

‘--version’

Display program version number and exit.

‘--help’

Display short usage summary and exit.

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