View source for HowTo Automate & Manage NST Geolocation Results

__TOC__
== '''Overview - nstgeolocate Session Manager''' ==
The '''nstgeolocate Session Manager''' page was designed to help manage and automate the generation of certain geolocation types. The NST script: '''[http://nst.sourceforge.net/nst/docs/scripts/nstgeolocate.html nstgeolocate]''' is mostly used for results presented on the page. Currently, auto-generated "'''ntop Host'''" geolocation sessions can be created, monitored and managed. Also, all previously generated "'''IPv4 Address Conversation'''" geolocation sessions can be viewed or managed. Using the NST menu, one can navigate to the '''nstgeolocate Session Manager''' page as shown in the screen shot below.

[[Image:Nstgeolocate_menu.png|center|frame|NST WUI nstgeolocate Session Manager Menu Selection]]

== '''Collapse / Expand Session Sections''' ==
The amount of information presented on the '''nstgeolocate Session Manager''' page can be large depending on the number of '''[http://www.ntop.org ntop] Host''' sessions configured and/or the number of '''IPv4 Address Conversations''' archived. The  "'''Collapse All Sessions'''" button and the "'''Expand All Sessions'''" button can be used in combination with the "'''Hide / Show'''" session section folder icons to display just the information relevant to you. This will not only reduce the amount of information you need to visually process, but will also speed up the rendering of the page.

== '''Manage & Monitor ntop Host Sessions''' ==
If your NST system if running [http://www.ntop.org ntop], it can be set up to periodically produce geographic representations of the information collected by [http://www.ntop.org ntop]. This is known as setting up a ''ntop host session''.

There are 2 sections that display configured '''[http://www.ntop.org ntop] Host''' sessions. One for auto-generating '''[http://www.ntop.org ntop] Host Geolocations''' on one or more '''Mercator World Map''' projections and the other for auto-generating one or more '''[http://www.ntop.org ntop] Host Geolocations''' '''[http://en.wikipedia.org/wiki/Keyhole_Markup_Language KML]''' documents that can be ''rendered'' on '''[http://earth.google.com Google Earth]'''. '''[http://www.ntop.org ntop] Host''' sessions are created and configured in the section: '''[[HowTo_Automate_%26_Manage_NST_Geolocation_Results#Create_.2F_Update_.2F_Import_ntop_Host_Sessions | Create / Update / Import nstgeolocate Host Session]]'''. A running '''[http://www.ntop.org ntop]''' server can be <u>local</u> (i.e., Running on your NST probe) or <u>remote</u> (i.e., Running on a system other than your local NST probe).

=== '''ntop Host Session - Table Column Descriptions''' ===
Each configured '''[http://www.ntop.org ntop] Host''' session type is presented in a table layout format. The following describes each column header associated with the tables.
* '''World Map nstgeolocate Host Session Directory''':
:Click on a link in this column to use the '''NST Directory/File Browser''' to view supporting files associated with the generation of producing the '''[http://www.ntop.org ntop] World Map Host''' bit image. Depending on how long you have set the "'''Map Pruning Interval'''" value for each session, you can also view historical generated maps in the associated directory.  

* '''KML Document nstgeolocate Host Session Directory''':
:Click on a link in this column to use the '''NST Directory/File Browser''' to view supporting files associated with the generation of producing the '''[http://www.ntop.org ntop] [http://en.wikipedia.org/wiki/Keyhole_Markup_Language KML]''' Document. Depending on how long you have set the "'''Map Pruning Interval'''" value for each session, you can also view historical generated '''[http://en.wikipedia.org/wiki/Keyhole_Markup_Language KML]''' Documents in the associated directory.

* '''C (''Cron Control Status'')''':
:This column indicates if the configured '''[http://www.ntop.org ntop] Host''' session is under '''[http://en.wikipedia.org/wiki/Cron cron]'''  control. A '''<span style="color: green;">green</span>''' circle icon indicates that it is and a '''<span style="color: red;">red</span>''' stop sign icon indicates that it is not. Use an associated "'''D'''" action button to ''disable'' '''[http://en.wikipedia.org/wiki/Cron cron]''' control for the session.

* '''Active 'ntop' Session ''':
:This column is used for linkage back to either the configured '''NST WUI''' probe '''[http://www.ntop.org ntop]''' management interface or the '''[http://www.ntop.org ntop]''' session user interface.
:* '''ntop Mgt (''HTTP'')''':
::Use this button to enter the '''NST WUI [http://www.ntop.org ntop]''' web-based management interface ('''HTTP''' access) for the '''[http://www.ntop.org ntop]''' session.
:* '''ntop Mgt (''HTTPS'')''':
::Use this button to enter the '''NST WUI [http://www.ntop.org ntop]''' web-based management interface ('''HTTPS''' access) for the '''[http://www.ntop.org ntop]''' session.
:* '''HTTP Access''':
::Use this link to enter the '''[http://www.ntop.org ntop] User''' web-based management interface ('''HTTP''' access) for the '''[http://www.ntop.org ntop]''' session (Default port: '''3000''').
:* '''HTTPS Access''':
::Use this link to enter the '''[http://www.ntop.org ntop] User''' web-based management interface ('''HTTPS''' access) for the '''[http://www.ntop.org ntop]''' session (Default port: '''3001''').

* '''Description''':
::The description for each '''[http://www.ntop.org ntop]''' session includes the "'''Session Annotation'''", participating "'''Network Capture Interfaces'''" and the current "'''[http://www.ntop.org ntop] Session Uptime'''".

* '''Action (''Buttons'')''':
:* '''U (''Update ntop Session Settings'')''':
::This action button will pre-fill all values associated with the '''[http://www.ntop.org ntop]''' session into the '''[[HowTo_Automate_%26_Manage_NST_Geolocation_Results#Create_.2F_Update_.2F_Import_ntop_Host_Sessions | "Create / Update / Import nstgeolocate Host Session"]]''' configuration form. Use this action when making changes to an existing '''[http://www.ntop.org ntop]''' session.
:* '''R (''Remove ntop Host Session'')''':
::This action button will remove an entire '''[http://www.ntop.org ntop]''' session including supporting files and all previously generated maps or '''[http://en.wikipedia.org/wiki/Keyhole_Markup_Language KML]''' documents. Make backups accordingly prior to using this action.

<div class="centerBlock"><div class="noteMessage">'''Note:''' Use either the "'''Remove All nstgeolocate Host World Map Sessions'''" button or the "'''Remove All nstgeolocate Host KML Doc Sessions'''" button to completely remove <u>All</u> host sessions for the associated geolocation rendered type. Remember to make any backups prior to performing the removal of all sessions.</div></div>

:* '''D (''Disable Cron Control'')''':
::This action button is used to ''disable'' '''[http://en.wikipedia.org/wiki/Cron cron]'''  control for the session. The '''[http://www.ntop.org ntop]''' session will still exist but auto-generation of maps or '''[http://en.wikipedia.org/wiki/Keyhole_Markup_Language KML]''' documents will not occur. To re-enable '''[http://en.wikipedia.org/wiki/Cron cron]'''  control, use a combination of the "'''U'''" action button and the "'''Create / Update nstgeolocate Session'''" button located in the '''[[HowTo_Automate_%26_Manage_NST_Geolocation_Results#Create_.2F_Update_.2F_Import_ntop_Host_Sessions | "Create / Update / Import nstgeolocate Host Session"]]''' section.
:* '''M (''Monitor Auto-Generated Maps or KML Documents'')''':
::This action is used to monitor each auto-generated '''[http://www.ntop.org ntop]''' Hosts session. See section: '''[[HowTo_Automate_%26_Manage_NST_Geolocation_Results#Monitor_ntop_Hosts_Mercator_World_Map | "Monitor ntop Hosts Mercator World Map"]]''' or section: '''[[HowTo_Automate_%26_Manage_NST_Geolocation_Results#Monitor_ntop_Hosts_KML_Document_.28Google_Earth.29 | "Monitor ntop Hosts KML Document (Google Earth)"]]''' for further details associated with each geolocation rendered type.


[[Image:Nstgeolocate_ntop_host.png|center|frame|nstgeolocate Session Manager: Configured ntop Host Sessions]]

=== '''Monitor ntop Mercator World Map Hosts''' ===
The "'''ntop World Map Hosts'''" page allows one to monitor geolocated hosts from an '''[http://www.ntop.org ntop]''' session in ''pseudo-realtime'' within your web browser using '''[http://en.wikipedia.org/wiki/Ajax_%28programming%29 AJAX]''' and image caching disabled. By enabling a '''[[HowTo_Geolocate_ntop_Data#World_Map:_Image_Control_Button_Grid | full screen map view]]''' (Kiosk mode) , you could display the "'''ntop World Map Hosts'''" presentation in a '''[http://en.wikipedia.org/wiki/Network_operations_center NOC]''' setting providing continual geolocated host updates.

The photo below demonstrates the '''Full Screen Map View''' of an "'''ntop World Map Host'''" session displayed on a 27" iMac using the '''[http://www.google.com/chrome/ Google Chrome]''' web browser.

[[Image:Ntop wm imac.png|center|frame|ntop World Map Host: Displayed on a 27" iMac using Google Chrome in a Full Screen Map View]]

<div class="centerBlock"><div class="noteMessage">'''Note:''' An NST menu shortcut can be used to view the default "'''ntop World Map Hosts'''" page by using: "'''Network'''" '''=>''' "'''Monitors'''" '''=>''' "'''ntop World Map Hosts'''".</div></div>

Every 10 seconds a request is made from your web browser back to the NST probe to check for any ''new'' map updates and status information changes. The "'''Map Update Interval'''" for generating a ''new'' "'''ntop World Map Hosts'''" image can be configured in section: '''[[HowTo_Automate_%26_Manage_NST_Geolocation_Results#Create_.2F_Update_.2F_Import_ntop_Host_Sessions | Create / Update / Import nstgeolocate Host Session]]'''.

{|cellpadding="5"
|[[Image:Nstgeolocate_ntop_wm_hosts.png|thumb|300px|center|ntop Hosts World Map]]
|[[Image:Nstgeolocate_ntop_wm_hosts_info_tooltip.png|thumb|300px|center|ntop Hosts World Map - with Information Tool Tip]]
|[[Image:Nstgeolocate_ntop_wm_hosts_ntop_tooltip.png|thumb|300px|center|ntop Hosts World Map - with ntop Tool Tip]]
|}

One can hover the mouse pointer over the "'''Information'''" icon to reveal a tool tip providing the '''Map Description''', '''ntop World Map Hosts Geolocation Update Information''' and '''Image Control Button Grid Usage'''. There are two status "'''Circle'''" icons depicting the state of the '''[http://www.ntop.org ntop]''' session and the combination of ''running'' the NST script: '''[http://nst.sourceforge.net/nst/docs/scripts/nstgeolocate.html nstgeolocate]''' under '''[http://en.wikipedia.org/wiki/Cron cron]''' control. '''<span style="color: green;">Normally</span>''' the status "'''Circle'''" icons will appear in the color '''<span style="color: green;">green</span>'''. A "'''<span style="color: orange;">Warning</span>'''" or "'''<span style="color: red;">Stopped</span>'''" condition may occur and will appear in the color '''<span style="color: orange;">orange</span>''' or '''<span style="color: red;">red</span>'''. Hover the mouse pointer over each status "'''Circle'''" icon to show the current state information and the associated color status definition. The '''[http://www.ntop.org ntop]''' "'''Circle'''" icon tool tip will also show "'''ntop System'''" and "'''ntop Session''' information similar to what is displayed in the "'''ntop Hosts World Map - with ntop Tool Tip'''" screen shot above.

=== '''Monitor ntop Hosts KML Document (Google Earth)''' ===
Auto-generated '''[http://www.ntop.org ntop]''' Hosts '''[http://en.wikipedia.org/wiki/Keyhole_Markup_Language KML]''' documents can be ''monitored'' and ''analyzed'' on a '''[http://en.wikipedia.org/wiki/Keyhole_Markup_Language KML]''' '''Earth Browser''' such as '''[http://earth.google.com Google Earth]''' (See: '''[[HowTo_Setup_Your_Client_System_To_View_Geolocation_Data | HowTo Setup Your Client System To View Geolocation Data]]'''). These documents will be updated each "'''Map Update Interval'''" which can be configured in section: '''[[HowTo_Automate_%26_Manage_NST_Geolocation_Results#Create_.2F_Update_.2F_Import_ntop_Host_Sessions | Create / Update / Import nstgeolocate Host Session]]'''.

<div class="centerBlock"><div class="noteMessage">'''Note:''' Generating an '''[http://www.ntop.org ntop]''' Hosts '''[http://en.wikipedia.org/wiki/Keyhole_Markup_Language KML]''' document can use significant '''CPU''' resources and time depending on the number of hosts to geolocate from an '''[http://www.ntop.org ntop]''' session. Be cautious of this fact especially on a slower '''CPU''' configured NST probe. One may need to choose a less frequent "'''Map Update Interval'''" or limit the number of hosts to geolocate to mitigate system resources necessary in the production these types of '''[http://en.wikipedia.org/wiki/Keyhole_Markup_Language KML]''' documents.</div></div>

Each host that was geolocated appears as a host marker and contains a ''''Host Description'''' balloon depicting selective '''[http://www.ntop.org ntop]''' network traffic statistics information. Click on a host marker to reveal the ''''Host Description'''' balloon. Hyperlinks are also provided to the '''[http://www.ntop.org ntop]''' (Host Collector) user interface and to the NST WUI ''''IP Tools'''' page for additional network processing using the host's IP Address.

{|cellpadding="5"
|[[Image:Nstgeolocate_ntop_kml_hosts.png|thumb|300px|center|ntop Hosts KML Document]]
|[[Image:Nstgeolocate_ntop_kml_hosts_description.png|thumb|300px|center|ntop Hosts KML Document - with Description Balloon]]
|[[Image:Nstgeolocate_ntop_kml_hosts_host_info.png|thumb|300px|center|ntop Hosts KML Document - with Host Balloon]]
|}

When using '''[http://earth.google.com Google Earth]''', one can also view the ''''Document Description'''' balloon by clicking on the generated '''[http://en.wikipedia.org/wiki/Keyhole_Markup_Language KML]''' '''ntop Hosts''' place found under '''Temporary Places''' within the sidebar on the left-hand side. You can also expand the '''ntop Hosts''' place to ''explore'' all geolocated hosts and associated network statistics.

== '''Manage & View IPv4 Address Conversation Sessions''' ==
Each time '''IPv4 Address Conversations''' are geolocated using the ''decode'' section from either the '''Single''' or the '''[[Multi-Tap_Network_Packet_Capturing | Multi-Tap Network Packet Capture]]''' page, they will be cataloged here in this section. Existing '''IPv4 Address Conversations''' are listed in two different sections based on the  rendered output (i.e., '''Mercator World Map''' or '''[http://en.wikipedia.org/wiki/Keyhole_Markup_Language KML] Document'''). Each section is '''Web Browser''' session aware. The sections are grouped by which browser generated the '''IPv4 Address Conversation''' geolocations (i.e., Your browser and all other browsers), ''sorted'' by '''date/time''' in descending order (i.e., More recent geolocations are listed first) and displayed in a table layout format.

The geolocate file naming convention used includes the geolocation render type (i.e., "'''wm'''" - Mercator World Map or "'''kml'''" - '''[http://en.wikipedia.org/wiki/Keyhole_Markup_Language KML] Document'''), network entity to geolocate (i.e, "'''conv'''" - '''IPv4 Address Conversation''') and the time the output was generated (i.e., "'''YYMMDD-hhmmss'''" - '''YY''' - Year, '''MM''' - Month, '''DD''' - Day, '''hh''' - Hour, '''mm''' - Minute and '''ss''' - Second).

=== '''IPv4 Address Conversation - Table Column Descriptions''' ===
The archived '''IPv4 Address Conversation''' sessions are presented in a table layout format. Each table is grouped by which browser generated the '''IPv4 Address Conversation''' geolocations. The "'''Conversation Directory'''" for this and/or other browsers can be viewed with the '''NST Directory/File Browser''' (i.e., Click on the browser '''Session ID''' link that starts with "'''<span style="color: blue;">sid_</span>'''") . The following describes each column header associated with the tables.
* '''World Map IPv4 Address Conversation''':
:Each link in this column represents an archived '''Mercator World Map IPv4 Address Conversation''' geolocation bit image using the file naming convention described above. Click on an image link to allow your browser to render it.

* '''Conversation XML''':
:Each link in this column represents a supporting '''[http://en.wikipedia.org/wiki/XML XML]''' file to an associated archived '''Mercator World Map IPv4 Address Conversation''' session. Click on the link to allow your browser to present the '''[http://en.wikipedia.org/wiki/XML XML]''' data in its native format.

* '''Capture / Description''':
:This column includes the "'''Capture File Name'''" and the "'''Session Annotation'''" text.

* '''Action (''Buttons'')''':
:* '''Conversation Session Directory Browser Headers'''
::* '''R (''Remove Conversation Session Directory'')''':
:::This action button will remove an entire '''IPv4 Address Conversation''' session directory including supporting files and all previously generated maps or '''[http://en.wikipedia.org/wiki/Keyhole_Markup_Language KML]''' documents for an associated browser. Make backups accordingly prior to using this action.

<div class="centerBlock"><div class="noteMessage">'''Note:''' Use either the "'''Remove All Mercator World Map Conversation Sessions'''" button or the "'''Remove All KML Document Conversation Sessions'''" button to completely remove <u>All</u> generated '''IPv4 Address Conversation''' sessions for each browser and for the associated geolocation rendered type. Remember to make any backups prior to performing the removal of all sessions.</div></div>

::* '''B (''Browse Conversation Session Directory'')
:::This action button uses the '''NST Directory/File Browser''' to view an '''IPv4 Address Conversation''' session directory for an associated browser.

:* '''Individual Conversations'''
::* '''R (''Remove Individual Conversation'')''':
:::This action button will remove an individual '''IPv4 Address Conversation''' session including supporting files and the generated map or '''[http://en.wikipedia.org/wiki/Keyhole_Markup_Language KML]''' document for an associated browser. Make backups accordingly prior to using this action.

::* '''V (''View Individual Conversations'')''':
:::This action is used to view each archived '''IPv4 Address Conversation''' session for an associated browser. See section: '''[[HowTo_Geolocate_Network_Packet_Capture_Data#Mercator_World_Map | "HowTo Geolocate Network Packet Capture Data: Mercator Wold Map"]]''' or section: '''[[HowTo_Geolocate_Network_Packet_Capture_Data#KML_Document_.28Google_Earth.29 | "HowTo Geolocate Network Packet Capture Data: KML Document (Google Earth)"]]''' for further details associated with each geolocation rendered type.

[[Image:Nstgeolocate_conversations.png|center|frame|nstgeolocate Session Manager: Archived IPv4 Address Conversation Geolocations]]

== '''Create / Update / Import nstgeolocate Host Sessions''' ==

<div class="centerBlock"><div class="noteMessage">'''Note:''' An '''[http://www.ntop.org ntop]''' server must already be running in order to create an '''[http://nst.sourceforge.net/nst/docs/scripts/nstgeolocate.html nstgeolocate]''' ''auto-generated'' "'''Host'''" session using the form in this section. If this is not the case, then see the '''NST Wiki''' page: "'''[http://wiki.networksecuritytoolkit.org/nstwiki/index.php/HowTo_Geolocate_ntop_Data HowTo Geolocate ntop Data]'''" for the steps on how to start up an '''[http://www.ntop.org ntop]''' server.</div></div>

This section explains the procedure for auto-generating selective network entity geolocations using the NST script: '''[http://nst.sourceforge.net/nst/docs/scripts/nstgeolocate.html nstgeolocate]'''. Currently only the geolocation of "'''Hosts'''" from an '''[http://www.ntop.org ntop]''' session is supported. Both '''Mercator World Map''' bitmap images and '''[http://en.wikipedia.org/wiki/Keyhole_Markup_Language KML]''' documents can be produced. The Linux System '''[http://en.wikipedia.org/wiki/Cron cron]''' facility is used for scheduling, updates and pruning expired maps and documents.

=== '''Create / Update / Import nstgeolocate Host Sessions Configuration Form''' ===
The following sections will describe each related selection and text input field configuration that comprise the "'''Create / Update / Import nstgeolocate Host Sessions Configuration Form'''".  

==== '''nstgeolocate Session Location''' ====
Use these selection and text input fields to clearly identify a ''new'' or ''existing'' '''nstgeolocate Session''' configuration. The '''[http://nst.sourceforge.net/nst/docs/scripts/nstgeolocate.html nstgeolocate]''' script uses a hierarchical directory structure based on these selection and text input fields to determine the directory location for network entity geolocation '''Mercator World Maps''', '''[http://en.wikipedia.org/wiki/Keyhole_Markup_Language KML]''' documents and associated supporting files. One can also import an existing '''nstgeolocate Session''' configuration by correctly filling in each configuration selection and text input field and then ''click'' on the "'''Import nstgeolocation Session'''" button. The location of an existing '''nstgeolocate Session''' configuration could be on a shared file system or on a ''removable'' flash drive.
 
*'''Geolocation Type''':
:* '''Generate'''
::Use this selection to generate either a '''Mercator World Map''' bitmap image or a '''[http://en.wikipedia.org/wiki/Keyhole_Markup_Language KML]''' document.

:*'''Map Type (''Network Entity'')''':
::The "'''Map Type'''" is the name of the '''Network Entity''' that is to be geolocated. Currently only the geolocation of "'''Hosts'''" from an '''[http://www.ntop.org ntop]''' session is supported.

:*'''Session Name''':
::The "'''Session Name'''" is a ''unique'' directory base name to describe the location for this  '''[http://nst.sourceforge.net/nst/docs/scripts/nstgeolocate.html nstgeolocate]''' session configuration. If the directory base name does not already exist, it will be ''created''. One can be creative with ''custom'' names. Lets say your configuration rotates the '''Mercator World Map''' every week. One may choose a '''Session Name''' like: "'''wm_host_weekly'''" for this configuration. 
::The associated "'''Select...'''" button to the right of the text input field can be used to automatically populate ''default'' or ''custom''  "'''Session Name'''" directory base names. The ''default'' "'''Session Name'''" directory base name for generating a '''Mercator World Map Host''' session is: "'''wm_host'''". The ''default'' "'''Session Name'''" directory base name for generating a '''[http://en.wikipedia.org/wiki/Keyhole_Markup_Language KML] Document Host''' session is: "'''kml_host'''". A newly created session or an imported session configuration will automatically populate the selection list if it is ''unique''. Use the "'''Edit nstgeolocate Session Name List'''" button to manually alter the "'''Session Name'''" selection list.

*'''Base Session Directory''':
:This is the base session directory used for storing the generated network entity geolocation '''Mercator World Maps''', '''[http://en.wikipedia.org/wiki/Keyhole_Markup_Language KML]''' documents and associated supporting files. Use the "'''Browse'''" button to bring up the '''NST Directory/File Browser''' for locating and automatically populating the base directory input text field. The default location is: "'''/var/nst/nstgeolocate'''". If the base session directory name does not already exist, it will be ''created''.

<div class="centerBlock"><div class="noteMessage">'''Computed Session Directory Example:'''
:These configuration settings will result in producing the following computed session directory:
:*Configuration Settings:
::Generate: '''Mercator''', Map Type: '''Host''', Session Name: '''wm_host''' and the Base Session Directory: '''/var/nst/nstgeolocate'''
:*Computed Session Directory:
::"'''/var/nst/nstgeolocate/mercator/host/wm_host'''"
</div></div>

*'''ntop URL Data Source''':
:Enter a '''[http://en.wikipedia.org/wiki/Uniform_Resource_Locator URL]''' to a ''running'' '''[http://www.ntop.org ntop]''' server that can be <u>local</u> (i.e., Running on your NST probe) or <u>remote</u> (i.e., Running on a system other than your local NST probe).

<div class="centerBlock"><div class="noteMessage">'''Note:''' The <u>remote</u> '''[http://www.ntop.org ntop]''' server does not necessarily have to be running on an "'''NST Probe'''". If this is the case, then some data and status information degradation may result in various related tool tips.</div></div>

==== '''Map Annotation''' ====
*'''ntop Map Title'''
:Use this text input field to override the session '''[http://wiki.networksecuritytoolkit.org/nstwiki/index.php/HowTo_Geolocate_ntop_Data#ntop_Annotation ntop Annotation]'''. Enter a short descriptive phrase (i.e., 22 Characters or less) to identify the traffic that the '''[http://www.ntop.org ntop]''' server is monitoring (e.g., "Corporate Web Site"). Leave this field blank to use the '''[http://wiki.networksecuritytoolkit.org/nstwiki/index.php/HowTo_Geolocate_ntop_Data#ntop_Annotation ntop Annotation]''' entered when the '''[http://www.ntop.org ntop]''' server was setup.

*'''ntop Interface Name(s)'''
:Use this text input field to override the '''[http://www.ntop.org ntop]''' session '''[http://wiki.networksecuritytoolkit.org/nstwiki/index.php/HowTo_Geolocate_ntop_Data#Network_Interface.28s.29 Interface Name(s)]'''. Leave this field blank to use the '''[http://wiki.networksecuritytoolkit.org/nstwiki/index.php/HowTo_Geolocate_ntop_Data#Network_Interface.28s.29 Interface Name(s)]''' entered when the '''[http://www.ntop.org ntop]''' server was setup.

==== '''Mercator Map Attributes''' (''Mercator World Map Only'') ====
*'''Geolocate Marker Option'''

:*'''Mark Type'''
::Select a marker symbol type for each network entity geolocated on the '''Mercator World Map''' projection.

:*'''Mark Color'''
::Select a marker symbol color for each network entity geolocated on the '''Mercator World Map''' projection.

==== '''Map Automation''' ====
*'''Map Update Interval'''
:Use one of these predefined selection list '''Time Interval''' values to specify how often the '''[http://en.wikipedia.org/wiki/Cron cron]''' facility should ''update'' or create a ''new'' geolocation session.

<div class="centerBlock"><div class="noteMessage">'''Mercator World Map Update Note:''' A brand-new '''Mercator World Map''' will only be created if the "'''Map Rotate Interval'''" period has <u>not</u> been exceeded. Therefore, the "'''Map Update Interval'''" allows one to accumulate history or build a collage with your network entity geolocations. If the "'''Map Rotate Interval'''" period has <u>not</u> been exceeded, the previously generated network entity geolocation '''Mercator World Map''' will be used as the base map thus continuing the accumulated geolocation history.  The '''[http://nst.sourceforge.net/nst/docs/scripts/nstgeolocate.html nstgeolocate]''' script is optimized so that only ''newly'' collected network entities each '''Map Update Interval''' will be geolocated thus saving system resources. If the "'''Map Rotate Interval'''" period has been exceeded, a blank '''Mercator World Map''' will be used as the base map thus starting a brand-new map.</div></div>

<div class="centerBlock"><div class="noteMessage">'''KML Document Update Note:''' A brand-new '''[http://en.wikipedia.org/wiki/Keyhole_Markup_Language KML]''' document will always be ''created'' with each update interval.</div></div>

:*'''Minute'''
::Select a '''Map Update Interval''' value between "'''1'''" and "'''59'''" minutes.

:*'''Hour'''
::Select a '''Map Update Interval''' value between "'''1'''" and "'''23'''" Hours.

:*'''Other'''
::Select a predefined '''Map Update Interval''' using one of the following values: "'''hourly'''", "'''daily'''", "'''midnight'''", "'''weekly'''", "'''monthly'''", "'''yearly'''",  or "'''annually'''".

*'''Map Rotate Interval (''Mercator World Map Only'')'''
:Select a '''Map Rotate Interval''' value that will determine how long to geolocate network entities on the <u>same</u> '''Mercator Map Projection'''. For each "'''Map Update Interval'''", if the "'''Map Rotate Interval'''" period has <u>not</u> been exceeded, the previously generated network entity geolocation '''Mercator World Map''' will serve as the base map thus continuing the accumulated geolocation history until the complete "'''Map Rotate Interval'''" has expired.

:*'''Minute'''
::Select a '''Map Rotate Interval''' value between "'''1'''" and "'''59'''" minutes.

:*'''Hour'''
::Select a '''Map Rotate Interval''' value between "'''1'''" and "'''23'''" hours.

:*'''Day'''
::Select a predefined '''Map Rotate Interval''' value between "'''1'''" and "'''365'''" days.

----
===== '''HowTo Generate A Long Duration ntop Host Mercator World Map''' =====
<div class="centerBlock"><div class="noteMessage">When using '''[http://www.ntop.org ntop]''' to monitor a relatively high network traffic environment, one could set a short "'''[http://wiki.networksecuritytoolkit.org/nstwiki/index.php/HowTo_Geolocate_ntop_Data#Setting_The_ntop_Host_Collection_Window_Size ntop Collection Window Size Interval]'''" (e.g., '''300 Seconds - 5 Minutes''') and use a frequent "'''Map Update Interval'''" (e.g., '''1 Minute''') but with an extended "'''Map Rotate Interval'''" (e.g., '''1 Day''') to generate a long duration '''[http://www.ntop.org ntop]''' Host geolocation map.</div></div>
----

==== '''Map Pruning (Delete Older Maps & Documents)''' ====
Use this section to purge older '''Mercator World Maps''' and '''[http://en.wikipedia.org/wiki/Keyhole_Markup_Language KML]''' documents. Essentially use the controls in this section to keep a window back in time of how many ''auto-generated'' geolocation maps and documents you would like to maintain.
 
*'''Map Pruning Check'''
:Select a time interval for checking when to ''prune'' expired maps and documents.

:*'''Minute'''
::Select a '''Map Pruning Check''' interval value between "'''1'''" and "'''59'''" minutes.

:*'''Hour'''
::Select a '''Map Pruning Check''' interval value between "'''1'''" and "'''23'''" hours.

:*'''Other'''
::Select a predefined '''Map Pruning Check''' interval using one of the following values: "'''hourly'''", "'''daily'''", "'''midnight'''", "'''weekly'''", "'''monthly'''", "'''yearly'''",  or "'''annually'''".

*'''Prune Map Back'''
:Select a window duration back in time of how many ''auto-generated'' geolocation maps and documents you would like to maintain.

:*'''Minutes'''
::Select a predefined '''Prune Map Back''' window value between "'''0'''" and "'''1440''' (i.e., '''1 Day''')" minutes.

:*'''Days'''
::Select a predefined '''Prune Map Back''' window value between "'''0'''" and "'''99999''' (i.e., '''Disable Purging''')" days.

For example, in the image below the '''Map Pruning Check''' field is set to ''12 hours'' and the '''Prune Map Back''' field is set to ''4 days''. This would result in the system checking for old map data every ''12 hours''. During each check, any map data found to be more than ''4 days'' old would be removed from the system.

[[Image:Nstgeolocate_create_update_import.png|center|frame|nstgeolocate Session Manager: Create, Update and Import ntop Host Sessions]]

== '''Cron Service Information''' ==
Use this section to maintain the '''[http://en.wikipedia.org/wiki/Cron crond]''' service and other related services providing <u>local</u> network entity data sources for geolocation.

=== '''Current Crontab Configuration''' ===
Use this section to view the '''root''' user's '''[http://wiki.kartbuilding.net/index.php/Crontab crontab]''' configuration in particular the entries related to a '''[http://nst.sourceforge.net/nst/docs/scripts/nstgeolocate.html nstgeolocate]''' session.