NAME¶

ssdpd — Simple Service Discovery Protocol daemon

SYNOPSIS¶

DESCRIPTION¶

Simple Service Discovery Protocol daemon (SSDP) for networked Linux devices. Useful for small and embedded systems that want to announce themselves to UPnP capable systems, e.g. Windows.

ssdpd is a stand-alone UNIX daemon with no external dependencies but the standard C library. It has a built-in web server for serving the UPnP XML description which Windows use to present the icon, by default an InternetGatewayDevice is announced.

On Linux systems, ssdpd reads /etc/os-release, or /etc/lsb-release, in that order to determine the distribution name and version, which along with the system hostname, is periodically transmitted in SSDP multicast discovery frames. If neither file exists a built-in default is used as server string. On non-Linux systems the information from uname(1) is used, since that is the canonical UNIX location for such information.

Each SSDP capable device on a LAN has its own UUID. This is generated the first time ssdpd is started and stored in a file called ssdpd.cache, either in /var/lib/misc/ or /var/db/, which is what *BSD systems use. Depending on your system this directory may be wiped on reboot, so ssdpd may start up with a different UUID every time. Use -c FILE to work around that.

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 beeen started with. The preferred user to drop to is ssdp, but if that is not set up in the system, user nobody is used as a fallback. In the event that user is also missing, ssdpd will log a warning and continue running as root.

OPTIONS¶

ssdpd starts without any options or arguments. By default it forks to the background, as 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. To run on a subset of interfaces, append the interface name as an argument.

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

-c FILE

When started as non-root it is 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, which is replaced by the interface's IP address. Example: https://%s:5000/rootDesc.xml

-h

Show program help text

-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, which is 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.

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>

When ssdpd is started with the -w option it is imperative that the -u UUID is also provided. Otherwise clients wil detect a mismatch in the advertised UUID and the XML file.

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)

AUTHORS¶

Joachim Wiberg ⟨troglobit@gmail.com⟩