Creating & uploading a route map – NS1 Help Center

Pulsar route maps are custom JSON files that allow users to define a mapping of source IP addresses to routing targets. You can use either the NS1 portal or the API to upload route maps.

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 to the NS1 platform.

You can upload route map files via the NS1 portal or via API.

To upload a route map via the NS1 portal:

Log in to the Managed DNS portal via https://my.nsone.net.
Click Pulsar in the top navigation bar.
Click Route Maps from the sub-navigation.
Upload a route map:
1. Click the Add Route Map button.
  
  The Upload New Map dialog opens.
2. Specify a name for the route map.
3. Click Browse and navigate to the route map you created.
4. Click the Upload button.

The file uploads to NS1.

NOTE

The file may require a few minutes to upload and process.

To upload a route map via API:

If you are using the NS1 API, you must execute two API commands to first create the route map metadata in the NS1 platform, and then a second command uploads the route map file to the NS1 platform. Data in the response to the first command is essential to the second.

Execute the following command to create the route map file metadata:
```
curl -X GET -H "X-NSONE-Key: $API_KEY" https://api.nsone.net/v1/pulsar/routemaps/create?name={name
```
where {name} (string) is the name of the route map you are creating (for example, "West Coast").

Example response:
```
{
  "customer": 0,
  "status": "uploading",
  "name": "example",
  "created": 0,
  "url": "https://s3.amazonaws.com/pulsar-routemap-uploads/example.json?...",
  "mapid": 0,
  "modified": 0
}
```
Note
IMPORTANT NOTE:
Note and record the URL provided in the response to the command above. This is the URL to which you must upload the route map in the next step.
Execute the following command to upload the route map file to the URL generated in the response to the command in the previous step.
```
curl -X PUT -L -H "Content-Length: {file_size}" -H "Client-Encoding: UTF-8" -T "{file_path}" "{aws_url}"
```
Where {file_size} is the size of the route map file, {file_path} is the path of the route map file, and {aws_url} is the unique URL generated in the response to the previous GET command (see previous step for details).

Next steps

Apply the route map filter to records and use the NS1 Filter Chain to route traffic accordingly.

Articles in this section