mdnsd - embeddable Multicast DNS Daemon

• About
• Features
• Usage
  • Service Records
  • Resolving .local Names
  • Browsing with mquery
• Build & Install
• Origin & References

About

mdnsd is a small Multicast DNS and DNS-SD (service discovery) responder and library for advertising hosts and services on the local link. It descends from Jeremie Miller's original mDNS/mDNS-SD daemon.

Download a versioned relased tarball (not a GitHub zip) to unlock a fully supported version. Hardcore devs. can proceed to clone the GIT repository, see below for help.

Features

• Dual-stack: answers over IPv4 (224.0.0.251) and IPv6 (ff02::fb), with A and AAAA records for the host and its services.
• RFC 6763 (DNS-SD) compliant. Service PTR records point at the service instance, so they show up in avahi-browse, mdns-scan, and the like. Responses bundle the matching SRV, TXT, and address records in the additional section, so clients skip the follow-ups. Key-only TXT attributes (boolean flags) work too.
• Multiple addresses per interface, with all of a host's services under one host name.
• Tracks interface and address changes in real time over netlink, no poll cycle.
• A small embeddable C library (libmdnsd), the mdnsd daemon, and the mquery scan/debug tool.
• Runs on GNU/Linux and the BSDs.

Usage

mdnsd by default reads service definitions from /etc/mdns.d/*, but a different path can be given, which may be a directory or a single file.

Usage: mdnsd [-hnsv] [-g GROUP] [-H NAME] [-i IFACE] [-l LEVEL]
             [-p FILE] [-t TTL] [-u USER] [PATH]

    -g GROUP  Group to drop privileges to after start
    -H NAME   Hostname to advertise, default: system hostname
    -h        This help text
    -i IFACE  Announce services only on this interface, default: all
    -l LEVEL  Set log level: none, err, notice (default), info, debug
    -n        Run in foreground, do not detach from controlling terminal
    -p FILE   Path to pid file, default: /run/mdnsd.pid
    -s        Use syslog even if running in foreground
    -t TTL    Set TTL of mDNS packets, default: 1 (link-local only)
    -u USER   User to drop privileges to after start
    -v        Show program version

Bug report address: https://github.com/troglobit/mdnsd/issues

By default mdnsd daemonizes, detaches from the controlling terminal and continues running in the background, logging errors (or debug messages if enabled) to the system log. There is no output to be expected. On GNU/Linux, use mdns-scan, the bundled mquery tool, or Wireshark to verify your setup. Other operating systems have their own set of tools for mDNS-SD and mdnsd may not even have a place there.

mdnsd runs on all multicast enabled system interfaces. It can be limited to run on only one using the -i IFACE command line option. Starting mdnsd early in the boot process, when the interface may not yet have acquired an IP address, or the interface itself may not even exist yet, is fine; mdnsd tracks interface and address changes in real time over netlink and (re)configures itself as they appear.

mdnsd needs no special privileges to answer over mDNS, so it can run as an unprivileged user. Either start it directly as that user, or start it as root and let it drop with -u USER (and optionally -g GROUP). When dropping, point -p FILE at a directory the user may write to. The one privileged operation is the -i IFACE filter: it uses SO_BINDTODEVICE, which needs the CAP_NET_RAW capability. Grant it out-of-band, e.g. by uncommenting AmbientCapabilities=CAP_NET_RAW in the bundled systemd unit; without it mdnsd still runs, but listens on all interfaces and logs a warning.

See the file API.md for pointers on how to use the mDNS library.

Service Records

This section provides a couple of service record examples. The syntax of the files is fairly free form. Optional directives: name, txt, target, and cname. See the mdnsd.service(5) manual for the full file format; in particular target sets the host the service's SRV record points to, while the service PTR always points to the instance.

You need at least one service record for mdnsd to respond to queries from, e.g., mdns-scan.

FTP service example:

# /etc/mdns.d/ftp.service -- mDNS-SD advertisement of FTP service
name Troglobit FTP Server
type _ftp._tcp
port 21
txt server=uftpd
txt version=2.6
cname ftp.local

HTTP service example:

# /etc/mdns.d/http.service -- mDNS-SD advertisement of HTTP service
name Troglobit HTTP Server
type _http._tcp
port 80
txt server=merecat
txt version=2.31
cname home.local

SSH service example:

# /etc/mdns.d/http.service -- mDNS-SD advertisement of SSH service
name Dropbear SSH Server
type _ssh._tcp
port 22

Resolving .local Names

mdnsd advertises this host and answers queries for it; it does not make the system resolver mDNS-aware. Resolving .local names on the host, e.g., ping foo.local or getaddrinfo(), needs a resolver that speaks mDNS itself.

libnss-mdns does not, despite the name. It sends no mDNS of its own; it forwards every lookup to avahi-daemon over a UNIX socket and fails when that daemon is not running. So it currently cannot (yet) pair with mdnsd to resolve .local without Avahi.

Run either mdnsd or avahi-daemon, not both; two responders on the same link would answer over each other.

Browsing with mquery

The bundled mquery tool discovers and resolves services on the local link, a bit like avahi-browse. Give it a service type or a host name; the .local. domain is implied.

mquery                     # browse all service types on the link
mquery _http._tcp          # list instances of a service type
mquery -t 33 NAME          # resolve an instance's host and port (SRV)
mquery -t 16 NAME          # show a service's TXT metadata
mquery -t 1  host          # resolve a host's address (-t 28 for IPv6)
mquery -D                  # scan and resolve into a device table
mquery -d host             # show one device in detail

The -D and -d modes print their table when you stop the scan with Ctrl-C, or automatically with -T (quiet timeout) or -w SEC. See the mquery(1) manual for the full list of record types and options.

Build & Install

This project is built for and developed on GNU/Linux systems, but should work on any UNIX[^1] like system. Use the standard GNU configure script to create a Makefile for your system and then call make.

$ ./configure
$ make all
$ make install
...

Users who checked out the source from GitHub must run ./autogen.sh first to create the configure script. This requires GNU autotools and pkg-config to be installed on the build system. For the test suite you also need libcmocka-dev.

IPv6 support is built by default; pass --disable-ipv6 to leave it out. For resolving .local names on the host, see Resolving .local Names above.

If you install to the default location used by the configure script, the library is installed in /usr/local/lib, which may not be in the default search path for your system. Depending on the C library used, the file /etc/ld.so.conf may exist (there may also be a sub-directory). If /usr/local/lib is already listed there, you may need to update the cache:

$ ldconfig -v |grep mdnsd
...

If you don't get any output from the above command, the ld.so.conf needs updating, or you may not be using the GNU C library.

[^1]: Builds and runs fine on: FreeBSD, NetBSD, OpenBSD, DragonFly BSD, and Illumos/SmartOS.

Origin & References

This mDNS-SD implementation was developed by Jeremie Miller in 2003, originally announced on the rendezvous-dev mailing list. The original name was 'mhttp'. It has many forks and has been used by many other applications over the years.

The GitHub project is an attempt by Joachim Wiberg to clean up the original code base, develop it further, and maintain it for the long haul under the name mdnsd.

Copyright (c) 2003  Jeremie Miller <jer@jabber.org>
Copyright (c) 2016-2026  Joachim Wiberg <troglobit@gmail.com>
All rights reserved.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met:
    * Redistributions of source code must retain the above copyright
      notice, this list of conditions and the following disclaimer.
    * Redistributions in binary form must reproduce the above copyright
      notice, this list of conditions and the following disclaimer in the
      documentation and/or other materials provided with the distribution.
    * Neither the name of the copyright holders nor the names of its
      contributors may be used to endorse or promote products derived from
      this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY
DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Contributing to mdnsd

We welcome any and all help in the form of bug reports, fixes, patches for new features, preferably as GitHub pull requests. Other methods are of course also possible: emailing the maintainer a patch or even a raw file, or simply emailing a feature request or an alert of a problem. However, email questions/requests/alerts always risk memory exhaustion on the part of the maintainer(s).

If you are unsure of what to do, or how to implement an idea or bug fix, open an issue with the title "[RFC: Unsure if this is a bug ... ?", or similar, so we can discuss it. Talking about the code first is the best way to get started before submitting a pull request.

Either way, when sending an email, patch, or pull request, start by stating the version the change is made against, what it does, and most importanyl -- why.

Please take care to ensure you follow the project coding style and the commit message format. If you follow these recommendations you help the maintainer(s) and make it easier for them to include your code.

Coding Style

Tip: Always submit code that follows the style of surrounding code!

First of all, lines are allowed to be longer than 72 characters these days. In fact, there exist no enforced maximum, but keeping it around 100 chars is OK.

The coding style itself is otherwise strictly Linux KNF.

Commit Messages

Commit messages exist to track why a change was made. Try to be as clear and concise as possible in your commit messages, and always, be proud of your work and set up a proper GIT identity for your commits:

git config --global user.name "Jane Doe"
git config --global user.email jane.doe@example.com

Example commit message from the Pro Git online book, notice how git commit -s is used to automatically add a Signed-off-by:

Brief, but clear and concise summary of changes

More detailed explanatory text, if necessary.  Wrap it to about 72
characters or so.  In some contexts, the first line is treated as
the subject of an email and the rest of the text as the body.  The
blank line separating the ummary from the body is critical (unless
you omit the body entirely); tools like rebase can get confused if
you run the two together.

Further paragraphs come after blank lines.

 - Bullet points are okay, too

 - Typically a hyphen or asterisk is used for the bullet, preceded
   by a single space, with blank lines in between, but conventions
   vary here

Signed-off-by: Jane Doe <jane.doe@example.com>

Code of Conduct

It is expected of everyone engaging in the project to, in the words of Bill & Ted; be excellent to each other.

Contributor Covenant Code of Conduct

Our Pledge

We as members, contributors, and leaders pledge to make participation in our community a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, religion, or sexual identity and orientation.

We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community.

Our Standards

Examples of behavior that contributes to a positive environment for our community include:

• Demonstrating empathy and kindness toward other people
• Being respectful of differing opinions, viewpoints, and experiences
• Giving and gracefully accepting constructive feedback
• Accepting responsibility and apologizing to those affected by our mistakes, and learning from the experience
• Focusing on what is best not just for us as individuals, but for the overall community

Examples of unacceptable behavior include:

• The use of sexualized language or imagery, and sexual attention or advances of any kind
• Trolling, insulting or derogatory comments, and personal or political attacks
• Public or private harassment
• Publishing others' private information, such as a physical or email address, without their explicit permission
• Other conduct which could reasonably be considered inappropriate in a professional setting

Enforcement Responsibilities

Community leaders are responsible for clarifying and enforcing our standards of acceptable behavior and will take appropriate and fair corrective action in response to any behavior that they deem inappropriate, threatening, offensive, or harmful.

Community leaders have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, and will communicate reasons for moderation decisions when appropriate.

Scope

This Code of Conduct applies within all community spaces, and also applies when an individual is officially representing the community in public spaces. Examples of representing our community include using an official e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event.

Enforcement

Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the community leaders responsible for enforcement at troglobit+mdnsd@gmail.com. All complaints will be reviewed and investigated promptly and fairly.

All community leaders are obligated to respect the privacy and security of the reporter of any incident.

Enforcement Guidelines

Community leaders will follow these Community Impact Guidelines in determining the consequences for any action they deem in violation of this Code of Conduct:

1. Correction

Community Impact: Use of inappropriate language or other behavior deemed unprofessional or unwelcome in the community.

Consequence: A private, written warning from community leaders, providing clarity around the nature of the violation and an explanation of why the behavior was inappropriate. A public apology may be requested.

2. Warning

Community Impact: A violation through a single incident or series of actions.

Consequence: A warning with consequences for continued behavior. No interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, for a specified period of time. This includes avoiding interactions in community spaces as well as external channels like social media. Violating these terms may lead to a temporary or permanent ban.

3. Temporary Ban

Community Impact: A serious violation of community standards, including sustained inappropriate behavior.

Consequence: A temporary ban from any sort of interaction or public communication with the community for a specified period of time. No public or private interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, is allowed during this period. Violating these terms may lead to a permanent ban.

4. Permanent Ban

Community Impact: Demonstrating a pattern of violation of community standards, including sustained inappropriate behavior, harassment of an individual, or aggression toward or disparagement of classes of individuals.

Consequence: A permanent ban from any sort of public interaction within the community.

Attribution

This Code of Conduct is adapted from the Contributor Covenant, version 2.0, available at https://www.contributor-covenant.org/version/2/0/code_of_conduct.html.

Community Impact Guidelines were inspired by Mozilla's code of conduct enforcement ladder.

For answers to common questions about this code of conduct, see the FAQ at https://www.contributor-covenant.org/faq. Translations are available at https://www.contributor-covenant.org/translations.

Security Policy

Supported Versions

mdnsd is a small project, as such we have no possibility to support older versions. The only supported version is the latest released on GitHub:

https://github.com/troglobit/mdnsd/releases

Reporting a Vulnerability

Two options:

1. Contact the project's maintainer to report and discuss vulnerabilities (slow)
2. Report using GitHub Security Advisories