Tequila Documentation
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:
- Create, edit and remove virtual mail domains.
- Create/edit/remove mail accounts (POP3 and IMAP [still in progress]).
- Create/edit/remove aliases to mail accounts and mail distribution lists.
- Delegate your virtual domain administration to different domain admins.
- Restrict those local domain admins to operate within their own domains only.
- Let your mail users configure their mail forwarder and auto responder within a vacation period.
- These vacation/forwarding services are (de-)activated automatically, depending on the dates of absence entered by the user (or turned on permanently, just as the user likes it).
- Let your mail users change their account passwords themselves.
- Let your mail users choose the language for their Tequila conversation from the list of available languages.
- Keep SASL accounts/passwords in sync with the Tequila accounts (SASL version 2).
- Define separate languages for the use by Tequila's Admin, Domain Admins and Users.
- Translate Tequila's messages into your native language without the need to be a programmer (do this job online under Tequila's web frontend in the Tequila Admin module).
- Create special mail accounts with arbitrary embedded backend scripts. Tequila comes along with a script called "detachmail", which can be used to split off attachments specified by name, and transfer the detached files to a ftp server (this includes the reply of automatically generated status mails to the sender and to one or more specified responsible persons, e.g. in your company).
Requirements
- Perl (http://www.perl.org)
Additionally, you need a bunch of Perl modules which can be downloaded at CPAN (http://www.cpan.org).
- Postfix (http://www.postfix.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 (http://www.reedmedia.net/software/virtualmail-pop3d/)
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.
- OpenSSL (http://www.openssl.org)
Is needed to communicate safely between a client (browser) and the server (Tequila) through SSL (Secure Socket Layer).
- Tequila (http://www.holgilein.de/coolprox/tequila)
It looks like you already found this address....
Architecture
- Postfix
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
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.
- Tequila
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
- One little advice
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! :-)
- Postfix
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 installSet 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/virtualModify 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 tequilaTell 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.
- OpenSSL
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.
- Tequila
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.
- Finishing the installation
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
- Some technical details
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
Tequila is designed to divide the responsibility of administration into Tequila admin tasks, domain administration, and user tasks:
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>
Contact
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