Difference between revisions of "Pandora: Documentation en: GIS"

From Pandora FMS Wiki
Jump to: navigation, search
(OpenStreetMap)
(22 intermediate revisions by 2 users not shown)
Line 10: Line 10:
 
== Setup ==
 
== Setup ==
  
=== The Agent's Configuration ===
+
=== Agent configuration ===
  
The agent now accepts new parameters to send the positional data. In the 'agent.conf', there some new parameters for longitude, latitude, altitude and position description now. Other parameters for an alternative way to obtain the coordinates are located in the file named 'gis_exec' now. This parameter has a script path which is going to return a string, containing the coordinates in the format of '[latitude],[longitude],[altitude]'.
+
The software agent pandora_agent.conf file contains parameters to configure the device's position: longitude, latitude, altitude and position description. The 'gis_exec' parameter can also be used, where the path of the script that returns the coordinates of a device by means of a string with the "latitude, logitude, altitude" format must be indicated.
  
 
This is an example:
 
This is an example:
Line 34: Line 34:
 
  position_description Madrid, centro
 
  position_description Madrid, centro
  
=== The Server's Configuration ===
+
=== Server configuration ===
  
The GIS features are also required to be enabled on the server. There is a new flag called 'activate_gis' for this. If this flag is set to '1', the server is going to process all GIS information it receives from the agents.
+
GIS features must also be enabled on the server, enabling the 'activate_gis' parameter. If this flag is set to '1', the server will process all GIS information received from the agents.
  
There is also the new feature of storing agent positions on Pandora FMS by positional data now. This data is coming from a source without high accuracy. It's possible to store a lot of different points very close to each other without an important difference on the position. To avoid this circumstance, the 'location_error' parameter determines the distance which is considered to be the same location. This is an error threshold on the position and all data received from an agent having a position within the distance (in meters) defined within this parameter will be stored as new data received on the same point, until the received position moves out of the defined error distance which triggers the setting of a new location.
+
There is also the new feature of storing agent positions on Pandora FMS. But this data comes from a source that is not highly accurate and it can cause for an agent with no significant position changes to send location change information. To avoid this, the 'location_error' parameter fixes the distance which is considered to be the same location. This is an error tolerance pn the position threshold and while the agent location continues to be within that range, it is considered that there has been no position change.
  
''' Recon Server and positional Information:'''
+
''' Discovery server and position information:'''
  
By using a reverse geolocation algorithm and a database, containing the relation of IPs and positional information, the Recon Server is now able to 'guess' the position of the discovered agents. It's able to use a file in [http://www.maxmind.com/app/geolitecity '''MaxMind GeoIP GeoLiteCity'''] format or a couple of tables on the database containing this particular information.
+
By using a reverse geolocation algorithm and a database, containing the relation of IPs and positional information, the Discovery server is now able to 'calculate' the position of the discovered agents. It can use a file in [http://www.maxmind.com/app/geolitecity '''MaxMind GeoIP GeoLiteCity'''] format or a couple of tables on the database containing this particular information.
  
There is also an entire two parameters which define this particular behavior of the Recon Server. The 'recon_reverse_geolocation_file' is only used to point to the file which contains the reverse geolocation information by using the 'MaxMind GPL GeoLiteCity.dat'. The last parameter is called 'recon_location_scatter_radius' which is used to place the discovered agents randomly around the point defined by the reverse geolocation algorithm and within the range (in meters) defined by the 'recon_location_scatter_radius' parameter.
+
There are also two parameters which define this particular Discovery server performance. The ''recon_reverse_geolocation_file'' is only used to point to the file which contains the reverse geolocation information by using the 'MaxMind GPL GeoLiteCity.dat' format and the 'recon_location_scatter_radius' parameter. The algorithm will calculate an approximated position for the agents and they will be  randomly placed around the calculated positions, taking into account the indicated 'recon_location_scatter_radius' radio.
  
You're also able to use the reverse geolocation provided by the Google API and OpenStreetMaps. You may activate Google's reverse geolocation by setting the parameter named 'google_maps_description' to '1'. You may activate OpenStreetMaps reverse geolocation by setting the parameter 'openstreetmaps_description' to '1'.
+
You may also use the reverse geolocation provided by the Google API and OpenStreetMaps. You may activate Google's reverse geolocation by setting the parameter named 'google_maps_description' to '1'. Be careful when using this feature, because it '''considerably decreases the Pandora FMS server's performance'''. Please keep in mind that you're required to have a direct '''connection to the Internet''' to use Google's API and Openstreet Maps. It also heavily depends on the service provider's availability.
 
 
Be careful in using this feature, because it considerably decreases the Pandora FMS server's performance. Please keep in mind that you're required to have a direct connection to the internet to use Google's API and Openstreet Maps. It also depends heavily on service provider's availability.
 
  
 
'''Configuration Example:'''  
 
'''Configuration Example:'''  
Line 79: Line 77:
 
   
 
   
 
  openstreetmaps_description 1
 
  openstreetmaps_description 1
 +
 +
There is a plugin that recalculates agent GIS localization. The plugin path is ''/usr/share/pandora_server/util/agent_gis_update.pl'' by default,
 +
but it can be place wherever the user prefers.
  
 
''' Use example:'''  
 
''' Use example:'''  
Line 92: Line 93:
 
<br><br>
 
<br><br>
  
=== The Console's Configuration ===
+
=== Console setup ===
  
Within the Console, the configuration must be activated in the main setup in order to utilize the GIS features.
+
To use GIS features, they must have been previously activated in the main setup in Pandora FMS console.
  
 
<center>
 
<center>
Line 100: Line 101:
 
</center>
 
</center>
  
Because of the activation, the following new sections of the user interface are available now:
+
Once activated, the following new user interface sections become available:
  
In Setup -> GIS map connection, the connections that can be used with map servers to provide maps for GIS functionalities must be defined.
+
In Setup -> GIS map connection, define the connections that can be used with map servers to provide maps for GIS features.
  
 
==== GIS Connections ====
 
==== GIS Connections ====
  
 
===== Basic Configuration =====  
 
===== Basic Configuration =====  
 +
 +
The connection comes with several basic parameters:
  
 
<center>
 
<center>
Line 112: Line 115:
 
</center>
 
</center>
  
The connection comes with several basic parameters:
 
  
 
* A '''name''' for the configuration, so it can be recognized when selecting a connection on the map definition screen.
 
* A '''name''' for the configuration, so it can be recognized when selecting a connection on the map definition screen.
* The '''group''' that owns the connection. This is going to be used to filter the connections available on the map builder, depending on the ACLs.
+
* The '''group''' the connection belongs to.
 
* The '''number of zoom levels''' defined on the map.
 
* The '''number of zoom levels''' defined on the map.
* The '''default zoom level''', recommended for the map (this can be redefined on the map) and it's the zoom level used when the map is open.
+
* The '''default zoom level''' recommended for the map (this can be redefined on the map) and it is the zoom in level used when the map is open.
  
Once the basic parameters are set, the administrator is required to select a connection type. Depending on the type there will be different options, and so are the types of connections and their options.
+
Once the basic parameters are set, the administrator is required to select a connection type. Depending on the type, there will be different options, and so are the types of connections and their options.
  
===== Open Street Maps =====
+
===== OpenStreet Maps =====
  
The default installation of Pandora FMS comes with a predefined connection with [http://www.openstreetmap.org/ '''OpenStreetMaps'''] so the users are able to directly see and test the GIS features. Usually the Pandora FMS server's location is a place without direct access to the Internet or the user would prefer to use it's own map server to have more flexibility, to be faster or to define it's own kind of tiles. Please check the topic named [[Pandora:Current_development:Pandora_GIS_Backend]] for a possible way to achieve this.
+
The default Pandora FMS installation comes with a predefined connection with [http://www.openstreetmap.org/ '''OpenStreetMaps'''] so the users are able to directly see and test the GIS features.  
  
In order to use an Open Street Maps type of map, the only parameter required is the URL of the tile server as shown on the image below.
+
In order to use an Open Street Maps type of map, the only parameter required is the URL of the '''title server''', as shown on the image below.
  
 
<center>
 
<center>
Line 131: Line 133:
 
</center>
 
</center>
  
This can be something like:
+
This could be something similar to:
 
  http://tiles.example.com/${z}/${x}/${y}.png
 
  http://tiles.example.com/${z}/${x}/${y}.png
  
 
===== Google Maps =====
 
===== Google Maps =====
  
Pandora FMS also supports the connection to Google Maps. A valid key for the Pandora FMS Console Server must be obtained from Google (see [https://developers.google.com/maps/documentation/directions/#api_key '''Google Maps API Policy''']) and placed in the corresponding field of the connection definition.
+
Pandora FMS also supports the connection to Google Maps. For that purpose, obtain a valid password for  
 +
Pandora FMS Console server from Google (see [https://developers.google.com/maps/documentation/directions/#api_key '''Google Maps API Policy''']) and place it on the corresponding field of the connection definition.
  
 
<center>
 
<center>
Line 142: Line 145:
 
</center>
 
</center>
  
By this key, it's possible to define several connections by using different types of base maps, e.g. 'hybrid', 'physical' or 'satellite'.
+
By means of this password, it is possible to define several connections using different base map types, e.g. 'Hybrid', 'Physical' or 'Satellite'.
 +
 
 +
 
 +
{{Tip|This password might take a couple of minutes to work after having obtained it.}}
  
 
===== Static Image =====
 
===== Static Image =====
  
Another type of supported connection is to utilize a static image as a map. In order to use this type of map, the image is required to be on a [http://en.wikipedia.org/wiki/EPSG:4326 EPSG:4326] projection.
+
Another type of supported connection is to use a Static Image as a map. In order to use this type of map, the image is required to be as a [http://en.wikipedia.org/wiki/EPSG:4326 EPSG:4326].
  
In this case, the parameters required for the map's definition are the URL of the image, the image's height and width and the positional limits ('longitude' and 'latitude') of the image's sides ('right', 'left', 'top' and 'bottom').
+
In this case, the parameters required for defining the map are the image URL, the image's height and width and the positional limits ('longitude' and 'latitude') of the image's edges ('right', 'left', 'top' and 'bottom').
  
 
<center>
 
<center>
Line 156: Line 162:
 
=====WMS Server=====
 
=====WMS Server=====
  
From version 7.0 Build 723 it is possible to add connections to WMS servers (Web Map Service), like [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 we want to get from it.
+
Sometimes Pandora FMS server is located somewhere without direct Internet connection, so it is not possible to use an online map service. Some other times, the user might prefer their own map server to achiever higher flexibility, work faster, or define his own mosaic types. From version 7.0 Build 723 onwards, it is possible to add connections to WMS servers (Web Map Service), like [http://geoserver.org/ GeoServer]. To do this, enter the address where the service is provided and the name or names of the layers you wish to get from it.
  
 
<br><br>
 
<br><br>
Line 164: Line 170:
 
<br><br>
 
<br><br>
  
For a minimum installation and configuration of a GeoServer server, see [[Pandora:Documentation_en:GeoServer_Installation|this annex]].
+
For a minimum Geoserver server installation and configuration, see [[Pandora:Documentation_en:GeoServer_Installation|this annex]].
  
 +
=====Map center and default position=====
  
=====The Map's Center and Default Position=====
+
The last thing to define for a map connection is the map center and the default position for agents without any positional data. In order to define them, it is possible to preview the map and click on it to set this parameters, depending on which parameter is selected by the 'Change in the Map' selector.
  
The last thing to define for a map connection is the map's center and the default position for agents without any positional data. In order to define them, it's possible to preview the map and click on the map to set this parameters, depending on which parameter is selected by the 'Change in the Map' selector.
+
Within this preview map, it is possible to move around by using the green arrows on the top left, change the zoom level with the '+' and '-' icons or use the 'magnifier' to use zoom in.
  
Within this preview map, it's possible to move the map around by using the green arrows on the top left, to change the zoom level with the '+' and '-' icons or to use the 'magnifier' to use the full zoom.
+
Of course, it is also possible to set the position by inserting the values into the corresponding input boxes.
 
 
It's also possible to set the position by inserting the values into the corresponding input boxes.
 
  
 
<center>
 
<center>
Line 179: Line 184:
 
</center>
 
</center>
  
Once all connection parameters are set, it's possible to save the connection in order to use it on the map builder by clicking on the 'Save' button.
+
Once all connection parameters are set, it is possible to save the connection in order to use it on the map builder by clicking on the 'Save' button.
  
 
====  GIS Maps ====
 
====  GIS Maps ====
  
Once the connections are defined, they may be used to define the maps within the '''GIS Maps '''.
+
Once the connections are defined, they may be used to define the maps within the '''GIS Maps ''' menu.
  
 
<center>
 
<center>
[[Image:‎Gis_map_menu.png]]
+
[[Image:‎Gis_map_menu.png | 500 px]]
 
</center>
 
</center>
  
The menu takes the user to a screen with defined maps, where it is possible to edit a map, visualize the map, set the map as default or delete a map.
+
The menu takes the user to a screen with defined maps, where it is possible to edit a map, view it, set it as default or delete it.
  
 
There is also a button to create new maps.
 
There is also a button to create new maps.
 
<br>
 
<br>
 
<br>
 
<br>
{{Warning|The Administrator '''is required''' to establish a default map which is going to be used for the agent's view in order to display the agent's position.}}
+
{{Warning|It '''is required''' to set a default map which will be used in the agent's view to display its position.}}
  
 
===== Creating a GIS Map =====
 
===== Creating a GIS Map =====
  
Once on the map's creation page, the first thing to do is to allocate a map name and to add a map connection from the available ones. It's possible to add more than one, which are going to be available later on as base layers. This means that only one can be active at a time. When the connection is selected or if the default connection for the map is changed, the Pandora FMS Console asks if you intend to use the default data from the connection for the map. If the answer is 'Accept', the console is going to insert or update all positional data ('center longitude', 'center latitude', 'center altitude', 'default longitude', 'default latitude' and 'default altitude') from the ones defined within the connection. The user is only required to set the default zoom level. If the answer is e.g. 'Cancel', no changes will be made within those fields and merely the connection is added.
+
Once on the map creation page, the first thing to do is to add a '''map name''' and a '''map connection''' from the ones available. You may add more than one, which will be available later on as base layers (only one of them can be active at once). When the connection is selected, or if the default connection for the map is changed, the Pandora FMS Console will ask whether you intend to use the default data from the connection for the map. If the answer is 'Accept', the console will fill out or update '''all positional data''' with the ones defined in the connection, and the user will just set the default zoom in level. If use of the default values is denied, '''no changes will be made''' and the connection will just be added.
  
 
<center>
 
<center>
Line 204: Line 209:
 
</center>
 
</center>
  
===== The Layer's Definition =====
+
===== Layer definition =====
 +
 
 +
Once the basic map parameters are set, it is time to define the map's layers used to select which elements are shown on the map - except if it is the default map - on which there is no need to define any layer, because it will be used to display the agent's position in the agent view.
  
Once the basic map parameters are set, it's time to define the map's layers used to select which elements are shown on the map, except if it's the default map - on which you have no need to define any layer, because it's going to be used to display the agent's position in the agent view.
+
Each map has one or more layers to display agents. Each layer was designed to display the ''group agents'', ''a list of agents'' and/or ''a group with an agent as a sample''. That way, it is easy to define the agents shown on each layer.
  
Each map has one or more layers to display the agents. Each layer was designed to display the agents of a group and a list of agents. In this way, it's easy to define the agents shown on each layer.
+
The layers can be defined as ''visible'' or ''hidden'' and it is possible to:
  
The layers can be defined as 'visible' or 'hidden'.
 
 
<br><br>
 
<br><br>
 
<center>
 
<center>
Line 216: Line 222:
 
</center>
 
</center>
 
<br><br>
 
<br><br>
* Choose the group with the selector to add their agents.
+
* Choose the group with the selector to add agents.
  
* Or add manually each agent.
+
* Add each agent manually.
  
* Or add a group with only one agents as its representation.
+
* Add a group with only one agents as sample.
  
{{Tip|Once you have created a group in a layer with its representative agent, you can not generate the same group with another agent.}}
+
{{Tip|Once you have created a group in a layer with its representative agent, you cannot generate the same group with another agent.}}
  
Once the layer is defined, it will be moved to the left column of defined layers, in which it's possible to arrange, delete or edit them again. The layer is '''not''' going to be entirely saved until the whole map is.
+
Once the layer is defined (it is not completely saved until the complete map is), it will be moved to the left column of defined layers, in which it is possible to arrange (move them up or down), delete or edit them again.  
 
   
 
   
Once the definition of the layers of the map is completed, it may be saved by clicking on the 'Save Map' button. The 'Update Map' button is only going to be displayed in case of editing any map.
+
Once the map layer definition is complete, it is saved by clicking on the 'Save Map' button ('Update Map' button in case the map was edited instead).
  
 
== Operation ==
 
== Operation ==
  
Once there is at least one map defined, it's possible to start the operation containing the GIS features.
+
Once there is at least one map defined, it is possible to start using GIS features.
  
=== The GIS Maps ===
+
=== GIS Maps ===
The GIS map menu displays all defined maps. Each one can be visualized by displaying the map with the parameters defined in the map.
+
The GIS map menu displays all defined maps. Each one can be viewed by displaying the map with the parameters defined in the map.
  
 
==== Moving around on the Map ====
 
==== Moving around on the Map ====
  
The controls for the map include four green arrows on the top left corner which allow to move around on the map. The '+' and '-' icons are intended to increase and decrease the zoom level. There is also a 'zoom bar', designed to directly select the favored zoom level.
+
The controls for the map include four green arrows on the top left corner which allow to move around on the map. The '+' and '-' icons are intended to increase and decrease the zoom level. There is also a 'zoom bar', designed to directly select the desired zoom level.
  
It's also possible to move around by dragging the map to its favored position.
+
It is also possible to move around by dragging the map to the desired position.
  
The agents shown on the map are able to be clicked on in order to display more information about the agent. Once the bubble containing the extra info is displayed, the agent's name consists of a link to the agent's view.
+
Click on the agents shown on the map to have more information about the agent displayed (once the extra information is displayed, the agent's name becomes a link to the agent's view).
  
==== Hide, Show and Select Layers ====
+
==== Hide, show and select Layers ====
  
The white '+' icon on the green background on the right is going to open the layer's controls. If you click on it, it's going to display a green box in which it's possible to select the base layer (it's the connection to the map's server, if more than one are defined for the map) and to determine which layers are visible.
+
The white '+' icon at the right opens the layer's controls. It displays a green box in which it is possible to select the base layer (the connection to the map's server, if there were more than one are defined for that map) and see which layers are '''visible'''.
  
There is also a special system-defined layer called 'Hierarchy of Agents'. If this layer is visible, it's going to display some red dashed lines, connecting an agent to its parent element if both of them are visible.
+
There is also a special system-defined layer called '''Agent Hierarchy'''. If this layer is visible, it will display some red dashed lines, connecting an agent to its parent element (if both of them are visible).
  
 
==== Filters ====
 
==== Filters ====
 
   
 
   
Above the map there are filtering options for the state of the agents:
+
Above the map there are filtering options for the agent states:
 
* Ok
 
* Ok
 
* Critical
 
* Critical
Line 259: Line 265:
 
==== Map Refresh ====
 
==== Map Refresh ====
  
Next to the filter buttons, there is a combo box named 'Refresh' to select the update rate for the map. The map utilizes [[http://en.wikipedia.org/wiki/AJAX '''AJAX Calls''']] to refresh the agents on the map by using the defined period.
+
Next to the filter buttons, there is a combo box called '''Refresh''' to select the map update rate. The map uses [[http://en.wikipedia.org/wiki/AJAX '''AJAX Calls''']] to refresh the agents on the map by using the defined period.
  
==== Map Edit and Full Screen ====
+
==== Map edit and full screen ====
  
The last three buttons on the map's top right is a link to the Public Visual Console, a GIS Map Builder link, intended for editing the map and a full-screen button to see the map in full-screen mode.
+
The last three buttons on the map's top right is a link to the Public Visual Console, a link to '''GIS Map Builder''', intended for editing the map and a full-screen button to see the map in '''full-screen mode'''.
  
 
<center>
 
<center>
Line 269: Line 275:
 
</center>
 
</center>
  
=== The Agent View ===
+
=== Agent View ===
 
 
The Pandora FMS console's agent view also comes with new GIS features.
 
  
The main view now displays the longitude, latitude and altitude values of the agent.
+
The Pandora FMS console agent view also comes with new GIS features. The main view now displays the agent location in terms pf longitude, latitude and altitude.
  
==== The Historical GIS View ====
+
==== Historical GIS view ====
  
There is a new button on the top bar in order to display the agent's GIS view (if GIS is activated).
+
There is a new button on the top bar to display the agent's '''GIS view''' (if GIS is enabled).
 
   
 
   
This view displays the agent's current position on the default map. It contains a table which displays the history of the agent's previous positions and a path of them on the map.
+
This view displays the agent's current position on the '''default map'''. It contains a table that shows the history of the agent's previous positions and their route on the map.
  
Each position on the map is represented by a dot, except the current one which is represented by the agent's or group's icon if the agent doesn't have one. It's possible to click on any of these dots in order to obtain position-related information. It's also possible to click on the agent's icon in order to display the agent's current information.
+
Each position on the map is represented by a dot (except the current one which is represented by the agent's icon). It is possible to click on any of these dots in order to get position-related information. It is also possible to click on the agent's icon in order to display the agent's current information. The following information shows the way covered by the Pandora FMS agent for Android devices.
  
 
<center>
 
<center>
Line 287: Line 291:
 
</center>
 
</center>
  
You're also able to display a table which contains all the agent's reported information, including a reverse geolocation system which was designed to display the agent's address including the street, city and country in which the Pandora FMS agent is located.
+
You are also able to display a table which contains all the agent's reported information, including a reverse geolocation system which was designed to display the agent's address including the street, city and country in which the Pandora FMS agent is located.
  
 
<center>
 
<center>
Line 295: Line 299:
 
=== The Agent's GIS Setup ===
 
=== The Agent's GIS Setup ===
  
Among the agent's administration tabs, there is a new tag to manually set the agent's position. The 'agent manage' tab also has some parameters which are going to affect the GIS features.
+
Among the agent's administration tabs, there is a new tag to manually set the agent's position. The 'agent manage' tab also has some parameters which affect the GIS features.
  
 
==== Ignoring GIS Data ====
 
==== Ignoring GIS Data ====
  
On the 'agent manage' tab, there is a new switch called 'Ignore GIS data'. If this switch is activated, the server is going to ignore all positional information received from the agent and uses the last valid values for it. This is useful in case an agent is reporting a wrong position or it's desired to place it on a fixed place.
+
On the 'agent manage' tab, there is a new switch called 'Ignore GIS data'. If this switch is activated, the server will ignore all positional information received from the agent and use the last valid values for it. This is useful in case an agent reports a wrong position or it gets its own fixed place.
  
 
<center>
 
<center>
Line 305: Line 309:
 
</center>
 
</center>
  
==== Manual Position of the Agent ====
+
==== Manual agent position ====
  
The 'GIS Data' view displays the default map on which it's possible to click on the agent in order to determine the agent's new position. It's also possible to determine the position by using the input boxes below the map.
+
The 'GIS Data' view displays the default map on which it is possible to click on the agent in order to define the agent's new position. It is also possible to determine the position by using the input boxes below the map.
  
 
<br><br>
 
<br><br>
Line 315: Line 319:
 
<br><br>
 
<br><br>
  
{{warning|Defining the agent's position is going to activate the''' 'Ignore GIS Data' '''switch in order to avoid the agent's next positional information data package to reset the agent's position again. If this is '''not''' the desired behavior, we recommend to deactivate the 'Ignore GIS Data' switch before clicking on the 'Update' button.}}
+
{{warning|Defining the agent's position will activate the''' 'Ignore GIS Data' ''' option in order to avoid the agent's next positional information data package to reset the agent's position again. If this is '''not''' the desired performance, we recommend deactivating the 'Ignore GIS Data' switch before clicking on the 'Update' button.}}
  
== Useful Links ==
+
== Useful links ==
  
This is a collection of interesting links which are quite useful if you intend to implement your own tile server and expand the current code's features.
+
This is a collection of interesting links which are quite useful for implementing test environments and development with OpenLayers.
  
 
=== OpenLayers ===
 
=== OpenLayers ===
Line 328: Line 332:
 
* Help with OpenLayer styles: [http://trac.openlayers.org/wiki/Styles OpenLayers Styles]
 
* Help with OpenLayer styles: [http://trac.openlayers.org/wiki/Styles OpenLayers Styles]
 
* Debugging by Firebug [http://openlayers.org/dev/examples/debug.html OpenLayers Debug]
 
* Debugging by Firebug [http://openlayers.org/dev/examples/debug.html OpenLayers Debug]
 
=== Mapnik ===
 
 
* [http://www.gisandchips.org/2009/10/23/openstreetmap-y-mapnik/ Mapnik setup by OpenStreetMap]
 
* [http://www.gisandchips.org/2009/10/22/renderizado-de-osmcon-mapnik-para-usar-en-openlayers/ Rendering by Mapnik]
 
* [http://trac.mapnik.org/wiki/UbuntuInstallation Ubuntu Installation]
 
  
 
=== OpenStreetMap ===
 
=== OpenStreetMap ===
  
 
* [http://wiki.openstreetmap.org/wiki/OpenLayers Some examples of OpenLayers]
 
* [http://wiki.openstreetmap.org/wiki/OpenLayers Some examples of OpenLayers]
* Make your first map [http://weait.com/content/make-your-first-map OpenStreetMap + osm2pgsql + PostGIS + Mapnik]
 
 
* [http://wiki.openstreetmap.org/wiki/Using_OpenStreetMap Using OpenStreetMap]
 
* [http://wiki.openstreetmap.org/wiki/Using_OpenStreetMap Using OpenStreetMap]
* Tiles download [http://planet.openstreetmap.org/ OSM]
+
* File download [http://planet.openstreetmap.org/ OSM]
 
* [http://wiki.openstreetmap.org/wiki/Osm2pgsql Osm2qgsql]
 
* [http://wiki.openstreetmap.org/wiki/Osm2pgsql Osm2qgsql]
  

Revision as of 13:08, 20 September 2019

Go back to Pandora FMS documentation index

1 The Pandora GIS

1.1 Introduction

A GIS map is a visual representation of the location of the agents inside the Pandora FMS installation. With this map we can see the current position, as well as a small history of the agents positions.

To be able to use the GIS maps, you must have configured the agents, the server and the console.

1.2 Setup

1.2.1 Agent configuration

The software agent pandora_agent.conf file contains parameters to configure the device's position: longitude, latitude, altitude and position description. The 'gis_exec' parameter can also be used, where the path of the script that returns the coordinates of a device by means of a string with the "latitude, logitude, altitude" format must be indicated.

This is an example:

# Agent position parameters
# Those parameters define the agent's geographical position. 

# gis_exec: Calls 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 42.70456
# longitude
longitude -3.897187 
# altitude
altitude 600

# Position description
position_description Madrid, centro

1.2.2 Server configuration

GIS features must also be enabled on the server, enabling the 'activate_gis' parameter. If this flag is set to '1', the server will process all GIS information received from the agents.

There is also the new feature of storing agent positions on Pandora FMS. But this data comes from a source that is not highly accurate and it can cause for an agent with no significant position changes to send location change information. To avoid this, the 'location_error' parameter fixes the distance which is considered to be the same location. This is an error tolerance pn the position threshold and while the agent location continues to be within that range, it is considered that there has been no position change.

Discovery server and position information:

By using a reverse geolocation algorithm and a database, containing the relation of IPs and positional information, the Discovery server is now able to 'calculate' the position of the discovered agents. It can use a file in MaxMind GeoIP GeoLiteCity format or a couple of tables on the database containing this particular information.

There are also two parameters which define this particular Discovery server performance. The recon_reverse_geolocation_file is only used to point to the file which contains the reverse geolocation information by using the 'MaxMind GPL GeoLiteCity.dat' format and the 'recon_location_scatter_radius' parameter. The algorithm will calculate an approximated position for the agents and they will be randomly placed around the calculated positions, taking into account the indicated 'recon_location_scatter_radius' radio.

You may also use the reverse geolocation provided by the Google API and OpenStreetMaps. You may activate Google's reverse geolocation by setting the parameter named 'google_maps_description' to '1'. Be careful when using this feature, because it considerably decreases the Pandora FMS server's performance. Please keep in mind that you're required to have a direct connection to the Internet to use Google's API and Openstreet Maps. It also heavily depends on the service provider's availability.

Configuration Example:

# Flag to activate GIS (positional information for agents and maps). It's deactivated by default.
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 containing the reverse geolocation information using
# the '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 which the agents will be place randomly when found by a recon task.
# The center of the cycle is guessed by geolocating the IP.
recon_location_scatter_radius 1000

# This enables real time reverse geocoding using the Google Maps public API.
# This requires internet access and could have performance penalties because of having to process GIS
# information due the connection required to resolve all GIS input.

google_maps_description 1

# This enables real time reverse geocoding using OpenStreetMaps public API.
# This requires internet access and could have performance penalties because of having to process GIS
# information due the connection required to resolve all GIS input.
# You may alter the code to use a local or your own OpenStreetMaps server.

openstreetmaps_description 1

There is a plugin that recalculates agent GIS localization. The plugin path is /usr/share/pandora_server/util/agent_gis_update.pl by default, but it can be place wherever the user prefers.

Use example:

/usr/share/pandora_server/util/agent_gis_update.pl /etc/pandora/pandora_server.conf

The default path of the plugin is /usr/share/pandora_server/util/agent_gis_update.pl, but you can locate it wherever you want.



Ejemplo GIS.png



1.2.3 Console setup

To use GIS features, they must have been previously activated in the main setup in Pandora FMS console.

Enable GIS.png

Once activated, the following new user interface sections become available:

In Setup -> GIS map connection, define the connections that can be used with map servers to provide maps for GIS features.

1.2.3.1 GIS Connections

1.2.3.1.1 Basic Configuration

The connection comes with several basic parameters:

Connection configuration basic.png


  • A name for the configuration, so it can be recognized when selecting a connection on the map definition screen.
  • The group the connection belongs to.
  • The number of zoom levels defined on the map.
  • The default zoom level recommended for the map (this can be redefined on the map) and it is the zoom in level used when the map is open.

Once the basic parameters are set, the administrator is required to select a connection type. Depending on the type, there will be different options, and so are the types of connections and their options.

1.2.3.1.2 OpenStreet Maps

The default Pandora FMS installation comes with a predefined connection with OpenStreetMaps so the users are able to directly see and test the GIS features.

In order to use an Open Street Maps type of map, the only parameter required is the URL of the title server, as shown on the image below.

Connection configruation openstreetmaps.png

This could be something similar to:

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

Pandora FMS also supports the connection to Google Maps. For that purpose, obtain a valid password for Pandora FMS Console server from Google (see Google Maps API Policy) and place it on the corresponding field of the connection definition.

Connection configruation goole.png

By means of this password, it is possible to define several connections using different base map types, e.g. 'Hybrid', 'Physical' or 'Satellite'.


Info.png

This password might take a couple of minutes to work after having obtained it.

 


1.2.3.1.4 Static Image

Another type of supported connection is to use a Static Image as a map. In order to use this type of map, the image is required to be as a EPSG:4326.

In this case, the parameters required for defining the map are the image URL, the image's height and width and the positional limits ('longitude' and 'latitude') of the image's edges ('right', 'left', 'top' and 'bottom').

Connection configruation static image.png

1.2.3.1.5 WMS Server

Sometimes Pandora FMS server is located somewhere without direct Internet connection, so it is not possible to use an online map service. Some other times, the user might prefer their own map server to achiever higher flexibility, work faster, or define his own mosaic types. From version 7.0 Build 723 onwards, it is possible to add connections to WMS servers (Web Map Service), like GeoServer. To do this, enter the address where the service is provided and the name or names of the layers you wish to get from it.



Gis-connection-wms-server.png



For a minimum Geoserver server installation and configuration, see this annex.

1.2.3.1.6 Map center and default position

The last thing to define for a map connection is the map center and the default position for agents without any positional data. In order to define them, it is possible to preview the map and click on it to set this parameters, depending on which parameter is selected by the 'Change in the Map' selector.

Within this preview map, it is possible to move around by using the green arrows on the top left, change the zoom level with the '+' and '-' icons or use the 'magnifier' to use zoom in.

Of course, it is also possible to set the position by inserting the values into the corresponding input boxes.

Connection configruation set center default.png

Once all connection parameters are set, it is possible to save the connection in order to use it on the map builder by clicking on the 'Save' button.

1.2.3.2 GIS Maps

Once the connections are defined, they may be used to define the maps within the GIS Maps menu.

Gis map menu.png

The menu takes the user to a screen with defined maps, where it is possible to edit a map, view it, set it as default or delete it.

There is also a button to create new maps.

Template warning.png

It is required to set a default map which will be used in the agent's view to display its position.

 


1.2.3.2.1 Creating a GIS Map

Once on the map creation page, the first thing to do is to add a map name and a map connection from the ones available. You may add more than one, which will be available later on as base layers (only one of them can be active at once). When the connection is selected, or if the default connection for the map is changed, the Pandora FMS Console will ask whether you intend to use the default data from the connection for the map. If the answer is 'Accept', the console will fill out or update all positional data with the ones defined in the connection, and the user will just set the default zoom in level. If use of the default values is denied, no changes will be made and the connection will just be added.

Gis map builder main.png

1.2.3.2.2 Layer definition

Once the basic map parameters are set, it is time to define the map's layers used to select which elements are shown on the map - except if it is the default map - on which there is no need to define any layer, because it will be used to display the agent's position in the agent view.

Each map has one or more layers to display agents. Each layer was designed to display the group agents, a list of agents and/or a group with an agent as a sample. That way, it is easy to define the agents shown on each layer.

The layers can be defined as visible or hidden and it is possible to:



GIS grupo.png



  • Choose the group with the selector to add agents.
  • Add each agent manually.
  • Add a group with only one agents as sample.

Info.png

Once you have created a group in a layer with its representative agent, you cannot generate the same group with another agent.

 


Once the layer is defined (it is not completely saved until the complete map is), it will be moved to the left column of defined layers, in which it is possible to arrange (move them up or down), delete or edit them again.

Once the map layer definition is complete, it is saved by clicking on the 'Save Map' button ('Update Map' button in case the map was edited instead).

1.3 Operation

Once there is at least one map defined, it is possible to start using GIS features.

1.3.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.

1.3.1.1 Moving around on the Map

The controls for the map include four green arrows on the top left corner which allow to move around on the map. The '+' and '-' icons are intended to increase and decrease the zoom level. There is also a 'zoom bar', designed to directly select the desired zoom level.

It is also possible to move around by dragging the map to the desired position.

Click on the agents shown on the map to have more information about the agent displayed (once the extra information is displayed, the agent's name becomes a link to the agent's view).

1.3.1.2 Hide, show and select Layers

The white '+' icon at the right opens the layer's controls. It displays a green box in which it is possible to select the base layer (the connection to the map's server, if there were more than one are defined for that map) and see which layers are visible.

There is also a special system-defined layer called Agent Hierarchy. If this layer is visible, it will display some red dashed lines, connecting an agent to its parent element (if both of them are visible).

1.3.1.3 Filters

Above the map there are filtering options for the agent states:

  • Ok
  • Critical
  • Warning
  • Other

1.3.1.4 Map Refresh

Next to the filter buttons, there is a combo box called Refresh to select the map update rate. The map uses [AJAX Calls] to refresh the agents on the map by using the defined period.

1.3.1.5 Map edit and full screen

The last three buttons on the map's top right is a link to the Public Visual Console, a link to GIS Map Builder, intended for editing the map and a full-screen button to see the map in full-screen mode.

Gis maps default all controls2.png

1.3.2 Agent View

The Pandora FMS console agent view also comes with new GIS features. The main view now displays the agent location in terms pf longitude, latitude and altitude.

1.3.2.1 Historical GIS view

There is a new button on the top bar to display the agent's GIS view (if GIS is enabled).

This view displays the agent's current position on the default map. It contains a table that shows the history of the agent's previous positions and their route on the map.

Each position on the map is represented by a dot (except the current one which is represented by the agent's icon). It is possible to click on any of these dots in order to get position-related information. It is also possible to click on the agent's icon in order to display the agent's current information. The following information shows the way covered by the Pandora FMS agent for Android devices.

Pandroid GIS22.png

You are also able to display a table which contains all the agent's reported information, including a reverse geolocation system which was designed to display the agent's address including the street, city and country in which the Pandora FMS agent is located.

Pandroid GIS23.png

1.3.3 The Agent's GIS Setup

Among the agent's administration tabs, there is a new tag to manually set the agent's position. The 'agent manage' tab also has some parameters which affect the GIS features.

1.3.3.1 Ignoring GIS Data

On the 'agent manage' tab, there is a new switch called 'Ignore GIS data'. If this switch is activated, the server will ignore all positional information received from the agent and use the last valid values for it. This is useful in case an agent reports a wrong position or it gets its own fixed place.

Agent management icon ignore gis data2.png

1.3.3.2 Manual agent position

The 'GIS Data' view displays the default map on which it is possible to click on the agent in order to define the agent's new position. It is also possible to determine the position by using the input boxes below the map.



Pos manual.png



Template warning.png

Defining the agent's position will activate the 'Ignore GIS Data' option in order to avoid the agent's next positional information data package to reset the agent's position again. If this is not the desired performance, we recommend deactivating the 'Ignore GIS Data' switch before clicking on the 'Update' button.

 


1.4 Useful links

This is a collection of interesting links which are quite useful for implementing test environments and development with OpenLayers.

1.4.1 OpenLayers

1.4.2 OpenStreetMap

1.4.3 OS Geo

1.4.4 Geo Server

1.4.5 PostgreSQL

Go back to Pandora FMS documentation index