(c) by SPP Handelsges.m.b.H. 2011 - All rights reserved - http://www.spp.

at/
Author: Siegfried Puchbauer
Feedback: splunk@spp.at
Google Maps for Splunk
======================
=== Documentation ===
Google Maps for Splunk allows you to easily plot any Splunk search results with
location information on a map.
== Professional Services and Support ==
This add-on has been developed by SPP (http://www.spp.at/), a Splunk Partner loc
ated in Vienna, Austria. If you require
support on getting solutions using Google Maps up and running, please contact sp
lunk@spp.at.
== Licence and Terms of Use ==
This app is licensed under the terms of the Creative Commons license and provide
d as-is without any warranty. It uses
third-party components that are licensed differently:
* Google Maps: http://code.google.com/apis/maps/terms.html
* MAXMIND GeoLite City database see http://geolite.maxmind.com/download/geoip/da
tabase/LICENSE.txt
* pygeoip see http://www.gnu.org/licenses/lgpl.html
== Using the Google Maps Search View ==
The App provides a flashtimeline-like view which allows you to simply enter a se
arch and display the results on the map.
In order to plot search results on the map they have to have some kind of locati
on information attached. This location
information has to be included in a field with the name _geo and has to be forma
tted as "<latitude>,<longitude>".
Latitude and Longitude have to be expressed as floating point numbers. As an exa
mple "47.11,0.815" would be a valid _geo
value. Other notations (like 47N 12',...) are not supported.
In most cases you don't have to build the _geo field yourself. The built-in geol
ocation lookup methods (geoip command
and geo lookup) are emitting this field by default. In cases where you already h
ave geolocation information in your
results, you can leverage the geonormalize command to build the _geo value for y
ou.
= Geolocation Lookup for IP addresses =
Performing Gelocation Lookup on external IP addresses
External IP address values can be easily translated to locations by using the bu
ilt-in geoip command or the geo lookup.
Examples:
Perform a geolocation lookup for values of the clientip field in access_combined
events:

sourcetype=access_combined | geoip clientip

Same as the previous example, but also perform DNS lookups in case when the valu
e of the clientip field is a hostname
and not an IP:
sourcetype=access_combined | geoip clientip resolve_hostnames=true
Same as the first example, but using the geo lookup instead of the command
sourcetype=access_combined | lookup geo ip as clientip
Performing Gelocation Lookup on internal IP addresses
In order to perform geolocation lookup on private IP address ranges you have to
implement a lookup yourself. Splunk
provides multiple ways to achieve this:
* Creating a CSV with the IP subnets and their locations and leveraging the CIDR
match_type
* Creating a scripted lookup which queries the geolocation information from an e
xisting asset management system.
Performing combined Geolocation Lookup on IP adresses
Lookups for external and interal IP addresses can be easily combined.
Examples:
sourcetype=access_combined clientip=*
| lookup geoip_internal ip as clientip
| geoip clientip
sourcetype=access_combined clientip=*
| lookup example_geo_internal ip as clientip
| lookup geo ip as clientip OUTPUTNEW _geo geo_info
= Use existing geolocation information available in search results =
It's common case that events already contain geo information.
The geonormalize command
The geonormalize command can detect existing fields containing the geoinformatio
n and normalizes them for the GoogleMaps
module. For doing this the command searches for field pairs (a latitude field an
d a longitude field) matching a name
scheme. The values of those fields are then merged and emitted as the _geo field
. The following name schemes are
supported:
* @*lat/*lng@
* @*lat/*lon@
* @*latitude/*longitude@
So for example when an event has the fields @gps_lat=47.11@ and @gps_lon=0.815@
the geonormalize command will detect
those fields and emit the _geo field with the value @47.11,0.815@.

Example:
sourcetype=device_tracking device_id=A47C08B13 | geonormalize

Manual building the _geo field

If you don't want to use the geonormalize command or if the location fields do n
ot match any naming scheme, you can
manually build the _geo field.
Example:
eventtype=phone_activation | eval _geo=phone_loc_1+","+phone_loc_2
(Assuming that phone_loc_1 contains the latitude and phone_loc_2 contains the lo
ngitude)
== Creating Dashboards with Google Maps ==
This add-on provides a Splunk UI module called @GoogleMaps@. This module can onl
y be using in *advanced XML* dashboards.
The usage of the module is quite similar to any built-in module in Splunk which
displays results (like
SimpleResultsTable, EventsViewer, etc.).
Example:
<module name="HiddenSearch" layoutPanel="panel_row1_col1" autoRun="true">
<param name="search">sourcetype=access_combined | geoip clientip</param>
<param name="earliest">-24h@h</param>
<module name="GoogleMaps">
<param name="height">500px</param>
<param name="mapType">roadmap</param>
<param name="scrollwheel">off</param>
</module>
</module>
All available options to the module can be found at the module reference at your
Splunk instance at
http://locahost:8000/modules#Splunk.Module.GoogleMaps