AVAHI vs Apple Bonjour: how do DNS-SD TXT records compare (size/encoding quirks) for device onboarding metadata?

Most device onboarding schemes that ride on mDNS/DNS-SD TXT records end up asking the same question: “How much metadata can I pack in here, and are there any format landmines between Avahi on Linux and Apple’s Bonjour implementations?” From a protocol perspective, Avahi and Bonjour both implement DNS-SD as defined in the IETF drafts/RFCs, which means TXT records behave the same on the wire. The differences you’ll care about for onboarding are mostly around practical limits, encoding edge cases, and how you generate those TXT records in each stack.

Below I’ll walk through where the specs are strict, where implementations are pragmatic, and what you should assume when designing onboarding metadata intended to work identically on Avahi-powered Linux devices and Bonjour-based Apple systems.

---

At-a-Glance Comparison

Quick Answer: For cross‑platform device onboarding metadata, treat Avahi and Apple Bonjour TXT records as equivalent: same key/value model, same per‑string size limits, and the same practical recommendations. If your priority is staying on the safe path for HomeKit‑style or mobile clients, Apple’s stricter guidance (<= 400–500 bytes total TXT payload) is often the better design target. For Linux‑first deployments where you generate TXT from /etc/avahi/services XML, Avahi 0.7+ adds convenient binary TXT support but you still need to respect the DNS 255‑byte per‑string limit.

Rank	Option	Best For	Primary Strength	Watch Out For
1	“Common subset” TXT profile	Cross‑platform onboarding (Avahi + Bonjour + other DNS-SD stacks)	Explicitly follows DNS-SD key/value rules, conservative size budget	Requires discipline: no exotic encoding, no oversized values
2	Apple Bonjour TXT conventions	iOS/macOS clients, HomeKit‑style onboarding	Well-documented limits, client libraries rely heavily on TXT metadata	Easy to assume “Apple-only” and overfit to specific apps
3	Avahi + XML + binary TXT	Linux-first fleets with static services in /etc/avahi/services	Simple deployment, supports binary TXT in Avahi ≥ 0.7	Binary TXT is not magically interoperable with all consumers

---

Comparison Criteria

We evaluated Avahi vs Apple Bonjour TXT behavior using three concrete criteria that matter for onboarding:

• Record size & limits: How much data can you realistically store in DNS-SD TXT for device onboarding without running into truncation, interoperability issues, or pathological behavior?
• Encoding and data model quirks: How are key/value pairs represented, how are bytes interpreted, and what happens with non-ASCII or binary data?
• Operational ergonomics on each stack: How you actually define and ship TXT records—in code, in XML, or via compatibility libraries—and what that means for device onboarding flows.

---

DNS-SD TXT basics (what Avahi and Bonjour both follow)

Both Avahi and Apple Bonjour implement the same DNS-SD TXT record model:

• TXT is a set of attributes, each encoded as a separate string.
• Each string is length‑prefixed (one octet) and up to 255 bytes.
• Each attribute is typically key=value or just key (boolean true).
• Keys are case‑insensitive ASCII; values are opaque bytes (traditionally ASCII/UTF‑8, but not enforced by the protocol).

From the DNS layer’s point of view:

• The per-string limit is 255 bytes (hard limit from the DNS wire format).
• The entire TXT RR nominally shares the DNS message size limits (512 bytes without EDNS0, ~64 KB with EDNS0), but in Zeroconf LAN use you should assume a few hundred bytes total if you want reliable behavior across stacks and link layers.

So on the wire, Avahi and Bonjour are interoperable and equivalent. The interesting parts are how each stack guides you to use TXT, and where you can get yourself into trouble when you treat TXT as a generic key/value blob store for onboarding.

---

Size limits: theoretical vs practical for onboarding metadata

Theoretical limits (both Avahi and Bonjour)

• Per attribute: max 255 bytes, including key= and value.
• Per TXT record: constrained by DNS message size, but not usually the bottleneck in LAN scenarios.
• Number of attributes: not formally fixed; you can have many small attributes.

Neither Avahi nor Bonjour change those protocol limits.

Practical limits (where you should actually design)

For device onboarding, you want TXT small enough to:

• Fit comfortably in a single mDNS response.
• Avoid fragmentation at the link layer (especially on Wi‑Fi).
• Be easily parsed by low‑resource clients (IoT, mobile).

Common practice and Apple’s published guidance for Bonjour‑based services converge on:

• Aim for ≤ 400 bytes total TXT payload.
• Keep individual values under ~100 bytes unless you have a specific reason not to.
• Prefer more keys with shorter values over one huge value.

Avahi doesn’t impose a different limit; it simply follows the protocol. But you should not let that tempt you into pushing TXT beyond what Bonjour‑centric clients expect. If you’re targeting both worlds, design TXT with Bonjour’s conservative envelope in mind.

Onboarding‑specific implication

For onboarding metadata (capabilities, supported auth methods, URLs, provisioning hints):

• Don’t store entire configuration documents, JWTs, or large certificates in TXT.
• Use TXT for capabilities and discovery hints, not for bulk configuration.
• Put larger artifacts behind a URI: TXT holds a short api=https://device.local/onboard pointer, not the payload.

Both Avahi and Bonjour will happily shuttle bytes inside 255‑byte strings, but downstream client behavior is your real constraint.

---

Encoding quirks and key/value handling

Key and value representation

Both Avahi and Bonjour adopt the DNS‑SD conventions:

• Keys
  • ASCII, case‑insensitive.
  • Should not be empty.
  • Typically lowercase with simple characters (a-z0-9-).
• Values
  • Opaque byte strings.
  • Commonly UTF‑8 text, but binary is allowed by the spec.
  • May be omitted (just key, meaning “true”).

Most cross‑platform issues arise when you push beyond “short ASCII/UTF‑8 strings” into binary values or non‑UTF‑8 encodings.

Apple Bonjour behavior

On Apple platforms:

• The dns_sd.h API exposes TXT records as raw bytes with explicit lengths.
• Higher‑level frameworks often assume UTF‑8 strings where appropriate.
• The official examples recommend UTF‑8 for human‑readable values and caution against encoding complex structures.

In practice:

• iOS/macOS clients expect TXT values they can decode easily.
• Some frameworks or apps will silently treat non‑UTF‑8 bytes as opaque and never display them.

Avahi behavior

On Linux with Avahi you get multiple integration options:

• D‑Bus API: programmatic registration and browsing; you can pass arbitrary byte arrays as TXT.
• C API (avahi-core, avahi-client): also operates on byte arrays with explicit lengths.
• XML definitions in /etc/avahi/services: static services described via XML.

The key quirk specific to Avahi is around XML:

• Up through Avahi 0.6.x, defining binary TXT via /etc/avahi/services was awkward or not directly supported.
• Avahi 0.7 introduced explicit support for encoding binary (non‑text) TXT records in XML service definitions. This made static publication of non‑ASCII values manageable.

So with Avahi ≥ 0.7, you can safely represent non‑text TXT in XML, as long as you follow the documented encoding scheme (e.g., hex or escaped sequences as supported by the schema).

Onboarding‑specific implications

If you want onboarding TXT records that behave consistently on Bonjour and Avahi:

• Restrict to UTF‑8 text for values whenever possible.
• Use simple, documented key names like ver, model, proto, auth, path.
• Only use binary values if you control both publisher and client, and you’ve verified behavior on both stacks.

You can rely on Avahi to carry binary TXT all the way through, especially with the 0.7+ XML support, but Bonjour‑side code and third‑party clients may not handle those bytes as you expect.

---

Data model for onboarding: what works well in TXT

The “common subset” that works equally well on Avahi and Bonjour for onboarding looks like this:

• Versioning
  • ver=1
• Device or model identification
  • id=ACME-ENV-1234
  • model=acme-sensor-v2
• Onboarding protocol hints
  • proto=ble+https or proto=mdns+https
  • auth=psk or auth=oauth2
• Endpoint pointers
  • path=/onboard
  • api=https://device.local/onboard
• Capability flags
  • tls=1
  • pairing=required

Keep each value short, explicit, and parseable. Avoid:

• Nested JSON in TXT (config={"foo":...}).
• Base64 blobs that approach the 255‑byte per‑string limit.
• Anything where a single key/value string is your critical onboarding artifact.

Both Avahi and Bonjour will interoperate with this style cleanly.

---

Detailed breakdown of the three “options”

To make the trade‑offs concrete, let’s frame three practical “options” for designing TXT records for onboarding, then map how Avahi and Bonjour behave with each.

1. “Common subset” TXT profile (Best overall for cross‑platform onboarding)

This profile intentionally uses only what both Avahi and Bonjour handle in a boring, standards‑driven way: short key/value pairs, ASCII keys, UTF‑8 or ASCII values, and conservative size.

Why it’s top choice: It aligns with the DNS-SD spec limits, with Bonjour guidance, and with Avahi’s implementation details, so you don’t have to special‑case Linux vs Apple behavior.

What it does well:

• Interoperability: Works across Avahi, Apple Bonjour, and other Zeroconf stacks.
  • No binary‑only tricks.
  • No assumptions about client‑side decoding beyond UTF‑8.
• Operational predictability: Safe within the ~400‑byte budget.
  • Easy for mobile apps, desktop clients, and daemons to parse.
  • Easy to debug with standard tools (avahi-browse, dns-sd, mdns-scan).

Tradeoffs & limitations:

• Limited expressiveness: You can’t stuff rich onboarding state into TXT.
  • You’ll point to HTTP or other protocols for full configuration.
  • You must design your onboarding protocol with an extra fetch step.

Decision trigger: Choose this when you want one TXT schema that just works on Avahi‑backed Linux systems and Bonjour‑based Apple devices, and your priority is reliable discovery, not maximal in‑record metadata.

---

2. Apple Bonjour TXT conventions (Best for Apple‑centric ecosystems)

Here you anchor your design in Apple’s documentation and examples, then verify Avahi compatibility rather than the other way around. This is often what you do if iOS/macOS apps are the primary onboarding clients.

Why it’s a strong fit: Apple provides clear guidance and real‑world usage patterns (AirPrint, AirPlay, HomeKit) that treat TXT as a small, structured set of hints.

What it does well:

• Clear constraints: Apple’s ecosystem pushes you toward:
  • Small TXT payloads.
  • Text values meant for app logic and sometimes UI.
  • Stable keys that client frameworks expect.
• Client support: Many Apple frameworks already parse specific TXT keys.
  • In some cases, TXT can influence how the OS shows or filters devices.
  • It’s straightforward to test behavior with Apple’s dns-sd tool and Bonjour Browser apps.

Tradeoffs & limitations:

• Apple‑leaning ecosystem: If you go too far into Apple‑specific keys or behaviors, other DNS-SD consumers might not make sense of your metadata.
• Slightly less attention to binary TXT: While allowed, binary values are less common in Apple examples and tooling, so misconfigurations can be harder to spot.

Avahi compatibility:

• Avahi, via its D‑Bus and C APIs, is fully capable of publishing and reading these same TXT records.
• As long as you respect the spec limits, Avahi will happily interoperate with Apple‑designed TXT profiles.

Decision trigger: Choose this if Apple devices are the primary onboarding clients and Linux/Avahi is there mainly as another publisher/responder. Design to Apple’s expectations and confirm that Avahi publishes the same bits.

---

3. Avahi + XML + binary TXT (Best for Linux‑first, static services)

This profile takes advantage of Avahi’s XML service definitions in /etc/avahi/services and the Avahi 0.7 feature that allows encoding of binary TXT records.

Why it stands out: For fleets of Linux devices or appliances, static XML‑defined services let you ship onboarding metadata without custom D‑Bus publishers, and you get a clean way to include non‑text data if you control the clients.

What it does well:

• Simple deployment: Drop an XML file into /etc/avahi/services, restart/reload Avahi, and the service (with TXT) is advertised.
  • Ideal for distro packages and embedded images.
• Binary TXT support in 0.7+:
  • You can encode non‑text metadata in TXT without writing a custom daemon.
  • This is useful for tightly‑controlled environments where both publisher and consumer are under your control.

Tradeoffs & limitations:

• Interoperability risk: Binary TXT may confuse:
  • Generic Bonjour browsers.
  • Third‑party iOS/macOS apps expecting UTF‑8.
• Version dependency: Relying on binary XML TXT means:
  • You need Avahi ≥ 0.7 everywhere.
  • Older distributions with 0.6.x won’t support that encoding style.

Decision trigger: Choose this if you run Linux‑first fleets, own both ends of the onboarding protocol, and are comfortable requiring Avahi 0.7+ on all devices. Then treat Bonjour interoperability as a secondary goal and explicitly test any Apple‑side client you care about.

---

TXT records vs onboarding flows: where to draw the line

For both Avahi and Bonjour, the most robust pattern is:

1. Use TXT for discovery and capabilities:

   • “This device speaks onboarding protocol X at path Y.”
   • “This device requires TLS and pairing.”
   • “This device is running onboarding spec version 2.”

2. Use another protocol for the heavy lifting:

   • HTTP(S) endpoint, referenced in TXT.
   • BLE or other out‑of‑band pairing channel described by TXT hints.
   • Application‑specific messages after you’ve connected to the service.

This keeps your onboarding metadata:

• Within the conservative DNS-SD TXT size envelope.
• Easily inspectable via generic tools on both Avahi and Bonjour.
• Decoupled from the specifics of one mDNS/DNS-SD implementation.

Whether the mDNS responder is Avahi on Linux or Bonjour on macOS/iOS, the behavior is the same if you stay inside that common TXT profile.

---

Final verdict

For device onboarding metadata carried in DNS-SD TXT records, Avahi and Apple Bonjour are effectively equivalent at the protocol level: same 255‑byte per‑string limit, same key/value structure, and same treatment of TXT as an opaque byte container. The differences are mostly about ergonomics and emphasis:

• Bonjour provides the best‑documented size and usage guidance, especially for mobile and Apple‑centric ecosystems.
• Avahi provides flexible Linux integration paths (D‑Bus, C APIs, /etc/avahi/services), including binary TXT support in XML from Avahi 0.7 onward.

If you want onboarding flows that behave predictably on both stacks:

• Design TXT within a conservative, Apple‑style envelope (~400 bytes total, UTF‑8 values, short keys).
• Treat TXT as discovery and capability metadata, not as a configuration transport.
• On Avahi, use D‑Bus or XML definitions to publish the same key/value pairs you expect Bonjour clients to consume.

That keeps service discovery boring and interoperable, which is exactly what mDNS/DNS-SD and Avahi are designed for.

---

Next Step

Get Started