System Administration

From FreeNATS Wiki
Jump to: navigation, search

System Administration functions are accessed through Configuration -> System Settings in version 1

Using the administration page users with the appropriate privilege are able to control and configure the FreeNATS system and environment as well as check for updates.


Users can be created, modified and destroyed within the admin interface. For more detail see the Users page.

Test Suspension

Tests can be suspended throughout FreeNATS by clicking the option to suspend testing. This will stop all new test threads from running (currently/still running ones are unaffected). No nodes are affected (their statuses do not change and they remain enabled).

This feature is for use when a temporary suspension is needed for example a network upgrade or firewall reboot or similar where ideally a lot of alerts would not be found (an option for a regular issue is to use master nodes). Feature introduced in 1.17.5.

Test Sessions

Through this interface you can view the raw test run output (clicking run/XXX on the left) or the relevant system log entries for the test run (system logs on the right).

Alert Actions

Alert actions (described in the alerts and alert actions section of the documentation) can be created and modified here.

System Logs

The system logs contain relevant system information to the appropriate log level (configured as a variable - see below). Through the log interface the system log can be filtered for event level (0 is fatal, 10 is debug info only), module or event type.

Admin SQL Console

If the site.enable.adminsql variable is set (1) then admin users can access the admin SQL console. This will execute SQL directly on the database using the configured FreeNATS SQL user/pass/db settings.

This can be used for debugging and manual node alternations etc...

Warning: this is advanced functionality and misuse could well cause a major system fault.

Admin DNS Console

The admin DNS console can be used to perform DNS queries to test connectivity/debug things from within the FreeNATS software.

File Manager

The file manager can be used to edit/upload/download files from various site directories used in developing event handlers and test modules for FreeNATS.

Uploading untested code is not recommended as if it fails to parse you won't even be able to use the file manager until you have stopped site includes (detailed in troubleshooting).

The file manager is locked to certain directories. To upload files these must be writeable by the web process (usually apache or httpd). You will probably need to chmod 777 the directories in question.

System Status

The system status display allows admin users to view some important FreeNATS information on the status of the underlying database and some other items. You can also optimise tables with shown freespace through this interface.


Variables control the system. To delete a variable simply save it with a blank variable name.

General Variables


the system event logger level (10 is log everything, 1 almost nothing), around 5 is a good idea (default 5)

retain.alert, retain.record, retain.testrun, retain.syslog

number of days to retain old alerts (default 356), test records (default 356), test run (default 30) and system log (default 30) data respectively


if 1 will participate in the tracker program by "pinging" a script on the freenats project homepage when pages are viewed.

Site-Specific Settings


site admin and contact details to be displayed in error pages (not yet implemented)


Date-time formatting string for use in displays where: H hours, i minutes, s seconds, d day of month, m number of month, Y full year, y small year. For example "H:i:s d/m/Y" is the site default, "H:i:s m/d/Y" would be the American format.


(As of 1.16.0) Defines the default system timezone for FreeNATS. Valid timezones are in PHP format:

site.text.passed, site.text.failed, site.text.warning, site.text.untested, site.text.closed

If set override the normal status texts on system pages (including views), designed for multi-lingual support. The site.text.closed is what is sent when a node alert is closed (and decreases are set for the alert action).

site.enable, site.enable.interactive, site.enable.tester, site.enable.web

Anything enabled, web interface enabled for non-admin users, tested enabled and able to run and web interface enabled for everyone respectively. REQUIRED

Do not trust site.enable.tester; use site.tester.suspended instead.


(As of 1.17.5) - if present and set to 1 all tests will be skipped (no change to the nodes will be made at all i.e. they won't be marked as untested just in their last state).

name to display for the site of the FreeNATS install (not yet implemented)


If set to 1 will enable the administration SQL console (see above) (default 0)

site.graph.public, site.graph.key

If site.graph.public is set to 1 then test graphs will be available to unauthenticated browsers (for views etc). Unauthenticated browsers must provide a key (if site.graph.key) is set in the URI variable graphkey.


If site.graph.transparent is set to 1 then test graphs will by default be transparent (unless overriden with a transparent=0 in the URI, see Graphs)


For some edit dialogues show update/created/deleted messages in a popup as well as at the top of the page if 1 (default off)

Include all .php files in the base/site/events directory if 1 (defaults to no if 0 or unset). Used for event handler development


Include all .php files in the base/site/tests directory if 1 (defaults to no if 0 or unset). Used for test development


Skip the update check on login if set to 1 - otherwise will always do a JS check on login


If set to 0 then the live monitor doesn't refresh (or check the time of) the current session. Once the session has "expired" though the live monitor will continue to work any other operations will require you to authenticate again.

site.alert.showvalue, site.alert.showtext

If set to 1 will show the result of the test in brackets in alert messages. site.alert.showvalue will include numeric results and site.alert.showtext will include textual alerts. Please note these may be clipped by size limitations of the alert type chosen.


If present and set to 1 will disable the firstrun warning - not recommended


Controls the authentication method used by users to the web interface. Method will always be builtin form (normal login form is dispayed) unless site.auth is set to http in which case HTTP authentication will be used.

API Settings

api.public, api.key

If api.public is set to 1 then the API will be available to unauthenticated browsers. Unauthenticated browsers must provide a key (if api.key) is set in the URI variable apikey.

Test Settings


time in seconds to wait for an ICMP (ping) response before declaring the test timed out (can be overridden by test-specific setting) (default 10)


Number of times to attempt the NODE ping test (will always try once and only retry if it fails) - to accomodate occasional random ICMP loss (default 2)


If set (1) will return MilliSeconds (1000ths of a second) for ping and ICMP tests (and will show this as the unit in appropriate displays) (default 0)


Default site wide http timeout setting (can be overridden on a per-test basis). Uses PHP site default if unset. Relies on being able to ini_set the PHP stream timeout. (default PHP site setting)


Default site wide SMTP timeout setting for use in SMTP tests (can be overridden on a per-test basis). Defaults to 20 seconds if unset or 0.


Default site wide IMAP timeout setting (can be overridden on a per-test basis). Defaults to PHP site setting if 0 or unset.


Default site wide MySQL timeout setting (can be overridden on a per-test basis). Uses PHP site default if unset or 0.


Default site wide TCP Connect timeout (can be overriden on a per-test basis). Uses 60s default if unset ot 0.


Default site wide UDP Connect timeout (can be overriden on a per-test basis). Uses 60s default if unset ot 0.


Delay in seconds between test-threaded spawning each individual node tester session to the background (can be floating point) no delay if unset or 0


Delay in seconds between tester doing each test in series on a node (can be floating point) no delay if unset or 0


Time in seconds after which a previous test session is seen as stale and closed by the tester script (avoiding "Tester Already Running" errors after a crash without having to manually clean them up). Defaults to 1 hour (3600 seconds) if unset, blank, non-numeric or negative. A value of 0 (zero) means test sessions are never expired automatically.

Mail Settings


Please see the mail settings section for information on these variables

Email Alert Settings

alert.subject.long, alert.subject.short

Subjects to be used in email alert action if long or short are selected (not blank). Default to "FreeNATS Alert" and "FreeNATS Alert" respectively if unset.


Text to include above everything else in a long format email alert. Defaults to "FreeNATS Alert," if unset. Will be followed by several newlines and then the alert body.

Short format emails have no header.


Text to include below the alert section in a long format email. Defaults to nothing if unset.

Short format emails have no footer.