3.4 Managing the Database

Managing the user database is a complex task, which looks differently from administrator’s and user’s point of view. Administrators have all privileges on the database, they can add new records and delete or modify existing ones. Users, of course, do not have such ample rights. The only thing a user is able to do is to maintain his own record in the database, provided that he already has one.

3.4.1 Administrators

All administrative tasks are done via the anubisadm command — a multipurpose tool for Anubis administrators.

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

3.4.1.1 Creating the Database

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

For example, 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 an 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 so big that 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.4.1.2 Listing Database Records

The ‘--list’ (or ‘-l’) option lists the existing database:

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

By default it displays all records from the database.

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 the record for AUTHID ‘test’, type:

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

3.4.1.3 Adding New Records

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

‘-i string’

‘--authid=string’

Specify the user SMTP AUTHID.

‘-p string’

‘--password=string’

Specify the user password.

‘-u string’

‘--user=string’

Specify the system user name for this 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.4.1.4 Removing Existing Records

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

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

3.4.1.5 Modifying Existing Records

To modify an existing record use the ‘--modify’ (‘-m’) option. The record is identified via the ‘--authid’ option. The following options supply the changed values:

‘-p string’

‘--password=string’

Specify new user password.

‘-u string’

‘--user=string’

Specify new system user name for this AUTHID.

‘-f string’

‘--rcfile=string’

Specify the user’s configuration file.

For example, the following command changes the name of configuration file for the user ‘smith’:

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

3.4.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.4.2 Users

Users maintain their database records via the anubisusr command. This command is built if anubis is configured with TLS support.

We suggest invoking anubisusr from your ‘~/.profile’, which will make sure that your configuration file is up to date when you log in.(5).

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 in netrc manual page), and if not found, it will prompt you to supply them.

Options

‘-m mech’

‘--mechanism mech’

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

‘--file=file’

‘-f file’

Sets the user configuration file name (default is ‘.anubisrc’).

‘--netrc+file’

‘-n file’

Sets the name of the automatic login configuration file (default is ‘.netrc’).

‘-v’

‘--verbose’

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

Options controlling encryption:

‘--disable-tls’

‘-d’

Disable the use of TLS encryption.

‘--tls-cafile=file’

‘-C file’

Sets the name of certificate authority file to use when verifying the server certificate.

‘--tls-priorities=list’

Sets cipher suite preferences to use. The list argument may contain a single initial keyword or be a colon-separated list of TLS keywords. The description of TLS keywords is well beyond the scope of this document. Please refer to Priority Strings in GnuTLS Manual, for a detailed discussion.

Default priority list is ‘NORMAL’.

Informational options:

‘--version’

Display program version number and exit.

‘--help’

Display short usage summary and exit.

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