{"id":19070718,"url":"https://github.com/powerdns/pdns-protobuf-receiver","last_synced_at":"2025-10-09T01:12:09.749Z","repository":{"id":55347896,"uuid":"267926736","full_name":"PowerDNS/pdns-protobuf-receiver","owner":"PowerDNS","description":"pdns protobuf receiver","archived":false,"fork":false,"pushed_at":"2021-06-23T20:42:15.000Z","size":383,"stargazers_count":24,"open_issues_count":4,"forks_count":11,"subscribers_count":9,"default_branch":"master","last_synced_at":"2025-04-18T17:19:28.050Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","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/PowerDNS.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-29T18:21:17.000Z","updated_at":"2025-03-18T04:22:25.000Z","dependencies_parsed_at":"2022-08-14T21:51:40.161Z","dependency_job_id":null,"html_url":"https://github.com/PowerDNS/pdns-protobuf-receiver","commit_stats":null,"previous_names":["dmachard/pdns-protobuf-receiver"],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PowerDNS%2Fpdns-protobuf-receiver","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PowerDNS%2Fpdns-protobuf-receiver/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PowerDNS%2Fpdns-protobuf-receiver/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PowerDNS%2Fpdns-protobuf-receiver/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/PowerDNS","download_url":"https://codeload.github.com/PowerDNS/pdns-protobuf-receiver/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251332938,"owners_count":21572715,"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":[],"created_at":"2024-11-09T01:20:10.033Z","updated_at":"2025-10-09T01:12:09.743Z","avatar_url":"https://github.com/PowerDNS.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ⚠️ Important notice\n\n**This project is no longer maintained.**\n\n👉 Please use [DNS-collector](https://github.com/dmachard/DNS-collector) instead, which provides a more complete and up-to-date solution.\n\n# PowerDNS protobuf receiver\n\n![](https://github.com/dmachard/pdns-protobuf-receiver/workflows/Publish/badge.svg)\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/pdns-protobuf-receiver)\n\nThe `pdns_protobuf_receiver` is a daemon in Python 3 that acts a protobuf server for PowerDNS's products. You can use it to collect DNS queries and responses and to log to syslog or a json remote tcp collector.\n\n## Table of contents\n* [Installation](#installation)\n* [Execute receiver](#execute-receiver)\n* [Startup options](#startup-options)\n* [Output JSON format](#output-json-format)\n* [PowerDNS configuration](#powerdns-configuration)\n* [About](#about)\n\n## Installation\n\n### PyPI\n\nFrom pypi, deploy the `pdns_protobuf_receiver` with the pip command.\nOnly Python3 is supported.\n\n```python\npip install pdns-protobuf-receiver\n```\n\nAfter installation, you will have `pdns_protobuf_receiver` binary available\n\n### Docker Hub\n\nPull the pdns-protobuf-receiver image from Docker Hub.\n\n```bash\ndocker pull dmachard/pdns-protobuf-receiver:latest\n```\n\nDeploy the container\n\n```bash\ndocker run -d -p 50001:50001 --name=pdns-pb01 dmachard/pdns-protobuf-receiver\n```\n\nFollow containers logs \n\n```bash\ndocker logs pdns-pb01 -f\n```\n\n## Execute receiver\n\nThe receiver is listening by default on the 0.0.0.0 interface and 50001 tcp port \n\nIf you want to print DNS queries and responses to stdout in JSON format, then execute the `pdns_protobuf` receiver as below: \n\n```\n# pdns_protobuf_receiver -v\n2020-05-29 18:39:08,579 Start pdns protobuf receiver...\n2020-05-29 18:39:08,580 Using selector: EpollSelector\n```\n\nIf you want to resend protobuf message to your remote tcp collector\nStart the pdns_protobuf receiver as below:\n\n```\n# pdns_protobuf_receiver -j 10.0.0.235:6000 -v\n2020-05-29 18:39:08,579 Start pdns protobuf receiver...\n2020-05-29 18:39:08,580 Using selector: EpollSelector\n2020-05-29 18:39:08,580 Connecting to 10.0.0.235 6000\n2020-05-29 18:39:08,585 Connected to 10.0.0.235 6000\n```\n\n## Startup options\n\nCommand line options are:\n\n```\nusage: -c [-h] [-l L] [-j J] [-v]\n\noptional arguments:\n  -h, --help  show this help message and exit\n  -l L        listen protobuf dns message on tcp/ip address \u003cip:port\u003e\n  -j J        write JSON payload to tcp/ip address \u003cip:port\u003e\n  -v          verbose mode\n```\n\n## JSON log format\n\nEach events generated by the `pdns_protbuf` receiver will have the following format:\n\n```json\n{\n    \"dns_message\": \"AUTH_QUERY\",\n    \"socket_family\": \"IPv6\",\n    \"socket protocol\": \"UDP\",\n    \"from_address\": \"0.0.0.0\",\n    \"to_address\": \"184.26.161.130\",\n    \"query_time\": \"2020-05-29 13:46:23.322\",\n    \"response_time\": \"1970-01-01 01:00:00.000\",\n    \"latency\": 0,\n    \"query_type\": \"A\",\n    \"query_name\": \"a13-130.akagtm.org.\",\n    \"return_code\": \"NOERROR\",\n    \"bytes\": 4\n}\n```\n\nKeys description:\n - dns_message: PDNS message type (CLIENT_QUERY, CLIENT_RESPONSE, ...)\n - socket_family: IP protocol used (IPv4 or IPv6)\n - socket_protocol: transport protocol used (UDP or TCP)\n - from_address: the querier IP address\n - to_address: the destination IP address\n - query_time: time of query reception\n - response_time: time of response reception\n - latency: difference between query and response time\n - query_type: the query type (A, AAAA, NS, ...)\n - query_name: the query name\n - return_code: the response code sent back to the client (NXDOMAIN, NOERROR, ...)\n - bytes: size in bytes of the query or response\n\n## PowerDNS configuration\n\nYou need to configure dnsdist or pdns-recursor to active remote logging.\n \n### dnsdist\n\nConfigure the dnsdist `/etc/dnsdist/dnsdist.conf` and add the following lines\nSet the newRemoteLogger function with the address of your pdns_protobuf_receiver\ninstance.\n\n```\nrl = newRemoteLogger(\"10.0.0.97:50001\")\naddAction(AllRule(),RemoteLogAction(rl))\naddResponseAction(AllRule(),RemoteLogResponseAction(rl))\n```\n\nRestart dnsdist.\n\n### pdns-recursor\n\nConfigure the powerdns recursor `/etc/pdns-recursor/recursor.conf` and add the following line\n\n```\nlua-config-file=/etc/pdns-recursor/recursor.lua\n```\n\nCreate the LUA file `/etc/pdns-recursor/recursor.lua`\nSet the protobufServer or outgoingProtobufServer functions with the address of your pdns_protobuf receiver instance.\n\n```\nprotobufServer(\"10.0.0.97:50001\", {logQueries=true,\n                                   logResponses=true,\n                                   exportTypes={'A', 'AAAA',\n                                                'CNAME', 'MX', \n                                                'PTR', 'NS',\n                                                'SPF', 'SRV',\n                                                'TXT'}} )\noutgoingProtobufServer(\"10.0.0.97:50001\",  {logQueries=true,\n                                            logResponses=true,\n                                            exportTypes={'A', 'AAAA',\n                                                         'CNAME', 'MX',\n                                                         'PTR', 'NS',\n                                                         'SPF', 'SRV',\n                                                         'TXT'}})\n```\n\nRestart the recursor.\n\n## About\n\n| | |\n| ------------- | ------------- |\n| Original Author |  Denis Machard \u003cd.machard@gmail.com\u003e |\n| | |\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpowerdns%2Fpdns-protobuf-receiver","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpowerdns%2Fpdns-protobuf-receiver","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpowerdns%2Fpdns-protobuf-receiver/lists"}