(View as Code
Updated: 10:48:37 04/06/2009
FreeNATS - Installation Documentation
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 www.purplepixie.org/freenats.
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.
9: FreeNATS creates various tables in the database all prefixed with "fn".
11: Install PHP Source Code
13: Extract freenats-V.vv.sr.tar.gz
14: "web" is the web interface directory and needs to be "published". 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.
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!).
17: You can do this automatically by running the "shell-install.sh" script in the root folder (copying and moving that is - not the DB setup etc).
19: Edit the base/config.inc.php file and put in your MySQL connection settings.
24: You can upgrade your system (files only - not schema) by using the "shell-install.sh" script. This will copy all files bar specific system config (the includes and config.inc files).
26: Feel free to try the experimental upgrade process to update the schema either by manually importing the
27: "schema.sql" and "schema.upgrade.sql" (one will create any missing tables and the other will
28: update any pre-existing tables) or by using the firstrun script (you will need to rename it from firstrun-.php and
29: then browse to it).
30: Expect lots of errors with the update as it will try to recreate tables/fields/keys already in existance - don't
31: worry too much about it. You should be able to see any "serious" errors.
33: Upgrading Virtual Appliance
35: Virtual Appliance users should use the "vm-upgrade.sh" script which will run the upgrade script with the correct default locations.
36: Please note this will only upgrade FreeNATS - you should check for rPath upgrades through it's admin console.
38: Automatic Installation
40: Rename the web/firstrun-.php file to web/firstrun.php
42: Navigate to http://your.freenats.url/firstrun.php
44: Follow the instructions
46: Manual Installation
48: In the base/sql dir there are various .sql files - schema, schema.drop, schema.upgrade, default and example
50: 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.
52: The example.sql file contains optional example node and group data and is recommended.
54: The schema.drop contains if table exists drop queries before trying to create the table so will clean out any
55: existing junk if required.
56: The schema.upgrade contains upgrade instructions (see above) and not used for a fresh install. If you want to
57: upgrade you will need to run mysql (with --force) on schema.sql, upgrade.sql and default.sql in that order.
58: The Tester Script
60: The tester script must be run (via cron or whatever) at regular intervals to poll the nodes. The recommended setting is five minutes.
61: It requires the working directory to be the bin dir on startup.
63: 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
64: 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
65: 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.
67: 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.
68: 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.
70: 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
71: require any special privs unlike the tester. See the documentation for more information.
74: See www.purplepixie.org/freenats