1wsdd(1) General Commands Manual wsdd(1)
2
6 wsdd - A Web Service Discovery host and client daemon.
7
9 wsdd [options]
10
12 wsdd implements both a Web Service Discovery (WSD) host and a WSD
13 client daemon. The host implementation enables (Samba) hosts, like your
14 local NAS device, to be found by Web Service Discovery clients like
15 Windows. The client mode allows searching for other WSD hosts on the
16 local network.
17 The default mode of operation is the host mode. The client or discovery
19 mode must be enabled explictely. Unless configured otherwise, the host
20 mode is always active. Both modes can be used at the same time.
21
23 General options
24 -4, --ipv4only
25 See below.
26 -6, --ipv6only
28 Restrict to the given address family. If both options are speci‐
29 fied no addreses will be available and wsdd will exit.
30 -A, --no-autostart
32 Do not start networking activities automatically when the pro‐
33 gram is started. The API interface (see below) can be used to
34 start and stop the networking activities while the application
35 is running.
36 -c DIRECTORY, --chroot DIRECTORY
38 chroot into the given DIRECTORY after initialization has been
39 performed and right before the handling of incoming messages
40 starts. The new root directory can be empty. Consider using the
41 -u option as well.
42 -h, --help
44 Show help and exit.
45 -H HOPLIMIT, --hoplimit HOPLIMIT
47 Set the hop limit for multicast packets. The default is 1 which
48 should prevent packets from leaving the local network segment.
49 -i INTERFACE/ADDRESS, --interface INTERFACE/ADDRESS
51 Specify on which interfaces wsdd will be listening on. If no in‐
52 terfaces are specified, all interfaces are used. Loop-back in‐
53 terfaces are never used, even when explicitly specified. For in‐
54 terfaces with IPv6 addresses, only link-local addresses will be
55 used for announcing the host on the network. This option can be
56 provided multiple times in order to restrict traffic to more
57 than one interface. This option also accepts IP addresses that
58 the service should bind to. For IPv6, only link local addresses
59 are actually considered as noted above.
60 -s, --shortlog
62 Use a shorter logging format that only includes the level and
63 message. This is useful in cases where the logging mechanism,
64 like systemd on Linux, automatically prepends a date and process
65 name plus ID to the log message.
66 -u USER[:GROUP], --user USER[:GROUP]
68 Change user (and group) when running before handling network
69 packets. Together with -c this option can be used to increase
70 security if the execution environment, like the init system,
71 cannot ensure this in another way.
72 -U UUID, --uuid UUID
74 The WSD specification requires a device to have a unique address
75 that is stable across reboots or changes in networks. In the
76 context of the standard, it is assumed that this is something
77 like a serial number. wsdd uses the UUID version 5 with the DNS
78 namespace and the host name of the local machine as inputs.
79 Thus, the host name should be stable and not be modified, e.g.
80 by DHCP. However, if you want wsdd to use a specific UUID you
81 can use this option.
82 -v, --verbose
84 Additively increase verbosity of the log output. A single occur‐
85 rence of -v/--verbose sets the log level to INFO. More -v op‐
86 tions set the log level to DEBUG.
87 -V, --version
89 Show the version number and exit.
90 Host Mode Options
92 -d DOMAIN, --domain DOMAIN
93 Assume that the host running wsdd joined an ADS domain. This
94 will make wsdd report the host being a domain member. It dis‐
95 ables workgroup membership reporting. The (provided) hostname is
96 automatically converted to lower case. Use the `-p` option to
97 change this behavior.
98 -n HOSTNAME, --hostname HOSTNAME
100 Override the host name wsdd uses during discovery. By default
101 the machine's host name is used (look at hostname(1)). Only the
102 host name part of a possible FQDN will be used in the default
103 case.
104 -o, --no-host
106 Disable host operation mode. If this option is provided, the
107 host cannot be discovered by other (Windows) hosts. It can be
108 useful when client/discovery mode is used and no announcement of
109 the host that runs wsdd should be made.
110 -p, --preserve-case
112 Preserve the hostname as it is. Without this option, the host‐
113 name is converted as follows. For workgroup environments (see
114 -w) the hostname is made upper case by default. Vice versa it is
115 made lower case for usage in domains (see -d).
116 -t, --no-http
118 Do not service HTTP requests of the WSD protocol. This option is
119 intended for debugging purposes where another process may handle
120 the Get messages.
121 -w WORKGROUP, --workgroup WORKGROUP
123 By default wsdd reports the host is a member of a workgroup
124 rather than a domain (use the -d/--domain option to override
125 this). With -w/--workgroup the default workgroup name can be
126 changed. The default work group name is WORKGROUP. The (pro‐
127 vided) hostname is automatically converted to upper case. Use
128 the `-p` option to change this behavior.
129 Client/Discovery Mode Options
131 -D, --discovery
132 Enable discovery mode to search for other WSD hosts/servers.
133 Found hosts are logged with INFO priority. The server interface
134 (see below) can be used for a programatic interface. Refer to
135 the man page for details of the server interface.
136 -l PATH/PORT, --listen PATH/PORT
138 Specify the location of the socket for the server programming
139 interface. If the option value is numeric, it is interpreted as
140 numeric port for a TCP server port. Then, the server socket is
141 bound to the localhost only. If the option value is non-nu‐
142 meric, it is assumed to be a path to UNIX domain socket to which
143 a client can connect to.
144
147 Handle traffic on eth0 and eth2 only, but only with IPv6 addresses
148 wsdd -i eth0 -i eth2 -6
149 or
151 wsdd --interface eth0 --interface eth2 --ipv6only
153 Set the Workgroup according to smb.conf, be verbose, run with dropped priv‐
155 ileges, and change the root directory to an (empty) directory
156 SMB_GROUP=$(grep -i '^workgroup=' smb.conf | cut -f2 -d= | tr -d
157 '[:blank:]')
158 wsdd -v -w $SMB_GROUP -u daemon:daemon -c /var/run/wsdd/chroot
160
162 Traffic for the following ports, directions and addresses must be al‐
163 lowed:
164 - Incoming and outgoing traffic to udp/3702 with multicast destination:
166 239.255.255.250 for IPv4 and ff02::c for IPv6
167 - Outgoing unicast traffic from udp/3702
169 - Incoming traffic to tcp/5357
171 You should further restrict the traffic to the (link-)local subnet,
173 e.g. by using the `fe80::/10` address space for IPv6. Please note that
174 IGMP traffic must be enabled in order to get IPv4 multicast traffic
175 working.
176
178 Wsdd provides a text-based, line-oriented API interface to query infor‐
179 mation and trigger actions. The interface can be used with TCP and UNIX
180 domain sockets (see -l/--listen option). The TCP socket is bound to the
181 local host only. The following commands can be issued:
182 clear - Clear list of discovered devices
184 Clears the list of all discovered devices. Use the probe command to
185 search for devices again. This command does not return any data and is
186 only available in discover mode.
187 list - List discovered devices
189 Returns a tab-separated list of discovered devices with the following
190 information. The possibly empty list of detected hosts is always ter‐
191 minated with a single dot ('.') in an otherwise empty line. This com‐
192 mand is only available in discover mode.
193 UUID UUID of the discovered device. Note that a multi-homed device
195 should appear only once but with multiple addresses (see below)
196 name The name reported by the device. For discovered Windows hosts,
198 it is the configured computer name that is reported here.
199 association
201 Specifies the domain or workgroup to which the discovered host
202 belongs to. The type of the association (workgroup or domain)
203 is separated from its value by a colon.
204 last_seen
206 The date and time the device was last seen as a consequence of
207 Probe/Hello messages provided in ISO8601 with seconds.
208 addresses
210 List of all transport addresses that were collected during the
211 discovery process delimited by commas. Addresses are provided
212 along with the interface (separated by '%') on which they were
213 discovered. IPv6 addresses are reported on square brackets.
214 Note that the reported addresses may not match the actual device
215 on which the device may be reached.
216 probe [INTERFACE] - Search for devices
218 Triggers a Probe message on the provided INTERFACE (eth0, e.g.) to
219 search for WSD hosts. If no interface is provided, all interfaces wsdd
220 listens on are probed. A Probe messages initiates the discovery mes‐
221 sage flow. It may take some time for hosts to be actually discovered.
222 This command does not return any data and is only available in discov‐
223 ery mode.
224 start - Start networking activities
226 This command starts the networking acitivies of wsdd if they haven't
227 been started yet. "Hello" messages are emitted and the host is an‐
228 nounced on the network(s) when the host mode is active. If the discov‐
229 ery mode is enabled a probe process is also started.
230 stop - Stop networking activities
233 This is the reverse operation to start. When this command is received,
234 "Bye" messages are sent in order to notify hosts in the network about
235 the host's disappearance. All networking sockets used for the WSD pro‐
236 tocol are closed as well. Activities can be restarted with the start
237 operation.
238
241 wsdd does not implement any security feature, e.g. by using TLS for the
242 http service. This is because wsdd's intended usage is within private,
243 i.e. home, LANs. The Hello message contains the hosts transport ad‐
244 dress, i.e. the IP address which speeds up discovery (avoids Resolve
245 message).
246
248 Using only IPv6 on FreeBSD
249 If wsdd is running on FreeBSD using IPv6 only, the host running wsdd
250 may not be reliably discovered. The reason appears to be that Windows
251 is not always able to connect to the HTTP service for unknown reasons.
252 As a workaround, run wsdd with IPv4 only.
253 Tunnel/Bridge Interface
255 If tunnel/bridge interfaces like those created by OpenVPN or Docker ex‐
256 ist, they may interfere with wsdd if executed without providing an in‐
257 terface that it should bind to (so it binds to all). In such cases, the
258 wsdd hosts appears after wsdd has been started but it disappears when
259 an update of the Network view in Windows Explorer is forced, either by
260 refreshing the view or by a reboot of the Windows machine. To solve
261 this issue, the interface that is connected to the network on which the
262 host should be announced needs to be specified with the -i/--interface
263 option. This prevents the usage of the tunnel/bridge interfaces.
264 Background: Tunnel/bridge interfaces may cause Resolve requests from
266 Windows hosts to be delivered to wsdd multiple times, i.e. duplicates
267 of such request are created. If wsdd receives such a request first from
268 a tunnel/bridge it uses the transport address (IP address) of that in‐
269 terface and sends the response via unicast. Further duplicates are not
270 processed due to the duplicate message detection which is based on mes‐
271 sage UUIDs. The Windows host which receives the response appears to de‐
272 tect a mismatch between the transport address in the ResolveMatch mes‐
273 sage (which is the tunnel/bridge address) and the IP of the sending
274 host/interface (LAN IP, e.g.). Subsequently, the wsdd host is ignored
275 by Windows.
276 wsdd(1)