/v3/api/sites (PATCH) - User Guide - BlueCat Edge

BlueCat Edge User Guide
ft:locale
en-US
Product name
BlueCat Edge
Update the DNS resolver service version or additional settings of specified sites.
Note: You must disable automatic DNS resolver service updates to update the DNS resolver service versions.
PATCH https://api-<BlueCat.edge.url>/v3/api/sites
Authorization: Bearer token
Content-type: application/JSON
[
    {
        "id": "a16a009e-4790-42b6-9374-b1b18e619d76",
        "version": "3.0.5",
        "blockedServicePointIds": ["7793fcc1-21d9-40d2-a382-3df72276b501", "1233fcc1-4569-40d2-a382-abc2276b502"]
        "streamDataToCI": true,
        "loggingEndpointId": "123e4567-e89b-12d3-a456-426614174000",
        "identityServiceEnabled": true,
        "randomizeAddresses": false,
        "soaDefinition": {
            "authorityZone": "example.com",
            "mName": "ns.primaryserver.com",
            "rName": "admin.example.com",
            "minTTL": 200
        },
        "gslbTtl": 5,
        "healthCheckIds": [
            "3fa85f64-5717-4562-b3fc-2c963f66afa6"
        ],
        "gslbRuleIds": [
            "0196e75c-4779-75c4-bedf-ff4d27f3bd99"
        ],
        "serviceIngress": {
            "unencryptedEnabled": true,
            "dohEnabled": true,
            "dohPath": "/dns-query",
            "dotEnabled": true,
            "certificateSecretId": "7b6f3752-a442-4e3e-ba0b-f4f9d41bdaec"
        }
    },
    ...
]

Parameters

Name Description Type Required
id The ID of the site. String Required
version The updated DNS resolver service version of the site. This value must be a supported DNS resolver service version.
Attention: This parameter must not be included if automatic DNS resolver service updates is enabled.
 String Optional
blockedServicePointIds The service points that were blocked from updating. Remove the ID of service points that were blocked to allow the service point to retry the update. String Optional
streamDataToCI Sends DNS queries from a service point to the BlueCat Edge Cloud console. The default value is true.
Note: If you do not enable any query logging options, the DNS resolver service operates as a resolver and no DNS queries will be stored or visible.
 Boolean Optional
loggingEndpointId The ID of local logging endpoint. If this parameter does not have a value, the service point will not send DNS queries to a local logging endpoint.
Note: If you do not enable any query logging options, the DNS resolver service operates as a resolver and no DNS queries will be stored or visible.
 String Optional
identityServiceEnabled Indicates whether DNS queries include a mapping of user IDs, in addition to client IP addresses. This information is retrieved by the identity service when Azure Event Hub is configured to use Microsoft Active Directory. This authorization allows requests to extract data from the event logs stored in Azure Event Hub. The default value is false. Boolean Optional
randomizeAddresses Indicates whether DNS Resolver Service shuffles responses in the Answer section that match the QTYPE of the query. The shuffled responses are limited to A, AAAA, MX, NS, PTR, and SRV QTYPES. Boolean Optional
soaDefinition Updates the SOA definition for DNS queries that are modified based on a BlueCat Edge policy, such as blocking a query or removing unhealthy answers. When enabled, enter the following information:
  • authorityZone—the FQDN of the DNS zone for which the SOA record is authoritative.
  • mName—the FQDN of the primary name server for the zone.
  • rName—the email address of the domain administrator, represented as a domain name. For example, admin.example.com
  • minTtl—(Optional) the minimum TTL value of the zone, in seconds. The value must be between 0 and 86400 seconds inclusively. If left blank, the default value is 300 seconds.
 String Optional
gslbTtl The maximum TTL for DNS responses sent to clients for queries that match a GSLB rule, in seconds. The value must be between 0 and 604800 seconds inclusively. The default value is 5 seconds. Integer Optional
healthCheckIds A list of health check configuration IDs that the site will use to verify the health of the endpoints. String Optional
gslbRuleIds A list of GSLB rule IDs that will be used to evaluate incoming queries from the site. String Optional
serviceIngress The services that determine how the DNS resolver services provides resolution to clients. The services are as follows:
Note: By default, if you do not specify the serviceIngress, inbound DNS queries are unencrypted.
  • unencryptedEnabled—when set to true, inbound DNS queries are unencrypted.
  • dohEnabled—when set to true, inbound DNS queries are encrypted using DNS over HTTPS (DoH). If enabled, enter the following additional parameters:
    • dohPath—the path for the DoH endpoint. The default path is /dns-query.
      Note:
      • The dohPath must conform to RFC9110 and RFC3986.
      • The dohPath must include a prefixing slash ( / ) character in the path.
    • certificateSecretId—the ID of the certificate in the Edge secrets manager.
  • dotEnabled—when set to true, inbound DNS queries are encrypted using DNS over TLS (DoT). If enabled, enter the following information:
    • certificateSecretId—the ID of the certificate in the Edge secrets manager.
Note: To enable DNS over TLS or DNS over HTTPS, you must first upload a certificate to the BlueCat Edge secrets manager. For more information, refer to Secrets manager.
Note: The following formats are supported for the certificate input data:
  • The certificate must be PEM-encoded DER format and contain a server certificate, optional intermediates, and private key
  • The PEM data of the certificate must not contain more than 10 intermediate certificates
  • The server and intermediate certificates must be X.509 format
  • The private key must be PKCS#8 encoded, and may be unencrypted or password encrypted
  • The following private key encryption algorithms are supported: AES128CBC, AES128GCM, AES192CBC, AES192GCM, AES256CBC, AES256GCM, and TripleDESCBC
  • The following private key signature algorithms are supported: RSA, ECDSA, and ED25519
 String Optional

Successful response

204 NO_CONTENT
If you have Edge Service Point instances configured, the response returns a skippedInstances section contains a list of sites and any associated DNS resolver services on Edge Service Point instances that did not successfully update due to version incompatibility. The following displays an example of the response:
200 OK
Content-Type: application/JSON
{
  "skippedInstances": {
    "site-id-1": ["dps-id-1", "dps-id-2"],
    "site-id-2": [...],
    ...
  }
}
Possible error codes
  • UNAUTHORIZED
  • NOT_FOUND
  • BAD_REQUEST
  • FORBIDDEN
  • UNEXPECTED_ERROR