This option controls what the nstidsgeolocate script will do. The following modes are available: ("xml", "kmz", "prunekml", "listprunekml", "rmsessiondir", "rmcrontab" and "bash"). If you specify "xml", this script will generate XML (Extensible Markup Language) formatted text to standard output (display) from the results of interrogating an IDS collector MySQL database for IDS event source host IPv4 Addresses and event signature information. If you specify "kmz", this script will generate a KML (Keyhole Markup Language) formatted document from the results of interrogating an IDS collector MySQL database for IDS event source host IPv4 Addresses and event signature information. The KML document will be compressed using the zip utility producing a KMZ file. KML is an XML-based language schema for expressing geographic annotation and visualization on existing or future Web-based, two-dimensional maps and three-dimensional Earth browsers (Geocoding). KML was developed for use with Google Earth. Use the "kmz" mode when rendering nstidsgeolocate results with Google Earth. Specify "prunekml" to remove older generated KML documents and associated XML status information files found within the "--odir" directory hierarchy. Use either the mandatory "--prune-min" or "--prune-day" option to establish the desired pruning window. Specify "listprunekml" to list generated KML documents and associated XML status information files found within the "--odir" directory hierarchy. Use the "--prune-min" or "--prune-day" option for the desired pruning window. This method is nondestructive and can be used to help determine your pruning time frame. Specify "rmsessiondir" to remove an entire session name directory: "--sname". All "crontab" entries associated with the session name directory: "--sname" will be removed first. Specify "rmcrontab" to remove all "crontab" entries associated with the session name directory: "--sname". Specify "bash" to display internal 'Bash' variables specific to nstidsgeolocate for 'Bash' scripting integration.

This directory will contain a tree of all "nstidsgeolocate" session directories specified by the "--sname" session name directory option. If omitted, it defaults to directory: "/var/nst/nstgeolocate". The directory will be created if it does not already exist.

This script may need to generate intermediate files before the final results are produced. This option enables one to specify a session name directory beneath the "--odir" directory for files produced by this script. The location of the session name directory will be based upon the "--mode" and "--map-type" type selected. If omitted, it defaults to a name representative of the default "--mode" and "--map-type". If the "--mode kmz" and the "--map-type kml" options were selected, then the default "--sname" session name directory will be: "kml/ids/kml_ids". If the base output directory option: "--odir" is set to: "/var/nst/nstgeolocate" and the session name directory "--sname" is set to: "kml_ids_1hr" with options "--mode kmz" and "--map-type kml" used, then the working directory for this 'nstidsgeolocate' session will be located in directory: "/var/nst/nstgeolocate/kml/ids/kml_ids_1hr". The session name directory will be created if it does not already exist.

Use this option to select the data source type for Geolocating IDS event source host IPv4 Addresses. Currently the valid data source type is: "idsdbxml". The default data source type is "idsdbxml".

This option is used to specific the map type: "kml" for the global imagery type. The "kml" value is the default type.

This optional parameter allows one to specify an alternative user name for accessing the IDS collector MySQL database. The default user name is: "snort"

Use this optional parameter to specify a Clear Text Password necessary for accessing the IDS collector MySQL database. If this option is not used, the password associated with the "NSTCTSNORTPASSWD" configuration entry found in the NST configuration file: "/etc/nst.conf" will be used.

Use this optional parameter to specify the IDS collector MySQL database server (IP Address or Host Name). A default value of "127.0.0.1" (localhost) will be used if the server parameter is not specified.

Use this option to specify the TCP/IP port number to use to connect to the IDS collector MySQL database if it is different from the default port value of "3306".

Use this option for overriding the "--server" value when accessing the MySQL database. One can still set the "--server" option for linkage back to the NST WUI from within Google Earth when generating a KML document.

Use this optional value to specify the "Start Time" of the first IDS alert event to retrieve from the IDS collector MySQL database. If this option is omitted, the Unix epoch time (i.e., 1970-01-01 00:00:00) will be used. Use the following formatted date/time string enclosed in double quotes when specifying this option: "YYYY-MM-DD hh:mm:ss" where: YY - Year, MM - Month, DD - Day, hh - Hour, mm - Minute and ss - Second.

Use this optional value to specify the "End Time" of the last IDS alert event to retrieve from the IDS collector MySQL database. If this option is omitted, the current date and time will be used. Use the following formatted date/time string enclosed in double quotes when specifying this option: "YYYY-MM-DD hh:mm:ss" where: YY - Year, MM - Month, DD - Day, hh - Hour, mm - Minute and ss - Second.

Use this option to specify the duration in "minutes" when retieving IDS alert events from the IDS collector MySQL database. The duration is calculated in "minutes" back from the "--end-event-time". If the "--end-event-time" is omitted, the duration is calculated in "minutes" back from the current date and time. This allows for a rolling window in time when generating IDS KML documents. The results of using the "--event-min-dur" parameter will effectively set an internal "--start-event-time". Therefore, if a "--start-event-time" parameter is also specified, it will be ignored and the "--event-min-dur" parameter will be used instead. The minimum value permitted is 1. The maximum value permitted is 1440.

Use this option to specify the duration in "days" when retieving IDS alert events from the IDS collector MySQL database. The duration is calculated in "days" back from the "--end-event-time". If the "--end-event-time" is omitted, the duration is calculated in "days" back from the current date and time. This allows for a rolling window in time when generating IDS KML documents. The results of using the "--event-day-dur" parameter will effectively set an internal "--start-event-time". Therefore, if a "--start-event-time" parameter is also specified, it will be ignored and the "--event-day-dur" parameter will be used instead. The minimum value permitted is 1. The maximum value permitted is 99999.

Use this option to adjust the "--end-event-time" value to fall on a clean date/time mark (e.g., A 'minute', 'hourly' or 'daily' boundary.). This parameter is specified in "minutes". Typically, this parameter is used when the "--end-event-time" parameter is omitted. In this case the "--end-event-time" is set to the current date and time. Example: If one is generating IDS KML documents hourly and wants to make sure that the internally generated "--start-event-time" (i.e., The "--event-min-dur" is set to "60".) falls a clean hourly mark, then set the "end-event-time-dur-boundary" to "60" (e.g., End Event Time: '2011-02-23 16:01:04' with "--end-event-time-dur-boundary 60" and "--event-min-dur 60" then the effective Start Event Time will be '2011-02-23 15:00:00' and the adjusted End Event Time is '2011-02-23 16:00:00'. This example uses an IDS event duration of 1 hour with IDS event retrieval set on the hour mark.). The following are some common values. For a clean 'minute' boundary (Adjust back in time to the previous minute.) set the "--end-event-time-dur-boundary" to "1". For a clean '10 minute' boundary (Adjust back in time to the previous 10 minute mark.) set the "--end-event-time-dur-boundary" to "10". For a clean '1/2 hour' boundary (Adjust back in time to the previous 30 minute mark.) set the "--end-event-time-dur-boundary" to "30". For a clean 'hourly' boundary (Adjust back in time to the previous hour.) set the "--end-event-time-dur-boundary" to "60". For a clean 'daily' boundary (Adjust back in time to the beginning of the day.) set the "--end-event-time-dur-boundary" to "1440". For a clean '10 day' boundary (Adjust back in time to the beginning of the last 10 day mark.) set the "--end-event-time-dur-boundary" to "14400". The minimum value permitted is 1. The maximum value permitted is 99999.

Use this optional parameter to specify an IDS Engine Sensor name filter to be added as a search criterion when retrieving IDS alert events. The "space" and "underscore" characters are interchangeable when specifying the "--sensor-filter" name. Enclose the sensor name filter in double quotes if you choose to uses spaces. If this option is used, it is best to match it with the cooresponding network interface filter: "--netint-filter" option to correctly identify the "IDS Engine Sensor" with its associated "Network Interface". ***Note: If the "--netint-filter" option is used and this option is not, the First Matched IDS Engine Sensor name will be used in the MySQL query selection when retrieving IDS data or information.

Use this optional parameter to specify an IDS Engine Network Interface filter to be added as a search criterion when retrieving IDS alert events. If this option is used, it is best to match it with the cooresponding IDS Sensor name filter: "--sensor-filter" option to correctly identify the "IDS Engine Sensor" with its associated "Network Interface". ***Note: If the "--sensor-filter" option is used and this option is not, the First Matched IDS Network Interface name will be used in the MySQL query selection when retrieving IDS data or information.

Use this option to specify a minimum threshold for the total number of IDS alert events that need to occur for a given event source host in order to be geolocated. The default value is "1". This parameter can be useful to filter out event source hosts that have generated a low number of IDS alert events.

Use this option to add an "Annotation" to the generated KML document. This will used as title text throughout the document and can be beneficial for historical review and analysis. Enclose the annotation with single or double quotes.

Use this option to add a public IP Address reference to the KML document for access back to the NST WUI. Detected "IDS" source hosts can then be used with the included NST WUI IP networking tools and utilities.

This option may be used with the "--mode rmcrontab" mode to specify a targeted UUID for removal of all associated "crontab" entries. The UUID is a DCE (Distributed Computing Environment) compatible Universally Unique IDentifier produced by the uuid command. The nstidsgeolocate script uses a UUID to identify and bound a set of nstidsgeolocate script crontab entries for the automatic generation of global imagery, map rotation and pruning. Typically this option is not necessary because the UUID can be found in a XML session information file within each nstidsgeolocate session name directory. It may be necessary at times to use this option for "crontab" house cleaning if nstidsgeolocate session name directories are removed and leftover "crontab" entries remain.

Use this option to set the crontab 'user' for automatic KML document generation using cron.

Use this option to create a crontab entry for automatic KML document generation using script: 'nstidsgeolocate' each "--cron-kml-min" minutes. A KML document will be generated each time this crontab entry is executed. The minimum value permitted is 1. The maximum value permitted is 59.

Use this option to create a crontab entry for automatic KML document generation using script: 'nstidsgeolocate' each "--cron-kml-hr" hours. A KML document will be generated each time this crontab entry is executed. The minimum value permitted is 1. The maximum value permitted is 23.

Use this option to create a crontab entry for automatic KML document generation using script: 'nstidsgeolocate' each "--cron-kml-other" time period. The following time period values are valid: '@hourly', '@daily or @midnight', '@weekly', '@monthly' or @yearly' or '@annually'. A KML document will be generated each time this crontab entry is executed.

Use this option to create a crontab entry for automatic KML document and status information file pruning using script: 'nstidsgeolocate' each "--cron-prune-min" minutes. The associated 'nstidsgeolocate' session directory will be pruned each time this crontab entry is executed. Either the "--prune-min" or the "--prune-day" option is required to establish how far back in time to remove KML documents and status information files. The minimum value permitted is 1. The maximum value permitted is 59.

Use this option to create a crontab entry for automatic KML document and status information file pruning using script: 'nstidsgeolocate' each "--cron-prune-hr" hours. The associated 'nstidsgeolocate' session directory will be pruned each time this crontab entry is executed. Either the "--prune-min" or the "--prune-day" option is required to establish how far back in time to remove KML documents and status information files. The minimum value permitted is 1. The maximum value permitted is 23.

Use this option to create a crontab entry for automatic KML document and status information file pruning using script: 'nstidsgeolocate' each "--cron-prune-other" time period. The following time period values are valid: '@hourly', '@daily or @midnight', '@weekly', '@monthly' or @yearly' or '@annually'. The associated 'nstidsgeolocate' session directory will be pruned each time this crontab entry is executed. Either the "--prune-min" or the "--prune-day" option is required to establish how far back in time to remove map imagery and status information files.

Use this option to specify in "minutes" the pruning window for previously generated KMZ Documents and associated status information files in the "--odir" directory. Specify how many "--prune-min" minutes back in time to maintain files. There is no default value set. Use the "--prune-day" option if you need to maintain documents for "1" day or more. This option is only used with modes: "prunekml" and "listprunekml". Note: When using mode "listprunekml", no file removal will actually take place. The "--prune-min" option will only specify the document and status information files to be pruned. This method is nondestructive and can be used to determine if your pruning value is desirable. The minimum value permitted is 0. The maximum value permitted is 1440.

Use this option to specify in "days" the pruning window for previously generated KMZ Documents and associated status information files in the "--odir" directory. Specify how many "--prune-day" days back in time to maintain document files. There is no default value set. This option is only used with modes: "prunekml" and "listprunekml". Note: When using mode "listprunekml", no file removal will actually take place. The "--prune-day" option will only specify the document and status information files to be pruned. This method is nondestructive and can be used to determine if your pruning value is desirable. The minimum value permitted is 0. The maximum value permitted is 99999.

Use this parameter to change the adnsresfilter command default options: "--wait --unchecked" (See: "adnsresfilter -h" for all available options.). The adnsresfilter command is used for non-blocking simultaneous DNS query lookups and insertion for each geolocated IDS alert event source host IPv4 Address. DNS name resolving can take a significant amount time to complete as the number of IDS alert event source hosts to resolve increases. One can use the "timeout" option to sacrifice complete DNS name resolving versus speed. The "timeout" option is specified in 'milliseconds' (Example: "--timeout 500 --unchecked"). Enclose options to this parameter in either single or double quotes.

When this option is specified, nstidsgeolocate will display a short one line description of nstidsgeolocate, followed by a short description of each of the supported command line options. After displaying this information nstidsgeolocate will terminate.

This option will attempt to pull up additional nstidsgeolocate documentation within a text based web browser. You can force which browser we use setting the environment variable TEXTBROWSER, otherwise, we will search for some common ones.

When you set this option to true, nstidsgeolocate will produce additional output. This is typically used for diagnostic purposes to help track down when things go wrong.

If this option is specified, the version number of the script is displayed.

File containing the IDS collector MySQL database clear text password that may be used as a default value by this script (See value for configuration entry: 'NSTCTSNORTPASSWD').

Directory containing resource files used by nstidsgeolocate.

This controls what text based browser is used to display help information about the script. If not set, we will search your system for available text-based browsers (Ex: elinks, lynx ...).