Skip to content

Commit 706aa88

Browse files
robotsnhsilamon
andauthored
docs: use flowing verse on debug page explaining DNS server failures (#45141)
Co-authored-by: Simon Lamon <32477463+silamon@users.noreply.github.com>
1 parent 158f641 commit 706aa88

1 file changed

Lines changed: 8 additions & 22 deletions

File tree

source/more-info/unsupported/dns_server.markdown

Lines changed: 8 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -5,28 +5,23 @@ description: "More information on why issues with a DNS server marks the install
55

66
## The issue
77

8-
Home Assistant requires a working DNS server to function. Without one it may be
9-
unable to provide functionality like checking and executing updates, showing
10-
documentation, reach external services required by add-ons and integrations, etc.
8+
Home Assistant requires a working DNS server to function. Without one, it may be unable to provide functionality like checking and executing updates, showing documentation, reaching external services required by add-ons and integrations, and other tasks that depend on internet access.
119

1210
## The solution
1311

14-
The easiest solution is to re-enable the fallback DNS option by executing the following
15-
command in the CLI:
12+
The easiest solution is to re-enable the fallback DNS option by executing the following command in the CLI:
1613

1714
```sh
1815
ha dns options --fallback=true
1916
```
2017

21-
Alternatively review your system issues by executing the following command in the
22-
CLI:
18+
Alternatively review your system issues by executing the following command in the CLI:
2319

2420
```sh
2521
ha resolution info
2622
```
2723

28-
You will see one or more issues with a context of `dns_server`. For each such issue,
29-
take the following actions based on the issue type.
24+
You will see one or more issues with a context of `dns_server`. For each such issue, take the following actions based on the issue type.
3025

3126
### `dns_server_failed`
3227

@@ -36,23 +31,14 @@ take the following actions based on the issue type.
3631

3732
### `dns_server_ipv6_error`
3833

39-
If you see this that means the application you are using for DNS is not handling
40-
A and AAAA requests correctly. You can test this by executing the following commands:
34+
If you see this, that means the application you are using for DNS is not handling A and AAAA requests correctly. You can test this by executing the following commands:
4135

4236
```sh
4337
server="<IP address of DNS server>"
4438
dig "@$server" _checkdns.home-assistant.io +noall +comments +answer A
4539
dig "@$server" _checkdns.home-assistant.io +noall +comments +answer AAAA
4640
```
4741

48-
A DNS server handling A and AAAA requests correctly will respond with status `NOERROR`
49-
for both of those queries even though there are no answers for the AAAA request.
50-
A DNS server mishandling this request will only return a `NOERROR` response for
51-
the first one and will return `NXDOMAIN`, `REFUSED`, `SERVFAIL` or some other error
52-
status for the second.
53-
54-
It is important to use a DNS server that handles this situation correctly since
55-
Home Assistant uses alpine for many of its containers. Alpine follows the DNS spec
56-
and will treat the entire domain as if it can't be resolved if it receives an error
57-
status for either query. Home Assistant will run into many unexpected issues in
58-
this situation, particularly around updates and installing software.
42+
A DNS server handling A and AAAA requests correctly will respond with status `NOERROR` for both of those queries even though there are no answers for the AAAA request. A DNS server mishandling this request will only return a `NOERROR` response for the first one and will return `NXDOMAIN`, `REFUSED`, `SERVFAIL` or some other error status for the second.
43+
44+
It is important to use a DNS server that handles this situation correctly since Home Assistant uses Alpine Linux for many of its containers. Alpine follows the DNS spec and will treat the entire domain as if it can't be resolved if it receives an error status for either query. Home Assistant will run into many unexpected issues in this situation, particularly around updates and installing software.

0 commit comments

Comments
 (0)