{"__v":1,"_id":"57f54e999daf6b220030ab57","category":{"__v":6,"_id":"5626d4fd3a4c6b0d00c454a5","pages":["5626d4fe3a4c6b0d00c454a7","5627d2eb80c9910d00134fd1","5627d302e2ce610d004e3f57","5627d3c2e2ce610d004e3f5b","5627d44c66c62617009d1864","5631445924014b0d00bd9a69"],"project":"5626d4fc3a4c6b0d00c454a1","version":"5626d4fc3a4c6b0d00c454a4","sync":{"url":"","isSync":false},"reference":false,"createdAt":"2015-10-20T23:57:49.447Z","from_sync":false,"order":0,"slug":"opendns-network-devices-api","title":"Umbrella Network Devices API"},"parentDoc":null,"project":"5626d4fc3a4c6b0d00c454a1","user":"560b40145148ba0d009bd0b5","version":{"__v":2,"_id":"5626d4fc3a4c6b0d00c454a4","project":"5626d4fc3a4c6b0d00c454a1","createdAt":"2015-10-20T23:57:48.904Z","releaseDate":"2015-10-20T23:57:48.904Z","categories":["5626d4fd3a4c6b0d00c454a5","57f53fa9485e6e2b005b2f2f"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"","version_clean":"1.0.0","version":"1.0"},"updates":[],"next":{"pages":[],"description":""},"createdAt":"2016-10-05T19:03:53.107Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"settings":"","results":{"codes":[]},"auth":"required","params":[],"url":""},"isReference":false,"order":9,"body":"After a successful registration, the device will receive a Device ID. This should be added to the DNS packet to create an EDNS0 packet. The format of EDNS0 packets is specified by [RFC2671](https://tools.ietf.org/html/rfc2671), with some specifics below. \n\nNote that the only piece of information that is required on the device itself is the Device ID. If desired, the actual registration can be done by a separate configuration utility using the device’s details (model, MAC address, label, and serial number). The resulting Device ID can then be passed to the device for future use. If the device itself is doing the registration, then each device will also need the API key and API token. The API key can be set for all devices, but the API token will need to be obtained from the specific customer dashboard and transferred to each device in some way.\n\n### OPT RR description ###\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Field\",\n    \"h-1\": \"Type\",\n    \"h-2\": \"Description\",\n    \"0-0\": \"Name\",\n    \"0-1\": \"Domain Name\",\n    \"0-2\": \"Empty (root domain, 0)\",\n    \"1-0\": \"Type\",\n    \"1-1\": \"u_int16\",\n    \"1-2\": \"OPT (41)\",\n    \"2-2\": \"Sender’s UDP payload size (default 512; Umbrella supports up to 4096)\",\n    \"2-1\": \"u_int16\",\n    \"2-0\": \"Class\",\n    \"3-0\": \"TTL\",\n    \"3-1\": \"u_int32\",\n    \"3-2\": \"Extended RCODE and flags (default 0)\",\n    \"4-0\": \"RDLEN\",\n    \"4-1\": \"u_int16\",\n    \"4-2\": \"Combined size in bytes of RDATA options\",\n    \"5-2\": \"One or two RDATA options, formatted in {attribute,value} pairs\",\n    \"5-1\": \"octet stream\",\n    \"5-0\": \"RDATA\"\n  },\n  \"cols\": 3,\n  \"rows\": 6\n}\n[/block]\n### RDATA description ###\n\nTwo RDATA options can be sent. The first (option code 0x6942) identifies the network device and is mandatory. The second (option code 0x4F44) identifies the local IP address originating the DNS query. RDATA option code 0x6942 can be sent without 0x4F44, but 0x4F44 should not be sent without 0x6942.\nPolicy can be applied to the network device RDATA, whereas the local IP address is for visibility and reporting only.\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Field\",\n    \"h-1\": \"Type\",\n    \"h-2\": \"Description\",\n    \"0-0\": \"OPTION-CODE\",\n    \"1-0\": \"OPTION-LENGTH\",\n    \"2-0\": \"OPTION-DATA\",\n    \"0-1\": \"u_int16\",\n    \"1-1\": \"u_int16\",\n    \"2-1\": \"Various\",\n    \"0-2\": \"Option Code (Umbrella accepts ‘0x6942’, or 26946 in decimal)\",\n    \"1-2\": \"Size in octets of OPTION-DATA (15 bytes)\",\n    \"2-2\": \"Data (“OpenDNS” + 8 octets of Device ID)\"\n  },\n  \"cols\": 3,\n  \"rows\": 3\n}\n[/block]\nIf the Device ID returned from the Register call is “0123456789abcdef”, RDATA would consist of the following array of bytes:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"[ 0x69, 0x42, 0x00, 0x0F, 0x4F, 0x70, 0x65, 0x6E, 0x44, 0x4E, 0x53, 0x01, 0x23, 0x45, 0x67, 0x89, 0xAB, 0xCD, 0xEF ]\",\n      \"language\": \"text\"\n    }\n  ]\n}\n[/block]\n###  Remote IP Address RDATA (optional) ####\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Field\",\n    \"h-1\": \"Type\",\n    \"h-2\": \"Description\",\n    \"0-0\": \"OPTION-CODE\",\n    \"0-1\": \"u_int16\",\n    \"0-2\": \"ODNS_AD (0x4F44)\",\n    \"1-0\": \"OPTION-LENGTH\",\n    \"1-1\": \"u_int16\",\n    \"1-2\": \"Size in octets of OPTION-DATA\",\n    \"2-0\": \"OPTION-DATA\",\n    \"2-1\": \"Octet stream\",\n    \"2-2\": \"As per below\"\n  },\n  \"cols\": 3,\n  \"rows\": 3\n}\n[/block]\nRemote IP address OPTION-DATA:\n\nInitial header (6B) is composed of a 4B \"magic value\", a 1B VERSION field and a 1B FLAGS field.\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/724af9a-Screen_Shot_2017-01-09_at_12.45.21_PM.png\",\n        \"Screen Shot 2017-01-09 at 12.45.21 PM.png\",\n        1224,\n        274,\n        \"#1e1615\"\n      ]\n    }\n  ]\n}\n[/block]\n* MAGIC is a value used to help distinguish an EDNS0 message using Umbrella’s OPTION-CODE from a message from another source that happens to use that same OPTION-CODE. The value of this field should always be 0x4F444E53 (\"ODNS\").\n* VERSION should be 0x00\n* FLAGS should be 0x00\nAfter the header each additional field will start with a 1B field type (bit values) followed by a fixed-length value.\n\nType\tLength\tContents\tComments/Restrictions\n0x08\t4\tOrganization ID\tRequired.\n0x10\t4\tRemote IPv4\tThe \"internal\" site address that's invisible to the DNS resolver\n0x20\t16\tRemote IPv6\tThe \"internal\" site address that's usually invisible to the DNS resolver\n\nOrganization ID and remote IP are both to be given in network-endian byte order.\n\nFor example, if organization ID is 012345678, remote IPv4 is 192.168.1.55, and remote IPv6 is not sent, the OPTION-DATA would consist of the following array of bytes:\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/a51fee7-magic.png\",\n        \"magic.png\",\n        1566,\n        160,\n        \"#dbdbd0\"\n      ]\n    }\n  ]\n}\n[/block]\n---\n[Registration API Endpoint](https://docs.umbrella.com/developer/networkdevices-api/registration-api-endpoint2/) < **Identifying DNS Traffic**","excerpt":"","slug":"identifying-dns-traffic2","type":"basic","title":"Identifying DNS traffic"}

Identifying DNS traffic


After a successful registration, the device will receive a Device ID. This should be added to the DNS packet to create an EDNS0 packet. The format of EDNS0 packets is specified by [RFC2671](https://tools.ietf.org/html/rfc2671), with some specifics below. Note that the only piece of information that is required on the device itself is the Device ID. If desired, the actual registration can be done by a separate configuration utility using the device’s details (model, MAC address, label, and serial number). The resulting Device ID can then be passed to the device for future use. If the device itself is doing the registration, then each device will also need the API key and API token. The API key can be set for all devices, but the API token will need to be obtained from the specific customer dashboard and transferred to each device in some way. ### OPT RR description ### [block:parameters] { "data": { "h-0": "Field", "h-1": "Type", "h-2": "Description", "0-0": "Name", "0-1": "Domain Name", "0-2": "Empty (root domain, 0)", "1-0": "Type", "1-1": "u_int16", "1-2": "OPT (41)", "2-2": "Sender’s UDP payload size (default 512; Umbrella supports up to 4096)", "2-1": "u_int16", "2-0": "Class", "3-0": "TTL", "3-1": "u_int32", "3-2": "Extended RCODE and flags (default 0)", "4-0": "RDLEN", "4-1": "u_int16", "4-2": "Combined size in bytes of RDATA options", "5-2": "One or two RDATA options, formatted in {attribute,value} pairs", "5-1": "octet stream", "5-0": "RDATA" }, "cols": 3, "rows": 6 } [/block] ### RDATA description ### Two RDATA options can be sent. The first (option code 0x6942) identifies the network device and is mandatory. The second (option code 0x4F44) identifies the local IP address originating the DNS query. RDATA option code 0x6942 can be sent without 0x4F44, but 0x4F44 should not be sent without 0x6942. Policy can be applied to the network device RDATA, whereas the local IP address is for visibility and reporting only. [block:parameters] { "data": { "h-0": "Field", "h-1": "Type", "h-2": "Description", "0-0": "OPTION-CODE", "1-0": "OPTION-LENGTH", "2-0": "OPTION-DATA", "0-1": "u_int16", "1-1": "u_int16", "2-1": "Various", "0-2": "Option Code (Umbrella accepts ‘0x6942’, or 26946 in decimal)", "1-2": "Size in octets of OPTION-DATA (15 bytes)", "2-2": "Data (“OpenDNS” + 8 octets of Device ID)" }, "cols": 3, "rows": 3 } [/block] If the Device ID returned from the Register call is “0123456789abcdef”, RDATA would consist of the following array of bytes: [block:code] { "codes": [ { "code": "[ 0x69, 0x42, 0x00, 0x0F, 0x4F, 0x70, 0x65, 0x6E, 0x44, 0x4E, 0x53, 0x01, 0x23, 0x45, 0x67, 0x89, 0xAB, 0xCD, 0xEF ]", "language": "text" } ] } [/block] ### Remote IP Address RDATA (optional) #### [block:parameters] { "data": { "h-0": "Field", "h-1": "Type", "h-2": "Description", "0-0": "OPTION-CODE", "0-1": "u_int16", "0-2": "ODNS_AD (0x4F44)", "1-0": "OPTION-LENGTH", "1-1": "u_int16", "1-2": "Size in octets of OPTION-DATA", "2-0": "OPTION-DATA", "2-1": "Octet stream", "2-2": "As per below" }, "cols": 3, "rows": 3 } [/block] Remote IP address OPTION-DATA: Initial header (6B) is composed of a 4B "magic value", a 1B VERSION field and a 1B FLAGS field. [block:image] { "images": [ { "image": [ "https://files.readme.io/724af9a-Screen_Shot_2017-01-09_at_12.45.21_PM.png", "Screen Shot 2017-01-09 at 12.45.21 PM.png", 1224, 274, "#1e1615" ] } ] } [/block] * MAGIC is a value used to help distinguish an EDNS0 message using Umbrella’s OPTION-CODE from a message from another source that happens to use that same OPTION-CODE. The value of this field should always be 0x4F444E53 ("ODNS"). * VERSION should be 0x00 * FLAGS should be 0x00 After the header each additional field will start with a 1B field type (bit values) followed by a fixed-length value. Type Length Contents Comments/Restrictions 0x08 4 Organization ID Required. 0x10 4 Remote IPv4 The "internal" site address that's invisible to the DNS resolver 0x20 16 Remote IPv6 The "internal" site address that's usually invisible to the DNS resolver Organization ID and remote IP are both to be given in network-endian byte order. For example, if organization ID is 012345678, remote IPv4 is 192.168.1.55, and remote IPv6 is not sent, the OPTION-DATA would consist of the following array of bytes: [block:image] { "images": [ { "image": [ "https://files.readme.io/a51fee7-magic.png", "magic.png", 1566, 160, "#dbdbd0" ] } ] } [/block] --- [Registration API Endpoint](https://docs.umbrella.com/developer/networkdevices-api/registration-api-endpoint2/) < **Identifying DNS Traffic**