Using the Additional Metadata filter

This filter passes along metadata as TXT records in the additional section of the DNS response.

Typically, NS1 users associate metadata with DNS answers and apply Filter Chain configurations to implement traffic steering policies based on the answer metadata. However, using the Additional Metadata filter and metadata fields, you can include additional information (key-value pairs) to DNS answers and apply the filter so that this metadata is included in the DNS response as TXT records. This type of metadata is not used for traffic steering purposes — instead, it can be useful for system troubleshooting, organization, and more.

Adding the filter to a record via API

The example POST command below edits a record by configuring two answers (both of which require additional metadata), then applying the Additional Metadata filter to the record. The meta section specifies the additional_metadata key-value pairs "foo": "bar" and "baz": "blarg" for answer1.test.com and "red": "blue" for answer2.test.com. The filters section specifies the additional_metadata filter, which is applied to the entire record.

curl -X POST -H 'X-NSONE-Key: $API_KEY' \
https://api.nsone.net/v1/zones/example.com/test.example.com/CNAME \
-d '{
  "answers": [
    {
      "answer": [
        "answer1.test.com"
      ],
      "meta": {
        "additional_metadata": [
          {
            "foo": "bar",
            "baz": "blarg"
          }
        ]
      }
    },
    {
      "answer": [
        "answer2.test.com"
      ],
      "meta": {
        "additional_metadata": [
          {
            "red": "blue"
          }
        ]
      }
    }
  ],
  "filters": [
    {
      "filter": "additional_metadata",
      "config": {}
    }
  ]
}'

The resulting DNS response based on the record above should match this:

$ dig @dns1.p01.nsone.net test.example.com

; <<>> DiG 9.10.6 <<>> @dns1.p01.nsone.net test.example.com
; (1 server found)
;; global options: +cmd
;; Got answer:
;; ->>HEADER<<- opcode: QUERY, status: NOERROR, id: 1750
;; flags: qr aa rd; QUERY: 1, ANSWER: 2, AUTHORITY: 0, ADDITIONAL: 5
;; WARNING: recursion requested but not available

;; OPT PSEUDOSECTION:
; EDNS: version: 0, flags:; udp: 1232
;; QUESTION SECTION:
;test.example.com.		IN	CNAME

;; ANSWER SECTION:
test.example.com.	3600	IN	CNAME	answer1.test.com.
test.example.com.	3600	IN	CNAME	answer2.test.com.

;; ADDITIONAL SECTION:
0.meta._ns1.		0	IN	TXT	"baz=blarg"
0.meta._ns1.		0	IN	TXT	"foo=bar"
1.meta._ns1.		0	IN	TXT	"red=blue"

;; Query time: 13 msec
;; SERVER: 198.51.44.1#53(198.51.44.1)
;; WHEN: Thu Sep 16 15:54:04 GMT 2021
;; MSG SIZE  rcvd: 189

Note the ADDITIONAL section includes a list of TXT records corresponding to the additional metadata key-value pairs applied to the DNS answers. Note the order of the TXT records corresponds to the order of eligible answers after being processed by the NS1 Filter Chain. For example, the first two TXT records listed correspond to the first DNS answer (answer1.test.com) and contain the 0.meta._ns1. domain name. The third TXT record corresponds to the second DNS answer (answer2.test.com) and contains the 1.meta._ns1 postfix. This postfix is applied to avoid interoperability issues. As such, the Additional Metadata filter must be placed at the end of the Filter Chain configuration to avoid breaking the association between the order of the TXT records and their corresponding answers.

Pulsar customers who have configured decisions over HTTP can specify additional metadata records and apply the filter to return the metadata in the JSON response under the meta section. For example (replacing $API_KEY accordingly):

$ curl -s -H "X-NSONE-Key: $API_KEY" -H "X-Forwarded-For:192.0.2.1" 'https://rt.ns1p.net/v1/decision?name=test.example.com&type=CNAME' | jq .
{
  "resources": [
    {
      "label": "answer1.test.com",
      "meta": {
        "baz": "blarg",
        "foo": "bar"
      }
    },
    {
      "label": "answer2.test.com",
      "meta": {
        "red": "blue"
      }
    }
  ],
  "ttl": 3600
}

Adding the filter to a record via the Portal

1. Navigate to the DNS page, then click Zones in the sub-navigation. A list of your records opens.
   
2. Select the record that you want to modify from the list of Zones:
   1. The Records tab for the zone opens, displaying query statistics and the list of records.
   2. Click the Records button to the right of the record to open the list of answers for that record.
      
3. Create or edit the Filter Chain to include the Additional Metadata filter.
   IMPORTANT
   Place the Additional Metadata filter at the end of the Filter Chain. If you do not do this, the order of the TXT records that are returned might not match the order of the answers in the DNS response.
   • If you have not yet created a Filter Chain, click the Create Filter Chain button.
   • If you are updating your Filter Chain, click the Edit Filter Chain button.
4. Add the additional metadata to the answer:
   1. Click the additional_metadata setting for the answer.
   2. Complete the Add additional metadata field.
   3. Click the Ok button.
5. Click Save Record to ensure that the filter is applied to the answers you updated.