[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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:
identd
)
to authenticate users.
Both modes have their advantages and deficiencies, which you have to weigh carefully before choosing which one to use. These are discussed below:
Deficiencies:
identd
installed on his machine.
Advantages:
Deficiencies:
Advantages:
identd
on their machines.
4.1 User Database 4.2 Database URL 4.3 Managing the Database
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
GNU Anubis uses User Database for keeping 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
AUTH PASSWORD
ACCOUNT
CONFIG
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.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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:
`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.
keyword=name
, parameters are separated
by semicolons.
4.2.1 Plain text databases 4.2.2 Databases in GDBM format 4.2.3 MySQL and PostgreSQL MySQL and PostgreSQL databases
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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.
The URL syntax for this type of databases is quite simple:
text:path |
where path specifies absolute file name of the database file.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The protocol value `gdbm' specifies a GDBM database. For the detailed description of GDBM system 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.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
This is the most flexible database format. GNU Anubis 4.0 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.
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:
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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.
4.3.1 Administrators The Administrator's View 4.3.2 Users The User's View
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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:
These operations are described in detail in the following subsections .
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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 4.2.1 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!
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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 4.3.1.1 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 |
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
To add a new record use command `--add' (`-a'). Additional data are specified via the following options:
SMTP AUTHID
.
AUTHID
.
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 |
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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 |
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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:
AUTHID
.
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 |
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
anubisadm command [options] database-url |
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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).
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.
[ << ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |