wsddn(8)

NAME

wsddn - WS-Discovery Host Daemon

SYNOPSIS

wsddn --help
wsddn --version
wsddn [--unixd|--systemd|--launchd] [-c path] [-i name]… [-4|-6] [--hoplimit number] [--uuid uuid] [-H name] [-D|-W name] [--log-level level] [--log-file path | --log-os-log] [--pid-file path] [-U user[:group]] [-r dir]

DESCRIPTION

wsddn is a native daemon that implements the WS-Discovery (WSD) host protocol. It allows UNIX hosts to be found by modern Windows versions and displayed in their Explorer Network views.

wsddn can be configured using command-line options or a configuration file (see --config option below); command-line options override values specified in the configuration file.

wsddn rereads its configuration file when it receives a hangup signal, SIGHUP.

OPTIONS

Unless otherwise specified, options cannot be repeated. The options are as follows:

General options

--help, -h: Print usage information and exit.
--version, -v: Print version and exit.
--unixd: Run as a traditional UNIX daemon.
--systemd: Run as a systemd daemon. This option is only available on systemd systems.
--launchd: Run as a launchd daemon. This option is only available on macOS.
--config path, -c path: Path to the configuration file. The file does not need to exist. If it exists, the file is read and options specified in it are applied if not already specified on the command line. See [CONFIG FILE] below for information about its syntax and content. Content of the configuration file is re-read upon SIGHUP signal. By default, if this option isn’t specified, no configuration file is read.

Daemon behavior options

--log-level level

Sets the verbosity of log output. Log levels range from 0 (disable logging) to 6 (detailed trace) with the default being 4. Passing values bigger than 6 is equivalent to 6.

--log-file path

The path of the file to write the log output to. If not specified, wsddn outputs its log messages as follows:

If invoked without any daemon flags: to standard output
If invoked with --systemd: to standard output, with systemd severity prefixes
If invoked with --launchd: to standard output
If invoked with --unixd: to /dev/null (no logging)

--log-os-log

Available on macOS only. If specified, log output is sent to the system log visible via the Console app or log command-line tool. This option is mutually exclusive with --log-file.

--pid-file path

Set the path to the PID file. If not specified, no PID file is written. Send SIGHUP to the process ID in the PID file to reload configuration. If the --user option is used, the directory of the PID file must allow the specified user to create and delete files.

--user username[:groupname], -U username[:groupname]

Set the identity under which the process that performs network communications will run. If the group name is not specified, the primary group of the username is used.

If this option is not specified, then the behavior is as follows:

If the wsddn process is run under the root account, it tries to use a special unprivileged account name (_wsddn:_wsddn or wsddn:wsddn depending on the platform). The user and group are created if they do not exist. Any failures in these steps stop the process.
Otherwise, wsddn uses the account it is run under.

The net effect of these rules is that wsddn will under no circumstances perform network communications under the root account.

--chroot dir, -r dir

Set the directory into which the process that performs network communications should chroot. This further limits any impact of potential network exploits against wsddn.

If not specified, the behavior is as follows:

If the wsddn process is run under the root account: use /var/empty or /var/run/wsddn depending on the platform. This directory will be created if it does not exist.
Otherwise: do not chroot.

Note: do not use external methods to chroot the wsddn process (e.g., using launchd config plist). Non-networking parts of wsddn need access to the normal filesystem to detect SMB configuration, etc.

Networking options

--interface name, -i name: Network interface to use. Pass this option multiple times for multiple interfaces. If not specified, all eligible interfaces will be used. Loop-back interfaces are never used, even when explicitly specified. For interfaces with IPv6 addresses, only link-local addresses will be used.

The equivalent config file option is interfaces.
--ipv4only, -4: Use only IPv4. By default, both IPv4 and IPv6 are used. This option cannot be combined with --ipv6only.

The equivalent config file option is allowed-address-family.
--ipv6only, -6: Use only IPv6. By default, both IPv4 and IPv6 are used. This option cannot be combined with --ipv4only.

The equivalent config file option is allowed-address-family.
--hoplimit number: Set the hop limit for multicast packets. The default is 1, which should prevent packets from leaving the local network segment.
--source-port number: 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.

Machine information options

--uuid uuid: The WS-Discovery protocol requires your machine to have a unique identifier that is stable across reboots or changes in networks. By default, wsddn uses UUID version 5 with a private namespace and the host name of the machine. This will remain stable as long as the hostname doesn’t change. If desired, you can override this with a fixed UUID using this option.
--hostname name, -H name: Override the hostname to be reported to Windows machines. By default, the local machine’s hostname (with domain part, if any, removed) is used. If you set the name to :NETBIOS:, then the NetBIOS hostname will be used. The NetBIOS hostname is either detected from SMB configuration, if found, or produced by capitalizing the normal machine hostname.
--domain name, -D name: Report this computer as a member of a Windows domain name. Options --domain and --workgroup are mutually exclusive. If neither is specified, domain/workgroup membership is auto-detected from SMB configuration. If no SMB configuration is found, it is set to a workgroup named WORKGROUP.

The equivalent config file option is member-of.
--workgroup name, -W name: Report this computer as a member of a Windows workgroup name. Options --domain and --workgroup are mutually exclusive. If neither is specified, domain/workgroup membership is auto-detected from SMB configuration. If no SMB configuration is found, it is set to a workgroup named WORKGROUP.

The equivalent config file option is member-of.
--smb-conf path: Path to smb.conf, samba.conf, or ksmbd.conf file to extract the SMB configuration from. This option is not available on macOS. By default, wsddn tries to locate this file on its own by querying your local Samba installation. Use this option if auto-detection fails, picks the wrong Samba instance, or if you are using KSMBD on Linux. The equivalent config file option is smb-conf.
--metadata path, -m path: Path to a custom metadata XML file. Custom metadata allows you to completely replace the information normally supplied by wsddn to Windows with your own. See https://github.com/gershnik/wsdd-native/blob/master/config/metadata/README.md for details about the metadata format and content.

ENVIRONMENT

The following environment variables, in order of precedence from highest to lowest, control wsddn color output:

NO_COLOR: Set to a non-empty value (1 is recommended) to prevent color output on stdout/stderr.
FORCE_COLOR: Set to a non-empty value (1 is recommended) to force color output on stdout/stderr.
CLICOLOR_FORCE: If set to 0 or false, it prevents color output on stdout/stderr. If set to any other non-empty value, it forces color output.
CLICOLOR: Same as CLICOLOR_FORCE but with lower precedence.
COLORTERM: If set to a non-empty value, the terminal is assumed to support color output. Unless suppressed by higher precedence variables, the output to stdout/stderr will be colored iff they are connected to the terminal (as reported by isatty()).
TERM: The content of this variable is used to detect whether the terminal supports colors. The detection criteria are undocumented and subject to change. If the terminal is deemed to support colors and unless suppressed by higher precedence variables, the output to stdout/stderr will be colored iff they are connected to the terminal (as reported by isatty()).

SIGNALS

wsddn handles the following signals:

SIGHUP: Gracefully stop network communications, reload configuration and re-start communications.
SIGTERM, SIGINT: Gracefully stop network communications and exit.

EXIT STATUS

The wsddn exit code is 0 upon normal termination (via SIGINT or SIGTERM) or non-zero upon error.

FIREWALL SETUP

Traffic for the following ports, directions and addresses must be allowed:

Incoming and outgoing traffic to udp/3702 with multicast destination: 239.255.255.250 for IPv4 and ff02::c for IPv6
Outgoing unicast traffic from udp/3702
Incoming traffic to tcp/5357

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.

CONFIG FILE

The syntax of the configuration file is TOML (https://toml.io/en/).

Any options specified on the command line take precedence over options in the config file. Most options are named and behave exactly the same as the corresponding command line options. Exceptions are explained in-depth below.

allowed-address-family = "IPv4" | "IPv6": Restrict communications to the given address family. Valid values are "IPv4" or "IPv6", case-insensitive. The equivalent command line options are --ipv4only and --ipv6only.
chroot = "path": Same as --chroot command line option.
hoplimit = number: Same as --hoplimit command line option.
source-port = number: Same as --source-port command line option.
hostname = "name": Same as --hostname command line option.
interfaces = [ "name", … ]: Specify which interfaces wsddn will be listening on. If no interfaces are specified, or the list is empty, all suitable detected interfaces will be used. Loop-back interfaces are never used, even when explicitly specified. For interfaces with IPv6 addresses, only link-local addresses will be used. The equivalent command line option is --interface.
log-level = number: Same as --log-level command line option.
log-file = "path": Same as --log-file command line option.
log-os-log = true/false: Same as --log-os-log command line option.
member-of = "Workgroup/name" | "Domain/name": Report whether the host is a member of a given workgroup or domain. To specify a workgroup, use "Workgroup/name" syntax. To specify a domain, use "Domain/name". The "workgroup/" and "domain/" prefixes are not case-sensitive. If not specified, workgroup/domain membership is detected from SMB configuration. If no SMB configuration is found, it is set to a workgroup named WORKGROUP. The equivalent command line options are --domain and --workgroup.
pid-file = "path": Same as --pid-file command line option.
smb-conf = "path": Same as --smb-conf command line option.
metadata = "path": Same as --metadata command line option.
user = "username[:groupname]": Same as --user command line option.
uuid = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx": Same as --uuid command line option.

EXAMPLES

Run as a traditional Unix daemon

wsddn --unixd --config=/usr/local/etc/wsddn.conf --pid-file=/var/run/wsddn/wsddn.pid --log-file=/var/log/wsddn.log

Run as a systemd daemon

wsddn --systemd --config=/etc/wsddn.conf

Handle traffic on eth0 and eth2 only, but only with IPv6 addresses

wsddn -i eth0 -i eth2 -6

AUTHOR

Eugene Gershnik gershnik@hotmail.com

BUG REPORTS

Report bugs at https://github.com/gershnik/wsdd-native/issues