Skip to content

wsddn.8.adoc

Latest commit

 

History

History
318 lines (226 loc) · 12.4 KB

wsddn.8.adoc

File metadata and controls

318 lines (226 loc) · 12.4 KB

wsddn(8) Manual Page

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 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 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 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 system log visible via Console app or log command line tool. This option is mutually exclusive with --log-file.

--pid-file path

Set the path to PID file. If not specified no PID file is written. Send SIGHUP to the process ID in the PID file to reload configuration. If --user option is used, the directory of the pidfile 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 group name is not specified, primary group of the username is used.

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

  • If wsddn process is run under the root account it tries to use a special unprivileged account name (_wsddn:_wsddn or wsddn:wsddn depending on a 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 under no circumstances will perform network communications under root account.

--chroot dir, -r dir

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

If not specified the behavior is as follows:

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

  • Otherwise: do not chroot.

Note: do not use external methods to chroot 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

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 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 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 Netbios hostname will be used. The Netbios hostname is either detected from SMB configuration, if found, or produced by capitalizing normal machine hostname.

--domain name, -D name

Report this computer as a member of 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 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 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 prevents color output stdout/stderr. If set to any other non-empty value 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

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

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 command line take precedence over options in the config file. Most options are named and behave exactly the same as 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 on 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