Bulk Import

FreeNATS can accept bulk imports of a standard XML format such as that output by the discovery tool or created by the exporter/script of your choice.

Using the Tool

Change to the server/bin directory (cd /opt/freenats/server/bin for virtual appliance users). The usage information from the tool is as follows:

FreeNATS Bulk Importer - www.purplepixie.org/freenats

Usage: php import.php filename.xml [--live] [--debug]

So you simply specify the filename to import an optional debug flag (displays the SQL output that results from the data) and an optional live flag (actually does the import).

It's a good idea to run without --live first to see any errors before trying to commit them to the environment.

So for example if we had run our discovery tool and created discover.xml in the same directory then:

php import.php discover.xml --debug

Would parse the data and show what would result including SQL statements but without actually importing.

php import.php discover.xml --debug --live

would parse the data, show the SQL and actually import it

Import Failures

The nodeid must be unique and obviously all the fields valid for the import to work. Tests are only imported if:

• The node has been imported (successfully) in the same import operation
• The node hasn't been imported in the same import operation (relies on the node already existing)

Note that unlike nodes tests can be duplicated so if you run the same import data containing new tests for existing nodes (the nodes don't exist in the import data) then the tests will be duplicated.

If the node is also in the data then it will be fine as the node will fail to import again and so the test will also be skipped (see above).

Import XML Format

The format is designed so you can easily edit/extend discover output or easily create your own data import from another source.

The format of the file is:

XML Header
<freenats-data>
... data blocks
</freenats-data>

Data blocks are either defaults or specific and set the fields/values to be inserted into the relevant table (fnnode or fnlocaltest).

Example Import XML File

<?xml version="1.0" encoding="UTF-8"?> <freenats-data>

<default TYPE="node">

<nodeenabled>1</nodeenabled>
<pingtest>0</pingtest>

</default>

<default TYPE="localtest">

<testenabled>1</testenabled>
<testrecord>0</testrecord>

</default>

<node NODEID="shark">

<nodeid>shark</nodeid>
<hostname>10.0.10.4</hostname>
<nodedesc>shark.lcoe.zz</nodedesc>

</node>

<localtest>

<nodeid>shark</nodeid>
<testtype>webtime</testtype>
<testparam>http://10.0.10.4/</testparam>

</localtest>

</freenats-data>

In this example you can see the default sections (for nodes and localtests) then a node and localtest being defined. Values defined in the individual node/test override defaults. If no value is provided for a field (either through the defaults or in the node/test data) then it will simply not be mentioned in the SQL statement and take it's default from the database schema.

You can of course set any field in the fnnode or fnlocaltest tables so for example:

<node NODEID="shark">

<nodeid>shark</nodeid>
<hostname>10.0.10.4</hostname>
<nodedesc>shark.lcoe.zz</nodedesc>
<nodename>The Shark Server</nodename>
<testinterval>1</testinterval>
<nsenabled>1</nsenabled>
<nspushenabled>1</nspushenabled>
<nskey>WibbleSticks</nskey>

</node> Would create the same node but with a node name, an interval of 1 minute (schema would default to 5 as it was unspecified in the previous example) and enable nodeside testing for push with a key of WibbleSticks.

<localtest>

<nodeid>shark</nodeid>
<testtype>dns</testtype>
<testparam>my.dns.server</testparam>
<testparam1>shark.lcoe.zz</testparam1>
<testparam2>A</testparam2>
<timeout>10</timeout>
<testname>DNS Lookup</testname>

</localtest> Would create a DNS test looking up shark.lcoe.zz's A record on my.dns.server with a public test name of DNS Lookup

Multiple Default Blocks

Default settings apply from where they are in the file downward. They are overridden either by a setting in a specific node/test or by another default block.

For example consider the following XML <?xml version="1.0" encoding="UTF-8"?> <freenats-data>

<default TYPE="node">

<nodeenabled>1</nodeenabled>

</default>

<node NODEID="grumpy">

<nodeid>grumpy</nodeid>

</node>

<node NODEID="sleepy">

<nodeid>sleepy</nodeid>
<nodeenabled>0</nodeenabled>

</node>

<default TYPE="node">

<nodeenabled>0</nodeenabled>

</default>

<node NODEID="dopey">

<nodeid>dopey</nodeid>

</node>

</freenats-data>

In this example:

• grumpy is enabled - the default would apply
• sleepy is disabled - the individual setting overrides the default
• dopey is disabled - the default has been changed after the second default block