{"id":13586267,"url":"https://github.com/dmachard/python-dnstap-receiver","last_synced_at":"2025-04-07T15:31:25.934Z","repository":{"id":36973022,"uuid":"266411880","full_name":"dmachard/python-dnstap-receiver","owner":"dmachard","description":"Dnstap streams receiver in Python","archived":true,"fork":false,"pushed_at":"2022-11-09T16:17:12.000Z","size":521,"stargazers_count":34,"open_issues_count":1,"forks_count":13,"subscribers_count":6,"default_branch":"master","last_synced_at":"2024-05-12T11:42:23.665Z","etag":null,"topics":["bind","coredns","dns","dnsdist","dnstap","nsd","pdns","powerdns","unbound"],"latest_commit_sha":null,"homepage":"https://github.com/dmachard/dns-collector","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/dmachard.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2020-05-23T20:12:46.000Z","updated_at":"2024-04-17T13:24:52.000Z","dependencies_parsed_at":"2023-01-17T11:16:25.163Z","dependency_job_id":null,"html_url":"https://github.com/dmachard/python-dnstap-receiver","commit_stats":null,"previous_names":["dmachard/dnstap_receiver"],"tags_count":18,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dmachard%2Fpython-dnstap-receiver","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dmachard%2Fpython-dnstap-receiver/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dmachard%2Fpython-dnstap-receiver/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dmachard%2Fpython-dnstap-receiver/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dmachard","download_url":"https://codeload.github.com/dmachard/python-dnstap-receiver/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247679429,"owners_count":20978048,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bind","coredns","dns","dnsdist","dnstap","nsd","pdns","powerdns","unbound"],"created_at":"2024-08-01T15:05:26.270Z","updated_at":"2025-04-07T15:31:25.573Z","avatar_url":"https://github.com/dmachard.png","language":"Python","readme":"# Dnstap streams receiver\n\n**If you want better performance and more features, please to use the [dnscollector](https://github.com/dmachard/go-dnscollector) tool written in Go.**\n\n![Testing](https://github.com/dmachard/dnstap_receiver/workflows/Testing/badge.svg) ![Build](https://github.com/dmachard/dnstap_receiver/workflows/Build/badge.svg) ![Pypi](https://github.com/dmachard/dnstap_receiver/workflows/PyPI/badge.svg) ![Dockerhub](https://github.com/dmachard/dnstap_receiver/workflows/DockerHub/badge.svg) \n\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n![PyPI - Python Version](https://img.shields.io/pypi/pyversions/dnstap_receiver)\n\nThis Python module acts as a [dnstap](https://dnstap.info/) streams receiver for DNS servers.\nInput streams can be a unix, tcp or raw socket.\nThe output is printed directly on stdout or sent to remote tcp address \nin JSON, YAML or one line text format and more. \n\nIf you want to use the **dnstap** feature of your dns server, please to read the following page [Dnstap: How to enable it on main dns servers](https://dmachard.github.io/posts/0001-dnstap-testing/)\n\n## Table of contents\n* [Installation](#installation)\n    * [PyPI](#pypi)\n    * [Docker Hub](#docker-hub)\n* [Inputs handler](#inputs-handler)\n    * [TCP socket (server)](#tcp-socket-server)\n    * [TCP socket (client)](#tcp-socket-client)\n    * [Unix socket](#unix-socket)\n    * [Raw socket (sniffer)](#raw-socket-sniffer)\n* [Outputs handler](#outputs-handler)\n    * [Stdout](#stdout)\n    * [File](#file)\n    * [TCP](#tcp)\n    * [Syslog](#syslog)\n    * [Metrics](#metrics)\n    * [Dnstap](#dnstap)\n    * [Kafka](#kafka)\n    * [RabbitMQ](#rabbitmq)\n    * [PostgreSQL](#postgresql)\n    * [Elasticsearch](#elasticsearch)\n* [More options](#more-options)\n    * [External config file](#external-config-file)\n    * [Verbose mode](#verbose-mode)\n    * [Filtering feature](#filtering-feature)\n    * [GeoIP support](#geoip-support)\n* [Statistics](#statistics)\n    * [Counters](#counters)\n    * [Tables](#tables)\n    * [Metrics](#metrics-1)\n* [Build-in Webserver](#build-in-webserver)\n    * [Configuration](#configuration)\n    * [Security](#security)\n    * [HTTP API](#http-api)\n* [Benchmark](#benchmark)\n* [Development](#development)\n* [About](#about)\n\n## Installation\n\n### PyPI\n\nDeploy the dnstap receiver in your DNS server with the pip command.\n\n```python\npip install dnstap_receiver\n```\n\nAfter installation, you can execute the `dnstap_receiver` to start-it.\n\nUsage:\n\n```\nusage: dnstap_receiver [-h] [-l L] [-p P] [-u U] [-v] [-c C]\n\noptional arguments:\n  -h, --help  show this help message and exit\n  -l L        IP of the dnsptap server to receive dnstap payloads (default: '0.0.0.0')\n  -p P        Port the dnstap receiver is listening on (default: 6000)\n  -u U        read dnstap payloads from unix socket\n  -v          verbose mode\n  -c C        external config file\n```\n\n\n### Docker Hub\n\nPull the dnstap receiver image from Docker Hub.\n\n```bash\ndocker pull dmachard/dnstap-receiver:latest\n```\n\nDeploy the container\n\n```bash\ndocker run -d -p 6000:6000 -p 8080:8080 --name=dnstap01 dmachard/dnstap-receiver\n```\n\nAdd the following argument to your container if you want to provide your own [configuration](#external-config-file) file.\n\n```bash\n-v /home/dnstap.conf:/etc/dnstap_receiver/dnstap.conf\n```\n\nFollow containers logs \n\n```bash\ndocker logs dnstap01 -f\n```\n\n## Inputs handler\n\nSeverals inputs handler are supported to read incoming dnstap messages:\n- [TCP socket (server)](#tcp-socket-server)\n- [TCP socket (client)](#tcp-socket-client)\n- [Unix socket](#unix-socket)\n- [Raw socket (sniffer)](#raw-socket-sniffer)\n\n### TCP socket (server)\n\nThe TCP socket input enable to receive dnstap messages from multiple dns servers.\nThis is the default input if you execute the binary without arguments.\nThe receiver is listening on `localhost` interface and the tcp port `6000`.\nYou can change binding options with `-l` and `-p` arguments.\n\n```\n./dnstap_receiver -l 0.0.0.0 -p 6000\n```\n\nYou can also activate `TLS` on the socket, add the following config as external config file\nto activate the tls support, configure the path of the certificate and key to use.\n\n```yaml\ninput:\n  tcp-socket:\n    # enable tls support\n    tls-support: true\n    # provide certificate server path\n    tls-server-cert: /etc/dnstap_receiver/server.crt\n    # provide certificate key path\n    tls-server-key: /etc/dnstap_receiver/server.key\n```\n\nThen execute the dnstap receiver with the configuration file:\n\n```\n./dnstap_receiver -c /etc/dnstap-receiver/dnstap.conf\n```\n\n### TCP socket (client)\n\nThe TCP socket input enable to receive dnstap messages from remote dns servers.\nThe communication is initiated by the dnstap receiver.\n\nConfigure this input as below\n\n```yaml\ninput:\n  # tcp client\n  tcp-client:\n    # enable or disable\n    enable: true\n    # retry interval in seconds to connect\n    retry: 1\n    # remote dns server address\n    remote-address: 10.0.0.2\n    # remote dns server port\n    remote-port: 6000\n```\n\n### Unix socket\n\nThe unix socket input enables read dnstap message from a unix socket. \nConfigure the path of the socket with the `-u` argument.\n\n```\n./dnstap_receiver -u /var/run/dnstap.sock\n```\n\n### Raw socket (sniffer)\n\nThis input enable to sniff a network interface.\nConfigure this input as below, you need to provide the name of your interface and associated ip.\n\n```yaml\ninput:\n  # sniff dns messages from network interface \n  sniffer:\n    # enable or disable\n    enable: true\n    # interface name to sniff\n    eth-name: ens18\n    # ip interface to sniff\n    eth-ip: [ 10.0.0.2 ]\n    # dnstap identity\n    dnstap-identity: sniffer\n    # sniff on the list of dns port\n    dns-port: [ 53 ]\n    # record incoming dns client queries\n    record-client-query: true\n    # record outgoing dns client responses\n    record-client-response: true\n```\n\n## Outputs handler\n\nOutputs handler can be configured to forward messages in several modes.\n- [Stdout](#stdout)\n- [File](#file)\n- [Metrics](#metrics)\n- [TCP](#tcp)\n- [Syslog](#syslog)\n- [Dnstap](#dnstap)\n- [Elasticsearch](#elasticsearch)\n\n### Stdout\n\nThis output enables to forward dnstap messages directly to Stdout.\nAdd the following configuration as external config to activate this output:\n\n```yaml\noutput:\n  stdout:\n    # enable or disable\n    enable: true\n    # format available text|json|yaml\n    format: text\n```\n\nOutput can be formatted in different way:\n- text (default one)\n- json \n- yaml\n\nText format:\n\n```\n2020-09-16T18:51:53.547352+00:00 lb1 CLIENT_QUERY NOERROR - - INET UDP 43b ns2.google.com. A -\n2020-09-16T18:51:53.591736+00:00 lb2 CLIENT_RESPONSE NOERROR - - INET UDP 59b ns2.google.com. A 0.048\n```\n\nJSON format:\n\n```json\n{\n    \"identity\": \"lb1\",\n    \"qname\": \"www.google.com.\",\n    \"rrtype\": \"A\",\n    \"query-ip\": \"192.168.1.114\",\n    \"message\": \"CLIENT_QUERY\",\n    \"family\": \"INET\",\n    \"protocol\": \"UDP\",\n    \"query-port\": 42222,\n    \"length\": 43,\n    \"timestamp\": \"2020-09-16T18:51:53.591736+00:00\",\n    \"rcode\": \"NOERROR\",\n    \"id\": 33422,\n    \"flags\": \"RD\",\n    \"latency\": \"-\"\n}\n```\n\nYAML format:\n\n```yaml\nidentity: lb1\nrcode: NOERROR\nlength: 49\nmessage: CLIENT_QUERY\nfamily: INET\nqname: dns4.comlaude-dns.eu.\nrrtype: AAAA\nquery-ip: '-'\nquery-port: '-'\ntimestamp: '2020-09-16T18:51:53.591736+00:00'\nprotocol: UDP\nid: 33422\nflags: RD\nlatency: '-'\n\n```\n\n### File\n\nThis output enables to forward dnstap messages directly to a log file.\nAdd the following configuration as external config to activate this output:\n\n```yaml\n  # forward to log file\n  file:\n    # enable or disable\n    enable: true\n    # format available text|json|yaml\n    format: text\n    # log file path or null to print to stdout\n    file: /var/log/dnstap.log\n    # max size for log file\n    file-max-size: 10M\n    # number of max log files\n    file-count: 10\n```\n\nIf you are running the dnstap in a container, follow this procedure to save logs in your host instead of the container.\n\nFirst one, create the folder in the host:\n\n```\nmkdir /var/dnstap/\nchown 1000:1000 /var/dnstap/\n```\n\nCreate the following configuration for your dnstap receiver\n\n```\ntrace:\n    verbose: true\noutput:\n  stdout:\n    enable: false\n  file:\n    enable: true\n    format: text\n    file: /home/dnstap/logs/dnstap.log\n    file-max-size: 10M\n    file-count: 10\n```\n\n\nThen execute the container with volume\n\n```\ndocker run -d -p 6000:6000 -p 8080:8080 -v ${PWD}/dnstap.conf:/etc/dnstap_receiver/dnstap.conf \\\n-v /var/dnstap:/home/dnstap/logs/ --name=dnstap01 dmachard/dnstap-receiver\n```\n\n\n### TCP\n\nThis output enables to forward dnstap message to a remote tcp collector.\nAdd the following configuration as external config to activate this output:\n\n```yaml\noutput:\n  # forward to remote tcp destination\n  tcp-socket:\n    # enable or disable\n    enable: true\n    # format available text|json|yaml\n    format: text\n    # delimiter\n    delimiter: \"\\n\"\n    # retry interval in seconds to connect\n    retry: 5\n    # remote ipv4 or ipv6 address\n    remote-address: 10.0.0.2\n    # remote tcp port\n    remote-port: 8192\n```\n\n### Syslog\n\nThis output enables to forward dnstap message to a syslog server.\nAdd the following configuration as external config to activate this output:\n\n\n```yaml\noutput:\n  syslog:\n    # enable or disable\n    enable: false\n    # syslog over tcp or udp\n    transport: udp\n    # format available text|json\n    format: text\n    # retry interval in seconds to connect\n    retry: 5\n    # remote ipv4 or ipv6 address of the syslog server\n    remote-address: 10.0.0.2\n    # remote port of the syslog server\n    remote-port: 514\n```\n\nExample of output on syslog server\n\n```\nSep 22 12:43:01 bind CLIENT_RESPONSE NOERROR 192.168.1.100 51717 INET UDP 173b www.netflix.fr. A 0.040\nSep 22 12:43:01 bind CLIENT_RESPONSE NOERROR 192.168.1.100 51718 INET UDP 203b www.netflix.fr. AAAA 0.060\n```\n\n### Metrics\n\nThis output enables to generate metrics in one line and print-it to stdout. Add the following configuration as external config to activate this output:\n\n```yaml\noutput:\n  metrics:\n    # enable or disable\n    enable: true\n    # print every N seconds.\n    interval: 300\n    # cumulative statistics, without clearing them after printing\n    cumulative: true\n    # log file path or null to print to stdout\n    file: null\n    # max size for log file\n    file-max-size: 10M\n    # number of max log files\n    file-count: 10\n```\n\nExample of output\n\n```\n2020-10-13 05:19:35,522 18 QUERIES, 3.6 QPS, 1 CLIENTS, 18 INET, 0 INET6, \n18 UDP, 0 TCP, 17 DOMAINS\n```\n\n### Dnstap\n\nThis output enables to send dnstap messages to a remote dnstap receiver. Add the following configuration as external config to activate this output:\n\n```yaml\n  # forward to another remote dnstap receiver\n  dnstap:\n    # enable or disable\n    enable: true\n    # retry interval in seconds to connect\n    retry: 1\n    # remote ipv4 or ipv6 address of the remote dnstap receiver\n    remote-address: 10.0.0.51\n    # remote port of the remote dnstap receiver\n    remote-port: 6000\n    # dnstap identity\n    dnstap-identity: dnstap-receiver\n```\n\n### Kafka\n\nThis output enables to send dnstap messages to a Kafka topic.\n\nInstall extra python library for kafka\n\n```python\npip install dnstap_receiver[kafka]\n```\n\nConfiguration\n\n```yaml\n  # forward to a Kafka topic\n  kafka:\n    # enable or disable\n    enable: false\n    # format available text|json|yaml\n    format: json\n    # configuration object to pass to librdkafka\n    rdkafka-config:\n      \"bootstrap.servers\": null\n      \"security.protocol\": null\n      \"sasl.mechanism\": null\n      \"sasl.username\": null\n      \"sasl.password\": null\n    # Kafka topic to forward messages to\n    topic: null\n```\n\n### RabbitMQ\n\nThis output enables to send dnstap messages to a RabbitMQ queue.\n\nInstall extra python library for rabbitmq\n\n```python\npip install dnstap_receiver[rabbitmq]\n```\n\nConfiguration\n\n```yaml\n  # forward to a RabbitMQ queue\n  rabbitmq:\n    # enable or disable\n    enable: false\n    # format available text|json|yaml\n    format: json\n    # connection configuration\n    connection:\n      username: null\n      password: null\n      host: 127.0.0.1\n      port: 5672\n    # Queue to forward messages to\n    queue:\n      queue: null\n      passive: false\n      durable: true\n      exclusive: false\n      auto_delete: false\n    # Exchange, default ''\n    exchange: \"\"\n    # Routing key, default = queue\n    routing-key: null\n    # Retries to connect/publish\n    retry-count: 2\n    # Retry delay seconds\n    retry-delay: 0.5\n```\n\n\n### PostgreSQL\n\nThis output enables to send dnstap messages to a PostgreSQL.\n\nInstall extra python library for PostgreSQL (asyncpg).\n\nSee [output_pgsql_userfunc.py](./dnstap_receiver/outputs/output_pgsql_userfunc.py) to replace table definition and data insertion.\n\n```python\npip install dnstap_receiver[pgsql]\n```\n\nConfiguration\n\n```yaml\n  # forward to postgresql server\n  pgsql:\n    # enable or disable\n    enable: false\n    # retry interval in seconds to connect\n    retry: 1\n    # dsn := postgres://user@host:port/database\n    # To explicitly write passwd in dsn is not recommended though possible.\n    # Instead use passfile below.\n    dsn: postgres://postgres@localhost:5432/postgres\n    # passfile := /path/to/.pgpass\n    # https://www.postgresql.org/docs/12/libpq-connect.html#LIBPQ-CONNECT-PASSFILE\n    passfile: ~/.pgpass\n    # min_size: minimum number of connections in the pool\n    min_size: 5\n    # max_size: maximum number of connections in the pool\n    max_size: 10\n    # busy_wait: wait this amount of seconds in the busy loop to write to PostgreSQL.\n    busy_wait: 1.0\n    # timeout: wait this amount of seconds to re-create the connection pool to PostgreSQL after it failed.\n    timeout: 60\n    # filename including user defined functions\n    userfuncfile: null\n```\n\n### Elasticsearch\n\nThis output enables to send dnstap messages to Elasticsearch.\n\n```yaml\noutput:\n  elasticsearch:\n    # enable or disable\n    enable: true\n    # url of the elasticsearch\n    url: text\n```\n\n\n## More options\n\n### External config file\n\nThe `dnstap_receiver` binary can takes an external config file with the `-c` argument or searches for a config file named dnstap.conf in /etc/dnstap_receiver/.\n\nSee [config file](/dnstap_receiver/dnstap.conf) example.\n\n```\n./dnstap_receiver -c /etc/dnstap-receiver/dnstap.conf\n```\n\n### Verbose mode\n\nYou can execute the binary in verbose mode with the `-v` argument:\n\n```\n./dnstap_receiver -v\n2020-11-25 20:26:59,790 DEBUG Start receiver...\n2020-11-25 20:26:59,790 DEBUG Output handler: stdout\n2020-11-25 20:26:59,790 DEBUG Input handler: tcp socket\n2020-11-25 20:26:59,790 DEBUG Input handler: listening on 0.0.0.0:6000\n2020-11-25 20:26:59,790 DEBUG Api rest: listening on 0.0.0.0:8080\n```\n\n### Filtering feature\n\nThis feature can be useful if you want to ignore some messages and keep just what you want.\nSeveral filter are available:\n- by qname field\n- by dnstap identity field.\n\n#### By dnstap identity\n\nYou can filtering incoming dnstap messages according to the dnstap identity field.\nA regex can be configured in the external configuration file to do that\n\n```yaml\nfilter:\n  # dnstap identify filtering feature with regex support\n  dnstap-identities: dnsdist01|unbound01\n```\n\n#### By qname\n\nYou can filtering incoming dnstap messages according to the query name.\nA regex can be configured in the external configuration file to do that\n\n```yaml\nfilter: \n  # qname filtering feature with regex support\n  qname-regex: \".*.com\"\n```\n\n### GeoIP support\n\nThe `dnstap receiver` can be extended with GeoIP. To do that, you need to configure your own city database in binary format.\n\n```yaml\n# geoip support, can be used to get the country, and city\n# according to the source ip in the dnstap message\ngeoip:\n    # enable or disable\n    enable: true\n    # city database path in binary format\n    city-database: /var/geoip/GeoLite2-City.mmdb\n    # represent country in iso mode\n    country-iso: false\n```\n\nWith the GeoIP support, the following new fields will be added:\n - country\n - city\n\n## Statistics\n\nSome statistics are computed [on the fly](/dnstap_receiver/statistics.py) and stored in memory, you can get them: \n- directly from the [web server](#web-server) through the HTTP API. \n- with the [dnstap-dashboard](https://github.com/dmachard/dnstap-dashboard), a top-like command\n- from your [Prometheus](https://prometheus.io/) instance\n\n### Counters\n\n- **query**: number of queries\n- **response**: number of answers\n- **qps**: number of queries per second\n- **clients**: number of unique clients ip\n- **domains**: number of unique domains\n- **query/inet**: number of IPv4 queries\n- **query/inet6**: number of IPv6 queries\n- **response/inet**: number of IPv4 answers\n- **response/inet6**: number of IPv6 answers\n- **query/udp**: number of queries with UDP protocol\n- **query/tcp**: number of queries with TCP protocol\n- **response/udp**: number of answers with UDP protocol\n- **response/tcp**: number of answers with TCP protocol\n- **response/[rcode]**: number of answers per specific rcode = noerror, nxdomain, refused,...\n- **query/[rrtype]**: number of queries per record resource type = = a, aaaa, cname,...\n- **query/bytes**: total number of bytes with queries\n- **response/bytes**: total number of bytes with answers\n- **response/latency0_1**: number of queries answered in less than 1ms\n- **response/latency1_10**: number of queries answered in 1-10 ms\n- **response/latency10_50**: number of queries answered in 10-50 ms\n- **response/latency50_100**: number of queries answered in 50-100 ms\n- **response/latency100_1000**: number of queries answered in 100-1000 ms\n- **response/latency_slow**: number of queries answered in more than 1 second\n\n### Tables\n\n- **tlds**: \n  - **hit/query**: table of [n] tlds sorted by number of queries\n  - **hit/response**: table of [n] tlds sorted by number of answers\n- **domains**: \n  - **[rcode]/query**: table of [n] domains sorted by number of queries\n  - **[rcode]/response**: table of [n] domains sorted by number of answers\n- **clients**: \n  - **hit/client**: table of [n] ip addresses sorted by number of queries\n  - **length/ip**: table of [n] ip addresses sorted by number of bytes\n- **rrtypes** \n  - **hit/query**: table of [n] resources record types sorted by the number of queries\n  - **hit/response**: table of [n] resources record types sorted by the number of answers\n- **top-rcodes**:\n  - **hit/query**: table of [n] return codes sorted by the number of queries\n  - **hit/response**: table of [n] return codes sorted by the number of answers\n  \n### Metrics\n\nMetrics in [Prometheus](https://prometheus.io/) format with global counters and specific by dnstap stream.\n\nSee [metrics file](/metrics.txt) example.\n```\n# HELP dnstap_queries Number of queries received\n# TYPE dnstap_queries counter\ndnstap_queries 0\n# HELP dnstap_responses Number of responses received\n# TYPE dnstap_responses counter\ndnstap_responses 0\n# HELP dnstap_responses_noerror Number of NOERROR answers\n# TYPE dnstap_responses_noerror counter\ndnstap_responses_noerror 0\n# HELP dnstap_responses_nxdomain Number of NXDomain answers\n# TYPE dnstap_responses_nxdomain counter\ndnstap_responses_nxdomain 0\n# HELP dnstap_responses_servfail Number of SERVFAIL  answers\n# TYPE dnstap_responses_servfail counter\ndnstap_responses_servfail 0\n...\n```\n\n## Build-in Webserver\n\nThe build-in web server can be used to get statistics computed by the dnstap receiver.\n\n### Configuration\n\nEnable the HTTP API, don't forget to change the default password.\n\n```yaml\n# rest api\nweb-api:\n    # enable or disable\n    enable: true\n    # web api key\n    api-key: changeme\n    # basicauth login\n    login: admin\n    # basicauth password\n    password: changeme\n    # listening address ipv4 0.0.0.0 or ipv6 [::]\n    local-address: 0.0.0.0\n    # listing on port\n    local-port: 8080\n```\n\n### Security\n\nThe following authentication methods are supported:\n- BasicAuth\n- X-API-Key\n\nTo access to the API, one of them method must be used in the request header.\nAn HTTP 401 response is returned when the authentication failed.\n\n### HTTP API\n\nSee the [swagger](https://generator.swagger.io/?url=https://raw.githubusercontent.com/dmachard/dnstap-receiver/master/swagger.yml) documentation.\n\n# Benchmark\n\n## Limited lab\n\nTested on a limited lab with the following processor: Intel Core i5-7200U @2,50GHz \n\nMetrics are extracted every second:\n\n```bash\nwatch -n 1 \"time curl --user admin:changeme http://[ip_dnstap_receiver]:8080/metrics\"\n```\n\nDns generator used:\n\n```bash\ndocker pull ns1labs/flame\ndocker run ns1labs/flame [ip_dns_server]\n```\n\nResult:\n\n| Parameters| Values | \n| ------------- | ------------- |\n| Query per seconds | ~11000 |\n| Domains | ~40000 |\n| Clients | 1 |\n| CPU usage | ~30% |\n| Memory usage | ~100Mo |\n| Network usage | ~5.7Mb |\n\n\n# Development\n\n## Run \n\nthe dnstap receiver from source\n\n```bash\npython3 -c \"from dnstap_receiver.receiver import start_receiver; start_receiver()\" -v\n```\n\n## Testunits\n\n```bash\npython3 -m unittest tests.test_receiver_tcpsocket -v\n```\n\n# About\n\n| | |\n| ------------- | ------------- |\n| Author | Denis Machard \u003cd.machard@gmail.com\u003e |\n| PyPI | https://pypi.org/project/dnstap-receiver/ |\n| Github | https://github.com/dmachard/dnstap-receiver |\n| DockerHub | https://hub.docker.com/r/dmachard/dnstap-receiver |\n| | |\n","funding_links":[],"categories":["Python"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdmachard%2Fpython-dnstap-receiver","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdmachard%2Fpython-dnstap-receiver","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdmachard%2Fpython-dnstap-receiver/lists"}