/v1/api/namespaces (POST) - BlueCat Edge - Service Point v4.x.x

BlueCat Edge User Guide
Locale
English
Product name
BlueCat Edge
Version
Service Point v4.x.x

Creates a namespace.

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

{
   "name": "namespace",
   "description": "this is a namespace",
   "forwarders": ["8.8.8.8", "2.2.2.2"],
   "matchLists": ["domainListId1", "domainListId2"],
   "exceptionLists": ["domainListId1", "domainListId2"],
   "umbrellaIntegrationId": "<id of umbrella integration>",
   "ttl": 60,
   "staleCacheEntriesTTL": 3600",
   "doHEnabled": false,
   "retryRCodes": [3, 2],
   "negativeCacheTTL": 60,
   "ecsConfiguration": {
            "v4Prefix": 24,
            "v6Prefix": 56,
            "override": true
    }
}

Parameters

Name Description Type Required
name The name of the namespace String Required
description A description of the namespace 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 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 Required
matchLists Domain list IDs for match lists String Optional
exceptionLists Domain list ID for exception lists String Optional
umbrellaIntegrationId The ID of the Cisco Umbrella integration created in Edge. String Optional
ttl The TTL of the query response in seconds. Enter a value between 0 and 2147483647 inclusively. 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
dohEnabled Enables or disables DNS over HTTPS (DoH) for Cisco Umbrella queries. The default value is false. 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: This only applies to sites configured with more than one namespace.
 String Optional
negativeCacheTTL The TTL of the expired DNS responses served from the cache. Enter a value 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

Successful response

201 CREATED

Response on unsuccessful authorization

401 Unauthorized
Content-Type: application/JSON
{"code": "UNAUTHORIZED", "brief": "You are not authorized to perform this action"}
Possible error codes
  • 400 Bad Request, TOO_MANY_DOMAIN_LISTS - The namespace can't contain more than 20 domain lists.
  • 400 Bad Request, TOO_MANY_DOMAINS - A domain list in the match list contains more than the maximum 100,000 domains allowed.
  • 400 Bad Request, TOO_MANY_DOMAINS - A domain list in the exception list contains more than the maximum 100,000 domains allowed.
  • 400 Bad Request, DOMAIN_LIST_NOT_FOUND - A domain list in the match list can't be found.
  • 400 Bad Request, DOMAIN_LIST_NOT_FOUND - A domain list in the exception list can't be found.
  • 400 Bad Request, INVALID_STALE_CACHE_ENTRIES_TTL - Stale cache entries TTL must be one of 0, 3,600, or 86,400 seconds.
  • 409 Conflict, NAMESPACE_ALREADY_EXISTS - The namespace name is already in use
  • 500 Internal Server Error, UNEXPECTED_SERVER_ERROR - Unexpected error while processing the request