The OpenDNS Network Devices API Developer Hub

Welcome to the OpenDNS Network Devices API developer hub. You'll find comprehensive guides and documentation to help you start working with OpenDNS Network Devices API as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    

Identifying DNS traffic

After successfully registering, the device receives 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, with some specifics below.

The only information that is required on the device is the Device ID. The registration can be done through 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 is doing the registration, each device also needs the API key and API token. The API key can be set for all devices, but the API token needs to be obtained from the specific customer dashboard and transferred to each device.

OPT RR Description

Field
Type
Description

Name

Domain Name

Empty (root domain, 0)

Type

u_int16

OPT (41)

Class

u_int16

Sender’s UDP payload size (default 512; Umbrella supports up to 4096)

TTL

u_int32

Extended RCODE and flags (default 0)

RDLEN

u_int16

Combined size in bytes of RDATA options

RDATA

octet stream

One or two RDATA options, formatted in {attribute,value} pairs

RDATA dDescription

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.

Field
Type
Description

OPTION-CODE

u_int16

Option Code (Umbrella accepts ‘0x6942’, or 26946 in decimal)

OPTION-LENGTH

u_int16

Size in octets of OPTION-DATA (15 bytes)

OPTION-DATA

Various

Data (“OpenDNS” + 8 octets of Device ID)

If the Device ID returned from the Register call is “0123456789abcdef”, RDATA would consist of the following array of bytes:

[ 0x69, 0x42, 0x00, 0x0F, 0x4F, 0x70, 0x65, 0x6E, 0x44, 0x4E, 0x53, 0x01, 0x23, 0x45, 0x67, 0x89, 0xAB, 0xCD, 0xEF ]

Remote IP Address RDATA (optional)

Field
Type
Description

OPTION-CODE

u_int16

ODNS_AD (0x4F44)

OPTION-LENGTH

u_int16

Size in octets of OPTION-DATA

OPTION-DATA

Octet stream

As per below

Remote IP address OPTION-DATA:

Initial header (6B) is composed of a 4B "magic value", a 1B VERSION field and a 1B FLAGS field.

  • 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:

0x4F, 0x44, 0x4E, 0x53

0x01

0x00

0x00, 0x08

0x00, 0xBC, 0x61, 0x4E

0x00, 0x10

0xC0, 0xA8, 0x01, 0x37

0x00, 0x40

0x01, 0x23, 0x45, 0x67, 0x89, 0xAB, 0xCD, 0xEF

Magic (ODNS)

Version

Flags

Type

Organization ID (012345678)

Type

Remote IPV4 (192.168.1.55)

Type

Device ID (0123456789abcdef)

The same option containing the IPv6 address FE80::0202:B3FF:fe1e:8329 would consist of the following array of bytes:

0x4F, 0x44, 0x4E, 0x53

0x01

0x00

0x00, 0x08

0x00, 0xBC, 0x61, 0x4E

0x00, 0x20

0xFE, 0x80, 0x00, 0x00,
0x00, 0x00,
0x00, 0x00,
0x02, 0x02,
0xB3, 0xFF,
0xFE, 0x1E,
0x83, 0x29

0x00, 0x40

0x01, 0x23, 0x45, 0x67, 0x89, 0xAB, 0xCD, 0xEF

Magic (ODNS)

Version

Flags

Type

Organization ID (012345678)

Type

Remote IPV6 (FE80::0202:B3FF:fe1e:8329)

Type

Device ID (0123456789abcdef)


Registration API Endpoint < Identifying DNS Traffic

Updated 7 months ago

Identifying DNS traffic


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.