Updated: 16:05:18 29/04/2025

FreeNATS - Installation Documentation

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.

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.

FreeNATS creates various tables in the database all prefixed with "fn".

Install PHP Source Code

Extract freenats-V.vv.sr.tar.gz

"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.

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!).

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).

Edit the base/config.inc.php file and put in your MySQL connection settings.

Upgrading

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).

Feel free to try the experimental upgrade process to update the schema either by manually importing the "schema.sql" and "schema.upgrade.sql" (one will create any missing tables and the other will update any pre-existing tables) or by using the firstrun script (you will need to rename it from firstrun-.php and then browse to it).

Expect lots of errors with the update as it will try to recreate tables/fields/keys already in existance - don't worry too much about it. You should be able to see any "serious" errors.

Upgrading Virtual Appliance

Virtual Appliance users should use the "vm-upgrade.sh" script which will run the upgrade script with the correct default locations.

Please note this will only upgrade FreeNATS - you should check for rPath upgrades through it's admin console.

Automatic Installation

Rename the web/firstrun-.php file to web/firstrun.php

Navigate to http://your.freenats.url/firstrun.php

Follow the instructions

Manual Installation

In the base/sql dir there are various .sql files - schema, schema.drop, schema.upgrade, default and example

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.

The example.sql file contains optional example node and group data and is recommended.

The schema.drop contains if table exists drop queries before trying to create the table so will clean out any existing junk if required.

The schema.upgrade contains upgrade instructions (see above) and not used for a fresh install. If you want to upgrade you will need to run mysql (with --force) on schema.sql, upgrade.sql and default.sql in that order.

The Tester Script

The tester script must be run (via cron or whatever) at regular intervals to poll the nodes. The recommended setting is five minutes.

It requires the working directory to be the bin dir on startup.

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 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 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.

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.

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.

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 require any special privs unlike the tester. See the documentation for more information. Troubleshooting

See www.purplepixie.org/freenats