Troubleshooting Guide
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
The Troubleshooting Guide provides structured procedures for diagnosing and resolving failures within the hardened DNS infrastructure on Parrot OS. This system incorporates Unbound as a local recursive resolver with DNS over TLS (DoT), DNSSEC validation, and immutable file protections to prevent unauthorized modifications by services like NetworkManager or Portmaster.
The guide covers manual status verification, automated monitoring alerts, and emergency restoration procedures. It is designed to assist administrators in identifying whether a failure is service-based (Unbound), configuration-based (resolv.conf), or transport-based (TLS/853).
Diagnostic Workflow
The project provides several tools to identify the current state of the DNS subsystem. Troubleshooting should begin with a status check to determine if the hardening flags are active or if the system has defaulted to an unencrypted state.
Primary Status Indicators
| Command | Purpose | Expected Result |
|---|---|---|
sudo ./scripts/dns_status.sh | Comprehensive hardening check | Status: HARDENED |
lsattr /etc/resolv.conf | Check file write protection | ----i--------- |
dig @127.0.0.1 +dnssec google.com | Verify DNSSEC | Presence of ad flag |
sudo ss -tupn | grep :853 | Verify encrypted upstream | Established TLS connections |
Sources: scripts/dns_status.sh:13-58, README.md:275-300, UNBOUND_TLS_STATUS.md:5-25
Automated Monitoring and Alerts
Periodic monitoring is performed by dns_monitor.sh and dns_alert.sh. These scripts track state changes and log compromises, such as the removal of the immutable flag from /etc/resolv.conf or the failure of the Unbound service.
This diagram illustrates the logic used by the monitoring suite to detect system drift or compromise.
Sources: scripts/dns_alert.sh:18-40, scripts/dns_monitor.sh:10-40, MONITORING.md:65-95
Emergency Restoration
When DNS resolution fails completely or configuration becomes corrupted, the dns_restore.sh script provides a rapid recovery mechanism. It is designed to restore basic connectivity in under 30 seconds by bypassing hardened configurations.
Restoration Steps
- Service Suspension: The script stops
unboundandsystemd-resolvedto prevent port conflicts and interference during restoration. - Configuration Backup: Current states of
/etc/resolv.conf,/etc/unbound/unbound.conf, and/etc/systemd/resolved.confare archived in/root/dns_backups/backup_TIMESTAMP/. - Immutable Flag Removal: The kernel-level immutable flag (
chattr -i) is removed from/etc/resolv.confto allow modification. - Resolver Reset: A standard
resolv.confis generated using public resolvers (Cloudflare, Quad9, Google). - Service Masking: problematic services are masked to prevent them from restarting and overriding the emergency settings.
Sources: scripts/dns_restore.sh:42-105, DNS_Hardening_Complete_Guide.md:60-110
Restoration Logic Flow
The sequence demonstrates the prioritized recovery path to ensure network reachability is restored before attempting any re-hardening.
Sources: scripts/dns_restore.sh:42-150
Service Specific Issues
Unbound Resolver Failures
If the local resolver at 127.0.0.1 is not responding but network connectivity is present, the issue typically resides in the Unbound configuration or service state.
- Config Validation: Run
sudo unbound-checkconfto identify syntax errors in/etc/unbound/unbound.conf. - Port Conflicts: Use
sudo netstat -tulpn | grep :53to ensure no other service (likednsmasqorsystemd-resolved) is bound to the DNS port. - Logs: Inspect
journalctl -u unboundfor errors related to certificate bundles or trust anchor files (/var/lib/unbound/root.key).
Sources: DNS_Hardening_Complete_Guide.md:164-180, README.md:200-215
DNS over TLS (DoT) and Fallback
The system is configured to prioritize TLS-encrypted queries to upstream providers on port 853.
- On-Demand Connections: TLS connections are established on-demand. If
ss -tnp | grep :853shows no output, run a few queries (e.g.,dig google.com) to trigger the connection. - Validation: The
dns_tls_monitor.shscript checks if the system is bypassing Unbound and using unencrypted fallback. If theadflag is missing fromdigresults, DNSSEC validation is failing, which may indicate a Man-in-the-Middle (MITM) attempt or local clock desynchronization.
Sources: UNBOUND_TLS_STATUS.md:40-75, scripts/dns_tls_monitor.sh:25-50
Conclusion
Troubleshooting the dns-hardening-parrot system requires a tiered approach, starting with the automated status tools to identify if the hardening features (immutable flags and Unbound) are active. In the event of a total failure, the emergency restoration script provides a fail-safe path to restore connectivity, allowing for incremental re-application of security layers once the root cause is identified.