Tequila Documentation



Preamble: This document contains text. It mainly consists in subjects, adjectives and verbs. The rest is an amount of indifferent, non-predictable conglomerations of letters that are part of a character class between 'a' and 'z' (occurances of characters from 'A' to 'Z' may be likely). Literarily contamination by digits was inevitable.


Table of contents



About Tequila

"Tequila" stands for "Tool Equipment for Lazy Admins" (people like me).

To be very honest, it's also a widely known alcoholic drink which gives you a special mexican feeling when you're drunk (I'd prefer "Red Wine", but a wise man told me this name already is used by a communist windows emulator).

Tequila is a toolset for administration tasks on a Postfix mail server.

The whole Tequila suite is written in Perl, and starting with the 2.0 release it is a standalone, pre-forking webserver with HTTP redirection, SSL encryption, gzipped HTML output (if the client browser supports it), built in session management with key expiration, and authentication-dependant menu navigation.

With Tequila you are able to:


Requirements

Additionally, you need a bunch of Perl modules which can be downloaded at CPAN (http://www.cpan.org).

Postfix is a Mail Transport Agent (MTA) like Sendmail, Exim, Qmail and others. It has some nice, clean features for virtual domain declaration and is very flexible in managing different virtual domain files.
VM-Pop3d is a POP3 daemon, which can be used as a replacement for "qpopper" or similar programs. Use this little daemon and throw away your unix user accounts, which are necessary for "normal" POP3 daemons. Instead, extract your old pop3 user accounts from the /etc/passwd file and store them under a virtual domain directory structure for the use by Vm-pop3d.
Is needed to communicate safely between a client (browser) and the server (Tequila) through SSL (Secure Socket Layer).
It looks like you already found this address....

Architecture

Incoming mail is delivered by Postfix to local mail files as in:

/var/spool/mail/<VIRTUAL.DOMAIN>/<VIRTUAL.USER>

The configuration files for the virtual domains reside at:

/opt/tequila/domains/<VIRTUAL.DOMAIN>/aliases[.db] and
/opt/tequila/domains/<VIRTUAL.DOMAIN>/virtual[.db]

A summary of both the virtual and aliases files can be found at:

/opt/tequila/domains/teq_summary_aliases[.db] and
/opt/tequila/domains/teq_summary_virtual[.db]

This way saving a lot of memory and reducing the number of interfaces between the Postfix configuration file and Tequila to these summary files.

Vm-pop3d is used to serve the email requests by the users. In other words, if a user clicks "Get Emails" (or the like) in it's mail software, Vm-pop3d gives him it's email(s) and empties the mail file on the server.

Vm-pop3d in turn will look up under /etc/virtual for the domain passwd files and in /var/spool/virtual for the mail files. Due to these expectations, /etc/virtual is simply a symlink to Tequila's domain directory, and /var/spool/virtual usually is a link to /var/spool/mail.

Is at home at /opt/tequila by installation default and contains the following ingredients:

./etc => SSL certificate/key, tequila.conf
./domains => virtual domains and domain password files
./bin => tequila http(s) server and binaries
./bin/modules => tequila modules (they do nearly all the work)
./htdocs => login page, icons, help texts
./docs => documentation (more or less ;-))

Tequila runs as standalone webserver, which listens on two ports: One for incoming HTTP requests and one for user communication through SSL. The first port simply sends redirect statements back to the client's browser, which in turn lead him to the SSL port to the login page, resp. the appropriate Tequila module. Thus all traffic between the Tequila server and the client will be encrypted, to avoid sending cleartext passwords over the net.

For authentication purposes, Tequila "signs" every page it sends to a browser with a 40 digit number, which expires after a specified duration (default: 20 minutes), to prevent users to forget their open Tequila session, thus leaving their desktop unattended and therefor open for abuse.

Tequila normally interacts with Postfix via the summary virtual + aliases DB /opt/tequila/domains/teq_virtual_summary[.db] and /opt/tequila/domains/teq_aliases_summary[.db].

The Tequila server is started and stopped via the init-script (default) "/etc/init.d/tequila".


Installation

Before I forget, I may give you an advice that is always underestimated:

Please backup your data first! At least the Postfix part and your probably existing virtual Tequila domains!

You might think: "Yo, later this day..." -- will probably come a moment you snivel! Just think about all the precious time you invested in your box. But wait a minute! If you like pain and doing a lot of senseless work, this may be the right way to get your full 100 percent package of it: Simply don't draw a backup! :-)

Get the software from www.postfix.org and install it.

Use the included example (./doc/examples/postfix_main.cf) to point Postfix' /etc/postfix/main.cf configuration to Tequila's domain summary files, in which all information concerning your virtual domains will be kept.

Please study this file carefully, since misconfiguration will give you a lot of trouble!

Sorry for not going too deep into Postfix' configuration at this point, but it would go beyond the scope of this document by far.

HINT FOR SUSE USERS:

SuSE version 7.x:

You urgently should set the option "POSTFIX_CREATECF" to "no" in the file "/etc/rc.config.d/postfix.rc.config"! If you fail to do so, Yast always re-creates the Postfix "main.cf" file when it runs "SuSEconfig"!

Bad behaviour.... which inspired me to swear like a beduin.


SuSE version 8.x:

Set the switch "ENABLE_SUSECONFIG" to "no" in the configuration file "/etc/sysconfig/suseconfig", to prevent SuSE from changing the Postfix config file.


Download the software at www.reedmedia.net/software/virtualmail-pop3d/

Follow these steps:

tar xzvf vm-pop3d-<version>.tar.gz
cd vm-pop3d-<version>
./configure --enable-virtual --prefix=/usr
make install

Set the symlink to the real domain/user maildata files:

ln -s /var/spool/mail /var/spool/virtual

Set the symlink to the domain password files:

ln -s /opt/tequila/domains /etc/virtual

Modify the inetd config file /etc/inetd.conf and replace 'pop3' with:

pop3 stream tcp nowait root /usr/sbin/tcpd /usr/sbin/vm-pop3d --user tequila --group tequila

Tell inetd about the changed configuration:

killall -HUP inetd

Test the POP3 server:

telnet localhost 110


Note I: Vm-pop3d distinguishes between lower and upper chars in account names and domains! For this reason, you should keep all hosted accounts in lower case and you should also inform your users about this mail account name idiosyncrasy.

Note II: If you use Netscape 4.xx, please replace '@' in your Netscape account name settings with ":", since Netscape pre-filters the account name before it sends it to the mail server.


Download the software from http://www.openssl.org, unpack it, change to the new created directory, and do a "./config; make; make test; make install". The installation goes into '/usr/local/ssl/', which is exactly the place Tequila expects it to be.


This 2nd Tequila release comes along with an install file. It probes for required software and Perl modules, and asks you some questions to customize your installation. To start the installer, jump into the new created directory after unpacking the archive and run './install'.

Please run this program now, and come back after you nailed Tequila onto your hard disk!

[...hours later...]

Ahhh! Most likely some Perl modules are missing on your system! If not, it would really make me wonder! ;-)

Perl modules:

The required modules are.... quite a lot!

To get/install a Perl module, either go to http://www.cpan.org, the Comprehensive Perl Archive Network, and download the appropriate module (typically followed by a "tar xzvf modulename.tar.gz; cd modulename; perl Makefile.pl; make; make install"), or do a

perl -MCPAN -e 'install Blah::Modulename'

However, I prefer the latter, due to the convenience and because it automatically resolves hidden dependencies. Simply follow the leader (as long as his first name isn't "Adolf", anyway... :-)).

Perl / Special notes for Debian users (including 'Woody'):

Note I: The Perl version is shipped with a 'DB_File' module which was linked against the Berkeley-DB version 2, which in turn produces DB-files with a version number 5, whereas Postfix was linked against Berkeley-DB version 3 (file version 7).

To prevent Tequila/Perl from producing DB-files that cannot be read by Postfix, you have to install the Debian package 'libdb3-dev', and then get/install the 'DB_File' Perl module.

Note II: If you have problems installing the Net::SSLeay module, try "apt-get install libnet-ssleay-perl". The Tequila installer should work afterwards.


After getting the modules to run, start the Tequila server (the path depends on your installation):

/etc/init.d/tequila start

Now point your browser to the address and HTTP port you have choosen at the installation. Let's say:

http://your_mail_server:8080

Tequila's login screen should appear (if not, your browser's proxy setting are most likely wrong).

Use the admin/example passwords below to login and play a bit with the shipped example domain.

Pre-installed passwords

Here are the passwords for the Tequila administrator and the pre-installed domains/users:

User
Password
Permission
admin
x
Admin
example.org x
Domain Admin
pink.panther@example.org x
User
any_other@example.org x
User

Tequila cronjob

Now, we finally (nearly, please stay patient ;-)) need a cronjob for the automated activation/deactivation of the auto replier and forwarder services.

Run "crontab -e" as user 'tequila' and insert the line:

0 0 * * * /opt/tequila/bin/cronjob_vacation


If you made it that far, the rest is administration and a question of understanding how Tequila requires Postfix to operate:

Virtual mail addresses are kept under Tequila's control in the files /opt/tequila/domains/DOMAIN/virtual and /opt/tequila/domains/DOMAIN/virtual.db. Two summary files (one for the aliases, one for the virtual users) also exist to collect all of your users/domains at a single place. This way, you don't need to change Postfix' main.cf all the time you create/delete a virtual domain.

Tequila uses postfix-style virtual domains due to better membership handling (see `man virtual` for details).

Each virtual address ("user.name@domain.net") is mapped to a local user ("user.name~domain.net"), which in turn can be found in the appropriate aliases file in /opt/tequila/domains/DOMAIN/aliases[.db].

These aliases files contain the delivery targets (can be either a regular mail file for POP usage, a backend script, an include file, a link to another virtual user address, or one or more of the mentioned already).

Have a look at the pre-installed domain examples beneath ./domains to see how the virtual/aliases files have to be styled.

The whole information in this section is mainly interesting if you need to build mass user accounts by own scripts (maybe for migration purposes). Normally, you're simply doing your domain stuff by clicking around in Tequila's web interface.

Basic operations

Create the domain if it doesn't exist yet, then create the list in the Domain Lists module.
If you would like to suppress Tequila's vacation response for this class of mail servers, please create/edit the file "~tequila/domains/novacation" with your favourite editor, and enter the machine names you'd like to blacklist. Simply enter one machine name per line ("grep" regular expressions are allowed).

Translations / Language localisation

Simply go into the Tequila Admin module, select "Language localisation", click "New language", and enter the name of your language and a proper identifier (like "de_DE"). Then select your language from the listbox, click "Edit language" and translate every program module into your language. After saving your translations go back to the Tequila Admin module select your now available language, and save the configuration.

Please send any new contributed localisation back to me, to make other admins happy, too!

Use the "Publish archive" button in the "Language Localisation" menu. Doing so, a compressed tar archive containing your contributed language directory will be created and subsequently sent back to me. Thanks!

Tequila mailing list

There's a Tequila mailing list available at:

<tequila-list@holgilein.de>

To subscribe this list, send an email to

          <tequila-list-subscribe@holgilein.de>

To unsubscribe send to

         <tequila-list-unsubscribe@holgilein.de>

And if you need help about the mailing list commands, send an email to

          <tequila-list-help@holgilein.de>

Subject line and message body may contain arbitrary text.


There's also a mailing list for Tequila developers

    <tequila-devel-list@holgilein.de>

The same rules/extensions apply as for the user mailing list above.

Contact

If you have ideas that might help improve Tequila, or problems with it, simply send me an email to:

Tequila's homepage is a part of my homepage, which can be found here. This is also the place to watch my pictures and to see me in my natural habitat, which is going to be New Zealand in the near future....

Disclaimer

Use the program(s) under the conditions listed in the file 'license.txt', which simply is the GPL.

I will give ABSOLUTELY NO WARRANTY to either any part of the Tequila suite, or regarding the integrity of any data on your computer.

If your box blows up and turns into smoke, it is simply your problem, not mine....


Enjoy your Tequila.... :-)

Holger Jahn, 01.09.2003