{"id":17744093,"url":"https://github.com/thomasvincent/snmp-bind9-statistics","last_synced_at":"2026-01-12T07:38:28.023Z","repository":{"id":235679811,"uuid":"787223992","full_name":"thomasvincent/snmp-bind9-statistics","owner":"thomasvincent","description":"SNMP monitoring agent for BIND9 DNS servers - Exposes statistics via SNMP for integration with Nagios, Zabbix, PRTG","archived":false,"fork":false,"pushed_at":"2025-11-25T23:28:07.000Z","size":40,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-11-27T22:13:32.257Z","etag":null,"topics":["bind","bind9","devops","dns","dns-server","infrastructure-monitoring","metrics","monitoring","nagios","network-monitoring","perl","snmp","statistics","sysadmin","zabbix"],"latest_commit_sha":null,"homepage":"https://github.com/thomasvincent/snmp-bind9-statistics","language":"Perl","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/thomasvincent.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2024-04-16T05:57:20.000Z","updated_at":"2025-11-25T23:28:11.000Z","dependencies_parsed_at":"2024-04-24T08:15:23.049Z","dependency_job_id":"29e94c0d-59d4-48ec-89d4-89a1a31fb71e","html_url":"https://github.com/thomasvincent/snmp-bind9-statistics","commit_stats":null,"previous_names":["thomasvincent/snmp-bind9-statistics"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/thomasvincent/snmp-bind9-statistics","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thomasvincent%2Fsnmp-bind9-statistics","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thomasvincent%2Fsnmp-bind9-statistics/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thomasvincent%2Fsnmp-bind9-statistics/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thomasvincent%2Fsnmp-bind9-statistics/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/thomasvincent","download_url":"https://codeload.github.com/thomasvincent/snmp-bind9-statistics/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thomasvincent%2Fsnmp-bind9-statistics/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28336612,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-12T06:09:07.588Z","status":"ssl_error","status_checked_at":"2026-01-12T06:05:18.301Z","response_time":98,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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","bind9","devops","dns","dns-server","infrastructure-monitoring","metrics","monitoring","nagios","network-monitoring","perl","snmp","statistics","sysadmin","zabbix"],"created_at":"2024-10-26T06:41:56.174Z","updated_at":"2026-01-12T07:38:28.018Z","avatar_url":"https://github.com/thomasvincent.png","language":"Perl","funding_links":[],"categories":[],"sub_categories":[],"readme":"# SNMP BIND9 Statistics\n\n[![Perl](https://img.shields.io/badge/Perl-5.10%2B-blue)](https://www.perl.org/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![GitHub release](https://img.shields.io/github/v/release/thomasvincent/snmp-bind9-statistics)](https://github.com/thomasvincent/snmp-bind9-statistics/releases)\n[![Maintenance](https://img.shields.io/badge/Maintained%3F-yes-green.svg)](https://github.com/thomasvincent/snmp-bind9-statistics/graphs/commit-activity)\n\nA comprehensive Perl-based monitoring solution for BIND9 DNS servers that exposes statistics via SNMP for integration with network monitoring systems.\n\n## 🚀 Overview\n\nSNMP BIND9 Statistics is a production-ready tool that bridges the gap between BIND9's built-in statistics and SNMP-based monitoring infrastructure. It collects detailed DNS server metrics using `rndc stats` and exposes them through SNMP, enabling seamless integration with monitoring platforms like Nagios, Zabbix, PRTG, and others.\n\n## ✨ Features\n\n- 📊 **Comprehensive Statistics Collection**\n  - Query types (A, AAAA, MX, PTR, TXT, etc.)\n  - Response codes and error rates\n  - Cache hit/miss ratios\n  - Zone transfer statistics\n  - Resolver performance metrics\n\n- 🔄 **Intelligent Polling**\n  - Configurable polling intervals\n  - Caching mechanism to reduce system load\n  - Force refresh capability\n  - Automatic statistics file rotation handling\n\n- 🛡️ **Enterprise-Ready**\n  - SNMP v2c support\n  - Custom OID mapping\n  - Comprehensive error handling\n  - Detailed logging with Log4perl\n  - Signal handling for graceful shutdown\n\n- 🔧 **Flexible Configuration**\n  - INI-based configuration files\n  - Environment variable support\n  - Command-line parameter overrides\n  - Multiple BIND9 instance support\n\n## 📋 Requirements\n\n### System Requirements\n- **Operating System**: Linux/Unix with BIND9\n- **Perl**: Version 5.10 or higher\n- **BIND9**: With `rndc` configured and operational\n- **Privileges**: Read access to BIND9 statistics file\n\n### Perl Modules\n```bash\n# Required modules\nConfig::IniFiles\nNet::SNMP\nFile::Slurp\nLog::Log4perl\nFindBin\nTime::HiRes\nScalar::Util\nPOSIX\n\n# Test modules (for development)\nTest::More\nTest::Warn\nFile::Temp\n```\n\n## 📦 Installation\n\n### From GitHub\n```bash\n# Clone the repository\ngit clone https://github.com/thomasvincent/snmp-bind9-statistics.git\ncd snmp-bind9-statistics\n\n# Install Perl dependencies using CPAN\ncpan Config::IniFiles Net::SNMP File::Slurp Log::Log4perl\n\n# Or using cpanm (recommended)\ncpanm Config::IniFiles Net::SNMP File::Slurp Log::Log4perl\n\n# Make the script executable\nchmod +x bin/snmp_bind9_stats.pl\n```\n\n### Using Makefile.PL\n```bash\nperl Makefile.PL\nmake\nmake test\nsudo make install\n```\n\n## ⚙️ Configuration\n\nCreate a configuration file `config.ini`:\n\n```ini\n[general]\n# Path to BIND9 statistics file\nstats_file = /var/cache/bind/named.stats\n\n# Command to generate statistics\nrndc_command = rndc stats\n\n# Logging level (DEBUG, INFO, WARN, ERROR)\nlog_level = INFO\n\n# Statistics polling interval in seconds\npoll_interval = 300\n\n[snmp]\n# SNMP community string\ncommunity = public\n\n# SNMP listening port\nport = 161\n\n# Agent bind address (0.0.0.0 for all interfaces)\nagent_addr = 0.0.0.0\n```\n\n### Environment Variables\nYou can override configuration using environment variables:\n```bash\nexport BIND9_STATS_FILE=/custom/path/named.stats\nexport SNMP_COMMUNITY=secret\nexport SNMP_PORT=1161\n```\n\n## 🚀 Usage\n\n### Basic Usage\n```bash\n# Run with default configuration\n./bin/snmp_bind9_stats.pl\n\n# Specify custom configuration file\n./bin/snmp_bind9_stats.pl --config=/etc/bind9-snmp/config.ini\n\n# Display help\n./bin/snmp_bind9_stats.pl --help\n\n# Show version\n./bin/snmp_bind9_stats.pl --version\n```\n\n### Running as a Service\n\n#### Systemd Service\nCreate `/etc/systemd/system/bind9-snmp.service`:\n```ini\n[Unit]\nDescription=SNMP BIND9 Statistics Agent\nAfter=network.target named.service\n\n[Service]\nType=simple\nUser=bind\nExecStart=/usr/local/bin/snmp_bind9_stats.pl --config=/etc/bind9-snmp/config.ini\nRestart=on-failure\nRestartSec=10\n\n[Install]\nWantedBy=multi-user.target\n```\n\nEnable and start the service:\n```bash\nsudo systemctl daemon-reload\nsudo systemctl enable bind9-snmp\nsudo systemctl start bind9-snmp\n```\n\n#### Init.d Script (Legacy Systems)\n```bash\nsudo cp contrib/init.d/bind9-snmp /etc/init.d/\nsudo chmod +x /etc/init.d/bind9-snmp\nsudo update-rc.d bind9-snmp defaults\nsudo service bind9-snmp start\n```\n\n## 📊 SNMP OID Mapping\n\nThe tool uses the following OID structure:\n\n```\nBase OID: 1.3.6.1.4.1.99999.1\n\nQuery Statistics (1.3.6.1.4.1.99999.1.1.*)\n├── .1 = incoming_queries_A\n├── .2 = incoming_queries_AAAA\n├── .3 = incoming_queries_NS\n├── .4 = incoming_queries_MX\n├── .5 = incoming_queries_PTR\n├── .6 = incoming_queries_TXT\n├── .7 = incoming_queries_SOA\n└── .8 = incoming_queries_CNAME\n\nName Server Statistics (1.3.6.1.4.1.99999.1.2.*)\n├── .1 = queries_resulted_in_successful_answer\n├── .2 = queries_resulted_in_authoritative_answer\n├── .3 = queries_resulted_in_non_authoritative_answer\n├── .4 = queries_resulted_in_nxrrset\n├── .5 = queries_resulted_in_SERVFAIL\n├── .6 = queries_resulted_in_NXDOMAIN\n├── .7 = queries_caused_recursion\n└── .8 = duplicate_queries_received\n\nResolver Statistics (1.3.6.1.4.1.99999.1.3.*)\n├── .1 = IPv4_queries_sent\n├── .2 = IPv6_queries_sent\n├── .3 = query_timeouts\n├── .4 = query_errors\n└── .5 = EDNS0_query_failures\n```\n\n### Querying via SNMP\n```bash\n# Get all statistics\nsnmpwalk -v2c -c public localhost 1.3.6.1.4.1.99999.1\n\n# Get specific statistic\nsnmpget -v2c -c public localhost 1.3.6.1.4.1.99999.1.1.1\n\n# Get query type statistics\nsnmpwalk -v2c -c public localhost 1.3.6.1.4.1.99999.1.1\n```\n\n## 🧪 Testing\n\n### Unit Tests\n```bash\n# Run all unit tests\nprove -r t/unit\n\n# Run specific test file\nprove t/unit/01_statistics.t\n\n# Run with verbose output\nprove -v t/unit/*.t\n```\n\n### Integration Tests\n```bash\n# Requires running BIND9 instance\nprove -r t/integration\n\n# Test SNMP functionality\nperl t/integration/02_snmp.t\n```\n\n### Manual Testing\n```bash\n# Test statistics collection\nperl -I lib -e 'use SNMP::BIND9::Statistics; my $s = SNMP::BIND9::Statistics-\u003enew(); print Dumper($s-\u003eget_all_stats());'\n\n# Test SNMP agent\nsnmpwalk -v2c -c public localhost:1161 1.3.6.1.4.1.99999.1\n```\n\n## 🔍 Monitoring Integration\n\n### Nagios/Icinga\n```bash\n# Check plugin example\ncheck_snmp -H localhost -C public -o 1.3.6.1.4.1.99999.1.2.5 -w 100 -c 200\n```\n\n### Zabbix Template\nImport the provided Zabbix template from `contrib/zabbix/bind9-snmp-template.xml`\n\n### PRTG Custom Sensor\nUse the SNMP Custom Advanced sensor with the provided OIDs\n\n## 🐛 Troubleshooting\n\n### Common Issues\n\n1. **Permission Denied on Stats File**\n   ```bash\n   # Check file permissions\n   ls -l /var/cache/bind/named.stats\n   \n   # Fix permissions\n   sudo chown bind:bind /var/cache/bind/named.stats\n   ```\n\n2. **SNMP Port Already in Use**\n   ```bash\n   # Check what's using port 161\n   sudo netstat -tulpn | grep 161\n   \n   # Use alternative port in config\n   port = 1161\n   ```\n\n3. **rndc Command Fails**\n   ```bash\n   # Test rndc manually\n   rndc stats\n   \n   # Check rndc configuration\n   rndc-confgen -a\n   ```\n\n4. **No Statistics Generated**\n   ```bash\n   # Enable statistics in named.conf\n   statistics-channels {\n       inet 127.0.0.1 port 8053 allow { 127.0.0.1; };\n   };\n   ```\n\n### Debug Mode\n```bash\n# Run with debug logging\nperl bin/snmp_bind9_stats.pl --config=config.ini 2\u003e\u00261 | tee debug.log\n\n# Check log output\ntail -f /var/log/bind9-snmp.log\n```\n\n## 📈 Performance Considerations\n\n- **Polling Interval**: Default 300 seconds, adjust based on monitoring needs\n- **Cache Duration**: Statistics are cached between polls to reduce load\n- **File I/O**: Stats file is read only when needed\n- **Memory Usage**: Typically under 20MB RSS\n- **CPU Usage**: Minimal, spike only during statistics collection\n\n## 🤝 Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\n1. Fork the repository\n2. Create your feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit your changes (`git commit -m 'feat: add amazing feature'`)\n4. Push to the branch (`git push origin feature/amazing-feature`)\n5. Open a Pull Request\n\n### Development Setup\n```bash\n# Install development dependencies\ncpanm Test::More Test::Warn Test::Pod Test::Pod::Coverage\n\n# Run full test suite\nmake test\n\n# Check code coverage\ncover -test\n```\n\n## 📄 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## 🔒 Security\n\nPlease see our [Security Policy](SECURITY.md) for details on reporting vulnerabilities.\n\n## 👨‍💻 Author\n\n**Thomas Vincent**\n- GitHub: [@thomasvincent](https://github.com/thomasvincent)\n\n## 🙏 Acknowledgments\n\n- BIND9 development team for the excellent DNS server\n- Perl community for the robust SNMP modules\n- Contributors and users of this project\n\n## 📚 Resources\n\n- [BIND9 Documentation](https://bind9.readthedocs.io/)\n- [Net::SNMP Documentation](https://metacpan.org/pod/Net::SNMP)\n- [SNMP OID Registry](http://www.oid-info.com/)\n- [Project Wiki](https://github.com/thomasvincent/snmp-bind9-statistics/wiki)\n\n## 🗺️ Roadmap\n\n- [ ] SNMP v3 support with authentication\n- [ ] Prometheus exporter alternative\n- [ ] Web-based statistics dashboard\n- [ ] Docker container support\n- [ ] Automated installer script\n- [ ] Performance metrics collection\n- [ ] Historical data storage\n- [ ] Alert threshold configuration\n\n---\n\nFor more information, bug reports, or feature requests, please visit the [GitHub repository](https://github.com/thomasvincent/snmp-bind9-statistics).","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthomasvincent%2Fsnmp-bind9-statistics","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fthomasvincent%2Fsnmp-bind9-statistics","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthomasvincent%2Fsnmp-bind9-statistics/lists"}