Index: wsdd/man/wsdd.1
===================================================================
--- /dev/null
+++ wsdd/man/wsdd.1
@@ -0,0 +1,254 @@
+.TH wsdd 1
+.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\-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
+UUID
+UUID 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.
Index: wsdd/man/wsdd.8
===================================================================
--- wsdd.orig/man/wsdd.8
+++ /dev/null
@@ -1,254 +0,0 @@
-.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\-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
-UUID
-UUID 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.