Graddress Documentation

About

Graddress is a LAMP (Linux, Apache, MySQL, (PHP, Perl, Python)) application that automatically generates graphical representations of e-mail addresses. Such graphical representations (using the default configuration) are resistant to Optical Character Recognition algorithms, because the address is "pasted" on top of a background that "confuses" OCR software.

The name is a short form of "graphical address."

Database Setup

Graddress requires a MySQL database to be setup before it will work. The database name, table name, etc. can be configured as described below. The table you use needs the following fields:

hash — varchar(255) not null
email — varchar(255) not null

The user specified in the configuration file needs SELECT, INSERT, and DELETE access to this table.

Configuration

The configuration file config.inc.php contains the following configuration options:

MySQL Configuration

$mysqlserver — hostname or IP address of your MySQL server
$mysqluser — username to authenticate to server
$mysqlpassword — password to authenticate to server
$mysqldatabase — MySQL database name
$mysqltable — table containing hashes and e-mail addresses
$hashsrc — tells the script where it should find the hash that identifies an e-mail address; values are:
- get — hash is passed as an HTTP GET variable
- dir — hash is the name of the directory the script file is in (usually a symbolic link to '.')
- filename — hash is the basename of the script file, up to, but not including the '.' before the file extension

Graphical Configuration

(These items may be moved into the database in future versions to allow configuration on a per-email basis.)

$pwd — full path of directory where the font and background files can be found (automatically set to the directory the script is in)
$fontfile — full path to the TTF font file to be used for the e-mail address
$fontminsize — minimum pseudorandom font size
$fontmaxsize — maximum pseudorandom font size
$fontminrot — minimum pseudorandom text rotation
$fontmaxrot — maximum pseudorandom text rotation
$fontcolor — font color
$minlines — minimum number of lines to draw
$maxlines — maximum number of lines to draw
$lineminred — minimum red channel value for lines
$linemaxred — maximum red channel value for lines
$linemingreen — minimum green channel value for lines
$linemaxgreen — maximum green channel value for lines
$lineminblue — minimum blue channel value for lines
$linemaxblue — maximum blue channel value for lines
$lineminthick — minimum line thickness
$linemaxthick — maximum line thickness
$bgtile — filename of a PNG image to tile onto the background

Apache Configuration

In order to use symbolic links with graphical filename extensions JPG, JPEG, GIF or PNG you have to configure Apache to treat files in the graddress directory with those extensions as PHP scripts. Here is a sample .htaccess file:

Options Indexes FollowSymLinks
AddHandler php-script .png
AddHandler php-script .jpg
AddHandler php-script .jpeg
AddHandler php-script .gif

Administration

E-mail addresses and hashes can be added and deleted through graddress/admin/. These scripts can automatically create symbolic links if $hashsrc is configured as 'dir' or 'filename'. It automatically cleans up symbolic links when you delete an address.

You can also integrate this into a wrapper around useradd and userdel. (Graddress does not come with such a wrapper. This is a reference for you if you choose to write one yourself.) The useradd wrapper needs to add the email address and hash to the database and create symbolic links (in the graddress directory) of the format '<hash>.jpg' that link to 'address.php' for 'filename' hashes or '<hash>' that links to '.' for 'dir' hashes. The userdel wrapper needs to delete the address and hash from the database and remove the symbolic links corresponding to that has.

Downloading

You can download graddress through SourceForge.

Included Fonts

Graddress includes sample fonts released under the GPL by Dustin Norlander.