Cantibra
262 lines
12 KiB
Plaintext
262 lines
12 KiB
Plaintext
.TH wsdd 8
|
|
.SH NAME
|
|
wsdd \- A Web Service Discovery host and client daemon.
|
|
.SH SYNOPSIS
|
|
.B wsdd [\fBoptions\fR]
|
|
.SH DESCRIPTION
|
|
.PP
|
|
.B wsdd
|
|
implements both a Web Service Discovery (WSD) host and a WSD client daemon. The
|
|
host implementation enables (Samba) hosts, like your local NAS device, to be
|
|
found by Web Service Discovery clients like Windows. The client mode allows
|
|
searching for other WSD hosts on the local network.
|
|
.PP
|
|
The default mode of operation is the host mode. The client or discovery mode
|
|
must be enabled explictely. Unless configured otherwise, the host mode is always
|
|
active. Both modes can be used at the same time.
|
|
.SH OPTIONS
|
|
.SS General options
|
|
.TP
|
|
\fB\-4\fR, \fB\-\-ipv4only\fR
|
|
See below.
|
|
.TP
|
|
\fB\-6\fR, \fB\-\-ipv6only\fR
|
|
Restrict to the given address family. If both options are specified no
|
|
addreses will be available and wsdd will exit.
|
|
.TP
|
|
\fB\-A\fR, \fB\-\-no-autostart\fR
|
|
Do not start networking activities automatically when the program is started.
|
|
The API interface (see below) can be used to start and stop the networking
|
|
activities while the application is running.
|
|
.TP
|
|
\fB\-c \fIDIRECTORY\fR, \fB\-\-chroot \fIDIRECTORY\fR
|
|
chroot into the given \fIDIRECTORY\fR after initialization has been performed
|
|
and right before the handling of incoming messages starts. The new root directory
|
|
can be empty. Consider using the \fB-u\fR option as well.
|
|
.TP
|
|
\fB\-h\fR, \fB\-\-help\fR
|
|
Show help and exit.
|
|
.TP
|
|
\fB\-H \fIHOPLIMIT\fR, \fB\-\-hoplimit \fIHOPLIMIT\fR
|
|
Set the hop limit for multicast packets. The default is 1 which should
|
|
prevent packets from leaving the local network segment.
|
|
.TP
|
|
\fB\-i \fIINTERFACE/ADDRESS\fR, \fB\-\-interface \fIINTERFACE/ADDRESS\fR
|
|
Specify on which interfaces wsdd will be listening on. If no interfaces are
|
|
specified, all interfaces are used. Loop-back interfaces are never used,
|
|
even when explicitly specified. 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.
|
|
This option also accepts IP addresses that the service should bind to.
|
|
For IPv6, only link local addresses are actually considered as noted above.
|
|
.TP
|
|
\fB\-\-metadata-timeout\ \fITIMEOUT\fR
|
|
Set the timeout for HTTP-based metadata exchange. Default is 2.0 seconds.
|
|
.TP
|
|
\fB\-\-source-port\ \fPORT\fR
|
|
Set the source port for outgoing multicast messages, so that replies will
|
|
use this as the destination port.
|
|
This is useful for firewalls that do not detect incoming unicast replies
|
|
to a multicast as part of the flow, so the port needs to be fixed in order
|
|
to be allowed manually.
|
|
.TP
|
|
\fB\-s\fR, \fB\-\-shortlog\fR
|
|
Use a shorter logging format that only includes the level and message.
|
|
This is useful in cases where the logging mechanism, like systemd on Linux,
|
|
automatically prepends a date and process name plus ID to the log message.
|
|
.TP
|
|
\fB\-u \fIUSER[:GROUP]\fR, \fB\-\-user \fIUSER[:GROUP]\fR
|
|
Change user (and group) when running before handling network packets.
|
|
Together with \fB\-c\fR this option can be used to increase security
|
|
if the execution environment, like the init system, cannot ensure this in
|
|
another way.
|
|
.TP
|
|
\fB\-U \fIUUID\fR, \fB\-\-uuid \fIUUID\fR
|
|
The WSD specification requires a device to have a unique address that is stable
|
|
across reboots or changes in networks. In the context of the standard, it is
|
|
assumed that 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 in 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. Thus, the host name should be stable and not be
|
|
modified, e.g. by DHCP. However, if you want wsdd to use a specific UUID you
|
|
can use this option.
|
|
.TP
|
|
\fB\-v\fR, \fB\-\-verbose\fR
|
|
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.
|
|
.TP
|
|
\fB\-V\fR, \fB\-\-version\fR
|
|
Show the version number and exit.
|
|
.SS Host Mode Options
|
|
.TP
|
|
\fB\-d \fIDOMAIN\fR, \fB\-\-domain \fIDOMAIN\fR
|
|
Assume that the host running wsdd joined an ADS domain. This will make
|
|
wsdd report the host 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.
|
|
.TP
|
|
\fB\-n \fIHOSTNAME\fR, \fB\-\-hostname \fIHOSTNAME\fR
|
|
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.
|
|
.TP
|
|
\fB\-o\fR, \fB\-\-no-host\fR
|
|
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 no announcement of the host that runs wsdd should be made.
|
|
.TP
|
|
\fB\-p\fR, \fB\-\-preserve-case\fR
|
|
Preserve the hostname as it is. Without this option, the hostname is
|
|
converted as follows. For workgroup environments (see -w) the hostname
|
|
is made upper case by default. Vice versa it is made lower case for usage
|
|
in domains (see -d).
|
|
.TP
|
|
\fB\-t\fR, \fB\-\-no-http\fR
|
|
Do not service HTTP requests of the WSD protocol. This option is intended
|
|
for debugging purposes where another process may handle the Get messages.
|
|
.TP
|
|
\fB\-w \fIWORKGROUP\fR, \fB\-\-workgroup \fIWORKGROUP\fR
|
|
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.
|
|
.SS Client/Discovery Mode Options
|
|
.TP
|
|
\fB\-D\fR, \fB\-\-discovery\fR
|
|
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. Refer to the man page for
|
|
details of the server interface.
|
|
.TP
|
|
\fB\-l \fIPATH/PORT\fR, \fB\-\-listen \fIPATH/PORT\fR
|
|
Specify the location of the socket for the server programming interface.
|
|
If the option value is numeric, it is interpreted as 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 is assumed to be a path to UNIX
|
|
domain socket to which a client can connect to.
|
|
|
|
.SH EXAMPLE USAGE
|
|
.SS 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
|
|
.SS 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
|
|
.SH FIREWALL SETUP
|
|
.PP
|
|
Traffic for the following ports, directions and addresses must be allowed:
|
|
.TP
|
|
- Incoming and outgoing traffic to udp/3702 with multicast destination: 239.255.255.250 for IPv4 and ff02::c for IPv6
|
|
.TP
|
|
- Outgoing unicast traffic from udp/3702
|
|
.TP
|
|
- Incoming traffic to tcp/5357
|
|
.PP
|
|
You should further restrict the traffic to the (link-)local subnet, e.g. by
|
|
using the `fe80::/10` address space for IPv6. Please note that IGMP traffic
|
|
must be enabled in order to get IPv4 multicast traffic working.
|
|
.SH 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 \fB\-l/\-\-listen\fR option). The TCP socket is bound to the local host
|
|
only. The following commands can be issued:
|
|
.SS \fBclear\fR - Clear list of discovered devices
|
|
Clears the list of all discovered devices. Use the \fBprobe\fR command to
|
|
search for devices again. This command does not return any data and is only
|
|
available in discover mode.
|
|
.SS \fBlist \fI[TYPE]\fR - 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.
|
|
.TP
|
|
URI
|
|
URI of the discovered device. Note that a multi-homed device should appear
|
|
only once but with multiple addresses (see below)
|
|
.TP
|
|
name
|
|
The name reported by the device. For discovered Windows hosts, it is the
|
|
configured computer name that is reported here.
|
|
.TP
|
|
association
|
|
Specifies the domain or workgroup to which the discovered host belongs to. The
|
|
type of the association (workgroup or domain) is separated from its value by a
|
|
colon.
|
|
.TP
|
|
last_seen
|
|
The date and time the device was last seen as a consequence of Probe/Hello
|
|
messages provided in ISO8601 with seconds.
|
|
.TP
|
|
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
|
|
on square brackets. Note that the reported addresses may not match the actual
|
|
device on which the device may be reached.
|
|
.TP
|
|
types
|
|
Types of the detected device, delimited by commas.
|
|
.SS \fBprobe \fI[INTERFACE]\fR - 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 messages 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.
|
|
.SS \fBstart\fR - Start networking activities
|
|
This command starts the networking acitivies 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.
|
|
|
|
.SS \fBstop\fR - 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.
|
|
|
|
.SH SECURITY
|
|
.PP
|
|
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 \fIHello\fR message contains the hosts transport address, i.e. the IP
|
|
address which speeds up discovery (avoids \fIResolve\fR message).
|
|
.SH KNOWN ISSUES
|
|
.SS Using only IPv6 on FreeBSD
|
|
If wsdd is running on FreeBSD using IPv6 only, the host running wsdd may not be
|
|
reliably discovered. The reason appears to be that Windows is not always able
|
|
to connect to the HTTP service for unknown reasons. As a workaround, run wsdd
|
|
with IPv4 only.
|
|
.SS Tunnel/Bridge Interface
|
|
.PP
|
|
If tunnel/bridge interfaces like those created by OpenVPN or Docker exist, they
|
|
may interfere with wsdd if executed without providing an interface that it
|
|
should bind to (so it binds to all). In such cases, the wsdd hosts appears after
|
|
wsdd has been started but it disappears when an update of the Network view in
|
|
Windows Explorer is forced, either by refreshing the view or by a reboot of the
|
|
Windows machine. To solve this issue, the interface that is connected to the
|
|
network on which the host should be announced needs to be specified with the
|
|
-i/--interface option. This prevents the usage of the tunnel/bridge
|
|
interfaces.
|
|
.PP
|
|
Background: Tunnel/bridge interfaces may cause \fIResolve\fR requests from Windows
|
|
hosts to be delivered to wsdd multiple times, i.e. duplicates of such request
|
|
are created. If wsdd receives such a request first from a tunnel/bridge it uses
|
|
the transport address (IP address) of that interface and sends the response via
|
|
unicast. Further duplicates are not processed due to the duplicate message
|
|
detection which is based on message UUIDs. The Windows host which receives the
|
|
response appears to detect a mismatch between the transport address in the
|
|
\fIResolveMatch\fR message (which is the tunnel/bridge address) and the IP of the
|
|
sending host/interface (LAN IP, e.g.). Subsequently, the wsdd host is ignored by
|
|
Windows.
|