<< Introduction

Contents

Installation (Virtual Appliance) >>

Installation (PHP Source)

FreeNATS requires a LAMP (Linux, Apache, MySQL and PHP) environment in which to operate (tested with Apache 2, MySQL 4 and 5, PHP 4 and 5). The actual test scripts may require special privileges to run (dependent on your site and/or PHP security setup).

Initial Setup

Download the current release (latest stable) from www.purplepixie.org/freenats

Extract the freenats-X.XX.Xx.tar.gz file

The "web" directory contains the interactive elements of the system and must be "published" by your web server. The other directories should ideally not be web readable (though all scripts should be safe and the directories contain .htaccess files to deny access if your configuration allows it).

If you move the "web" directory from the same location as the "base" directory you must edit "web/include.php" and change the BaseDir variable to the new location of "base" (including trailing slash).

You can optionally relocate the other directories but each must have it's "include.php" file edited to point BaseDir at the "base" location.

Edit "base/config.inc.php" and input your MySQL server, username, password and database settings.

To Setup Database Automatically

Rename "web/firstrun-.php" to "web/firstrun.php"

Navigate to http://YOUR.FREENATS.WEB.URL/firstrun.php

Follow the onscreen instructions here to test the database connection and setup the schema. If one of these stages returns an error then you should probably go no further. If your database test is failing then check your connection information, perhaps with a third-party tool. You can use the feedback link at www.purplepixie.org/freenats to report the problem.

Rename the file back to "web/firstrun-.php" to stop anyone else from running it (a check ensures it will only run if named correctly).

To Setup Database Manually (Skip if Setup Automatically - above)

The "base/sql" directory contains three .sql files - schema.sql and default.sql contain the schema and default settings respectively and must be imported via the tool of your choice.

The example.sql file contains some example settings and is optional though recommended.

Scheduled Jobs

In order for the system to perform tests the test script must be periodically called (usually via cron). The tester script may require special privileges to operate as it performs low level socket operations.

You can test this using the "test/ping.sh" script (more details are available in the advanced section of the documentation).

All scripts run must have the current directory set to their directories. There are two ways of running the test script, which is recommended to be run every five minutes.

The "bin/test-threaded.sh" script (the recommended method) spawns a background process to test each enabled node. Each node completes testing and then generates email alerts (flushes the alert queue). You will get one alert action (email) for each node event (if two nodes fail then you will get two alerts).

The "bin/tester.sh" script (not recommended) will run through each node one at a time in sequence testing each in turn. This will not complete and flush the alert queues until all tests have been processed and recorded so is much slower and if it hangs all tests will stop not just the one node. This method is slower and much more liable to failure but generates one alert per total testing run and can be useful for debug purposes.

The "bin/cleanup.sh" script is recommended to be run at least daily and will clean up old data inline with your data retention settings (see advanced documentation for more information). It only operates on the database and should require no special user privileges to operate.

Obviously you can execute your chosen test method and cleanup periodically with the scheduling tool of your choice but there follows an example setup for CROND on *nix:

• Create the directory /etc/cron.five
  
• In it create a script to fire the tester called something like freenats-tester.sh
  

  #!/bin/bash
  cd /opt/freenats/bin
  ./test-threaded.sh 2>&1 > /dev/null
  

  
  
• chmod /etc/cron.five/freenats-tester.sh 755
• Add the following lines to /etc/crontab:
  

  01 * * * * root run-parts /etc/cron.five
  06 * * * * root run-parts /etc/cron.five
  11 * * * * root run-parts /etc/cron.five
  16 * * * * root run-parts /etc/cron.five
  21 * * * * root run-parts /etc/cron.five
  26 * * * * root run-parts /etc/cron.five
  31 * * * * root run-parts /etc/cron.five
  36 * * * * root run-parts /etc/cron.five
  41 * * * * root run-parts /etc/cron.five
  46 * * * * root run-parts /etc/cron.five
  51 * * * * root run-parts /etc/cron.five
  56 * * * * root run-parts /etc/cron.five
  

  
  
• Create the following script in /etc/cron.daily called something like freenats-cleanup.sh:
  

  #!/bin/bash
  cd /opt/freenats/bin
  ./cleanup.sh 2>&1 > /dev/null
  

  
  

Setup Complete

You should now be able to navigate to http://YOUR.FREENATS.URL/ and login with the username of admin and password of admin (which you should then change via the settings link).