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 0.9.1).

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

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

- 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)