====== GIS Monitoring ======

{{indexmenu_n>20}}

<wrap #ks1 />

===== Pandora FMS GIS =====

A **GIS map** is a visual representation of the geographical location of the agents of Pandora FMS installation. With this map you may see the current position, as well as a small history summary of the agents' positions.

<WRAP center round tip 90%>

In order to use GIS maps, the agents, the server and the console must be configured.

</WRAP>

<wrap #ks2 />

===== Installation =====

<wrap #ks2_1 />

==== Agent Configuration ====

The ''pandora_agent.conf'' file of [[:en:documentation:pandorafms:installation:05_configuration_agents|Software Agents]] has parameters to configure device positioning:

  * Longitude.
  * Latitude.
  * Altitude.
  * Item description.

You may also use the ''gis_exec''  parameter to indicate the path of a //script//  that returns the device coordinates in a string with the format "latitude,longitude,altitude".
<code>

# Agent position parameters
# Those parameters define the geographical position of the agent

# gis_exec: Call a script that returns a string with "latitude,longitude,altitude"
# i.e.: 41.377,-5.105,2.365

#gis_exec /tmp/gis.sh

# latitude
latitude 40.37346827
# longitude
longitude -3.6418548
# altitude
altitude 637

# Position description
position_description Madrid, Vallecas

</code>

<wrap #ks2_2 />

==== Server Configuration ====

GIS features should be enabled in the server with the parameter [[:en:documentation:pandorafms:installation:04_configuration#activate_gis|activate_gis]]. When this flag is set to ''1''  , the server will process all the GIS information received from the agents.

With data positioning, there is the possibility of storing agent positions in Pandora FMS, but this data comes from a source that is not completely reliable, and can cause an agent without significant position changes to send location change information. To avoid this, the parameter [[:en:documentation:pandorafms:installation:04_configuration#location_error|location_error]] sets the distance that is considered as the same position. This is an error tolerance on the position threshold, and as long as the agent's location remains at that threshold, //it will be considered to be in the same position//.

<wrap #ks2_2_1 />

=== Discovery server and location information ===

Using an inverse geolocation algorithm and a database with IP addresses and positioning information, the Discovery server can calculate the position of the discovered agents. This can be done either by using a formatted [[http://www.maxmind.com/app/geolitecity|MaxMind GeoIP GeoLiteCity]] file, or a couple of tables in the database with that information.

There are two parameters that define this performance of the Discovery server: the [[:en:documentation:pandorafms:installation:04_configuration#recon_reverse_geolocation_file|recon_reverse_geolocation_file]], used to point to the file with the reverse geolocation information (using the MaxMind GPL ''GeoLiteCity.dat''' ), and the parameter [[:en:documentation:pandorafms:installation:04_configuration#recon_location_scatter_radius|recon_location_scatter_radius]]. The algorithm will calculate an approximate position for the agents and they will be randomly arranged around the calculated positions, taking into account the radius indicated in ''recon_location_scatter_radius''  .

The reverse geolocation service provided by the Google® API or OpenStreetMaps® (OSM) can also be used.

  * Google® reverse geolocation can be enabled by setting the parameter [[:en:documentation:pandorafms:installation:04_configuration#google_maps_description|google_maps_description]], to ''1''  .
  * You may activate the reverse geolocation of OpenStreetMaps® by setting the parameter [[:en:documentation:pandorafms:installation:04_configuration#openstreetmaps_description|openstreetmaps_description]], to ''1''.
  * This feature **decreases the performance of Pandora FMS server**.
  * **Internet access**  is required to use the Google® or OpenStreetMaps® API and that, of course, this feature depends on the availability of the providers of these services.
<code>

# Flag to activate GIS (positional information for agents and maps) by default it is deactivated
activate_gis 1

# Radius of the Error in meters to consider two gis locations as the same location.
location_error 10

# Recon reverse geolocation file (databases with the reverse geolocation information using
# MaxMind GPL GeoLiteCity.dat format).
# Comment it to disable the IP geolocation on agent creation.

recon_reverse_geolocation_file /usr/local/share/GeoIP/GeoLiteCity.dat

# Radius (in meters) of the circle in where the agents will be place randomly when found by a recon task
# The center of the cicle is guessed by geolocating the IP address.
recon_location_scatter_radius 1000

# This enables realtime reverse geocoding using Google Maps public API.
# This requires internet access, and could have performance penalties processing GIS
# information due the connection needed to resolve all GIS input.

google_maps_description 1

# This enables realtime reverse geocoding using OpenStreetMaps public API.
# This requires internet access, and could have performance penalties processing GIS
# information due the connection needed to resolve all GIS input.
# You can alter the code to use a local (your own) OpenStreetMaps server.

openstreetmaps_description 1

</code>

<wrap #ks2_3 />

==== Console Configuration ====

In the Web Console, to use the GIS feature, it must first be enabled in the main configuration.

Menu <wrap :en>**Management → Setup → Setup → General setup → Enable GIS features → Update**</wrap>.

This will make available some new sections of the user interface.

<wrap #ks2_3_1 />

=== Basic Configuration ===

In <wrap :en>**Setup → Setup → GIS map connection**</wrap> you will define the connections that can be used with **map servers **to provide maps for GIS features.

  * <wrap :en>**Group**</wrap>: The group to which the connection belongs. **Even if the user who is creating the GIS map connection does not explicitly**  belong to the **ALL**  group ([[:en:documentation:pandorafms:management_and_operation:11_managing_and_administration#ks1_2_2|ALL]]), you may still assign the **ALL**  group as the group to which the connection belongs.
  * <wrap :en>**Number of zoom levels**</wrap>: The zoom number defined on the map.
  * <wrap :en>**Default zoom level**</wrap>: The default magnification level recommended for the map (which can be redefined on the map) and is the zoom level used when the map is displayed.

Once the basic parameters are configured, the administrator must select a connection type and, depending on the type, there will be different options.

<wrap #ks2_3_2 />

=== OpenStreetMap ===

The default installation of Pandora FMS has a predefined connection with [[http://www.openstreetmap.org/|OpenStreetMap®]], so users may directly test and see the GIS features.

To use an OpenStreet® map type, the only parameter needed is the URL of the **title server**:

{{  :wiki:pfms-setup-setup-gis_map_connection-create_new-openstreetmaps.png  }}
<code>

http://tiles.example.com/${z}/${x}/${y}.png

http://tile.example.com/${z}/${x}/${y}.png

</code>

You may check out [[https://wiki.openstreetmap.org/wiki/Tile_servers|the official list of servers on the OpenStreetMap®]] website with instructions on naming and accreditation.

<wrap #ks2_3_3 />

=== Google Maps ===

Pandora FMS also includes the connection to Google Maps®. For this, it is necessary for a valid **password**  to be obtained from Google® (see [[https://developers.google.com/maps/documentation/directions/#api_key|Google Maps API policy ]]) and that it is placed in the corresponding field of the connection definition.

{{  :wiki:pfms-setup-setup-gis_map_connection-create_new-google.png  }}

With this password, it is possible to define several connections using different types of base maps: //Hybrid//, //Physical//  or //Satelite//.

<WRAP center round tip 90%>

This password may take several minutes to work after being obtained.

</WRAP>

<wrap #ks2_3_4 />

=== Static Image ===

Another type of connection provided is to use a <wrap :en>**Static Image**</wrap> as a map. To use this type of map, the image must be as EPSG:4326 (WGS84).

In this case, the parameters needed for the map definition are the **URL**  of the image, the **height**  and **width**  of the image, and the position limits (longitude and latitude) of the image borders (right, left, top and bottom).

<wrap #ks2_3_5 />

=== WMS Server ===

A local WMS map server (<wrap :en>**Web Map Service**</wrap>) can be installed and used when it is impossible to use an online map service. This also allows defining [[:en:documentation:pandorafms:introduction:03_glossary#mosaic|mosaic]]] types for higher speed.

Since version 723 it is possible to add connections to WMS servers, such as [[http://geoserver.org/|GeoServer]]. To do this, it is necessary to enter the address where the service is provided and the name or names of the layers to be obtained from it.

{{  :wiki:pfms-setup-setup-gis_map_connection-create_new-wms_server.png  }}

You can see how to perform a minimal installation and configuration of a GeoServer in [[:en:documentation:pandorafms:technical_annexes:13_geoserver_installation|this technical annex]].

<wrap #ks2_3_6 />

=== Map center and default position ===

The last thing to define in a map connection is the map center and default position for agents without //positional data//. To define these, it is possible to preview the map and click on it to set these parameters, depending on which (<wrap :en>**Map center**</wrap> or <wrap :en>**Default position for agents without GIS data**</wrap>) was selected with the <wrap :en>**Change in the Map**</wrap> selector.

In this preview map, it is possible to scroll using the green arrows at the top left, change the //zoom// level with the **+**  and **-**  icons, or use the magnifying glass icon to see it in full //zoom//.

It is also possible to set the position by entering the values in their corresponding input cells (here the decimal separator is the point).

{{  :wiki:connection_configruation_set_center_default.png  }}

Once all the connection parameters have been set, it will be possible to save the connection for use in the map configurator by clicking on the <wrap :en>**Save**</wrap> button.

<wrap #ks2_4 />

==== GIS Maps ====

Once the connections have been defined, they may be used to define maps in the <wrap :en>**GIS Maps**</wrap> menu.

The menu takes the user to a screen with defined maps, where it is possible to edit a map, display the map, set the default map (<wrap :en>//default map//</wrap>) or delete a map.

{{  :wiki:pfms-topology_maps-gis_maps-list_of_gis_maps_sample.png  }}

There is also a button to create new maps (<wrap :en>**Create**</wrap> button).

<WRAP center round important 90%>

A **default map**  must be set, which will be the one used in the agent's view to show its position.

</WRAP>

**Create a GIS Map**

When accessing the map creation page, the first thing to do is to add a name (<wrap :en>**Map Name**</wrap>) and a map connection (<wrap :en>**Add Map connection**</wrap>), selecting one of those already available. It is possible to add more than one, which will be available later as a base layer (only one of them can be active at the same time).

{{  :wiki:gis_map_builder_main.png  }}

After selecting the connection (or when the default connection of the map is changed) Pandora FMS console will ask whether you want to use the default data of the connection for the map. If yes, the console will fill (or update) **all positioning data**  with the ones already defined in the connection, and the user will have to set only the //default zoom level//. If the use of the default values is rejected, **no change will be made**  and the connection will just be added.

**Layer Definition**

When the basic parameters of the map have been set, it is time to define the layers (<wrap :en>**LAYERS**</wrap>) of the map that will be used to select which elements to display on the map. **If it is the default map,**  it is unnecessary to define any layer because it will be used to show the agent's position in the agent view.

Each map has one or more layers to display agents. Each layer may display the //agents of a group//, a //list of agents//  and/or //a group with an agent as representative//. That way, it is easy to set the agents to be displayed in each layer.

Layers can be configured as //visible//  or //hidden//, and it is possible to:

  * Select the group with the selector to add your agents.
  * Add agents with the cell individually.
  * Add a group with a single agent as representative.

<WRAP center round tip 90%>

Once a group has been created in a layer with its representative agent, it is not possible to generate another group with another agent.

</WRAP>

Once the layer is set (it will be completely saved, with the complete map, by clicking <wrap :en>**Save map**</wrap>) it will be moved to the left column of the defined layers, where it is possible to sort them (move up and down), delete or edit them again.

Once you are finished defining the map layers, you may save them all with the <wrap :en>**Save map**</wrap> button (<wrap :en>**Update map**</wrap> button in the case of editing a map).

<wrap #ks3 />

===== Operation =====

<wrap #ks3_1 />

==== GIS Maps ====

The GIS map menu displays all defined maps. Each one can be viewed by displaying the map with the parameters defined in the map. In turn, once opened, each map can be edited by clicking on the <wrap :en>**Setup**</wrap> button located at the top edge.

{{  :wiki:pfms-topology_maps-gis_maps-list_of_gis_maps-setup_gear.png  }}

<wrap #ks3_1_1 />

=== Moving around the map ===

The controls for the map include four green arrows in the upper left corner that allow you to scroll the map in each direction. With **+**  and **-**  icons to increase and decrease the zoom level, and a zoom bar to directly select the desired level.

By dragging the map it is also possible to move around.

Agents shown on the map can be clicked on to get more information about the agent (and once the balloon with the extra information is displayed, the agent name is a link to the **agent view**).

{{  :wiki:pfms-topology_maps-gis_maps-list_of_gis_maps-control_navigation.png  }}

<wrap #ks3_1_2 />

=== Layers ===

Clicking on the **+**  button on the right will open the layer controls. It displays a green box where it is possible to select the base layer (the //connection to the map server//, if more than one has been defined for the map), and display which layers are **visible**.

{{  :wiki:pfms-topology_maps-gis_maps-list_of_gis_maps-control_layers.png  }}

There is also a special layer defined by the system called <wrap :en>**Agent hierarchy**</wrap>. If this layer is visible, it will show red dotted lines connecting an agent to its parent agent (if both are visible).

<wrap #ks3_1_3 />

=== Filters ===

Above the map there are filtering options by agent status:

  * OK.
  * Critical.
  * Warning.
  * Other.

<wrap #ks3_1_4 />

=== Refresh Map ===

Next to the filter buttons, there is a list box named <wrap :in>**Refresh**</wrap> to select the map refresh range. The map uses AJAX calls to refresh the agents on the map using the chosen period.

<wrap #ks3_2 />

==== Agent view ====

The agent view of Pandora FMS console also has GIS features. The first thing that appears in the main view is the agent's location in terms of longitude, latitude and altitude.

<wrap #ks3_2_1 />

=== GIS History View ===

There is a button on the top bar (provided that GIS is enabled) that displays the **GIS view**  of the agent.

This view shows the agent's position on the **default map**, in a table with all the information reported by the agent, including a reverse geolocation system that shows the agent's address with the street, city and country where it is located.

{{  :wiki:pandroid_gis22.png  }}

<wrap #ks3_3 />

==== GIS Agent Configuration ====

Among the agent management tabs, there is an option to manually set the agent position. Also the <wrap :en>**Agent manage**</wrap> tab has some parameters that affect the GIS features.

<wrap #ks3_3_1 />

=== Update GIS data ===

In the <wrap :en>**Agent manage**</wrap> tab, there is an option called <wrap :en>**Update new GIS data**</wrap>.

  * If enabled, the server will update all position information received from the agent and will stop using the last valid values for this agent.
  * When this option is inactive, it is useful in case an agent is reporting an erroneous position or needs to be placed in a fixed location.

<wrap #ks3_3_2 />

=== Manual position of the agent ===

The <wrap :en>**GIS Data**</wrap> tab shows the default map. It is possible to click on it to define the new agent position, or set it using the form at the bottom of the map.

{{  :wiki:pos_manual.png  }}

<WRAP center round important 90%>

Setting //manually//  the agent's position will also activate the option to ignore new GIS data (<wrap :en>**Ignore new GIS data**</wrap>, which will then take the opposite value in the "[[#ks3_3_1|Update new GIS data]]" option), thus preventing the next data packet with //positional//  information from the agent from resetting the position again.

If this is not the desired performance, remember to uncheck the <wrap :en>**Ignore new GIS data**</wrap> option before clicking <wrap :en>**Update**</wrap>.

</WRAP>

[[:en:documentation:start|Back to Pandora FMS Documentation Index]]