Brandeis University GULP login tracking system
Copyright 2008 Brandeis University

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program.  If not, see <http://www.gnu.org/licenses/>.

== How it works ==

This system collects information about successful user logins in a database,
then provides a web interface for browsing and searching that information.
There's even a module to look for misuse of accounts by using IP geography
data to find rapid logins by the same user from distant locations.

Two programs read data into the database: gulp.php, which is designed to
read from UNIX-style syslog files; and gulp-csv.php, which is designed to
read from arbitrary CSV files.

Cron jobs update the geography data regularly and pre-cache IP->geography
mappings for performance.

== Requirements ==

* UNIX-like system (developed on RedHat Linux)
* PHP
* A central log collection server (probably - you could run gulp on multiple
  systems)
* MySQL

== Setup ==

1. Create a MySQL database to hold the GULP data. Load the schema from
etc/gulp.sql into it.

2. Create a MySQL database to hold the IP geography data. Load the schema
from etc/geocity.sql into it.

3. Copy the files from sbin/ somewhere, like /usr/local/sbin/

4. Copy the files from htdocs/* somewhere in the web server's document root
that PHP is parsed.

5. Edit lib/gulp-config.php. Set your database connection information and
configure the regular expressions you'll be using to read from syslog files.
A good way to perfect the regular expressions is to run perl from the
command line against your syslog files.

6. Copy the files from lib/* somewhere in the PHP include path. I like to
create /usr/local/lib/php and add that to the path in php.ini.

7. Install etc/gulp.cron in /etc/cron.d

8. Use index.php to browse GULP data. Use stolen-account.php to look for
stolen accounts.