> For the complete documentation index, see [llms.txt](https://book.bsdcn.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://book.bsdcn.org/ask/flat/chapter-37-servers/di-37.4-jie-ling-pei-zhi-wang-luo-mdns-dns-sd.md).

# 37.4 Zero-Configuration Networking (mDNS/DNS-SD)

Zero-configuration networking ([Zero-configuration networking](https://datatracker.ietf.org/doc/html/rfc6762), also known as *Zeroconf*) is a set of technologies that simplify network configuration, enabling network devices to automatically complete address assignment, domain name resolution, and service discovery without administrator intervention.

This functionality is particularly useful on embedded devices. In some scenarios, users cannot obtain the IP address of a Raspberry Pi through a screen or serial port but need to connect via SSH. Raspberry Pi OS enables the Avahi service by default and supports multicast DNS. In this case, users can directly use `ping raspberrypi.local` to obtain the IP address, or connect directly via SSH to `raspberrypi.local`.

The main components of zero-configuration networking include:

| Component                   | English Name          | Description                                                 |
| --------------------------- | --------------------- | ----------------------------------------------------------- |
| Link-Local Addressing       | Link-Local Addressing | Provides automatic assignment of numeric network addresses  |
| Multicast DNS               | mDNS                  | Provides automatic distribution and resolution of hostnames |
| DNS-Based Service Discovery | DNS-SD                | Provides automatic discovery of service instances           |

A common implementation of Zeroconf is [Avahi](https://avahi.org/). **nss-mdns** enables all tools that use **nsswitch** (The Name Service Switch, NSS) to look up hostnames with the `*.local` suffix via the mDNS protocol.

## Installing Avahi and nss-mdns

Install using pkg:

```sh
# pkg install avahi-app nss_mdns
```

Install using Ports:

```sh
# cd /usr/ports/net/avahi-app/ && make install clean
# cd /usr/ports/dns/nss_mdns/ && make install clean
```

## Configuring the Name Service Switch

dns/nss\_mdns installs the following NSS modules:

```sh
lib/nss_mdns.so.1
lib/nss_mdns_minimal.so.1
lib/nss_mdns4.so.1
lib/nss_mdns4_minimal.so.1
lib/nss_mdns6.so.1
lib/nss_mdns6_minimal.so.1
lib/nss_mdns.so
lib/nss_mdns_minimal.so
lib/nss_mdns4.so
lib/nss_mdns4_minimal.so
lib/nss_mdns6.so
lib/nss_mdns6_minimal.so
```

For descriptions of the above modules, see [avahi/nss-mdns](https://github.com/avahi/nss-mdns).

The **/etc/nsswitch.conf** file is the nsswitch configuration file, with source code located at **lib/libc/net/nsswitch.conf**. The default file content is as follows:

```ini
#
# nsswitch.conf(5) - name service switch configuration file
#
group: compat
group_compat: nis
hosts: files dns
netgroup: compat
networks: files
passwd: compat
passwd_compat: nis
shells: files
services: compat
services_compat: nis
protocols: files
rpc: files
```

To enable mDNS, append `mdns` and `mdns6` after the `hosts: files dns` line.

```ini
hosts: files dns mdns mdns6
```

## Enabling Services

D-Bus is automatically installed as a dependency of Avahi. Set it to start automatically at boot:

```sh
# service dbus enable
```

Start the D-Bus service:

```sh
# service dbus start
```

Set the Avahi daemon to start automatically at boot:

```sh
# service avahi-daemon enable
```

Start the Avahi service:

```sh
# service avahi-daemon start
```

## Testing the Service

Execute the ping command to test the FreeBSD hostname, which will display the IP address.

```powershell
PS C:\Users\ykla> ping ykla

Pinging ykla.local [192.168.179.129] with 32 bytes of data:
Reply from 192.168.179.129: bytes=32 time=6ms TTL=64
Reply from 192.168.179.129: bytes=32 time=1ms TTL=64
Reply from 192.168.179.129: bytes=32 time=3ms TTL=64
Reply from 192.168.179.129: bytes=32 time=3ms TTL=64

Ping statistics for 192.168.179.129:
    Packets: Sent = 4, Received = 4, Lost = 0 (0% loss),
Approximate round trip times in milli-seconds:
    Minimum = 1ms, Maximum = 6ms, Average = 3ms
```

> **Tip**
>
> The `ykla` and `ykla.local` in the above example are placeholders and need to be replaced with actual values.

You can also view the IPv6 address:

```powershell
PS C:\Users\ykla> ping -6 ykla

Pinging ykla.local [fe80::20c:29ff:fe8a:22dc%18] with 32 bytes of data:
Reply from fe80::20c:29ff:fe8a:22dc%18: time=1ms
Reply from fe80::20c:29ff:fe8a:22dc%18: time=3ms
Reply from fe80::20c:29ff:fe8a:22dc%18: time=4ms
Reply from fe80::20c:29ff:fe8a:22dc%18: time=13ms

Ping statistics for fe80::20c:29ff:fe8a:22dc%18:
    Packets: Sent = 4, Received = 4, Lost = 0 (0% loss),
Approximate round trip times in milli-seconds:
    Minimum = 1ms, Maximum = 13ms, Average = 5ms
```

This matches the actual IP address of the FreeBSD host, confirming the configuration is correct.

Connect to the device using SSH:

```powershell
PS C:\WINDOWS\system32> ssh ykla@ykla

FreeBSD 16.0-CURRENT (GENERIC) #0 main-n285005-e9fc0c538264: Mon Apr 13 12:44:54 UTC 2026

Welcome to FreeBSD!

……partial output omitted……
```

> **Tip**
>
> The username `ykla` and hostname `ykla` shown in the examples in this section are for demonstration purposes. Please replace them with the actual username and hostname for your environment.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://book.bsdcn.org/ask/flat/chapter-37-servers/di-37.4-jie-ling-pei-zhi-wang-luo-mdns-dns-sd.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.