Bind the listening socket to a specific address/interface (not just mDNS advertising)

[haavar]

Background. On a multi-homed host I'd like to run one Shairport Sync instance per network interface, with each instance only reachable on its own address. Today general.interface scopes the mDNS advertisement (mdns_avahi.c uses config.interface_index), but the RTSP listener in rtsp_listen_loop() still binds the wildcard address — getaddrinfo(NULL, portstr, &hints /* AI_PASSIVE */, …) — so the instance accepts connections on all interfaces regardless of that setting. (The per-connection RTP/data sockets already bind a specific local address via bind_socket_and_port().)

Proposal. Add an option to bind the listening socket(s) to a specific local IP address, so the daemon only listens where intended. I'd be happy to implement it and open a PR against development, tested on a multi-homed host.

A few design questions before I code:

1. New option vs. existing interface. I lean toward a new explicit address setting (config general.address + a matching command-line flag), leaving interface as the advertising knob, to avoid changing current behavior. Would you prefer instead that interface also restrict the listener? Or bind by interface name (resolving its addresses via getifaddrs())?
2. Address vs. interface as the primitive. Binding an IP is portable across Linux and the BSDs (no SO_BINDTODEVICE/privilege). Any objection to making the address the primary knob, with interface-name support as a possible follow-up?
3. CLI + config. I'd expose it both ways (config value, overridden by the command line), matching port/name. Sound right?
4. Should an unset value keep today's behavior exactly (bind all interfaces, dual-stack v4/v6)? I'd preserve the existing IPV6_V6ONLY handling.

Happy to adjust naming/semantics to your preference.

[haavar]

Following up with a working prototype and a design question — plus, at the end, the larger use case that motivates it.

The change

rtsp_listen_loop() passes NULL to getaddrinfo, so the RTSP listener always binds the wildcard address; general.interface only scopes the mDNS advertisement. On a multi-homed host an instance therefore advertises on one interface but accepts connections on all of them.

I prototyped the minimal fix — pass a configured node instead of NULL — behind a new general.address / --address:

• bound to one IP, the listener appears on that IP:7000 only; other local addresses are refused;
• unset, it's the unchanged dual-stack wildcard bind;
• verified with classic and AirPlay 2 builds, including end-to-end playback.

Everything else (AI_PASSIVE, IPV6_V6ONLY, the bind loop, error handling) is untouched. I also made the built-in tinysvcmdns backend honour the same address, so the setting isn't left half-applied depending on the mDNS backend — details in the recipe below. Branch: haavar/shairport-sync@poc/listen-address.

Design question — address vs interface

While testing I found three behaviours keyed off three different things:

• what the socket listens on → the new address;
• what interface Avahi advertises on → interface (config.interface_index);
• the device-id MAC → get_device_id() in common.c, which takes the first non-loopback interface and ignores both.

Having to set interface and address is confusing. An IP belongs to exactly one interface, so one option could reasonably drive all three: given an address, bind the socket to it, scope the advertisement to the interface that owns it, and derive the device-id from that interface — with interface kept as a legacy alias. What's your preference on the config surface before I open a PR — a standalone address, folding it into interface, or that unification?

What this unlocks — multiple AP2 instances on one host

AIRPLAY2.md says multiple AP2 instances can't share a system because clients get confused by multiple players at the same IP. The workaround has always been a separate IP per instance — which is exactly what --address makes clean. I took it further and got multiple instances working in a single network namespace, with no per-room netns/macvlan, and it plays: two instances, two different sources, simultaneously, each out its own audio device.

The full recipe, beyond --address, is small:

• nqptp: two instances need two nqptps, but nqptp binds 319/320 + control (9000) to the wildcard/localhost and demands exclusive 319/320. I added -a <addr> (bind PTP to a local address) and -c <addr> (bind the control port); open_sockets_at_port() already takes the node, so it's a small main() change. Branch: haavar/nqptp@poc/multi-instance.
• shairport: a matching --nqptp-control-address (hard-coded localhost today in ptp-utilities.c).
• …and this needs no configuring: when the control address is unset, both sides derive it from the bind address — a.b.c.d → 127.b.c.d, still loopback-only — so nqptp's -a and shairport's --address produce the same address and coordinate automatically. In practice each instance is just --address / -a; -c / --nqptp-control-address remain as overrides. Branch: haavar/shairport-sync@poc/multi-instance.
• mDNS: with avahi it's config-only per instance (allow-interfaces + a distinct host-name). For the built-in tinysvcmdns backend I made --address do the same in code: scope the multicast socket (imr_interface + IP_MULTICAST_IF) to the address, and — since it advertised with a single gethostname() — derive a per-instance host label from the service name ("SP AddrTest A" → "sp-addrtest-a.local"). Both preserve the old behaviour when no address is set.

I'm not asking you to take all of that here — the --address change stands on its own and is what this issue is about. But since nqptp is your repo too, I wanted you to see the whole path in one place rather than splitting it across issues. Happy to turn any of it into PRs against development in whatever form you prefer.

[haavar]

Two updates since the above.

Control address, now derived in one place. I moved the nqptp control-address derivation out of the binaries. Rather than nqptp and shairport-sync each deriving 127.b.c.d (and relying on the two staying in step), docker/run.sh now derives it once from --address and passes -c to nqptp and --nqptp-control-address to shairport-sync; the binaries keep only the explicit options with a localhost default. Same result for the user — still just --address per instance — but the coordination lives in one place, and that place is this repo's own entrypoint. Verified with two instances playing two different sources at once.

On address vs interface — I've come round to address being the primitive. Building this out, everything binds to an IP: the RTSP socket, nqptp's PTP sockets, the derived control loopback, and the mDNS multicast scope (imr_interface / IP_MULTICAST_IF). And the resolution only goes one way cleanly:

• an address belongs to exactly one interface, so from --address you can derive the interface, its MAC (for the device-id), and the advertisement scope;
• an interface has zero, one, or many addresses, so it can't tell you which IP to bind.

So an address is the more complete setting — you can derive the interface-y things from it, but not the reverse. Making interface primary and resolving it to a bind IP is exactly where the ambiguity (and complication) creeps in. interface's one genuine advantage is DHCP / stable naming, and that's covered by treating it as sugar that resolves to its current address at startup — sugar over address, not the other way round.

So my suggestion has firmed up: address as the authoritative setting, driving the socket bind, the advertisement scope, and the device-id; interface kept as an alias/convenience that resolves to an address. The open question for you is really just the config surface and naming, not the primitive.

[mikebrady]

Bear with me please — a bit busy just in the next few days.

[haavar]

No problem. It was not a nag, I've been working on it and I did not want to have the information here be stale as I discover things.

[mikebrady]

Okay, please bear in mind that we don't really know what the real problems are, but here goes.

As far as I remember, efforts to run separate Shairport Sync and NQPTP apps on different IP address and even different connections all run into the problem that the Avahi daemon seems to gather up all the IP addresses and advertise them together. It may advertise on just on one connection, but AFAIR all IP addresses are advertised. You will be able to see the advertisements for all the separate AirPlay 2 endpoints running on your system, but they will all have the same set of IP addresses.

So, let me gently suggest that you keep these suggested modifications on your own fork until it can be fully proved that they are worthwhile.

I'd love to be wrong, of course!

[haavar]

Thanks — you're remembering it exactly right, and that was our first symptom too: with a single Avahi daemon, one hostname gets A-records for every IP, so all the endpoints resolve to the whole set. Tapping one connected to another, and they flickered in the list.

What worked for us was scoping the the Avahi daemon with allow-interfaces=<that instance's interface> and a distinct host-name. With allow-interfaces, the daemon genuinely doesn't gather the other IPs — one scoped to a single interface logs only:

Registering new address record for 192.168.1.118 on <iface>.IPv4

and nothing for the others. So each endpoint advertises just its own IP under its own hostname. (For the built-in tinysvcmdns backend I did the equivalent in code, since it takes its host label from gethostname() and can't be scoped by config.)

And it's working end-to-end: two AirPlay 2 instances on different IPs in one namespace, two different sources playing at once, each to its own output — no cross-talk, no flicker, each service resolving one-to-one to a single IP.

Honest pros and cons:

Pros

• Lowers bar for running multiple instances on one host
• Drops the per-container network namespace. Can be run in a unprivileged container, and not extra network plumbing.
• Each instance it's essentially just --address; the nqptp control coordination is derived automatically.

Cons

• It's a coordinated set of small changes across shairport-sync and nqptp, not a single patch.
• Those N Avahi daemons now share one namespace, all bound to 5353 (SO_REUSEADDR) — unusual next to one-per-namespace, though it's been solid in testing.
• Proven on our setup so far, not broadly.

I'm not pushing to land the multi-instance side. I'd genuinely like it upstream one day so we can drop some extra plumbing on my end, but I'm happy to keep it on the fork until it's earned that more widely — I mostly wanted to share that it does work, and I think it's useful.

Thanks again for looking, and for the healthy skepticism.

[mikebrady]

That sounds really very promising — the allow-interfaces stuff in particular. Let me take a few days to play with it. It would be just great to get true multiple instances working!

[mikebrady]

The tinysvcmdns stuff is only for classic AirPlay, and that has no problems with multiple instances even now.

[haavar]

I did not realize that. I was using avahi in my setup, but I made the needed changes to tinysvcmdns. Either mDNS service needs a unique hostname to publish. For tinysvcmdns I'm deriving it from the Airplay service name. That was a good chunk of the lines changes. If that's not needed, I think the argument for this change gets a little bit stronger.

I've been running multiple instances for a while now using macvlan, but I got an itch to simplify that and run on an unprivileged LXC. The instances are all outputting to individual channels on 7.1 surround devices. I run 5 instances on my server using 2 audio devices. the 2 audio devices could run up to 8 shairport instances.

To run with host networking, I have a wrapper around run.sh that takes care of the avahi setup (requires my fork):

cat >/etc/avahi/avahi-daemon.conf <<EOF
[server]
host-name=${AV_HOST}
use-ipv4=yes
use-ipv6=yes
allow-interfaces=${IFACE}
[publish]
publish-hinfo=no
publish-workstation=no
[rlimits]
EOF

exec /run.sh -vv --address "${ROOM_IP}" -a "${ROOM_NAME}" -- -d "${ALSA_DEV}"```

[haavar]

Update on the multi-instance front -- with a working playback result now, not just a wiring diagram.

Combining the --address change with @jslove's nqptp#50 + #2273, I have two AirPlay 2 instances sharing one network namespace, holder-free, on an unprivileged LXC. Tested with real devices:

two different sources, one to each instance, playing at once -- independent, no cross-talk;
one source grouped to both instances at once -- they play together and stay in sync; and repeatedly dropping either room from the group and re-adding it leaves the other room playing throughout -- the exact clock-clearing regression #50 fixes.
The topology is clean: one nqptp binds 319/320 for the whole namespace and keeps a separate clock per instance, keyed by the shared-memory name each instance sends (#50 + #2273) -- so my earlier per-instance loopback-control-address scheme disappears entirely; instances reach nqptp on stock localhost. And each instance's RTSP bind, mDNS scope, AirPlay 2 device-id, and nqptp shared-memory name are all derived from its --address, so there is no per-instance config -- one shared config file, with --address + --name + the output device on the command line.

That suggests a design principle worth making explicit: every setting that must differ between instances on one host should be reachable from the command line -- so a single config file can be shared and only the command lines differ. Some settings suit a direct flag (--name); others fall out of one you already set (--address here drives the device-id, the mDNS scope, and the nqptp shm-name). Today interface, airplay_device_id and nqptp_shared_memory_interface_name are config-only, which is what forces a separate config file per instance -- closing that (a flag, or derivation from --address) is what makes one shared config possible. It's an end state @jslove and I both seem to be aiming at.

On the mDNS point, which is the real blocker you named: in my container deployment I resolve it in the entrypoint (run.sh) by scoping each instance's Avahi daemon (allow-interfaces + a distinct host-name) -- that's what stops the "one hostname gathers every IP" behaviour. That's a deployment recipe, not a code change, though: it lives in run.sh, not in Shairport Sync itself. The version that removes the run.sh dependency -- and works on bare Linux with a single system Avahi daemon -- is @jslove's in-code mDNS change (a per-instance hostname via the Avahi API), which he reports running on three concurrent grouped instances. So bare-Linux multi-instance looks like --address + nqptp#50/#2273 + that in-code mDNS fix.

Integrated branch to look at (shairport side; the nqptp side is #50): https://github.com/haavar/shairport-sync/tree/demo/shape2 -- everything's on it so you can see it end-to-end, and there's a docker-compose example of the shared-nqptp wiring under docker/examples/multi-instance. @jslove, two small commits I stacked make --address sufficient: the AirPlay 2 device-id is taken from the address's interface MAC, and the nqptp shm-name is derived from the address. The shm-name one sits right on top of your #2273 -- you might prefer to fold "derive from the address when unset" into #2273 itself; happy either way.

PR sequencing, to keep each one clean: the minimal --address change first; then #2273/#50 (+ the mDNS fix); then the two "derive from --address" commits last, rebased on both -- device-id can land as soon as address does, shm-name after #2273. The branch is just to show it working; we'd split it along those lines before any PRs.

[haavar]

A follow-on that I think is more broadly useful than the per-IP setup: multiple AirPlay 2 instances can share a single IP on distinct ports — no per-instance IPs, and no veths at all.

The blocker was that AP2 fixes the RTSP port to 7000: general.port is honored for classic AirPlay but overwritten to 7000 for AirPlay 2, so two instances on one IP collided on :7000. That turns out to be the only fixed-port conflict — the audio/timing/control ports are negotiated in-band, and nqptp + mDNS are already shared. So the change is tiny: honor a user-set port for AP2 too. Since mdns_register already advertises config.port, the SRV record carries the chosen port automatically — no extra work.

I tested it: two instances on one IP (…​.118), ports 7000 and 7001, each with its own name and device id, advertised through one Avahi daemon. On an iPhone: both appear, connecting to the 7001 instance works, switching between them works, and playing to both at once works. So AP2 clients do follow the SRV port — they don't assume 7000. That was the open question, and it's a clear yes.

This sits on top of the multi-instance foundation — @jslove's nqptp#50 (a shared clock keyed by shared-memory name, which is what the shared nqptp here uses) and the mDNS work. For the multi-IP case, @jslove's in-code per-instance mDNS is what avoids the "one hostname gathers every IP" collision; the single-IP case is the happy special case where there is only one IP, so it resolves cleanly even through the stock avahi backend. Either way this builds directly on that line of work.

Why it's interesting: it removes the per-room IP plumbing entirely — the part most people trip over. Everything runs under network_mode: host on the host's own IP; each instance is just --address --port 700N. No macvlan, no moved-veth namespaces, no per-instance IP wiring.

I'd suggest it as an optional capability alongside the multi-instance support, not a replacement for per-IP — per-IP is still cleaner when you have the addresses and want stable, IP-derived identities. But for anyone who is IP-constrained or just wants the simplest possible setup, single-IP-multi-port is a lot less to stand up.

The patch is a one-liner: default the RTSP port only when it is unset, instead of forcing 7000. Backward compatibility is narrow — AP2 now honors a port it previously ignored — and even that is soft, since the SRV advertises whatever it binds, so clients follow. I'd treat it as a release note rather than a new parameter: port is already "the RTSP listening port", it was just ignored for AP2.

One remaining piece for a fully turnkey single-IP setup: the per-instance identity (AirPlay 2 device id, nqptp shared-memory name) currently derives from the bind address, which is no longer unique when the IP is shared — those would key off the port instead. In the test I set them explicitly per instance. The port change itself stands on its own.

Happy to open it as its own small PR against development if it's of interest.

[jslove]

I'm very interested in the one IP multiple port approach! That was my initial path and I got detoured to the multiple IP. But multi-port working would clean up the network!

[jslove]

@haavar — the single-IP/multi-port result is the interesting one, and I think it settles a question you asked me earlier in a way that argues against one of your suggestions.

You offered to fold "derive the nqptp shm-name from the address when unset" into #2273. I'd rather not, and your own multi-port test is why.

The address stops being a unique key exactly where the multi-port work takes us. You found this yourself: with two instances on one IP you had to set the AirPlay 2 device-id and the shm-name explicitly, because the address no longer distinguishes them. So address-derivation is correct in the multi-IP topology and wrong in the single-IP one — and the single-IP one is the topology you're proposing precisely because it removes the per-room IP plumbing most people trip over. Baking a rule into #2273 that silently breaks in the setup we're trying to make easier seems like the wrong default.

It also gives #2273 a dependency it doesn't have today. #2273 is self-contained: it's a config setting, a validation, and a default that is unchanged for single instances. It doesn't need --address, and --address isn't filed yet. Keeping them separate is your own sequencing principle — minimal --address first, then #2273/#50, then the derive-from-address commits last, rebased on both. Folding derivation in inverts that: the standalone piece would land holding a dependency on the piece still under discussion.

And the shm-name is a poor candidate for derivation regardless of topology. It's a name in a host-wide POSIX shared-memory namespace, shared with anything else on the box talking to nqptp. An explicit /nqptp-kitchen is greppable, predictable, and is what an operator has already written into the systemd unit or the compose file. A derived /nqptp-192-168-1-45 is none of those, and it changes under DHCP — harmless for the shm segment itself, but it means the name in the logs isn't the name in the config, which is a bad trade for a debugging surface.

What I think actually solves the problem derivation was aimed at. Your motivation for deriving was the real one: avoid a separate config file per instance. But that's a config-surface problem, not a naming problem, and it has a direct fix — put the setting on the command line. I've drafted --nqptp-shared-memory-interface-name onto #2273 (command line takes precedence over the config file, same validation on both paths, default unchanged). That gets you one shared config file with only the command lines differing, which is the end state you described, without committing to a derivation rule that only holds in one topology.

That leaves the identity settings you named — interface, airplay_device_id, nqptp_shared_memory_interface_name — reachable from the command line, which I think is the right general answer to "every setting that must differ between instances should be reachable from the command line." Derivation can still land later as sugar on top, and if it does, it should key off whatever tuple is genuinely unique, which after your port work is (address, port), not the address alone. (Note though, that I'm using the config files, not command line)

@mikebrady — on the mDNS half you called the blocker: my in-code fix (a per-instance hostname published via avahi_entry_group_add_address() with AVAHI_PUBLISH_NO_REVERSE) is what makes this work on bare Linux with the single system Avahi daemon, no per-instance daemon and no run.sh. It's running here on 11 instances on one host, verified grouped and PTP-synced across three of them at once. I said I'd stack it on --address — @haavar, it's ready whenever you file that one against development; say the word and I'll rebase onto it the same day.

I'm also very interested in the single-IP/multi-port path. That was where I started before the mDNS collisions pushed me to per-IP macvlans; if a user-set port is honored for AirPlay 2, most of the network plumbing on my end goes away.

[jslove]

Two results from testing on real hardware, both on a bare-Linux host with the single system Avahi daemon — no per-instance avahi-daemon, no container entrypoint, no run.sh.

1. --address + a per-instance mDNS hostname, on bare Linux

I rebased my mDNS fix onto @haavar's --address as promised, and the rebase turned out to remove code rather than replace it. My original keyed off general.interface and had to call a resolve_interface_to_address() helper to discover the IP — which was the weakest part of it (an interface can carry zero, one, or many addresses, so "first" was a guess). With --address the IP is simply given, so the helper and the guess both disappear. The hostname label now derives from the bound address (shairport-192-168-1-45.local).

Tested with two instances on their own IPs, on a host already running eleven other AirPlay 2 instances, all sharing one Avahi daemon. Each service resolves one-to-one:

192.168.1.55  shairport-192-168-1-55.local  ZZ Test Alpha
192.168.1.56  shairport-192-168-1-56.local  ZZ Test Beta

From an iPhone: both appear, each selection activates the one selected, and grouping them works — both carried the same group UUID, played together, and I dropped one from the group and re-added it twice with the other playing throughout, no drops. No underruns; the only log noise was the usual transient NQPTP clock information is not valid at session start.

@mikebrady — this is the mDNS half you called the blocker, working without the deployment recipe. The branch is ready to file as a PR the moment --address is filed; @haavar, it stacks directly on poc/listen-address with no changes to yours.

2. Single IP, multiple ports — clients do follow the SRV port

I tested @haavar's poc/ap2-configurable-port too, and can independently confirm the finding. Two AirPlay 2 instances on one IP, ports 7000 and 7001, advertised through the one system Avahi daemon:

ZZ Port A   192.168.1.55:7000   device 1C697A65B957
ZZ Port B   192.168.1.55:7001   device 1C697A65B958

From an iPhone: both appear; connecting specifically to the 7001 instance works; switching between them works; and playing to both at once works. So iOS reads the port out of the SRV record rather than assuming 7000. No macvlan, no veth, no second address.

For me this is the more interesting of the two. My deployment is eleven rooms on eleven macvlan IPs, and the per-room IP plumbing is the fiddliest part of standing it up. If a port is enough, most of that goes away.

3. A concrete data point on derived vs. explicit identity

This ran into the exact question we were discussing, so it is worth recording what happened.

Both single-IP instances derived the same mDNS hostname, because the address they derive it from is shared. That turned out to be harmless — it maps to the one correct address, and the SRV port is what tells the two services apart, so nothing collided. But the AirPlay 2 device id and the nqptp shared-memory name are a different matter: had those been derived from the address, they would have collided outright. They didn't, because my per-instance configs set airplay_device_id_offset and nqptp_shared_memory_interface_name explicitly.

That is the case I had in mind for keeping #2273's setting explicit rather than folding "derive from the address when unset" into it: the derivation is correct for one topology and wrong for the other, and the explicit setting is the one that survives both. Derivation is still worth having as sugar on top — it just wants to key off whatever is actually unique, which after this is (address, port), not the address alone.

4. An operational wrinkle worth knowing about, for #2273 / nqptp#50

A brand-new shared-memory name always fails its own first startup probe. Shairport Sync sends "/nqptp-whatever T" and then checks for the shared memory segment; nqptp creates the segment on receiving that message, but the check happens too soon, so the first start logs NQPTP service not found and falls back to Classic AirPlay — which binds port 5000 instead of 7000. The next start finds the segment and comes up in AirPlay 2 mode normally.

Both of my test instances did this on their first launch. It is invisible in a systemd deployment, because the unit restarts and the second attempt succeeds, which is presumably why I had not noticed it across eleven rooms. But anyone adopting per-instance shared-memory names will hit it the first time they add an instance, and "it silently came up as AirPlay 1 on the wrong port" is an unpleasant thing to debug. It looks like a small race between the send and the check rather than anything in the multi-client change itself, but it only becomes reachable once instances stop sharing the default name.