/v2/api/namespaces (POST) - User Guide - BlueCat Edge

BlueCat Edge User Guide
ft:locale
en-US
Product name
BlueCat Edge

Creates a namespace.

User-defined namespaces

POST https://api-<BlueCat.edge.url>/v2/api/namespaces
Authorization: Bearer token
Content-Type: application/json

{
     "name": "another namespace 2",
     "type": "USER",
     "description": "test-namespace-description-1",
     "isDefault": true,
     "matchLists": [],
     "exceptionLists": [],
     "ipMatchLists": [],
     "ipExceptionLists": [],
     "ttl": 60,
     "staleCacheEntriesTTL": 86400,
     "negativeCacheTTL": 30,
     "ecsConfiguration": {
         "v4Prefix": 24,
         "v6Prefix": 56,
         "override": false
     },
     "retryRCodes": [
         3,
         5
     ],
     "forwarderType": "UNENCRYPTED",
     "forwarders": [
         "127.0.0.1",
         "8.9.10.11"
     ],
     "forwarderCertificate": "",
     "umbrellaIntegrationId": ""
}

Parameters

Name Description Type Required
name The name of the namespace String Required
type The type of namespace. The type can be one of the following:
  • USER - Creates a user-defined namespace.
  • DISCOVERED - Creates a discovered namespace.
  • RECURSIVE - Creates a recursive namespace.

For user-defined namespaces, enter USER.

 String Required
description A description of the namespace String Required
isDefault Indicates whether the namespace is a default namespace Boolean Optional
matchLists Domain list IDs for match lists String Optional
exceptionLists Domain list ID for exception lists String Optional
ipMatchLists IP list IDs for match lists String Optional
ipExceptionLists IP list ID for exception lists String Optional
ttl The TTL of the query response in seconds. Enter a value between 0 and 2147483647 inclusively.
Note: If you don't specify the TTL value, the value defaults to -1.
 Integer Optional
staleCacheEntriesTTL The TTL of the expired DNS queries. If unspecified, the default value is 3600.
Note: Currently, the only supported TTL values are 0, 3600, and 86400 seconds.
 Integer Optional
negativeCacheTTL The maximum TTL applied to responses that return NXDOMAIN responses, in seconds. The value must be between 0 and 2147483647 inclusively. Integer Optional
ecsConfiguration Configures the EDNS Client Subnet (ECS) option on a namespace. ecsConfiguration has the following properties:
  • v4Prefix - The IPv4 prefix as an integer between 0-32.
  • v6Prefix - The IPv6 prefix as an integer between 0-128.
  • override - The boolean value that determines whether the namespace overrides the ECS option on incoming queries with the specified prefixes.

If override is set to true, the namespace applies the specified IPv4 or IPv6 prefix as the ECS value, overriding any existing ECS value of incoming DNS queries. On the response, the inbound ECS value will be restored.

If override is set to false, the existing ECS value is forwarded in queries and responses if the value is present on the incoming query. For queries that do not contain an ECS value, one will be added using the specified v4Prefix or v6Prefix. On the response, the inbound ECS value will be restored.

If the ecsConfiguration is not specified or has a null value, the ECS value is removed from incoming DNS queries before they are forwarded, but is restored on the response.

 Integer, Boolean Optional
retryRCodes A list of numeric values that represent DNS query response codes as outlined in RFC2929. If any of the configured DNS query responses are returned to this namespace, the next namespace within a site will attempt to resolve the DNS queries.
Note: To configure the NODATA response, set the value to 4020.
Note: This only applies to sites configured with more than one namespace.
 String Optional
forwarderType The forwarder type that will be used by the namespace. All forwards for this namespace can be one of the following:
  • UNENCRYPTED: forwards unencrypted queries to a forwarder.
  • UMBRELLA: forwarders queries to Cisco Umbrella.
  • UMBRELLA_DOH: forwarders queries to Cisco Umbrella using DNS over HTTPS (DoH).
  • DOT: forwards encrypted queries to a forwarder using DNS over TLS (DoT).
  • DOH: forwards encrypted queries to a forwarder using DNS over HTTPS (DoH).
Note: You cannot configure the forwarderCertificate parameter if the forwarderType is not DOH or DOT
 String Required
forwarders Forwarder IPv4 or IPv6 addresses. Optionally, you can define a custom port number or forwarders that listen on ports other than the standard DNS port. For example, 1.2.3.4:123 for IPv4 addresses or [2001:db8:1111:2222:3333:4444:5555:6666:7777]:123 for IPv6 addresses. Based on the forwarderType, enter the following:
  • UNENCRYPTED: enter the IPv4 or IPv6 addresses and optional port. If no port is defined, the default port used is 53.
  • DOT: enter the IPv4 or IPv6 addresses and optional port. If no port is defined, the default port used is 853.
  • DOH: enter HTTPS URI and optional port. If no port is defined, the default port used is 443.
  • UMBRELLA: the forwarders list must be empty. By default, the Cisco Umbrella forwarders are used ["208.67.222.222", "208.67.220.220"]
  • UMBRELLA_DOH: the forwarders list must be empty. By default, the Cisco Umbrella DoH forwarder is used ["https://doh.umbrella.com/dns-query"]
Note:
  • The forwarders field is required for UNENCRYPTED, DOH, and DOT forwarder types.
  • You must only use IPv4 or IPv6 destinations supported by the service point network connection. For example, if you configure the service point using only an IPv4 address, the forwarders must only be IPv4 addresses.
  • If you configure multiple forwarders within a namespace, queries are load balanced based on the following criteria:
    • The server with the least number of queries 'in the air' is selected.
    • In the event of a tie, the server with the lowest measured latency is selected. The lowest measured latency is calculated over an average on the last 128 queries answered by that server.
  • BlueCat Edge performs a health check on all configured forwarders in a namespace. If a server is unreachable, it is skipped and the next forwarder is used.
Attention: DOT, DOH, and UMBRELLA_DOH are only supported on DNS Resolver Service v26.1.0 or greater.
 String Optional
forwarderCertificate If you are configuring DOH or DOT forwarder, enter the PEM certificate string for the forwarders. String Optional
umbrellaIntegrationId The ID of the Cisco Umbrella integration created in Edge.
Note: If you include the ID of a Cisco Umbrella integration, the forwarderType parameter must be set to UMBRELLA or UMBRELLA_DOH.
 String Optional

Discovered namespaces

POST https://api-<BlueCat.edge.url>/v2/api/namespaces
Authorization: Bearer token
Content-Type: application/json

{
     "name": "discovered namespace",
     "type": "DISCOVERED",
     "description": "A namespace configured to resolve using discovered data",
     "isDefault": true,
     "matchLists": [],
     "exceptionLists": [],
     "ipMatchLists": [],
     "ipExceptionLists": [],
     "ttl": 60,
     "staleCacheEntriesTTL": 86400,
     "negativeCacheTTL": 30,
     "ecsConfiguration": {
         "v4Prefix": 24,
         "v6Prefix": 56,
         "override": false
     },
     "retryRCodes": [
         3,
         5
     ],
     "forwarders": [
         "127.0.0.1",
         "8.9.10.11"
     ],
     "useSystemResolver": true,
     "discoveryIds": [
         "123aaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa",
         "456bbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb"
     ],
     "authority": []
     "searchDomains": []
}

Parameters

Name Description Type Required
name The name of the namespace String Required
type The type of namespace. The type can be one of the following:
  • USER - Creates a user-defined namespace.
  • DISCOVERED - Creates a discovered namespace.
  • RECURSIVE - Creates a recursive namespace.

For discovered namespaces, enter DISCOVERED.

 String Required
description A description of the namespace String Required
isDefault Indicates whether the namespace is a default namespace Boolean Optional
matchLists Domain list IDs for match lists String Optional
exceptionLists Domain list ID for exception lists String Optional
ipMatchLists IP list IDs for match lists String Optional
ipExceptionLists IP list ID for exception lists String Optional
ttl The TTL of the query response in seconds. Enter a value between 0 and 2147483647 inclusively.
Note: If you don't specify the TTL value, the value defaults to -1.
 Integer Optional
staleCacheEntriesTTL The TTL of the expired DNS queries. If unspecified, the default value is 3600.
Note: Currently, the only supported TTL values are 0, 3600, and 86400 seconds.
 Integer Optional
negativeCacheTTL The maximum TTL applied to responses that return NXDOMAIN responses, in seconds. The value must be between 0 and 2147483647 inclusively. Integer Optional
ecsConfiguration Configures the EDNS Client Subnet (ECS) option on a namespace. ecsConfiguration has the following properties:
  • v4Prefix - The IPv4 prefix as an integer between 0-32.
  • v6Prefix - The IPv6 prefix as an integer between 0-128.
  • override - The boolean value that determines whether the namespace overrides the ECS option on incoming queries with the specified prefixes.

If override is set to true, the namespace applies the specified IPv4 or IPv6 prefix as the ECS value, overriding any existing ECS value of incoming DNS queries. On the response, the inbound ECS value will be restored.

If override is set to false, the existing ECS value is forwarded in queries and responses if the value is present on the incoming query. For queries that do not contain an ECS value, one will be added using the specified v4Prefix or v6Prefix. On the response, the inbound ECS value will be restored.

If the ecsConfiguration is not specified or has a null value, the ECS value is removed from incoming DNS queries before they are forwarded, but is restored on the response.

 Integer, Boolean Optional
retryRCodes A list of numeric values that represent DNS query response codes as outlined in RFC2929. If any of the configured DNS query responses are returned to this namespace, the next namespace within a site will attempt to resolve the DNS queries.
Note: To configure the NODATA response, set the value to 4020.
Note: This only applies to sites configured with more than one namespace.
 String Optional
forwarders Forwarder IPv4 or IPv6 addresses. Optionally, you can define a custom port number or forwarders that listen on ports other than the standard DNS port. For example, 1.2.3.4:123 for IPv4 addresses or [2001:db8:1111:2222:3333:4444:5555:6666:7777]:123 or IPv6 addresses. If you do not define a port, the BlueCat Edge Service Point forwards all queries on destination port 53.

If the namespace uses a Cisco Umbrella integration, enter the two standard Cisco Umbrella cloud IP addresses.

Note:
  • You must only use IPv4 or IPv6 destinations supported by the service point network connection. For example, if you configure the service point using only an IPv4 address, the forwarders must only be IPv4 addresses.
  • If you configure multiple forwarders within a namespace, queries are load balanced based on the following criteria:
    • The server with the least number of queries 'in the air' is selected.
    • In the event of a tie, the server with the lowest measured latency is selected. The lowest measured latency is calculated over an average on the last 128 queries answered by that server.
  • BlueCat Edge performs a health check on all configured forwarders in a namespace. If a server is unreachable, it is skipped and the next forwarder is used.
 String Optional
useSystemResolver Indicates whether the namespace uses the system resolver Boolean Optional
discoveryIds A list of discovery configuration IDs to link to the discovered namespace. String Required
authority Authoritative nameservers for discovered namespaces. authority has the following additional properties:
  • zoneName - The associated DNS zone name
  • nameservers - A set of unique DNS nameservers containing the following:
    • name - The hostname of the server.
    • addresses - A list of unique IP addresses where the server can be reached.
 String Optional
searchDomains Search domains for the discovered namespace. searchDomains has the following additional properties:
  • subnet - The subnet used to match queries to the search domain suffix by source IP address.
  • suffix - The domain name suffix to apply to queries whose source IP address matches the subnet.
 String Optional

Recursive namespaces

POST https://api-<BlueCat.edge.url>/v2/api/namespaces
Authorization: Bearer token
Content-Type: application/json

{
     "name": "external namespace",
     "type": "RECURSIVE",
     "description": "A namespace configured to resolve external records",
     "isDefault": true,
     "matchLists": [],
     "exceptionLists": [],
     "ipMatchLists": [],
     "ipExceptionLists": [],
     "ttl": 60,
     "staleCacheEntriesTTL": 86400,
     "negativeCacheTTL": 30,
     "ecsConfiguration": {
         "v4Prefix": 24,
         "v6Prefix": 56,
         "override": false
     },
     "retryRCodes": [
         3,
         5
     ],
     "enableDnsSec": false,
     "customRootHints": {
         "ttl": 3600,
         "rootServers": [
             {
                 "name": "bluecatnetworks.com",
                 "addresses": [
                     "192.168.0.50",
                     "2001:0db8:85a3:0000:0000:8a2e:0370:7334"
                 ]
             },
             {
                 "name": "bluecatlabs.net",
                 "addresses": [
                     "192.168.0.49"
                 ]
             }
         ]
     }
}

Parameters

Name Description Type Required
name The name of the namespace String Required
type The type of namespace. The type can be one of the following:
  • USER - Creates a user-defined namespace.
  • DISCOVERED - Creates a discovered namespace.
  • RECURSIVE - Creates a recursive namespace.

For recursive namespaces, enter RECURSIVE.

 String Required
description A description of the namespace String Required
isDefault Indicates whether the namespace is a default namespace Boolean Optional
matchLists Domain list IDs for match lists String Optional
exceptionLists Domain list ID for exception lists String Optional
ipMatchLists IP list IDs for match lists String Optional
ipExceptionLists IP list ID for exception lists String Optional
ttl The TTL of the query response in seconds. Enter a value between 0 and 2147483647 inclusively.
Note: If you don't specify the TTL value, the value defaults to -1.
 Integer Optional
staleCacheEntriesTTL The TTL of the expired DNS queries. If unspecified, the default value is 3600.
Note: Currently, the only supported TTL values are 0, 3600, and 86400 seconds.
 Integer Optional
negativeCacheTTL The maximum TTL applied to responses that return NXDOMAIN responses, in seconds. The value must be between 0 and 2147483647 inclusively. Integer Optional
ecsConfiguration Configures the EDNS Client Subnet (ECS) option on a namespace. ecsConfiguration has the following properties:
  • v4Prefix - The IPv4 prefix as an integer between 0-32.
  • v6Prefix - The IPv6 prefix as an integer between 0-128.
  • override - The boolean value that determines whether the namespace overrides the ECS option on incoming queries with the specified prefixes.

If override is set to true, the namespace applies the specified IPv4 or IPv6 prefix as the ECS value, overriding any existing ECS value of incoming DNS queries. On the response, the inbound ECS value will be restored.

If override is set to false, the existing ECS value is forwarded in queries and responses if the value is present on the incoming query. For queries that do not contain an ECS value, one will be added using the specified v4Prefix or v6Prefix. On the response, the inbound ECS value will be restored.

If the ecsConfiguration is not specified or has a null value, the ECS value is removed from incoming DNS queries before they are forwarded, but is restored on the response.

 Integer, Boolean Optional
retryRCodes A list of numeric values that represent DNS query response codes as outlined in RFC2929. If any of the configured DNS query responses are returned to this namespace, the next namespace within a site will attempt to resolve the DNS queries.
Note: To configure the NODATA response, set the value to 4020.
Note: This only applies to sites configured with more than one namespace.
 String Optional
enableDnsSec Indicates whether to enable DNSSEC validation and validate the authenticity of the DNS responses form the resolvers. Boolean Optional
customRootHints Configures custom root hint servers to use instead of public root servers. If you do not include this field, public internet root hint servers are used.
The customRootHints field includes the following properties:
  • ttl - The TTL value of the cache, in seconds. The default value is 86400 seconds (24 hours).
  • rootServers - The list of custom root servers. This field includes the following additional properties:
    • name - The FQDN of the root server.
    • addresses - A list of IPv4 or IPv6 addresses of the root name servers.
      Note: You must include at least one valid IPv4 address.
 String Optional

Successful response

201 CREATED
Possible error codes
  • 400 Bad Request - Invalid request body or namespace.
  • 409 Conflict - The namespace name is already in use
  • 500 Internal Server Error - Unexpected error while processing the request