OVERVIEW
--------
GetTor is a program for serving Tor and related files over SMTP. Users interact
with GetTor by sending it email.

The following document explains how to setup GetTor for a server admin.

PREREQUISITES
-------------

To deploy GetTor, you'll want a machine that invokes .forward files
for users. You'll also want to have python (>= 2.5) and rsync installed.

There are some limits with smtp software for outgoing email sizes. You should
check your software to ensure that you can send files that are as large
as the largest files Tor distributes. For postfix, you may want to have a line
that looks like the following in /etc/postfix/main.cf:

    message_size_limit = 50360000

In Exim, the default message size is now 50MB, which should be sufficient. The
value is also adaptable through the config file parameter 'message_size_limit'
in case you need to.

SETUP
-----

This setup descripton presumes that you have access to the latest gettor svn 
trunk somewhere in your local file system.

    gettor@hostname:~/tmp$ svn co https://freehaven.net/svn/projects/gettor gettor

After checking out the GetTor source code, you will need to install everything
as follows:

    gettor@hostname:~/tmp$ cd gettor/
    gettor@hostname:~/tmp/gettor$ python setup.py trans
    gettor@hostname:~/tmp/gettor$ python setup.py install_data
    gettor@hostname:~/tmp/gettor$ python setup.py install

This will copy necessary files to ~/opt/gettor.

Once you have everything installed, you'll want to initialize the file store:

    gettor@hostname:~/opt/gettor$ python GetTor.py -fp

You should see an rsync and finally something like:

    sent 1637 bytes  received 415792532 bytes  9558486.64 bytes/sec
    total size is 415735925  speedup is 1.00
    2009-01-05 16:49:29,226 (9222) Syncing Tor packages done.
    2009-01-05 16:49:30,155 (9222) Building packages done.

Now you'll install the cronjob. This clears the blacklist and updates packages 
daily:

    gettor@hostname:~/opt/gettor$ python GetTor.py -i

Set up a password for package forwarding commands if you wish to use that 
feature:

    gettor@hostname:~/opt/gettor$ python GetTor.py -s seCreTpAssworD

The secret password will be stored in whereever `PASSFILE' is configured in 
the configuration.

Finally, you need to setup email forwarding to the GetTor bot like so:

    gettor@hostname:~$ echo "|python /home/g/opt/gettor/GetTor.py" > ~/.forward

Now GetTor is installed, prepared and ready to serve files. Send it email!

TRANSLATION FILES
-----------------
Provided there is a working locale environment, GetTor will compile and setup
locale files for you as follows:

    gettor@hostname:~/opt/gettor$ python setup.py trans
    gettor@hostname:~/opt/gettor$ python setup.py install_data

To add a new language to GetTor, one must create a new .po file in subversion
in the proper directory. For Korean, one would create po/ko/ and add the
untranslated file (called gettor.po) to that directory. This file should be
translated but partial translations are allowed. Once this file has been
created, the GetTor program does not need to be modified.

CONFIGURATION
-------------
A proper GetTor configuration file is expected in the user's home directory
and should look similar to this:

    gettor@hostname:~$ cat .gettor.conf

    # What `From:' address are we using by default?
    MAIL_FROM = "GetTor <[email protected]>"

    # Where it is all based at. Subdirs for GetTor start from here.
    BASEDIR = "/home/gettor/gettor"

    # Should we send a `Your package will arrive soon, be patient' mail?
    DELAY_ALERT = True

    # Basename of the GetTor log files. Will be expandet to 
    # $LOGFILE-YYYY-MM-DD.log
    LOGFILE = "gettor_log"

    # The file containing the hashed command password
    PASSFILE = "gettor.pass"

    # Where do we dump erronous emails?
    DUMPFILE = "gettor.dump"

    # Do we send every mail type to every user only once before we blacklist 
    # them for it?
    BLACKLIST_BY_TYPE = True

    RSYNC_MIRROR = "rsync.torproject.org"

    # Default locale
    DEFAULT_LOCALE = "en"

    # Which languages to we support in GetTor?
    SUPP_LANGS = { "en": ("english", ),
                   "fa": ("farsi", ),
                   "de": ("deutsch", ),
                   "ar": ("arabic", ),
                   "es": ("spanish", ),
                   "fr": ("french", ),
                   "it": ("italian", ),
                   "nl": ("dutch", ),
                   "pl": ("polish", ),
                   "ru": ("russian", ),
                   "zh_CN": ("chinese", "zh",) }


    #            "bundle name": ("single file regex", "split file regex")
    PACKAGES = { "tor-browser-bundle": 
                 ("tor-browser-.*_en-US.exe$", "tor-browser-.*_en-US_split"), }


VALIDATION OF REQUESTED FILES
-----------------------------

When a user submits a successful request, GetTor will respond with an email
that has one attachment. This attachment is a zip file with a .z file
extension. The compressed file currently consists of two files: the requested
tool and a gpg signature from the packager of the respective file.

FILE SIZE ISSUES
----------------

Some email providers may not be happy with the files GetTor sends.
Gmail provides documentation of their incoming and outgoing file sizes. It is
currently 20MB (though we have sent around 21MB without issue):

	http://mail.google.com/support/bin/answer.py?hl=en&answer=8770

Other providers are not as transparent and this may cause failures.

SPAM / ABUSE PREVENTION
------------------------------

GetTor does some spam/abuse prevention. This is primarily because we don't want 
to hammer innocent inboxes with huge amounts of tor packages.

First of all, there is a DKIM checker (see "WHAT'S DKIM / WHY DKIM" above) that
prevents GetTor from answering useless spam emails. On top of that, there are 
some hard-coded checks being performed on the sender address. Only mails coming
from yahoo.com and gmail.com are allowed. However, DKIM checking and hard-coded
domain checks are currently disabled in GetTor. Mails from all addresses are 
being passed to GetTor processing. But note that besides GMail and Yahoo, only
vry few mail providers allow attachments of the size that GetTor will send out.

On top of that, there is a blacklisting mechanism. It works as follows: Each 
unique email address is allowed to mail GetTor the same type of mail once each
7 days. Mail types are sendDelayAlert, sendPackage, sendPackageHelp, 
sendSplitPackage. Blacklists are stored in the form of hashed email files under
directories. In reality, that looks as follows:

    gettor@hostname:~/opt/gettor$ ls -d /home/gettor/gettor/bl/*
        /home/gettor/gettor/bl/general
        /home/gettor/gettor/bl/sendPackage
        /home/gettor/gettor/bl/sendSplitPackage
        /home/gettor/gettor/bl/sendDelayAlert
        /home/gettor/gettor/bl/sendPackageHelp

    gettor@hostname:~/opt/gettor$ ls /home/gettor/gettor/bl/sendDelayAlert \
                                                                    | head -n 2
     0154d8584c0afa6290e21098e7ab4cc635b7d50a
     02a33e16feece8671f1274de62de32068a67cf20

In addition to this automatic blacklisting mechanism, there is the possibility 
to add blacklist entries by hand as follows:

    gettor@hostname:~/opt/gettor$ python GetTor.py -b [email protected]

Email addresses that are added this way, go to the general/ directory in the 
blacklist directory and will therefore be blocked from using GetTor in any way.

Besides the blacklisting mechanism, there is a whitelisting mechanism. It works
analogous to the manual blacklisting mechanism:

    gettor@hostname:~/opt/gettor$ python GetTor.py -w [email protected]

Whitelisting wins over blacklisting. If a user if blacklisted for X, but also
whitelisted, he will be allowed to do X.

WHAT'S DKIM / WHY DKIM?
-----------------------

NOTE THAT THIS SECTION IS CURRENTLY OUTDATED, BECAUSE GETTOR DOESN'T DO DKIM
CHECK ITSELF ANYMORE. IT RELIES ON THAT BEING DONE SOMEWHERE ELSE BEFORE THE
EMAIL ARRIVES AT GETTOR.

People who send mail to gettor need to either use a mail provider that
signs outgoing mail with DKIM, or have their email address or domain
added to the whitelist.

"DomainKeys Identified Mail", aka DKIM, is a mechanism that lets the mail
provider prove that the mail is really coming from the domain and sender
it claims to be from.

Currently GMail and Yahoo both support DKIM, along with other more
esoteric domains like paypal, AOL, earthlink, linkedin, etc. You can
check if your mail provider uses DKIM by examining the headers of emails
you send. If there's a "DomainKey-Signature:" header, then you're in
good shape.

If we didn't check the DKIM signature, people could abuse gettor into
mailbombing innocent email addresses -- one short email resulting in a
15MB attachment sent to an address of their choice is quite an attack
multiplier.

There are a few other alternative options (for example, Microsoft uses its
own proprietary design called 'Sender ID'), but since GMail is already
very common for users in blocked countries, we figured DKIM was a good
starting point.

And last, be aware that the set of domains that technically support
DKIM is probably not exactly the same set that we should recommend for
our users, due to other properties of each mail provider like their
privacy policies.