Creating and uploading a route map

You can upload a custom route map file for granular control over traffic steering decisions. Route maps are custom JSON files that map IP addresses (CIDR ranges) to routing targets corresponding to answers within DNS records.

Step 1 - Prepare the route map file

Route maps are plain-text JSON files created locally before uploading them to the NS1 platform. Note that you must use the .json file extension when you save your files.

The route map file uses the following format. Version, networks, and labels are required:

{
  "meta": {
    "version": 1
  },
  "map": [
    {
      "networks": [],
      "labels": []
    }
  ]
}
Field Data type Description
meta object Metadata
version integer (Required) Version of the exchange data format; determines the semantics of the remainder of the exchange.
Note: Version 1 is current.
map array of objects Each member object declares a segment of the map as defined by the list of network addresses contained within.
networks array of strings (Required) IPv4 and/or IPv6 addresses in CIDR format; a single network definition can include both v4 and v6 addresses.
labels array of strings (Required) Array of labels associated with the networks. These are arbitrary strings used to associate DNS answers with map segments.
Note: The order in which you list the labels is important, as it determines the order in which the answers are emitted. For example, a list ["b", "c", "a"] emits DNS answers for "b" first, then "c", and then "a".
Sample route map

The following map defines three networks. The target labels hkg and sin are applied to the first group of networks (192.168.10.0/24 to 192.168.60.0/24). Using multiple target labels allows you to apply route maps more broadly; in this example, the first group of networks applies to both Hong Kong and Singapore geographical regions. The target label nrt is applied to the second group of networks (192.168.132.0/24 to 192.168.144.0/24).

{
  "meta": {
    "version": 1
  },
  "map": [
    {
      "networks": [
        "192.168.10.0/24",
        "192.168.20.0/24",
        "192.168.40.0/24",
        "192.168.50.0/24",
        "192.168.60.0/24"
      ],
      "labels": ["hkg", "sin"]
    },
    {
      "networks": [
        "192.168.132.0/24",
        "192.168.133.0/24",
        "192.168.135.0/24",
        "192.168.144.0/20"
      ],
      "labels": ["nrt"]
    },
    {
      "networks": [
        "172.16.5.0/24",
        "172.16.1.0/24",
        "192.168.111.0/24",
        "fd0d:82a7:be8b:ae00::/56",
        "fde2:d85e:f372:7408::/64"
      ],
      "labels": ["syd"]
    }
  ]
}

In this example, for the first group of networks, the target label hkg is referenced first, as it appears first in the map file. If there are no corresponding answers that match the hkg metadata, then the next label (sin) is referenced.

Step 2 - Upload the route map

Follow the instructions below to upload a route map file via the IBM® NS1 Connect® portal or API.

Upload via the portal
  1. In the portal, navigate to the Pulsar page in the main navigation.
  2. Click the Route maps tab.
  3. Click Add route map.
  4. Enter a name for the route map.
  5. Click Browse and select to the route map file.
  6. Click Upload.
Note: It may take a few minutes for the route map file to be processed.
Upload via API

If using the API, you must run two API requests. The first request creates the route map metadata in preparation for the upload. The response contains critical information you'll need for the second request which uploads the route map file to the IBM NS1 Connect® platform.

Note: You need a valid API key created within the IBM NS1 Connect® portal to authenticate API requests.

First, use the GET request below to create the route map metadata, replacing <name> with a name for the route map.

curl -X GET -H "X-NSONE-Key: $NSONE_API_KEY" https://api.nsone.net/v1/pulsar/routemaps/create?name=<name>

Example response:

{
  "customer": 0,
  "status": "uploading",
  "name": "example",
  "created": 0,
  "url": "https://s3.amazonaws.com/pulsar-routemap-uploads/example.json?...",
  "mapid": 0,
  "modified": 0
}
Attention: Record the URL provided in the response (https://s3.amazonaws.com/pulsar-routemap-uploads/...) as you need this to complete the next step.

Second, use the following PUT request to upload the route map file, replacing <fileSize> with the size of the route map file, <filePath> with the route map file path, and <aws_url> with the unique URL provided in response to the previous request.

curl -X PUT -L -H "Content-Length: <fileSize>" -H "Client-Encoding: UTF-8" -T "<filePath>" "<aws_url>"

Next steps

Configure a Filter Chain within the relevant DNS record(s) using the Route Map filter to activate the configuration.