wsdd(1)

📦
version 0.8 · 2 versions
, in ubuntu questing, ubuntu resolute, ubuntu stonking

✨ wsdd ✨ — the manual page, but make it make sense 💅

ok bestie so this is the wsdd(1) page from the General Commands Manual, and we're gonna walk through it together, no gatekeeping 💖

🎀 NAME 🎀

wsdd — a Web Service Discovery host and client daemon. that's the whole vibe.

🦋 SYNOPSIS 🦋

wsdd [options]

short. sweet. iconic.

💜 DESCRIPTION 💜

okay so here's the tea ☕ — wsdd implements both a Web Service Discovery (WSD) host and a WSD client daemon. two modes, one little program, main character energy fr fr.

The host implementation is the one that lets (Samba) hosts — like your local NAS device, yes YOURS 🫶 — get found by Web Service Discovery clients like Windows. So Windows just sees your box on the network. slay.

The client mode is the other direction: it lets you go searching for other WSD hosts on the local network. like a little scavenger hunt but for servers 🔍

Now the important part, listen up 👑 — the default mode of operation is host mode. The client / discovery mode has to be enabled explicitely (that's the original spelling, we keep it, we don't fix it, that's the rules 💅). Unless you configure it otherwise, the host mode is always active. And both modes can be used at the same time. multitasking queen behavior.

🌸 OPTIONS 🌸

⭐ General options ⭐

  • -4, --ipv4only — See below. (yes, that's literally what it says, keep reading bestie, -6 explains it 💀)
  • -6, --ipv6only — Restrict to the given address family. And here's the catch 🚨 — if you specify both options, then no addresses will be available and wsdd will just... exit. like, it dips. so don't do that unless you want it to leave the group chat.
  • -A, --no-autostart — Do not start networking activities automatically when the program starts. The API interface (see below 👇) can be used to start and stop the networking activities while the application is still running.
  • -c DIRECTORY, --chroot DIRECTORY — chroot into the given DIRECTORY after initialization has been performed, and right before the handling of incoming messages starts. The new root directory can be empty, no stress. Consider using the -u option as well (they're besties, they pair well 🫶).
  • -h, --help — Show help and exit. the classic.
  • -H HOPLIMIT, --hoplimit HOPLIMIT — Set the hop limit for multicast packets. The default is 1, which should prevent packets from leaving the local network segment. keeping it local, keeping it cozy 🏠
  • -i INTERFACE/ADDRESS, --interface INTERFACE/ADDRESS — Specify which interfaces wsdd will be listening on. If no interfaces are specified, all interfaces are used. Loop-back interfaces are never used — even when you explicitly specify them, sorry bestie, they said no 🙈. For interfaces with IPv6 addresses, only link-local addresses will be used for announcing the host on the network. This option can be provided multiple times in order to restrict traffic to more than one interface. It also accepts IP addresses that the service should bind to. For IPv6, only link local addresses are actually considered, as noted above. so, one option, so many jobs 💅
  • --metadata-timeout TIMEOUT — Set the timeout for HTTP-based metadata exchange. Default is 2.0 seconds. punctual queen ⏰
  • -s, --shortlog — Use a shorter logging format that only includes the level and the message. Super useful when the logging mechanism, like systemd on Linux, already automatically prepends a date, process name, and process ID to the log message. why repeat yourself, we hate redundancy ✨
  • -u USER[:GROUP], --user USER[:GROUP] — Change user (and group) when running, before handling network packets. Together with -c this option can be used to increase security if the execution environment — like the init system — cannot ensure this in another way. glow-up but for permissions 🔐
  • -U UUID, --uuid UUID — okay this one's a whole paragraph so buckle up 🎢 The WSD specification requires a device to have a unique address that stays stable across reboots or changes in networks. In the context of the standard, it's assumed this is something like a serial number. wsdd attempts to read the machine ID from /etc/machine-id and /etc/hostid (in that order) before potentially chrooting into another environment. If reading the machine ID fails, wsdd falls back to a version 5 UUID with the DNS namespace and the host name of the local machine as inputs. Which means — the host name should be stable and not be modified, e.g. by DHCP, or your UUID goes rogue 😭. But if you want wsdd to use a specific UUID, you can use this option.
  • -v, --verbose — Additively increase verbosity of the log output. A single occurrence of -v/--verbose sets the log level to INFO. More -v options set the log level to DEBUG. so -v is "talk to me" and -vv is "tell me EVERYTHING" 🗣️
  • -V, --version — Show the version number and exit.

👑 Host Mode Options 👑

  • -d DOMAIN, --domain DOMAIN — Assume that the host running wsdd joined an ADS domain. This will make wsdd report the host as being a domain member. It disables workgroup membership reporting. The (provided) hostname is automatically converted to lower case. Use the -p option to change this behavior.
  • -n HOSTNAME, --hostname HOSTNAME — Override the host name wsdd uses during discovery. By default the machine's host name is used (look at hostname(1)). Only the host name part of a possible FQDN will be used in the default case. so it trims the drama off the end ✂️
  • -o, --no-host — Disable host operation mode. If this option is provided, the host cannot be discovered by other (Windows) hosts. It can be useful when client/discovery mode is used and you don't want the host that runs wsdd to make an announcement. stealth mode, lowkey 🥷
  • -p, --preserve-case — Preserve the hostname as it is. Without this option, the hostname gets converted as follows: for workgroup environments (see -w) the hostname is made upper case by default. Vice versa it's made lower case for usage in domains (see -d). pick your case, we support your choices 💅
  • -t, --no-http — Do not service HTTP requests of the WSD protocol. This option is intended for debugging purposes, where another process may handle the Get messages. debug girlies, this one's for you 🔧
  • -w WORKGROUP, --workgroup WORKGROUP — By default wsdd reports the host is a member of a workgroup rather than a domain (use the -d/--domain option to override this). With -w/--workgroup the default workgroup name can be changed. The default work group name is WORKGROUP. The (provided) hostname is automatically converted to upper case. Use the -p option to change this behavior.

🦋 Client/Discovery Mode Options 🦋

  • -D, --discovery — Enable discovery mode to search for other WSD hosts/servers. Found hosts are logged with INFO priority. The server interface (see below 👇) can be used for a programatic interface (again, their spelling, we respect it 💖). Refer to the man page for details of the server interface.
  • -l PATH/PORT, --listen PATH/PORT — Specify the location of the socket for the server programming interface. If the option value is numeric, it's interpreted as a numeric port for a TCP server port. Then, the server socket is bound to the localhost only. If the option value is non-numeric, it's assumed to be a path to a UNIX domain socket that a client can connect to. two flavors, one option, obsessed 🍓

💫 EXAMPLE USAGE 💫

Handle traffic on eth0 and eth2 only, but only with IPv6 addresses

wsdd -i eth0 -i eth2 -6

or

wsdd --interface eth0 --interface eth2 --ipv6only

Set the Workgroup according to smb.conf, be verbose, run with dropped privileges, and change the root directory to an (empty) directory

SMB_GROUP=$(grep -i '^\s*workgroup\s*=' smb.conf | cut -f2 -d= | tr -d '[:blank:]')

wsdd -v -w $SMB_GROUP -u daemon:daemon -c /var/run/wsdd/chroot

look at that pipeline go 😭 she's beautiful

🔥 FIREWALL SETUP 🔥

Traffic for the following ports, directions, and addresses must be allowed:

  • Incoming and outgoing traffic to udp/3702 with multicast destination: 239.255.255.250 for IPv4 and ff02::c for IPv6
  • Outgoing unicast traffic from udp/3702
  • Incoming traffic to tcp/5357

You should further restrict the traffic to the (link-)local subnet, e.g. by using the fe80::/10 address space for IPv6.

🚨 bestie listen — please note that IGMP traffic must be enabled in order to get IPv4 multicast traffic working. no IGMP, no multicast, no discovery. periodt.

💅 API INTERFACE 💅

wsdd provides a text-based, line-oriented API interface to query information and trigger actions. The interface can be used with TCP and UNIX domain sockets (see the -l/--listen option). The TCP socket is bound to the local host only.

The following commands can be issued:

clear — Clear list of discovered devices

Clears the list of all discovered devices. Use the probe command to search for devices again. This command does not return any data, and is only available in discover mode.

list [TYPE] — List discovered devices

Returns a tab-separated list of discovered devices of the provided TYPE (e.g. "pub:Computer") with the following information. If no type is provided, all discovered devices are listed. The possibly empty list of detected hosts is always terminated with a single dot (.) in an otherwise empty line. This command is only available in discover mode.

  • UUID — UUID of the discovered device. Note that a multi-homed device should appear only once, but with multiple addresses (see below).
  • name — The name reported by the device. For discovered Windows hosts, it's the configured computer name that gets reported here.
  • association — Specifies the domain or workgroup to which the discovered host belongs. The type of the association (workgroup or domain) is separated from its value by a colon.
  • last_seen — The date and time the device was last seen, as a consequence of Probe/Hello messages, provided in ISO8601 with seconds.
  • addresses — List of all transport addresses that were collected during the discovery process, delimited by commas. Addresses are provided along with the interface (separated by %) on which they were discovered. IPv6 addresses are reported in square brackets. Note that the reported addresses may not match the actual device on which the device may be reached.
  • types — Types of the detected device, delimited by commas.

probe [INTERFACE] — Search for devices

Triggers a Probe message on the provided INTERFACE (eth0, e.g.) to search for WSD hosts. If no interface is provided, all interfaces wsdd listens on are probed. A Probe message initiates the discovery message flow. It may take some time for hosts to be actually discovered. This command does not return any data, and is only available in discovery mode.

start — Start networking activities

This command starts the networking acitivies (their spelling again, iconic 🎀) of wsdd if they haven't been started yet. "Hello" messages are emitted and the host is announced on the network(s) when the host mode is active. If the discovery mode is enabled, a probe process is also started.

stop — Stop networking activities

This is the reverse operation to start. When this command is received, "Bye" messages are sent in order to notify hosts in the network about the host's disappearance. All networking sockets used for the WSD protocol are closed as well. Activities can be restarted with the start operation. it's giving ✨ farewell era ✨

🔐 SECURITY 🔐

wsdd does not implement any security feature, e.g. by using TLS for the http service. This is because wsdd's intended usage is within private, i.e. home, LANs.

The Hello message contains the host's transport address, i.e. the IP address, which speeds up discovery (it avoids the Resolve message).

💀 no cap — that's the whole security section. it's a home-LAN girly. don't put her on the open internet, she is not built for that.

<div align="left">💖 ✨ 🎀 🦋 🌸 💅 🫶 😭 🔥 👑 🌈 ⭐ 💀 🙈 🍓 🧚 💜</div>

and that's part one bestie — there's more coming, don't go anywhere 💅✨

🦋 KNOWN ISSUES 🦋

Okay bestie, real talk — this software is iconic but nothing's perfect, and the maintainers were super upfront about the lil gremlins that live in here. Not me reading the bug notes like gossip 💀. Here's the tea, fr fr.

🌸 Using only IPv6 on FreeBSD

So picture this: wsdd is vibing on FreeBSD and you've got it running with IPv6 only. In that situation, the host running wsdd might not get discovered reliably. Lowkey devastating, I know.

What's the actual cause? It appears to be that Windows just... is not always able to connect to the HTTP service, for reasons that are, quote unquote, unknown. We don't know why, nobody knows why, it's giving mystery. 🙈

The glow-up fix: just run wsdd with IPv4 only. Workaround secured, problem dodged, we move. ✨

🎀 Tunnel/Bridge Interface

This one is the main character of the known-issues section, honestly, so buckle up.

If you've got tunnel or bridge interfaces hanging around — think the ones created by OpenVPN or Docker — they can absolutely interfere with wsdd if you run it without providing an interface that it should bind to (meaning it binds to all of them). 🫠

And here's what that messy situation looks like in practice:

  • The wsdd host does show up — but only after wsdd has been started. Slay, right? ✨
  • Then it disappears the moment an update of the Network view in Windows Explorer gets forced. And forcing it means either refreshing the view or rebooting the Windows machine. 😭

So it's there, and then it's not. Iconic behaviour, terrible outcome.

The fix, bestie: you need to specify the interface that is connected to the network on which the host should be announced, using the -i/--interface option. That prevents the tunnel/bridge interfaces from being used at all. Problem: solved. 💅

🌈 The Background (iykyk)

Okay so why does this happen? The maintainers explain it and it's actually fascinating, so let's get into it:

Tunnel/bridge interfaces may cause Resolve requests from Windows hosts to be delivered to wsdd multiple times — meaning duplicates of such a request get created.

Now, if wsdd receives such a request first from a tunnel/bridge, it uses the transport address (that's the IP address) of that interface, and sends the response via unicast.

Further duplicates are not processed, thanks to the duplicate message detection, which is based on message UUIDs. Very demure, very mindful, very deduplicated. 🧚

But here's the plot twist: the Windows host that receives the response appears to detect a mismatch between:

  • the transport address in the ResolveMatch message (which is the tunnel/bridge address), and
  • the IP of the sending host/interface (the LAN IP, e.g.)

And subsequently? The wsdd host is ignored by Windows. 💀 Betrayal. Absolute betrayal.

So yeah — if your host keeps ghosting Windows Explorer, it's probably not a you problem, it's a tunnel/bridge interface problem. Pass -i/--interface and reclaim your main character energy. 👑

That's the whole page, bestie — you made it all the way to the end and I'm so proud of you. 🥹 This one's from the wsdd(1) manual, and yes, the footer really does just say wsdd(1) — no dramatic source, version or date drop to flex here, just the classic page reference. Go forth and be discoverable. 🦋✨💖

📦 where this page comes from