Additional metadata filter

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 metadata fields and filter, you can apply discretionary 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.

The example POST command below edits a record by applying two answers, both with additional metadata applied and applies 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 “filter” section specifies the additional_metadata filter which is applied to the entire record.

curl -X POST -H 'X-NSONE-Key: $APIKEY' -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" : {}}]}' https://api.nsone.net/v1/zones/example.com/test.example.com/CNAME

The example below is the resulting DNS query based on the record above.

$ dig @localhost -p 5302 test.example.com CNAME

; <<>> DiG 9.12.3 <<>> @localhost -p 5302 rec.mishatest.com CNAME
; (2 servers found)
;; global options: +cmd
;; Got answer:
;; ->>HEADER<<- opcode: QUERY, status: NOERROR, id: 31620
;; 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: 123
;; 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: 3 msec
;; SERVER: 127.0.0.1#5302(127.0.0.1)
;; WHEN: Tue Jan 26 15:31:18 EST 2021
;; MSG SIZE  rcvd: 194

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. postfix. 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:

$ curl -H "X-NSONE-Key: $APIKEY" -H "X-Forwarded-For:192.0.2.1" 'https://rt.ns1p.net/v1/decision?name=test.example.com&type=CNAME' | jq .
% Total % Received % Xferd Average Speed Time Time Time Current
Dload Upload Total Spent Left Speed
100 161 100 161 0 0 18142 0 --:--:-- --:--:-- --:--:-- 20125
{
"resources": [
{
"label": "answer1.test.com",
"meta": {
"baz": "blarg",
"foo": "bar"
}
},
{
"label": "answer2.test.com",
"meta": {
"red": "blue"
}
}
],
"ttl": 3600
}