Skip to content

Commit 2b3e412

Browse files
jeppestaerkjeppestaerk
committed
🎉 Release of add-on Technitium DNS Server (Host Network) 1.14.1
1 parent c827eda commit 2b3e412

File tree

8 files changed

+396
-0
lines changed

8 files changed

+396
-0
lines changed

‎README.md‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -34,6 +34,19 @@ Self-hosted DNS server with Home Assistant add-on integration.
3434

3535
[:books: Technitium DNS Server add-on documentation][addon-doc-technitium-dns]
3636

37+
### ✓ [Technitium DNS Server (Host Network)][addon-technitium-dns-host]
38+
39+
![Latest Version][technitium-dns-host-version-shield]
40+
![Supports armhf Architecture][technitium-dns-host-armhf-shield]
41+
![Supports armv7 Architecture][technitium-dns-host-armv7-shield]
42+
![Supports aarch64 Architecture][technitium-dns-host-aarch64-shield]
43+
![Supports amd64 Architecture][technitium-dns-host-amd64-shield]
44+
![Supports i386 Architecture][technitium-dns-host-i386-shield]
45+
46+
Self-hosted DNS server with Home Assistant add-on integration (Host Network mode enabled).
47+
48+
[:books: Technitium DNS Server (Host Network) add-on documentation][addon-doc-technitium-dns-host]
49+
3750

3851
## Support
3952

@@ -65,6 +78,15 @@ MIT License - Copyright (c) 2025 Jeppe Stærk
6578
[technitium-dns-armhf-shield]: https://img.shields.io/badge/armhf-no-red.svg
6679
[technitium-dns-armv7-shield]: https://img.shields.io/badge/armv7-no-red.svg
6780
[technitium-dns-i386-shield]: https://img.shields.io/badge/i386-no-red.svg
81+
[addon-technitium-dns-host]: https://github.com/staerk-ha-addons/addon-technitium-dns-host/tree/v1.14.1
82+
[addon-doc-technitium-dns-host]: https://github.com/staerk-ha-addons/addon-technitium-dns-host/blob/v1.14.1/README.md
83+
[technitium-dns-host-issue]: https://github.com/staerk-ha-addons/addon-technitium-dns-host/issues
84+
[technitium-dns-host-version-shield]: https://img.shields.io/badge/version-v1.14.1-blue.svg
85+
[technitium-dns-host-aarch64-shield]: https://img.shields.io/badge/aarch64-yes-green.svg
86+
[technitium-dns-host-amd64-shield]: https://img.shields.io/badge/amd64-yes-green.svg
87+
[technitium-dns-host-armhf-shield]: https://img.shields.io/badge/armhf-no-red.svg
88+
[technitium-dns-host-armv7-shield]: https://img.shields.io/badge/armv7-no-red.svg
89+
[technitium-dns-host-i386-shield]: https://img.shields.io/badge/i386-no-red.svg
6890
[frenck]: https://github.com/frenck
6991
[ha-addons]: https://addons.community/
7092
[license]: https://github.com/staerk-ha-addons/repository/blob/main/LICENSE

‎technitium-dns-host/CHANGELOG.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
**Full Changelog**: https://github.com/staerk-ha-addons/addon-technitium-dns-host/compare/v1.14.1

‎technitium-dns-host/DOCS.md‎

Lines changed: 208 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,208 @@
1+
# 🏠 Home Assistant Add-on: Technitium DNS Server
2+
3+
## 📝 TL;DR
4+
5+
Quick setup and best practices:
6+
7+
### DNS Server Setup
8+
9+
- Use this add-on as your primary DNS server
10+
- Configure your router DNS to use `homeassistant.local` (or Home Assistant IP)
11+
12+
### Local DNS Zone
13+
14+
```plaintext
15+
# Quick zone setup
16+
1. Access via the Web UI
17+
2. Add zone: home.lab
18+
3. Add records:
19+
nas.home.lab. A 192.168.1.10
20+
printer.home.lab A 192.168.1.20
21+
```
22+
23+
## DNS Flow and Protocol Options
24+
25+
> This diagram illustrates how DNS queries flow through your network, showing both unencrypted (🔓) and encrypted (🔐) paths. Local devices can use either standard DNS or secure protocols (DoH/DoT/DoQ) to query the Technitium DNS Server, which then forwards requests to Cloudflare using selected dns_forwarders.
26+
27+
![DNS flow diagram][dns-diagram]
28+
29+
### Key Points
30+
31+
- 🏡 **Local Network**: Devices and router can use any supported protocol
32+
- 🔒 **Security Options**: Choose between standard DNS or encrypted protocols
33+
- 🌐 **Flexible Forwarding**: All protocols supported for external queries
34+
- ⚡ **Modern Standards**: Full support for DoH, DoT, and DoQ
35+
36+
> [!NOTE]
37+
> Port 53 (DNS) is always available for compatibility with standard clients.
38+
39+
## 🔧 Configuration
40+
41+
> [!NOTE]
42+
> When accessing the web interface for the first time:
43+
>
44+
> - **Username:** `admin`
45+
> - **Password:** `admin`
46+
>
47+
> You will be required to change the password on your first login for security purposes.
48+
49+
### 🎯 Best Practices
50+
51+
This add-on is designed to be your primary DNS server, acting as a secure forwarding DNS server that queries external DNS providers using encrypted protocols (DoH or DoT).
52+
53+
Recommended setup:
54+
55+
1. Configure your router to use this DNS server (typically `homeassistant.local` or the IP of your Home Assistant)
56+
2. Or configure individual devices to use this DNS server
57+
3. Use encrypted forwarding (DoH, DoT, or DoQ) to upstream DNS providers
58+
4. Keep query logging enabled for troubleshooting
59+
5. Optionally, set up local DNS zones for your home lab (e.g., `home.lab`, `internal`)
60+
61+
> [!TIP]
62+
> By using this add-on as your DNS server, you get:
63+
>
64+
> - Encrypted DNS queries to external providers
65+
> - Local DNS resolution for your network
66+
> - Query logging for troubleshooting
67+
> - Ability to block unwanted domains
68+
> - Faster response times through caching
69+
> - Custom domain names for local devices
70+
> - Service discovery through DNS records
71+
72+
### 🔌 Port Configuration
73+
74+
| Port | Protocol | Description |
75+
| ---- | -------- | ---------------------------------- |
76+
| 53 | UDP | Standard DNS service |
77+
| 853 | TCP | DNS-over-TLS |
78+
| 853 | UDP | DNS-over-QUIC |
79+
| 443 | TCP | DNS-over-HTTPS (HTTP/1.1 + HTTP/2) |
80+
| 443 | UDP | DNS-over-HTTPS (HTTP/3) |
81+
82+
To change port mappings:
83+
84+
1. Go to the add-on configuration page
85+
2. Scroll to "Network" section
86+
3. Click the port number you want to change
87+
4. Enter new port number (e.g., `8853` for DNS-over-TLS)
88+
5. Click "Save"
89+
90+
> [!NOTE]
91+
> Only port 53 are enabled by default.
92+
93+
### 🏠 Local DNS Zones
94+
95+
Technitium DNS Server can host your own DNS zones for your home lab environment.
96+
97+
#### Setting up a Local Zone
98+
99+
1. Access the web interface at `http://homeassistant.local:5380`
100+
2. Navigate to Zones → Add Zone
101+
3. Enter your desired domain (e.g., `home.lab`, `local.network`)
102+
4. Click "Add"
103+
104+
Example records for your home lab:
105+
106+
```plaintext
107+
# A Records (IPv4)
108+
server1.home.lab. A 192.168.1.10
109+
nas.home.lab. A 192.168.1.20
110+
printer.home.lab. A 192.168.1.30
111+
112+
# CNAME Records (Aliases)
113+
www.home.lab. CNAME server1.home.lab.
114+
files.home.lab. CNAME nas.home.lab.
115+
116+
# TXT Records (Service Information)
117+
home.lab. TXT "v=spf1 ip4:192.168.1.0/24 -all"
118+
_service.home.lab. TXT "location=basement rack=1"
119+
```
120+
121+
### 🏗️ Advanced Configuration
122+
123+
#### Reverse DNS Zone
124+
125+
```plaintext
126+
# Create reverse zone for 192.168.1.0/24
127+
Zone name: 1.168.192.in-addr.arpa
128+
129+
# PTR Records
130+
10 PTR server1.home.lab.
131+
20 PTR nas.home.lab.
132+
30 PTR printer.home.lab.
133+
```
134+
135+
> [!TIP]
136+
> Best practices for local zones:
137+
>
138+
> - Use a dedicated domain suffix (e.g., `.home.lab`, `.internal`)
139+
> - Document all DNS records
140+
> - Use meaningful naming conventions
141+
> - Set appropriate TTL values
142+
> - Regular backups of zone files
143+
144+
## 🔍 Troubleshooting
145+
146+
### ❌ Common Issues
147+
148+
1. **Certificate Issues**
149+
- Check certificate paths are correct
150+
- Verify certificate permissions
151+
- Check logs for certificate conversion errors
152+
153+
2. **Port Conflicts**
154+
- Ensure no other services use ports
155+
- Try alternative ports if needed
156+
- Check firewall settings
157+
158+
3. **DNS Resolution Problems**
159+
- Verify forwarder settings
160+
- Check DNS server logs
161+
- Test with `dig` or `nslookup`
162+
163+
## 💡 Support
164+
165+
Got questions?
166+
167+
- Create an [issue on GitHub][issue] for bug reports, feature requests, or questions
168+
- Add a ⭐️ [star on GitHub][repository] to support the project
169+
170+
## 🤝 Contributing
171+
172+
This is an active open-source project. We welcome contributions from anyone interested in using or improving the code:
173+
174+
- Fork the repository
175+
- Make your changes
176+
- Submit a pull request
177+
- Follow the coding standards
178+
179+
## 👥 Authors & Contributors
180+
181+
The original setup of this repository is by [Jeppe Stærk][staerk].
182+
183+
## 🙏 Acknowledgments
184+
185+
Special thanks to [Franck Nijhof][frenck] and the [Home Assistant Community Add-ons][ha-addons] project for their invaluable work. This add-on heavily relies on their foundation:
186+
187+
- Base container images
188+
- CI, workflows and best practices
189+
- Readme and docs templates
190+
191+
Their open-source contributions make add-ons like this possible.
192+
193+
## ⚠️ Disclaimer
194+
195+
This is a third-party add-on for Home Assistant and not an official add-on. It is provided as-is, without warranty of any kind. While care has been taken in its development, use it at your own risk. Always ensure you have proper backups before making changes to your Home Assistant DNS settings. This add-on is not affiliated with Technitium Software.
196+
197+
## 📄 License
198+
199+
MIT License - Copyright (c) 2025 Jeppe Stærk
200+
201+
[dns-diagram]: https://raw.githubusercontent.com/staerk-ha-addons/addon-technitium-dns/refs/heads/main/images/flowchart-dns.svg
202+
[frenck]: https://github.com/frenck
203+
[issue]: https://github.com/staerk-ha-addons/addon-technitium-dns/issues
204+
[repository]: https://github.com/staerk-ha-addons/repository
205+
[staerk]: https://github.com/staerk-ha-addons
206+
[ha-addons]: https://addons.community/
207+
[duckdns-link]: https://github.com/home-assistant/addons/tree/master/duckdns
208+
[security-link]: https://www.home-assistant.io/docs/configuration/securing/#remote-access

‎technitium-dns-host/README.md‎

Lines changed: 126 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,126 @@
1+
# 🏠 Home Assistant Add-on: Technitium DNS Server (Host Network)
2+
3+
[![GitHub Release][releases-shield]][releases]
4+
![Project Stage][project-stage-shield]
5+
[![License][license-shield]](LICENSE)
6+
7+
8+
> [!TIP]
9+
> ⭐ Love this add-on? Show your support by giving a [star on GitHub!][repository] Every star helps make this project more visible and encourages continued development.
10+
11+
> [!IMPORTANT]
12+
> This is the **Host Network** variant of the Technitium DNS Server add-on. It runs with `host_network: true`, which means:
13+
> - The add-on shares the host's network stack directly
14+
> - DNS server is accessible on port 53 without port mapping
15+
> - Better performance and compatibility in some network configurations
16+
> - **Note**: Only install this variant if you specifically need host network mode
17+
>
18+
> For the standard version (without host network), see [addon-technitium-dns](https://github.com/staerk-ha-addons/addon-technitium-dns)
19+
20+
## 🌐 Modern DNS Solution for Home Assistant
21+
22+
A fully featured DNS server for Home Assistant that acts as a secure forwarding DNS server, querying external providers using modern encrypted protocols. Perfect for improving your home network's privacy and security.
23+
24+
## ✨ Features
25+
26+
A fully featured DNS server for Home Assistant that:
27+
28+
- 🔒 Securely forwards DNS queries using DoH/DoT/DoQ
29+
- 🌐 Supports local DNS zones and custom domains
30+
- ⚡ Provides fast DNS caching
31+
- 🛡️ Includes DNS filtering and blocking
32+
33+
## 🏃 Quick Start
34+
35+
1. Click the Home Assistant My button below to add the repository to your Home Assistant instance.
36+
37+
[![Open your Home Assistant instance and show the add add-on repository dialog with a specific repository URL pre-filled.](https://my.home-assistant.io/badges/supervisor_add_addon_repository.svg)](https://my.home-assistant.io/redirect/supervisor_add_addon_repository/?repository_url=https%3A%2F%2Fgithub.com%2Fstaerk-ha-addons%2Frepository)
38+
39+
2. Find the "Technitium DNS Server (Host Network)" add-on in the add-on store.
40+
3. Click "Install" to download the add-on.
41+
4. Click "Start" to start the add-on.
42+
5. Check the logs of the add-on to see if everything went well.
43+
6. Click "Open Web Ui" and login.
44+
45+
> [!NOTE]
46+
> When accessing the web interface for the first time:
47+
>
48+
> - **Username:** `admin`
49+
> - **Password:** `admin`
50+
>
51+
> You will be required to change the password on your first login for security purposes.
52+
53+
## 📖 Documentation
54+
55+
Want to get the most out of this add-on? Our comprehensive documentation covers:
56+
57+
- Detailed setup guides
58+
- Configuration options
59+
- Best practices
60+
- Local DNS hosting
61+
- Troubleshooting
62+
63+
Check the [:books: DOCS.md][docs] for full details.
64+
65+
## DNS Flow and Protocol Options
66+
67+
> This diagram illustrates how DNS queries flow through your network, showing both unencrypted (🔓) and encrypted (🔐) paths. Local devices can use either standard DNS or secure protocols (DoH/DoT/DoQ) to query the Technitium DNS Server, which then forwards requests to Cloudflare using selected dns_forwarders.
68+
69+
![DNS flow diagram][dns-diagram]
70+
71+
### Key Points
72+
73+
- 🏡 **Local Network**: Devices and router can use any supported protocol
74+
- 🔒 **Security Options**: Choose between standard DNS or encrypted protocols
75+
- 🌐 **Flexible Forwarding**: All protocols supported for external queries
76+
- ⚡ **Modern Standards**: Full support for DoH, DoT, and DoQ
77+
78+
## 💡 Support
79+
80+
Got questions?
81+
82+
- Create an [issue on GitHub][issue] for bug reports, feature requests, or questions
83+
- Add a ⭐️ [star on GitHub][repository] to support the project
84+
85+
## 🤝 Contributing
86+
87+
This is an active open-source project. We welcome contributions from anyone interested in using or improving the code:
88+
89+
- Fork the repository
90+
- Make your changes
91+
- Submit a pull request
92+
- Follow the coding standards
93+
94+
## 👥 Authors & Contributors
95+
96+
The original setup of this repository is by [Jeppe Stærk][staerk].
97+
98+
## 🙏 Acknowledgments
99+
100+
Special thanks to [Franck Nijhof][frenck] and the [Home Assistant Community Add-ons][ha-addons] project for their invaluable work. This add-on heavily relies on their foundation:
101+
102+
- Base container images
103+
- CI, workflows and best practices
104+
- Readme and docs templates
105+
106+
Their open-source contributions make add-ons like this possible.
107+
108+
## ⚠️ Disclaimer
109+
110+
This is a third-party add-on for Home Assistant and not an official add-on. It is provided as-is, without warranty of any kind. While care has been taken in its development, use it at your own risk. Always ensure you have proper backups before making changes to your Home Assistant DNS settings. This add-on is not affiliated with Technitium Software.
111+
112+
## 📄 License
113+
114+
MIT License - Copyright (c) 2025 Jeppe Stærk
115+
116+
[dns-diagram]: https://raw.githubusercontent.com/staerk-ha-addons/addon-technitium-dns-host/refs/heads/main/images/flowchart-dns.svg
117+
[docs]: https://github.com/staerk-ha-addons/addon-technitium-dns-host/blob/main/technitium-dns/DOCS.md
118+
[frenck]: https://github.com/frenck
119+
[issue]: https://github.com/staerk-ha-addons/addon-technitium-dns-host/issues
120+
[releases-shield]: https://img.shields.io/github/release/staerk-ha-addons/addon-technitium-dns-host.svg
121+
[releases]: https://github.com/staerk-ha-addons/addon-technitium-dns-host/releases
122+
[repository]: https://github.com/staerk-ha-addons/repository
123+
[staerk]: https://github.com/jepestaerk
124+
[project-stage-shield]: https://img.shields.io/badge/project%20stage-experimental-yellow.svg
125+
[license-shield]: https://img.shields.io/github/license/staerk-ha-addons/addon-technitium-dns-host.svg
126+
[ha-addons]: https://addons.community/

0 commit comments

Comments
 (0)