By default, IoT Monitoring uses public geographic databases to resolve external IP addresses to geolocations. You can instead use IoT custom geo mapping to map internal IP addresses to geolocations for your IoT applications. 

With custom geo mapping, you can monitor the performance of devices running in Virtual Private Clouds (VPCs) with internal addresses distributed across different geographies.

Methods to Map IP Addresses

You can map one IP address, a range of IP addresses, or multiple IP addresses with a subnet mask to one geolocation, giving you a wide range of control over how to map internal IP addresses to geographic locations.

Scope of Custom Geo Mapping

You can only use custom geo mapping in SaaS Controllers. You can provide one custom geo mapping for each app key. Each app key can include multiple applications, enabling them to use the custom geo mapping.

Geo Mapping File

The geo-mapping file is an XML file used to map IP addresses to geolocations. You upload this file to the Controller for your IoT application. 

File Specification

The geo-mapping file size is limited to 1 GB, but there is no limit to the number of mapped IP addresses.

Default Mapping

If you upload a custom geo-mapping file, IoT Monitoring will only resolve the IP addresses based on your mapped IP addresses and locations. Thus, if you are going to use a custom geo-mapping file, you should configure the default to cover the entire IP range. 

IP Addresses and Ranges

You can only specify IPv4 addresses in the custom geo-mapping file.

When using IP address ranges, you must list the addresses in ascending order. For example, if your geo-mapping file specifies the two ranges 1.1.1.1–2.2.2.2 and 2.2.2.2–3.3.3.3, you must list the first range before the second so that they are in ascending order.

Example Geo Mapping Files

The example geo-mapping files below show you the scope of mapping geolocations and provide a general use case for each.

The simplest configuration maps one IP address to one geolocation.

<mappings>
    <mapping>
        <ip-range from="192.168.123.0" to="192.168.123.0"/>
        <location country="United States" region="California" city="San Jose"/>
    </mapping>
    <default country="United States" region="California" city="San Francisco"/>
</mappings>
XML

It's more common for a range of IP addresses to represent one geolocation. You can use the range attribute to specify a range of IP addresses.

<mappings>
    <mapping>
        <ip-range from='192.168.1.1' to='192.168.1.255'/>
            <location country='USA' region='CA' city='Walnut Creek'/>
    </mapping>
    <default country='USA' region='NY' city='New York'/>
</mappings>
XML

If you have a limited number of IP addresses, you can maximize the network connections by using IP subnet masking to split one IP address into many.

<mappings>
    <mapping>
        <subnet from="192.168.1.1" mask="255.255.255.0"/>
        <location country="United States" region="California" city="San Francisco"/>
    </mapping>
    <default country='China' region='Zhejiang' city='Hangzhou'/>
</mappings>
XML

 

Geo Mapping File XML Schema

You can download the XML schema file custom-geo-mapping.xsd below to validate your geo-mapping XML file. 

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<xs:schema version="1.0" xmlns:xs="http://www.w3.org/2001/XMLSchema">
  <xs:element name="mappings" type="config"/>
  <xs:element name="ip-range" type="explicitIpAddressRange"/>
  <xs:element name="subnet" type="subnetIpAddressRange"/>
  <xs:complexType name="config">
    <xs:sequence>
      <xs:element name="mapping" type="mapping" minOccurs="0" maxOccurs="unbounded"/>
      <xs:element name="default" type="geoLocation" minOccurs="0" maxOccurs="1"/>
    </xs:sequence>
  </xs:complexType>
  <xs:complexType name="mapping">
    <xs:sequence>
      <xs:choice>
        <xs:element ref="ip-range"/>
        <xs:element ref="subnet"/>
      </xs:choice>
      <xs:element name="location" type="geoLocation" minOccurs="1"/>
    </xs:sequence>
  </xs:complexType>
  <xs:complexType name="geoLocation">
    <xs:attribute name="country" type="xs:string" use="required"/>
    <xs:attribute name="region" type="xs:string" use="required"/>
    <xs:attribute name="city" type="xs:string" use="required"/>
  </xs:complexType>
  <xs:complexType name="explicitIpAddressRange">
      <xs:attribute name="from" type="xs:string" use="required"/>
      <xs:attribute name="to" type="xs:string" use="required"/>
  </xs:complexType>
  <xs:complexType name="subnetIpAddressRange">
      <xs:attribute name="from" type="xs:string" use="required"/>
      <xs:attribute name="mask" type="xs:string" use="required"/>
  </xs:complexType>
</xs:schema>
XML

Upload Geo Mapping Files 

From your SaaS Controller, you can perform the following actions with your custom geo-mapping file:

Upload New Geo Mapping File

  1. Navigate to the Configuration > Custom GeoMap.

  2. From the Upload Custom GeoMap file dialog, click Choose File.
  3. Select a geo-mapping XML file.
  4. Click Upload.
  5. If the upload was successful, you should see the following confirmation.
    Successful File Upload
  6. If you see the following error message, see Troubleshooting the Geo Map File.
    Failed File Upload

After you have uploaded the geo-mapping file, it may take some time for IoT Monitoring to apply the new custom mapping to your applications.

Overwrite Existing Geo Map File

  1. Navigate to the Configuration > Custom GeoMap.

  2. From the Upload Custom GeoMap file dialog, click Overwrite Current Mapping.
  3. Select a geo-mapping XML file.
  4. Click Upload.
  5. If the upload was successful, you should see the following confirmation.
    Successful File Upload
  6. If you see the following error message, see Troubleshooting the Geo Map File.
    Failed File Upload

Reset Geo Map File

  1. Navigate to the Configuration > Custom GeoMap.

  2. From the Upload Custom GeoMap file dialog, click Reset to Default.
  3. From the Reset Confirmation dialog, click Reset.

View Custom Geo Locations

You can add the Geo widget to one or more of the available dashboards to view the geolocation information of your devices. The Geo widget will display geo locations resolved with the public geographic databases or a custom IP address mapping. To view the geolocations from the Device Dashboard:

  1. From your IoT application, navigate to Devices.
  2. Scroll down to the Geo widget.
  3. (Optional) Build a custom Geo widget. You can filter the devices by geodata such as city, region, or country.

In addition, you can filter data in the other widgets by geodata based on your geo-mapping file.

Troubleshooting the Geo Map File

Upload Issues

If you get an error message trying to upload the custom geo-mapping file, check the following:

  • XML validity: Use an XML validation tool to determine if your XML of your geo-mapping file is valid.
  • XML schema: Confirm that your custom geo-mapping file conforms to the XML schema.
  • Invalid IP addresses: Confirm your IP addresses are valid.
  • File size: Confirm that the custom geo-mapping file is less than 1 GB.

Incorrect Geo Mapping

If IP addresses are not being resolved to the correct geolocations, confirm that the IP addresses and geo-locations in your geo-mapping file are correct.