Extracts location information from IP addresses by using 3rd-party databases. This command supports IPv4 and IPv6.
The IP address that you specify in the
ip-address-fieldname argument, is looked up in the database. Fields from that database that contain location information are added to each event. The setting used for the
allfields argument determines which fields are added to the events.
Because all the information might not be available for each IP address, an event can have empty field values.
For IP addresses which do not have a location, such as internal addresses, no fields are added.
iplocation [prefix=<string>] [allfields=<bool>] [lang=<string>] <ip-address-fieldname>
- Syntax: <field>
- Description: Specify an IP address field, such as
- Syntax: allfields=<bool>
- Description: Specifies whether to add all of the fields from the database to the events. If set to
true, adds the fields City, Continent, Country, lat (latitude), lon (longitude), MetroCode, Region, and Timezone.
- Default: false. Only the City, Country, lat, lon, and Region fields are added to the events.
- Syntax: lang=<string>
- Description: Render the resulting strings in different languages. For example, use "lang=es" for Spanish. The set of languages depends on the geoip database that is used. To specify more than one language, separate them with a comma. This also indicates the priority in descending order. Specify "lang=code" to return the fields as two letter ISO abbreviations.
- Syntax: prefix=<string>
- Description: Specify a string to prefix the field name. With this argument you can add a prefix to the added field names to avoid name collisions with existing fields. For example, if you specify
prefix=iploc_the field names that are added to the events become
iploc_lat, and so forth.
- Default: NULL/empty string
The Splunk software ships with a copy of the
GeoLite2-City.mmdb database file. This file is located in the
Updating the MMDB file
You can replace the version of the .mmdb file that ships with the Splunk software with a copy of the paid version of the file or with a monthly update of the free version of the file.
- From http://dev.maxmind.com/geoip/geoip2/geolite2/, download the binary gzipped version of the GeoLite2 City database file.
- Copy the file to the search head on your Splunk Enterprise instance.
- Expand the GZ file.
- Copy the GeoLite2-City.mmdb file to the
$SPLUNK_HOME/share/directory to overwrite the file there.
Impact of upgrading Splunk software
When you upgrade your Splunk platform, the
GeoLite2-City.mmdb file in the
share directory is replaced by the version of the file that ships with the Splunk software. One option is to store the MMDB file in a different path.
Storing the MMDB file in a different path
If you prefer to update the
GeoLite2-City.mmdb file yourself, for example if you use a paid version of the file, you can store the MMDB file in a different path. The path that is used by the Splunk software to access the file must be updated.
- Only users with file system access, such as system administrators, can specify a different path to the MMDB file in the
- Review the steps in How to edit a configuration file in the Admin Manual.
- You can have configuration files with the same name in your default, local, and app directories. Read Where you can place (or find) your modified configuration files in the Admin Manual.
Never change or copy the configuration files in the default directory. The files in the default directory must remain intact and in their original location. Make the changes in the local directory.
If you are using Splunk Cloud and want to edit the configuration file, file a Support ticket.
- Open the local
limits.conffile for the Search app. For example,
- Add the
- Add the
db_pathsetting and specify the absolute path to the
db_pathsetting does not support standard Splunk environment variables such as
db_path = /Applications/Splunk/mmdb/GeoLite2-City.mmdbspecifies a new directory called
- Ensure a copy of the MMDB file is stored in the
Storing the MMDB file with a different name
Alternatively, you can add the updated MMDB to the
share directory using a different name and then specify that name in the
db_path setting. For example:
db_path = /Applications/Splunk/share/GeoLite2-City_paid.mmdb.
The MMDB file and distributed deployments
iplocation command is a distributable streaming command, which means that it can be processed on the indexers. The
share directory is not part of the knowledge bundle. If you update the MMDB file in the
share directory, the updated file is not automatically sent to the indexers in a distributed deployment. To add the MMDB file to the indexers, use the tools that you typically use to push files to the indexers.
Add location information to web access events. By default, the
iplocation command adds the
Region fields to the results.
sourcetype=access_* | iplocation clientip
Search for client errors in web access events, returning only the first 20 results. Add location information and return a table with the IP address, City, and Country for each client error.
sourcetype=access_* status>=400 | head 20 | iplocation clientip | table clientip, status, City, Country
Prefix the fields added by the
iplocation command with "iploc_". Add all of the fields in the
GeoLite2-City.mmdb database file to the results.
sourcetype = access_* | iplocation prefix=iploc_ allfields=true clientip | fields iploc_*
Have questions? Visit Splunk Answers and see what questions and answers the Splunk community has using the iplocation command.
This documentation applies to the following versions of Splunk Cloud™: 7.0.0, 6.5.1, 6.5.1612, 6.6.0, 6.6.1, 6.6.3, 6.5.0