DHCP Statistics - BlueCat Integrity - 9.5.0

Address Manager Legacy v1 API Guide

Locale
English
Product name
BlueCat Integrity
Version
9.5.0

The DHCP Statistics service uses a monitoring module that runs on the DNS/DHCP Server to collect statistics by sniffing DHCP packets. You can use these metrics for troubleshooting and identifying anomalies or misconfiguration in your DHCP environment.

When enabled, DHCP Statistics information is collected by the DNS/DHCP Server based on the configured parameters and sent to a configured destination. You can choose to send the information to an HTTP endpoint, Splunk server, Kafka cluster, or Elasticsearch server.

Additionally, you can configure DHCP Statistics to send information to an Indeni (BlueCat Assurance) server using an HTTP endpoint. For more information, refer to https://indeni.com/docs/user-guide/part-2-getting-started-2/2-1-adding-user/2-1-1-bluecat/.
Attention:
  • You can only enable this service on DNS/DHCP Server v9.4.0 or greater.
  • Output to Kafka clusters and Elasticsearch servers can only be configured on DNS/DHCP Server v9.5.0.

Example http configuration

{
    "version": "1.1.0",
    "services": {
        "dhcpStatistics": {
            "configurations": [
                {
                    "dhcpStatisticsConfiguration": {
                        "sources": [
                            {
                                "enableDhcpV6": false,
                                "enableDhcpV4": true,
                                "type": "dhcp-statistics"
                            }
                        ],
                        "sinks": [
                            {
                                "healthCheck": false,
                                "buffer": {
                                    "maxEvents": 5,
                                    "type": "memory"
                                },
                                "type": "http",
                                "uri": "http://10.244.104.131"
                            }
                        ],
                        "enable": true
                    }
                }
            ]
        }
    }
}

Example splunk_hec configuration

{
    "version": "1.1.0",
    "services": {
        "dhcpStatistics": {
            "configurations": [
                {
                    "dhcpStatisticsConfiguration": {
                        "sources": [
                            {
                                "enableDhcpV6": false,
                                "enableDhcpV4": true,
                                "type": "dhcp-statistics"
                            }
                        ],
                        "sinks": [
                            {
                                "type": "splunk_hec",
                                "host": "https://10.0.0.1:9002",
                                "token": "MghrvMTU4NjIyMzA0NjYxMzpwb3J0YWxVc2Vy",
                                "healthCheck": true,
                                "buffer": {
                                    "maxEvents": 5,
                                    "type": "memory"
                                },
                                "tls": {
                                    "caCert": "<certificate_content>",
                                    "verifyCertificate": true,
                                    "verifyHostname": true
                                }
                            }
                        ],
                        "enable": true
                    }
                }
            ]
        }
    }
}

Example kafka configuration

{
    "version": "1.1.0",
    "services": {
        "dhcpStatistics": {
            "configurations": [
                {
                    "dhcpStatisticsConfiguration": {
                        "sources": [
                            {
                                "enableDhcpV6": false,
                                "enableDhcpV4": true,
                                "type": "dhcp-statistics"
                            }
                        ],
                        "sinks": [
                            {
                                "type": "kafka",
                                "bootstrap_servers": "10.14.22.123:9092,10.14.23.332:9092",
                                "topic": "topic-1234",
                                "key_field":"user_id",
                                "healthCheck": true,
                                "buffer": {
                                    "maxEvents": 5,
                                    "type": "memory"
                                },
                                "tls": {
                                    "caCert": "<certificate_content>",
                                    "verifyCertificate": true,
                                    "verifyHostname": true
                                }
                            }
                        ],
                        "enable": true
                    }
                }
            ]
        }
    }
}

Example elasticsearch configuration

{
    "version": "1.1.0",
    "services": {
        "dhcpStatistics": {
            "configurations": [
                {
                    "dhcpStatisticsConfiguration": {
                        "sources": [
                            {
                                "enableDhcpV6": false,
                                "enableDhcpV4": true,
                                "type": "dhcp-statistics"
                            }
                        ],
                        "sinks": [
                            {
                                "type": "elasticsearch",
                                "endpoint": "http://10.24.32.122:9000",
                                "user": "user1",
                                "password": "pass123",
                                "index": "testIndex",
                                "healthCheck": true,
                                "buffer": {
                                    "maxEvents": 5,
                                    "type": "memory"
                                },
                                "tls": {
                                    "caCert": "<certificate_content>",
                                    "verifyCertificate": true,
                                    "verifyHostname": true
                                }
                            }
                        ],
                        "enable": true
                    }
                }
            ]
        }
    }
}
Parameters
  • Under sources, enter the following information:
    • type—enter the name of the DNS/DHCP Server Service. This must be set to dhcp-statistics.
    • enableDhcpV4—set to true to enable the collection of DHCPv4 statistics; set to false to disable the collection of DHCPv4 statistics.
    • enableDhcpV6—set to true to enable the collection of DHCPv6 statistics; set to false to disable the collection of DHCPv6 statistics.
  • Under sinks, enter the following information:
    • type—enter where the DHCP Statistics data will be logged. You can log data to an HTTP endpoint, Splunk server, Kafka cluster, or Elasticsearch server.
      If you enter http, enter the following additional parameters:
      • uri—enter the URI of the HTTP endpoint that will be consuming the DHCP statistics information.
        Note:
        • BlueCat recommends entering the IP address of the endpoint in this field. If you are entering a hostname, you must use a different DNS server as the resolver for that host. The DNS/DHCP server you are configuring DHCP statistics on can still be used as a resolver for clients, but cannot be used as a resolver for its own OS related lookups.
        • If the domain name is used in the URI, you must ensure that the domain name can be resolved on the DNS/DHCP Server.
        • The URI for the uri field must follow the format outlined in RFC2396.
      • token—enter the bearer token used to authenticate with the HTTP endpoint. This field is optional.
      • healthCheck—set to true to enable health check service; set to false to disable health check service. Upon initialization, the healthcheck ensure that the downstream service is accessible and can accept the DHCP statistics data.
      • healthCheckUri—enter the URI of the HTTP endpoint that will be consuming the health check information.
        Note: The URI for the healthCheckUri field must follow the format outlined in RFC2396.
      If you enter splunk_hec, enter the following additional parameters:
      • host—enter the URI of the Splunk HEC host. The standard format of the HEC URI in Splunk Enterprise is as follows:
        <protocol>://<FQDN or IP address of the host only>:<port>
        Note:
        • BlueCat recommends entering the IP address of the endpoint in this field. If you are entering a hostname, you must use a different DNS server as the resolver for that host. The DNS/DHCP server you are configuring DHCP statistics on can still be used as a resolver for clients, but cannot be used as a resolver for its own OS related lookups.
        • If the domain name is used in the URI, you must ensure that the domain name can be resolved on the DNS/DHCP Server.
        • Ensure that the HEC URI format is followed exactly as described above without adding or omitting any pieces. The port is required, even if default. Do not include extra slashes or folders in the URI.
        • The URI for the host field must follow the format outlined in RFC2396.
      • token—enter the Splunk HEC token.
      • healthCheck—set to true to enable health check service; set to false to disable health check service. Upon initialization, the healthcheck ensure that the downstream service is accessible and can accept the DHCP statistics data.
        Note: When selecting this check box, the DNS/DHCP Server uses the default Splunk healthcheck endpoint at /services/collector/health/1.0.
      If you enter kafka, enter the following additional parameters:
      • bootstrap_servers—enter a comma-separated list of host and port pairs that are the addresses of the Kafka brokers in a “bootstrap” Kafka cluster that a Kafka client connects to initially to bootstrap itself. This field supports IPv4, IPv6 and FQDN values.

        Example: 10.14.22.123:9092,10.14.23.332:9092

        Note:
        • BlueCat recommends using IP addresses in this field. If you are entering a hostname, you must use a different DNS server as the resolver for that host. The DNS/DHCP server you are configuring DHCP statistics on can still be used as a resolver for clients, but cannot be used as a resolver for its own OS related lookups.
        • Do not include http or https in the addresses of the Kafka brokers.
        • If a domain name is used, you must ensure that the domain name can be resolved on the DNS/DHCP Server.
      • topic—enter the name of the Kafka topic to write events to.
      • key_field—enter the log field name or tags key to use for the topic key. If the field does not exist in the log or in tags, a blank value will be used. If unspecified, the key is not sent. Kafka uses a hash of the key to choose the partition or uses round-robin if the record has no key. This field is optional.
      • healthCheck—set to true to enable health check service; set to false to disable health check service. Upon initialization, the healthcheck ensure that the downstream service is accessible and can accept the DHCP statistics data.
        Note: The health check URI is configured based on the Kafka Broker address.
      If you enter elasticsearch, enter the following additional parameters:
      • endpoint—enter the Elasticsearch endpoint to send logs to. This field supports IPv4, IPv6, and FQDN values.

        Example: http://10.24.32.122:9000

        Example: https://example.com

        Example: https://user:password@example.com

        Note:
        • BlueCat recommends using the IP address of the endpoint in this field. If you are entering a hostname, you must use a different DNS server as the resolver for that host. The DNS/DHCP server you are configuring DHCP statistics on can still be used as a resolver for clients, but cannot be used as a resolver for its own OS related lookups.
        • If the domain name is used, you must ensure that the domain name can be resolved on the DNS/DHCP Server using nslookup or an entry in /etc/hosts.
      • user—enter the basic authentication user name.
      • password—enter the basic authentication password.
      • index—enter Elasticsearch index name to write events to.
      • healthCheck—set to true to enable health check service; set to false to disable health check service. Upon initialization, the healthcheck ensure that the downstream service is accessible and can accept the DHCP statistics data.
        Note: The health check URI is configured based on the Elasticsearch instance.
    • When configuring buffer settings, enter the following parameters:
      • type—enter the buffer type where DHCP statistics events are stored until they are processed. Once the buffer is full, the newest events are dropped.
        • memory—DHCP statistics events that have not been processed are stored in the memory of the DNS/DHCP Server.
          • maxEvents—enter the maximum number of DHCP statistics events to be stored in the buffer. The maximum value is 188,235,000 events.
    • When configuring tls settings, enter the following parameters:
      Attention: If you enter a HTTPS endpoint in the uri, healthCheckUri, host, bootstrap_servers, or endpoint field when configuring output, you must select this check box and enter TLS information.
      • caCert—enter the content of CA certificate (trusted third party or self-signed) that will be used to authenticate the CA signature on the TLS server certificate of the remote host.
        Note: The CA certificate or certificate bundle must be in PEM format. To ensure a successful TLS handshake, the CA certificate provided to the client (BDDS) should be the same CA certificate (and intermediate certificates if applicable) used by the server to authenticate the CA signature of its TLS server certificate. The CA certificate can be acquired via browser export or other trusted source, and converted to PEM format.
      • verifyCertificate—set to true to attempt a TLS handshake using the provided CA certificate with the remote host's TLS server certificate.
        Note: verifyCertificate does not verify the authenticity of the provided certificate. verifyCertificate in this context only checks if the CA certificate matches correctly with the TLS server certificate to create a successful handshake.
        Note: If encountering errors with Verify Certificate, the CA/chain-CA certificates may have to be installed manually on the DNS/DHCP Server. Refer to KB-17944 on the BlueCat Customer Care portal for manual installation instructions.
      • verifyHostname—set to true to validate the hostname section of the URI against the CN (Common Name) or SAN (Subject Alternative Name) of the server certificate during the TLS handshake; set to false if you do not want to perform this validation.
        Note: If using self-signed certificates, users are advised to add a subject alternative name with the IP address (see RFC 5280 4.2.1.6), or disable the verifyHostname check.
  • enable—set to true to enable DHCP statistics service; set to false to disable DHCP statistics service.
    Note: When you enabled DHCP Statistics, the firewall rules on the DNS/DHCP Server are modified to allow egress to the specified URI endpoint. Outbound traffic is allowed for the specified IP address.