Sleep Proxy

OS:: 🪐 Platform-independent

A Sleep Proxy is an always-on device that maintains the network presence of hosts that have gone to sleep, and wakes them again on demand. The concept and its wire protocol originate from Apple’s Bonjour Sleep Proxy (also known as Wake on Demand): before a machine suspends, it hands its services over to a proxy via multicast DNS; the proxy keeps answering service discovery queries on the sleeper’s behalf, and the instant a client actually tries to use one of those services, the proxy wakes the machine back up.

Desomnia can act as either end of this exchange:

As a Sleep Proxy server — the always-on device that accepts registrations and wakes hosts. This is the role described on this page.
As a Sleep Proxy client — a machine that registers its own services before suspending. Because that is part of a host’s departure handshake, it is configured through the handoff attribute and documented on the Handoff page.

Because it speaks the standard protocol, a Desomnia proxy can serve non-Desomnia clients, and a Desomnia client can register with a non-Desomnia proxy. Since Apple’s mDNSResponder is the implementation with the biggest reach, the interoperability — in both directions — is covered on its own page: Apple Compatibility.

Hint

The Sleep Proxy builds directly on promiscuous mode and the address-claiming machinery described under Handoff. If you have not yet set up a working proxy, start with the Wake-on-LAN: Proxy guide; the Sleep Proxy adds automatic, standards-based service registration on top of that foundation.

How it works

A host about to suspend sends a registration to the proxy, listing its MAC address, its IP addresses, and the services it wants to be kept reachable (for example RDP on port 3389).
The proxy grants a lease for a bounded duration and defends the host’s addresses on the link so that connection attempts reach it. If mDNS advertising is enabled, it additionally answers service-discovery queries for those services, so that browsing devices continue to find the host as if it were awake.
When a client tries to reach one of the registered services — or when the lease is about to expire with the expiry action set to wake — the proxy sends a Magic Packet and the host comes back online.
Once the host is awake again it announces its return, the lease ends immediately, and the proxy releases everything it was holding on the host’s behalf.

Enabling the proxy

The Sleep Proxy service is offered automatically when a <NetworkMonitor> runs in promiscuous mode and is allowed to learn hosts and/or services dynamically. In practice this means combining watchMode="promiscuous" with an autoDetect value that includes Host and/or Service:

<SystemMonitor version="1">

  <NetworkMonitor watchMode="promiscuous" autoDetect="Host|Service">
    <!-- statically declared hosts may still appear here -->
  </NetworkMonitor>

</SystemMonitor>

The distinction between the two discovery entities is important for the proxy:

Service: The proxy may attach newly registered services to hosts that already exist in its configuration. A registration for a host it does not know is rejected.
Host: The proxy may additionally create host definitions on the fly for hosts it has never seen, purely from their registration. Combined with Service this yields a proxy that requires no per-host configuration at all.

See auto-configuration for the full list of autoDetect entities and how inheritance between <NetworkMonitor> and individual hosts works.

Advertising over mDNS

Accepting registrations and waking hosts does not by itself make a sleeping host findable over multicast DNS (Bonjour/DNS-SD). The proxy always defends the host’s addresses at the link layer, so a client that already has the host’s IP address connects straight through and triggers the wake — but reaching that point can depend on two things the proxy does not do by default:

Resolving the host’s name to an address, if the client connects by name and the network has no other authority answering for a sleeping host. Enable advertiseHosts.
Keeping the host’s services discoverable to service-browsing clients. Enable advertiseServices.

<NetworkMonitor watchMode="promiscuous" autoDetect="Host|Service" advertiseHosts="true" advertiseServices="true">
  <!-- ... -->
</NetworkMonitor>

Both are off by default and independent of each other; see the mDNS responder page for when each is worth turning on.

Leases

Every registration is bound to a lease with a finite duration. The client requests a duration — for a Desomnia client this is its handoffDuration (see Handoff) — and the proxy clamps the request into the range it is willing to grant. The granted duration is returned in the registration response.

sleepProxyLeaseExpire

default:: wake

What the proxy does when a lease reaches its end without the host having come back on its own:

none: Simply release the lease. If the host is still asleep, its services stop being advertised until it registers again.
wake: Send a Magic Packet to wake the host before releasing the lease — but only if the host is not already responding. A woken host reclaims its presence and, once it idles again, suspends with a fresh registration; a registered host therefore never silently disappears from the network. This mirrors the behaviour of Apple’s proxies, which always wake a host whose lease runs out.

sleepProxyLeaseDurationMin

inherited:
default:: 30min

The shortest lease the proxy will grant. Requests below this are rounded up.

sleepProxyLeaseDurationMax

default:: 365d

The longest lease the proxy will grant. Requests above this are capped.

sleepProxyLeaseLimit

default:: 100

The maximum number of simultaneous leases. Once the pool is exhausted, further registrations are refused until a lease ends. This bounds the resources a single proxy commits to sleeping hosts.

Choosing between proxies

Several Sleep Proxies may be present on one network. Each advertises a four-part metric that lets clients pick the most suitable one — a dedicated, mains-powered, always-on device is a better proxy than an incidentally-available laptop. Clients prefer the proxy with the lowest metric; a Desomnia client works through the candidates from best to worst until a registration succeeds (see handoffRetry on the Handoff page).

sleepProxyMetrics

default:: best

The metric this proxy advertises. You may use one of the shorthands best, average or worst, or specify the four fields explicitly as intent-portability-marginalPower-totalPower (each 10–99), following Apple’s convention — for example 30-40-70-70. Lower is more preferred. Leave this at Best if this device is the intended proxy for the segment; raise it if the machine is only an opportunistic fallback.

sleepProxyPort

The UDP port the Sleep Proxy service listens on. Clients discover the port through the proxy’s DNS-SD advertisement, so it does not normally need to be fixed: when unset, Desomnia reserves an ephemeral port from the operating system. Setting an explicit port makes the endpoint predictable (for example for firewall rules); the port is then bound shareable, so it may coexist with other programs on the machine that also bind it reusably — such as an OS-level mDNS responder when using 5353.

Registering with a Sleep Proxy

To make this machine register its services with a proxy before it sleeps, configure handoff with handoff="SleepProxy" rather than the options on this page — those govern the accepting side. Desomnia locates a proxy to register with in one of two ways:

Statically, by declaring the proxy as a <SleepProxy> host inside <NetworkMonitor>.
Dynamically, by enabling autoDetect="SleepProxy" so that Desomnia discovers advertised proxies on the network and registers with the one offering the best metric.

<NetworkMonitor autoDetect="SleepProxy" handoff="SleepProxy">
  <!-- or point at a specific proxy: -->
  <SleepProxy name="proxy" IPv4="192.168.1.2" port="1234" />
</NetworkMonitor>

sleepProxyDiscovery

default:: eager

Controls when a client looks for a proxy to register with:

eager: Discover a proxy up front and keep the registration current, so handoff at suspend time is immediate.
lazy: Defer discovery until the host is actually about to suspend. This avoids background traffic at the cost of a slightly slower suspend.

Note

eager and lazy are mutually exclusive. A discovered proxy is forgotten again when the local host resumes, so that a proxy which has itself gone away is not trusted indefinitely.

Advanced

The pages below document the machinery behind the proxy: the wire-level details of the protocol and Desomnia’s implementation of it, and the specifics of interoperating with Apple’s Bonjour Sleep Proxy. None of it is required for configuring or using the proxy — read on if you are curious how it works under the hood, or if you are debugging the exchange with a third-party implementation: