1: <p align="right"><i>Updated: 19:32:00 02/03/2008</i></p>
  2: 
  3: <h1>FreeNATS - Installation Documentation</h1>
  4: 
  5: This brief installation document is the only documentation that comes with FreeNATS. For full up-to-date documentation and licence information visit the FreeNATS website at <a href=http://www.purplepixie.org/freenats/>www.purplepixie.org/freenats</a>.
  6: <br><br>
  7: There are two methods of installation available; automatic where a script does all the work creating the relevant database tables or you can import the SQL manually.
  8: <br><br>
  9: FreeNATS creates various tables in the database all prefixed with &quot;fn&quot;.
 10: <br><br>
 11: <b>Install PHP Source Code</b>
 12: <br><br>
 13: Extract freenats-V.vv.sr.tar.gz<br><br>
 14: &quot;web&quot; is the web interface directory and needs to be &quot;published&quot. Ideally the other dirs (base and bin) should be not published at all by apache but (a) it should be safe to call any of those scripts anyway and (b) there are .htaccess files in the dirs.<br><br>
 15: If you have moved web somewhere (so the base dir is not ../base from the web dir) will need to edit the include.php file in the web dir and give it the base location (WITH TRAILING SLASH!).
 16: <br><br>
 17: Edit the base/config.inc.php file and put in your MySQL connection settings.
 18: <br><br>
 19: 
 20: <b>Automatic Installation</b>
 21: <br><br>
 22: Rename the web/firstrun-.php file to web/firstrun.php
 23: <br><br>
 24: Navigate to http://your.freenats.url/firstrun.php
 25: <br><br>
 26: Follow the instructions
 27: <br><br>
 28: <b>Manual Installation</b>
 29: <br><br>
 30:  31: <br><br>
 32: You will need to run/import schema (the database table structure) and default (the admin user and some necessary default settings) for the system to work.
 33: <br><br>
 34: The example.sql file contains optional example node and group data and is recommended.
 35: <br><br>
 36: <b>The Tester Script</b>
 37: <br><br>
 38: The tester script must be run (via cron or whatever) at regular intervals to poll the nodes. The recommended setting is five minutes.<br><br>
 39: It requires the working directory to be the bin dir on startup.
 40: <br><br>
 41: There are two choices - either run bin/tester.sh which will test all enabled nodes waiting for each node/test in sequence and then raising the relevant
 42: alerts and emails etc. The other option is to run bin/test-threaded.sh which will fork a background process for each node to test. This is better but will
 43: send an alert email for each node that fails (rather than one with all the failures from that test run at the end). See the documentation for more information.
 44: <br><br>
 45: On many PHP/Linux security setups many of the low level tests (such as ping for example) can require root or some other special privs. You can always run the tester script manually from the console in different environments to test the output.<br><br>
 46: Please note that a script crash for lack of privs may not be caught gracefully and may result in stuck monitor scripts and/or just an open monitor record in the database stopping other monitors from running.
 47: <br><br>
 48: In addition to the tester script you should run bin/cleanup.sh daily or so to clean out old sessions and data (inline with your retention settings). This doesn't
 49: require any special privs unlike the tester. See the documentation for more information.
 50: <b>Troubleshooting</b>
 51: <br><br>
 52: See <a href=http://www.purplepixie.org/freenats/>www.purplepixie.org/freenats</a>
 53: <br><br>
 54: 
 55: