ssdpd(8)

✨ ssdpd 💅

okay so you're reading the System Manager's Manual page for ssdpd(8) and honestly? it's a little baddie of a daemon and i'm obsessed. let's get into it 🫶

---

🌸 NAME 🌸

ssdpd — Simple Service Discovery Protocol daemon

like, it's a daemon. it does SSDP. the name is literally the whole thing, no notes, periodt. 👑

---

🎀 SYNOPSIS 🎀

ssdpd [-hnsvw] [-c FILE] [-d URL] [-i SEC] [-l LEVEL] [-m NAME] [-M URL]
      [-p URL] [-P FILE] [-r SEC] [-R NUM] [-t TTL]
      [IFACE [IFACE [...]]]

---

🦋 DESCRIPTION 🦋

So bestie, ssdpd is the Simple Service Discovery Protocol daemon (that's SSDP, iykyk) for networked Linux devices. It's literally made for small and embedded systems that just want to announce themselves to UPnP-capable systems — think Windows, yes that Windows. main character energy fr. ✨

ssdpd is a stand-alone UNIX daemon and it has zero external dependencies besides the standard C library. not a single one. it's giving self-sufficient icon. 💅 It also has a built-in web server for serving the UPnP XML description that Windows uses to present the icon — and by default what it announces is an InternetGatewayDevice.

On Linux systems, ssdpd reads /etc/os-release, or /etc/lsb-release, in that order, to figure out the distribution name and version. That info, along with the system hostname, gets periodically transmitted in SSDP multicast discovery frames. If neither file exists, a built-in default is used as the server string. And on non-Linux systems it uses the info from uname(1), since that's the canonical UNIX location for that kind of thing. respectful of tradition, we love to see it. 🌈

Every SSDP-capable device on a LAN gets its own UUID. This gets generated the first time ssdpd is started and stored in a file called ssdpd.cache, either in /var/lib/misc/ or /var/db/ — that second one is what *BSD systems use. Depending on your system, this directory may get wiped on reboot, which means ssdpd might start up with a different UUID every single time 😭. Use -c FILE to work around that, bestie.

The way it goes: as soon as the UUID is saved or read from the cache file, and the PID file has been created, ssdpd drops any root privileges it may have been started with. The preferred user to drop to is ssdp, but if that's not set up on the system, user nobody is the fallback. And in the event that user is also missing? ssdpd logs a warning and just keeps running as root. 🙈

---

💖 OPTIONS 💖

ssdpd starts without any options or arguments. By default it forks to the background like a regular UNIX daemon and runs on all interfaces that are up and have an IPv4 address. New and deleted interfaces are discovered at runtime — it's tracking them live, no cap. To run on only a subset of interfaces, just append the interface name as an argument.

To control other aspects of ssdpd, these command line options are available:

• -c FILE — When started as non-root it's usually not possible to write files in the /var/lib/misc/, or /var/db/, directory. Use this option to specify the full path to an alternate cache file where ssdpd can store and/or read the UUID. 🍓
• -d URL — Override the UPnP description URL in SSDP announcement messages and replies. Default: http://%s:1901/description.xml.

A single '%s' modifier is allowed, and it gets replaced by the interface's IP address. Example:

https://%s:5000/rootDesc.xml

• -h — Show program help text. the classic. 💜
• -i SEC — SSDP notify interval (30-900), default 300 sec.
• -l LEVEL — Set log level to one of the following, default notice:
  • none — Disable all logging
  • error — Error conditions
  • warning — Warning conditions
  • notice — Normal but significant condition (default)
  • info — Informational
  • debug — Debug-level messages
• -n — Run in foreground, do not daemonize by default.
• -m NAME — Override manufacturer in description.xml.
• -M UIRL — Override manufacturerURL in description.xml.
• -p URL — Override presentationURL in description.xml. This is usually the URL to access the device's web interface. Default: http://%s/

In the UPnP spec. this can be an absolute or relative URL, but the default description.xml does not have the <URLBase> option set. See the -d option for overriding the UPnP presentation URL entirely to support a relative presentationURL.

A single '%s' modifier is allowed, and it gets replaced by the interface's IP address. Example:

https://%s:8080/index.php

• -P FILE — Override default PID file location, absolute path required, default: /run/ssdpd.pid.
• -r SEC — Interface refresh interval (5-1800), default 600 sec.
• -R NUM — Initial number of retries to get a valid SSDP discovery socket when starting up, default 3.

When starting up, the system may not yet have any interface up with a valid IP address. By default, ssdpd retries 3 times, using a hard-coded 10 sec refresh interval, before reverting to the regular refresh interval, -r. Unused on systems with netlink interface monitoring (Linux).

• -s — Use syslog, default unless running in foreground, -n.
• -t TTL — TTL for multicast frames, default 2, according to the UPnP Device Architecture (UDA).
• -u UUID — Custom UUID to use. By default, ssdpd generates a UUID when starting up the first time. That UUID is cached between restarts in the file /var/lib/misc/ssdpd.cache. When this option is given, the built-in UUID generator is disabled and the cache file is not used. 🧚
• -v — Show program version.
• -w — Disable built-in micro HTTP server on port 1901. Use this when you want to use another (more capable) web server to provide the description.xml file that clients request to read the IP address and, optionally, custom icon for your device. See below for an example of how the description.xml file can look.
• [IFACE] — By default ssdpd runs on all IPv4-capable interfaces, except loopback. If interface names are given as arguments, ssdpd will run only on them. Interfaces are refreshed at runtime, so if an interface given on the command line does not exist at first, ssdpd will add them later. it's patient like that. 🦋

---

👑 WEB SERVER 👑

The built-in micro HTTP server runs on port 1901 (base SSDP port + 1). Its only purpose is to serve the file description.xml that clients request after receiving the SSDP announcement frames. The default XML file looks like this:

<?xml version="1.0"?>
<root xmlns="urn:schemas-upnp-org:device-1-0">
 <specVersion>
   <major>1</major>
   <minor>0</minor>
 </specVersion>
 <device>
  <deviceType>urn:schemas-upnp-org:device:InternetGatewayDevice:1</deviceType>
  <friendlyName>HOSTNAME</friendlyName>
  <manufacturer>Troglobit Software Systems</manufacturer>
  <manufacturerURL>https://troglobit.com</manufacturerURL>
  <modelName>Generic</modelName>
  <UDN>uuid:12345678-coff-eede-adbe-ff00-123456654321</UDN>
  <presentationURL>http://1.2.3.4/description.xml</presentationURL>
 </device>
</root>

⚠️ okay this part matters bestie: when ssdpd is started with the -w option it is imperative that the -u UUID is also provided. Otherwise clients will detect a mismatch in the advertised UUID and the XML file. like, don't do that. 💀

---

🌟 FILES 🌟

• /run/ssdpd.pid — PID file, created as soon as all setup is complete
• /etc/os-release — Linux standard base release information. Primarily used to figure out distribution name and release version
• /etc/lsb-release — If /etc/os-release does not exist, ssdpd falls back to query this non-standard file for information on the distribution name and release version
• /var/lib/misc/ssdpd.cache — Cached UUID (Linux), may be wiped by the system on reboot
• /var/db/ssdpd.cache — Cached UUID (*BSD), may be wiped by the system on reboot

---

🔥 SEE ALSO 🔥

ssdp-scan(1) avahi-daemon(8) lldpd(8)

UPnP Device Architecture (UDA): http://upnp.org/specs/arch/UPnP-arch-DeviceArchitecture-v1.0.pdf

---

💐 AUTHORS 💐

Joachim Wiberg <troglobit@gmail.com>

---

and that's the whole page, bestie! this one's from the Debian squad and it's dated Feb 14, 2023 — happy valentine's day to daemons everywhere i guess 😭💖 slay. 🌸🫶