Skip to main content

Python client for dnsdist console

Tool to interact with your dnsdist console from Python.

powerdns dnsdist 1.9.x powerdns dnsdist 1.8.x powerdns dnsdist 1.7.x powerdns dnsdist 1.6.x

Table of contents

Installation

python 3.12.x python 3.11.x python 3.10.x python 3.9.x python 3.8.x

This module can be installed from pypi website

pip install dnsdist_console

Generate console key

You must configure your dnsdist load balancer to accept remote connection to the console. This module can be used to generate the secret key as below.

The command in one line

python3 -c "from dnsdist_console import Key;print(Key().generate())"
OTgmgAR6zbrfrYlKgsAAJn+by4faMqI1bVCvzacXMW0=

Save-it in your /etc/dnsdist/dnsdist.conf with the setKey directive.

controlSocket('0.0.0.0:5199')
setKey("GQpEpQoIuzA6kzgwDokX9JcXPXFvO1Emg1wAXToJ0ag=")

Generate hash password

You can use this module to generate a hash for the webserver of your dnsdist. Since 1.7.0 the password should be hashed and salted.

The command in one line

python3 -c "from dnsdist_console import HashPassword as H;print(H().generate(\"bonjour\"))"
$scrypt$ln=10,p=1,r=8$SZmi+pjuZ4u7L4jhXIkLww==$VRW7BuYUjSVjkjDIK6J1VB/RWx2s4gbz+YXgflWspf8=

Run command

Configure the client with the IP address and the TCP port of your dnsdist as well as the associated secret key. If the provided key is incorrect, an exception will be raised.

from dnsdist_console import Console

console_ip = "127.0.0.1"
console_port = 5199
console_key = "GQpEpQoIuzA6kzgwDokX9JcXPXFvO1Emg1wAXToJ0ag="

console = Console(host=console_ip,
                  port=console_port, 
                  key=console_key)

Please refer to the dnsdist documentation for all available commands.

o = console.send_command(cmd="showVersion()")
print(o)
dnsdist 1.4.0

Get statistics

Use this module to extract some statistics on your dnsdist load balancer. Statistics are stored in a python dictionary.

from dnsdist_console import Statistics

s = Statistics(console=console)
print(s["global"]["queries"])
3993

# get top queries
print(s["top-queries"])
[
    {'entry': 'www.apple.com.', 'hits': '9'},
    {'entry': 'www.facebook.com.', 'hits': '3'},
    {'entry': 'www.microsoft.com.', 'hits': '3'}
]


# get top nx domain
print(s["top-nxdomain"])
[
    {'entry': 'www.nxdomain.com.', 'hits': '1'}
    
]

# get top clients
print(s["top-clients"])
[
    {'entry': '127.0.0.1', 'hits': '21'}
]

Display basic dashboard

You can use this client to display a dashboard of your dnsdist from your command line. The dashboard is updated every second.

from dnsdist_console import Dashboard

Dashboard(console=console)

Run your script and you will see something like below.

Dashboard for dnsdist

Global:
        Uptime (seconds): 47735
        Number of queries: 0
        Query per second: 0
        ACL drops: 0
        Dynamic drops: 0
        Rule drops: 0
        CPU Usage (%s): 2.8
        Cache hitrate: 0
Backends:
        #0 / 10.0.0.140:53 / -- / dns_others
                Number of queries: 0
                Query per second: 0.0
                Number of drops: 0
        #1 / 10.0.0.55:53 / -- / dns_internal
                Number of queries: 0
                Query per second: 0.0
                Number of drops: 0
        #2 / 8.8.8.8:53 / -- / dns_internet
                Number of queries: 0
                Query per second: 0.0
                Number of drops: 0
        #3 / 1.1.1.1:53 / dns_1 / --
                Number of queries: 0
                Query per second: 0.0
                Number of drops: 0

Ctrl+C to exit

Metadata

Release files for dnsdist-console 1.6.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for dnsdist-console 1.6.0
File Size Uploaded Provenance Actions
dnsdist_console-1.6.0.tar.gz 10.3 kB With provenance Details for dnsdist_console-1.6.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for dnsdist-console 1.6.0
File Interpreter ABI Platform Actions
dnsdist_console-1.6.0-py3-none-any.whl Python 3 none any Details for dnsdist_console-1.6.0-py3-none-any.whl

Total release size: 21.7 kB

Release files / dnsdist_console-1.6.0.tar.gz

Download URL dnsdist_console-1.6.0.tar.gz
Size 10.3 kB
Tags Source
SHA-256 checksum
How to use checksums
4afb35b52640db5c4865aa6458147651c757907465204497e6c74f36f5a7eb0a
BLAKE2b-256 checksum
How to use checksums
e3f91d3eb92c2a94af1fd970b42e48584f544e832a3d40c86d14340f1def78db
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.12.9

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Apr 2, 2025.

Transparency log

Release files / dnsdist_console-1.6.0-py3-none-any.whl

Download URL dnsdist_console-1.6.0-py3-none-any.whl
Size 11.3 kB
Tags Python 3
SHA-256 checksum
How to use checksums
074056c0364d6450636051bb1d49a0d07620ae9cf14b1b9ce17f130b8585adce
BLAKE2b-256 checksum
How to use checksums
67545005c1355e3d97ee4cf7e5d118836d898d5ed58470ab8a63139dead16b14
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.12.9

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Apr 2, 2025.

Transparency log

Security for dnsdist-console 1.6.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for dnsdist_console-1.6.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Apr 2, 2025.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page