Index: wsdd/man/wsdd.1 =================================================================== --- wsdd.orig/man/wsdd.1 +++ /dev/null @@ -1,244 +0,0 @@ -.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\-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 -uses the UUID version 5 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\fR - List discovered devices -Returns a tab-separated list of discovered devices with the following information. -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. -.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 =================================================================== --- /dev/null +++ wsdd/man/wsdd.8 @@ -0,0 +1,244 @@ +.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\-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 +uses the UUID version 5 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\fR - List discovered devices +Returns a tab-separated list of discovered devices with the following information. +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. +.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.