Initialize Git Repository: 'WSDD'
This commit is contained in:
Cantibra
@@ -0,0 +1,261 @@
|
||||
.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.
|
||||
Reference in New Issue
Block a user