effectivelywild.technitium_dns.technitium_dns_get_top_stats module – Get top statistics for a specific type

Note

This module is part of the effectivelywild.technitium_dns collection (version 1.1.2).

It is not included in ansible-core. To check whether it is installed, run ansible-galaxy collection list.

To install it, use: ansible-galaxy collection install effectivelywild.technitium_dns.

To use it in a playbook, specify: effectivelywild.technitium_dns.technitium_dns_get_top_stats.

New in effectivelywild.technitium_dns 0.8.0

Synopsis

  • Retrieve top statistics data for a specified stats type

  • Can retrieve top clients, top domains, or top blocked domains.

Parameters

Parameter

Comments

api_port

integer

Port for the Technitium DNS API. Defaults to 5380

Default: 5380

api_token

string / required

API token for authenticating with the Technitium DNS API

api_url

string / required

Base URL for the Technitium DNS API

end

string

End date in ISO 8601 format. Only applies to ‘Custom’ type.

limit

integer

Maximum number of records to return.

Default: 1000

no_reverse_lookup

boolean

Disable reverse DNS lookup for Top Clients. Only applicable with TopClients stats type.

Choices:

  • false ← (default)

  • true

node

string

The node domain name for which the stats data is needed

When unspecified, the current node is used

Set node name as ‘cluster’ to get aggregate stats for the entire cluster

This parameter can be used only when Clustering is initialized

only_rate_limited_clients

boolean

List only clients that are being rate limited. Only applicable with TopClients stats type.

Choices:

  • false ← (default)

  • true

start

string

Start date in ISO 8601 format. Only applies to ‘Custom’ type.

stats_type

string / required

The type of statistics to retrieve.

Choices:

  • "TopClients"

  • "TopDomains"

  • "TopBlockedDomains"

type

string

The duration type for statistics.

Choices:

  • "LastHour" ← (default)

  • "LastDay"

  • "LastWeek"

  • "LastMonth"

  • "LastYear"

  • "Custom"

validate_certs

boolean

Whether to validate SSL certificates when making API requests.

Choices:

  • false

  • true ← (default)

See Also

See also

effectivelywild.technitium_dns.technitium_dns_get_stats

Get general DNS statistics from the dashboard

effectivelywild.technitium_dns.technitium_dns_delete_all_stats

Delete all statistics from the server

Examples

- name: Get top 10 clients for last hour
  technitium_dns_get_top_stats:
    api_url: "http://localhost"
    api_token: "myapitoken"
    stats_type: "TopClients"
    limit: 10
  register: result

- name: Get top domains for last day
  technitium_dns_get_top_stats:
    api_url: "http://localhost"
    api_token: "myapitoken"
    type: "LastDay"
    stats_type: "TopDomains"
    limit: 100
  register: result

- name: Get top blocked domains without reverse lookup
  technitium_dns_get_top_stats:
    api_url: "http://localhost"
    api_token: "myapitoken"
    stats_type: "TopBlockedDomains"
    limit: 50
  register: result

- name: Get only rate limited clients
  technitium_dns_get_top_stats:
    api_url: "http://localhost"
    api_token: "myapitoken"
    stats_type: "TopClients"
    only_rate_limited_clients: true
  register: result

- name: Get cluster-wide top domains
  technitium_dns_get_top_stats:
    api_url: "http://localhost"
    api_token: "myapitoken"
    stats_type: "TopDomains"
    node: "cluster"
  register: result

- debug:
    var: result.data

Return Values

Common return values are documented here, the following are the fields unique to this module:

Key

Description

changed

boolean

Whether the module made changes (always false for get operations)

Returned: always

Sample: false

data

list / elements=dictionary

Top statistics data (format depends on stats_type)

Returned: always

Sample: [{"domain": "server1.local", "hits": 236, "name": "192.168.10.5", "rateLimited": false}]

failed

boolean

Whether the module failed

Returned: always

Sample: false

topBlockedDomains

list / elements=dictionary

List of top blocked domains (only when stats_type is TopBlockedDomains)

Returned: when stats_type is TopBlockedDomains

hits

integer

Number of blocked queries for this domain

Returned: always

Sample: 10

name

string

Blocked domain name

Returned: always

Sample: "mobile.pipe.aria.microsoft.com"

topClients

list / elements=dictionary

List of top clients (only when stats_type is TopClients)

Returned: when stats_type is TopClients

domain

string

Client hostname (if resolved)

Returned: always

Sample: "server1.local"

hits

integer

Number of queries from this client

Returned: always

Sample: 236

name

string

Client IP address

Returned: always

Sample: "192.168.10.5"

rateLimited

boolean

Whether client is rate limited

Returned: always

Sample: false

topDomains

list / elements=dictionary

List of top domains (only when stats_type is TopDomains)

Returned: when stats_type is TopDomains

hits

integer

Number of queries for this domain

Returned: always

Sample: 34

name

string

Domain name

Returned: always

Sample: "www.google.com"

Authors

  • Frank Muise (@effectivelywild)