diff options
Diffstat (limited to 'README')
| -rw-r--r-- | README | 227 |
1 files changed, 227 insertions, 0 deletions
@@ -0,0 +1,227 @@ + Tamarind + + Say Good-Bye to Spam, Forever + + +1. INTRODUCTION + +Tamarind is a web application intended for use on GNU/Linux systems which host +both a web and mail server. Tamarind lets a user of such a system easily manage +a list of randomly generated e-mail aliases, through a simple and friendly +web interface. + +Tamarind is an acronym; it stands for: + + Throwaway Mail Alias Randomization is not Defeatable. + ^ ^ ^ ^ ^ ^ ^ ^ + +2. FUNCTIONALITY + +The user of Tamarind logs into the Tamarind web service by entering +their Linux user ID and password into a form. Once authenticated, +the user is presented with a list of their e-mail aliases, intially +empty. + +A new alias can be created by optionally filling in the Memo +input field, and clicking the Create New button. + +The randomly generated alias consists of a ten digit numeric string resembling +a North American style telephone number, exemplified by 123-456-7890. +This is the local part of the e-mail address. Of course, it has a domain +part: the configured mail domain of the server. If the domain is example.com, +then the alias looks like 123-456-7890@example.com. + +The alias becomes active immediately. E-mail received for this alias is +delivered to the user's mailbox. + +The Memo field is a piece of arbitrary text associated with an alias; +the user can put whatever information they wish. + +An alias can be deleted at any time. The user can simply enable a checkbox +next to the alias in the alias list view. After checkboxing one or more +aliases, the Del button permanenty removes them. + +Once removed, an alias stops working; mail received by the mail server +for that alias is simply undeliverable at the SMTP level, and "bounces" +back to the originator. + +2. ARCHITECTURE + +Tamarind is a CGI program written in the TXR language, running under +the Apache web server. Each web request from a web browser launches +a new instance of the Tamarind program. + +Tamarind authenticates users via SASL---it opens a Unix domain socket +to the saslauthd daemon to validate their user ID and password. + +User sessions are maintained in per-user persistent files stored on the server +in a configurable session directory. A browser cookie is associated with an +authenticated browser. + +A user may have only one session at a time, making it impossible to log +in at the same time from multiple locations. If a user makes a new session +on Computer B, the previous session from Computer A is overwritten, and +the cookie stored in the browser on Computer A becomes invalid. + +The aliases maniupulated by Tamarind are stored in a single alias file, +usually called /etc/tamarind/aliases which is hooked into the Exim mail +server's configuration as an auxiliary aliases file processed in +addition to the usual /etc/aliases. + +The Memo texts are stored in the aliases file; to the mail server, +those lines of the file appear as comments. + +Here is a visual representation of the architecture: + + + +---------+ HTTPS +------------+ + | Browser | <-------> | Apache | + +---------+ +------------+ + ^ + | + CGI + | + v + +------------+ +------------+ + | Tamarind | <-- Unix Socket --> | saslauthd | + +------------+ +------------+ + | | + | \ + | -- /var/run/tamarind/session/* + \ + ------------ /etc/tamarind/aliases + / + | + | + SMTP mail +----------+ + ----------------> | Exim MTA | ----> your inbox + +----------+ + + +3. HOW TO INSTALL TAMARIND + +3.1 Overview. + +An intallation of Tamarind requires the correct configuration in +multiple places, with correct permissions of files an directories. + +Tamarind itself must be configured where to maintain the aliases file, and +where to keep the sessions. The default values for these configurations can +probably be used. + +The Apache web server must be configured to present the Tamarind application to +the world. The Apache account (www-data, on Debian servers) must be added to +the sasl group in /etc/groups, so that Tamarind has permissions to open the +SASL socket. + +The Exim mail server must be configured to scan the Tamarind-maintained aliases +file, and optionally may be configured such that mail received for Tamarind +aliases bypass some anti-spam checks. The rationale for this is given +below. + +Of course, the TXR language is required: version 135 or later. + +Detailed configuration steps follow. + +3.2 Apache + +Choose a location for the code, and put the code there. Make sure the +directory is owned by the the Apache user and group (www-data:www-data) +and has appropriate permissions to that directory and the code. + +For instance, suppose the code lives in /home/projects/tamarind. + +Also suppose that we want the application to appear on the +server as /tamarind + +Then use a configuration similar to the following in Apache's +httpd.conf: + +Alias /tamarind /home/projects/tamarind + +<Directory "/home/projects/tamarind"> + AllowOverride None + Options All -Indexes FollowSymlinks MultiViews + Options +ExecCGI + Order allow,deny + Allow from all + AddHandler cgi-script .txr + RewriteBase /tamarind + RewriteEngine on + RewriteCond %{HTTPS} !^on$ [NC] + RewriteRule ^$ https://%{HTTP_HOST}%{REQUEST_URI} [R,L] + RewriteRule ^$ main.txr +</Directory> + +Don't forget that Apache has to be restarted for config +changes to take effect. You may wait to do this restart +until configuring SASL permissions. + +3.3 SASL-Related Group Permissions + +Edit the /etc/groups file. Ensure that the sasl group +contains the Apache user. On Debian, that user is www-data, +and the line in /etc/groups might look like this: + + sasl:x:45:www-data + +Of course, other user IDs may be present there in addition +to www-data. Multiple user IDs are comma separated, as in: + + sasl:x:45:joe,mary,www-data + +(joe, mary and www-data are members of the sasl group). + +Apache must be restarted into order to pick up this +new group membership. + +3.4 Exim + +3.4.1 Create the Tamarind aliases directory + +# mkdir -p /etc/tamarind +# touch /etc/tamarind/aliases +# chown -R www-data:www-data /etc/tamarind + +Make sure the directory itself has rwxr-x--- (750) permissions. 755 is also +acceptable (the directory can be readable and searchable to others, but not +writable). Tamarind's umask ensures that the files in this directory are only +readable to their owner and group, not others. + +3.4.2 Exim Permissions to read Aliases + +Exim runs as the "Debian-exim" user on Debian. This user doesn't have access +to files created by the Apache user "www-data", such as the file +/etc/tamarind/aliases. To address this, we add the Debian-exim user to the +www-data group in the /etc/groups file. + + www-data:x:33:list,Debian-exim + +3.4.3 Exim Configuration + +Early versions of Tamarind worked directly with /etc/aliases. Later, it was +changed to use an alternative aliases file, /etc/tamarind/aliases. + +An Exim configuration change is required for it to process this file just like +it processes aliases. + +On the system where Tamarind is developed, Exim is configured using the "all in +one file" configuration style. The following has been added to the file, right +after the system_aliases: section: + +##################################################### +### router/450_exim4-config_tamarind_aliases +##################################################### +tamarind_aliases: + debug_print = "R: tamarind_aliases for $local_part@$domain" + driver = redirect + domains = +local_domains + allow_fail + allow_defer + data = ${lookup{$local_part}lsearch{/etc/tamarind/aliases}} +##################################################### +### end router/450_exim4-config_tamarind_aliases +##################################################### + +In a "separate files" configuration style for Exim, this would be placed in its +own file: router/450_exim4_config_tamarind_aliases. |