Repository files navigation

A Unix daemon that makes your macOS/Linux/BSD/illumos/HaikuOS machine visible in Network view of Windows Explorer on newer versions of Windows.

It implements WS-Discovery protocol that Windows now uses to discover machines on local network. It is a native daemon, written in C++.

• Features
• Binary packages
  • macOS
    • Standalone installer
    • Homebrew
    • Macports
  • Ubuntu/Debian/Mint/Raspberry Pi
  • RedHat/CentOS/Fedora
  • OpenSUSE
  • Arch Linux
  • Alpine
  • FreeBSD
  • OpenBSD
  • Docker
• Building from sources
  • Prerequisites
  • Building and installing
  • Setting up daemon
• Usage
  • Firewall Setup
  • Security
  • Custom metadata
• Acknowledgements
• Reporting Bugs

• Fully supports macOS, Linux, FreeBSD, OpenBSD, NetBSD and illumos. Partial support for Haiku OS
• Can be configured via a configuration file, not just command line.
• Discovers Samba/macOS SMB configuration on its own. (This can be overridden, if desired)
• Can present the Unix host as something other than "Computer" in Windows Explorer.
• Integrates well withsystemd andlaunchd. Of course, it can also run as a classical Unix daemon for other init systems.
• Friendly to various log rotation methods likenewsyslogd andlogrotate. Supports standard reload semantics via SIGHUP.
• Written with security in mind first and foremost.
• Will never run any network code as root. Designated user account to run under is created automatically, if needed.

There are a couple of similar projects available:wsdd written in Python andwsdd2 written in C. Neither of them, however, fully provides the features above.

On macOS there are 3 ways to installwsddn: via a standalone installer package,Homebrew orMacports.Using a standalone installer is simpler but you will have to manually install any future updates as well.Homebrew/Macports are a bit more complicated to set up but it provides updatability similar to Linux/BSD package managers.

For all 3 methods the supported platforms are:

• macOS Catalina (10.15) and above
• Both Intel and Apple Silicon

sudo installer -pkg /path/to/wsddn-macos-1.22.pkg -target /

sudo launchctl kickstart system/io.github.gershnik.wsddnsudo launchctlkill TERM system/io.github.gershnik.wsddnsudo launchctlkill HUP system/io.github.gershnik.wsddn

log show --last 15m --debug --info \  --predicate'subsystem CONTAINS "wsddn" OR process CONTAINS "wsddn"'

brew tap gershnik/repo

brew install wsddn

sudo bash<<'___'set -epemurl=https://gershnik.com/macports-repo/macports.pemporturl=https://www.gershnik.com/macports-repo/ports.tar.bz2prefix=$(dirname $(dirname $(which port)))pemfile="$prefix/share/macports/gershnik.pem"pubkeysfile="$prefix/etc/macports/pubkeys.conf"sourcesfile="$prefix/etc/macports/sources.conf"curl -s $pemurl > "$pemfile"grep -qxF "$pemfile" "$pubkeysfile" || echo $pemfile >> "$pubkeysfile"grep -qxF "$porturl" "$sourcesfile" || echo $porturl >> "$sourcesfile"sudo port sync___

sudo port install wsddn

sudo launchctl kickstart system/org.macports.wsddnsudo launchctlkill TERM system/org.macports.wsddnsudo launchctlkill HUP system/org.macports.wsddn

log show --last 15m --debug --info \  --predicate'subsystem CONTAINS "wsddn" OR process CONTAINS "wsddn"'

Pre-built packages are available in a custom apt repository for systems newer than Ubuntu 20.04 (focal) orDebian 11 (bullseye). Any Debian system based upon those or newer should work.

Architectures supported:amd64 (akax86_64),arm64 (akaaarch64) andarmhf

sudo apt updatesudo apt install wsddn

sudo ufw allow wsddn

sudo systemctl start wsddnsudo systemctl stop wsddnsudo systemctl reload wsddn

journalctl -u wsddn

sudo /etc/init.d/wsddn startsudo /etc/init.d/wsddn stopsudo /etc/init.d/wsddn reload

Pre-built packages are available onFedora Copr repository.Visit that link to see currently supported distributions and architectures.

sudo dnf install dnf-plugins-core#or with yum#sudo yum install yum-plugin-copr

sudo dnf coprenable gershnik/wsddn#or with yum#sudo yum copr enable gershnik/wsddn

sudo dnf install wsddn#or with yum#sudo yum install wsddn

sudo systemctlenable wsddnsudo systemctl start wsddn

sudo systemctl start wsddnsudo systemctl stop wsddnsudo systemctl reload wsddn

journalctl -u wsddn

Pre-built OpenSUSE packages for Tumbleweed are available viaFedora Copr.

Architectures supported:x86_64 andaarch64

wget -qO wsddn.gpg  https://download.copr.fedorainfracloud.org/results/gershnik/wsddn/pubkey.gpg \&& sudo rpm --import wsddn.gpg \&& rm wsddn.gpg

sudo zypper addrepo -f https://download.copr.fedorainfracloud.org/results/gershnik/wsddn/opensuse-tumbleweed-$(arch) wsddn

sudo zypper refresh

sudo zypperin wsddn

sudo systemctlenable wsddnsudo systemctl start wsddn

sudo systemctl start wsddnsudo systemctl stop wsddnsudo systemctl reload wsddn

journalctl -u wsddn

Source package is available onAUR athttps://aur.archlinux.org/packages/wsdd-native

Pre-built packages are available in a custompacman repository.

Architectures supported:x86_64 andaarch64

sudo pacman-key --recv-keys'CF567A58C5DB9C6908C6E87E6EBB54370005A361' \&& sudo pacman-key --lsign-key'CF567A58C5DB9C6908C6E87E6EBB54370005A361'

[gershnik]Server = https://www.gershnik.com/arch-repo/$arch

sudo pacman -Sy

sudo pacman -S wsdd-native

sudo ufw allow wsddn

sudo systemctlenable wsddnsudo systemctl start wsddn

sudo systemctl start wsddnsudo systemctl stop wsddnsudo systemctl reload wsddn

journalctl -u wsddn

Pre-built packages are available in a customapk repository for Alpine 3.18 or above.

Architectures supported:x86_64 andaarch64

wget -qO-  https://www.gershnik.com/alpine-repo/gershnik@hotmail.com-6643812b.rsa.pub \| sudo tee /etc/apk/keys/gershnik@hotmail.com-6643812b.rsa.pub>/dev/null

sudo mkdir -p /etc/apk/repositories.d&& \echo"https://www.gershnik.com/alpine-repo/main" \| sudo tee /etc/apk/repositories.d/www.gershnik.com.list>/dev/null

sudo apk update

sudo apk add wsdd-native

sudo rc-update add wsddnsudo rc-service wsddn start

sudo rc-service wsddn startsudo rc-service wsddn stopsudo rc-service wsddn reload

Pre-built packages are available for FreeBSD 13 and 14 in a custom binary package repository.Bothamd64 (akax86_64) andarm64 (akaaarch64) architectures are supported.

sudo pkg updatesudo pkg install wsddn

wsddn_enable="YES"

sudo service wsddn startsudo service wsddn stopsudo service wsddn reload

A standalone binary package is available for OpenBSD 7.5 and higher. Onlyamd64 (akax86_64)architecture is currently supported. The package is available fromReleases.

mv wsddn-1.22-OpenBSD-amd64.tgz wsddn-1.22.tgz

#pkg_add -D unsigned wsddn-x.y.tgz

#pkg_delete [-c] wsddn

#rcctlenable wsddn

#rcctl start wsddn#rcctl stop wsddn#rcctl reload wsddn

On Linux, if you are loath to install or build anything you also have an option to runwsdd-native in a Docker container.

docker run --net=host -e WSDDN_HOSTNAME=$(hostname) gershnik/wsddn

• Git
• C++20 capable compiler. Minimal compilers known to work are GCC 10.2, Clang 13 and Xcode 13.
• CMake 3.25 or greater. If your distribution CMake is older than that you can download a newer version fromhttps://cmake.org/download/
• Optional: On Linux if you wish to enablesystemd integration make sure you havelibsystemd library and headers installed on your system. On APT systems use:

  sudo apt install libsystemd-dev

  On DNF systems use

  sudo dnf install systemd-devel

git clone https://github.com/gershnik/wsdd-native.gitcd wsdd-nativecmake -S. -B out -DCMAKE_BUILD_TYPE=RelWithDebInfo cmake --build outsudo cmake --install out --strip

Thewsddn executable will be installed into/usr/local/bin and manpage added to section 8 of the manual.

The following flags can be passed to CMake configure step:

• -DWSDDN_PREFER_SYSTEM_LIBXML2=ON|OFF
• -DWSDDN_PREFER_SYSTEM_FMT=ON|OFF
• -DWSDDN_PREFER_SYSTEM_SPDLOG=ON|OFF
• -DWSDDN_PREFER_SYSTEM_TOMLPLUSPLUS=ON|OFF

This controls whether to prefer system package version of 3rd party libraries or fetch and use them from sources.By default all dependencies are fetched and used from sources.

On Linux:

-DWSDDN_WITH_SYSTEMD="yes"|"no"|"auto".

This controls whether to enablesystemd integration. Auto performs auto-detection (this is the default).

Theconfig directory of this repo contains sample configuration files for different init systems (Systemd, Launchd, SysV init, FreeBSD and OpenBSD rc.d and OpenRC). You can adapt those as appropriate to your system.

Command line flags and configuration file entries are documented inman wsddn and onlinehere

Note: The following instructions are copied almost verbatim fromwsdd since the requirements are identical

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

• incoming and outgoing traffic toudp/3702 with multicast destination:
  • 239.255.255.250 for IPv4
  • ff02::c for IPv6
• outgoing unicast traffic fromudp/3702
• incoming totcp/5357

You should further restrict the traffic to the (link-)local subnet, e.g. by using thefe80::/10 address space for IPv6. Please note that IGMP traffic must be enabled in order to get IPv4 multicast traffic working.

For UFW and firewalld, application/service profiles can be found underconfig/firewalls. If using binary installation packages these are providedas part of the installation. Note that UFW profiles only allow to grant the traffic on specific UDP and TCP ports, but a restriction on the IP range (like link local for IPv6) or the multicast traffic is not possible.

There are four main security concerns with a daemon that accepts network requests and delivers data about local machine over the network

1. A bug inside the daemon code may allow a remote attacker to penetrate the machine running it.
2. The information legitimately provided by the daemon will disclose something to an attacker that would otherwise remain unknown, enabling him to mount further attacks.
3. A bug or even thenormal functionality of the daemon might allow a remote attacker to use it to mount further attacks against other systems. For example it might be possible to "convince" the daemon to become a part of a distributed denial of service (DDoS) attack.
4. A bug or a normal operation of the daemon might allow a remote attacker to make it or even the entire machine hosting it unresponsive resulting in a denial of service.

Currently the implementation ignores the second concern. The thingswsdd-native discloses are the existence of the local host, its name, presence of Samba on it and domain/workgroup membership. All of these are generally disclosed by Samba itself via SMB broadcasts so, assuming the firewall is configured as described above, there is no net gain for an attacker. WS-Discovery protocol contains provisions for encrypting its HTTP traffic and potentially authenticating clients accessing your host via their client certificates. This limits exposure somewhat but at a significant configuration and maintenance cost. If there is interest in any of it it is possible to easily add this functionality in a future version.

The first concern is by far the most significant one. All software contains bugs and despite developer's best efforts there is always a risk that a bad actor can discover some kind of input that allows him to hijack the server process. To address this possibilitywsdd-native takes the following measures (apart from general secure coding practices):

• The process performing network communications never runs as root. If launched as root it will create an unprivileged account (_wsddn:_wsddn orwsddn:wsddn based on platform conventions) and run network process under it.
• Similarly when started as root the daemon will lock the network process in achroot jail (usually/var/empty or/var/run/wsddn or another platform appropriate location).

These measures are automatic and cannot be bypassed. Taken together they should limit the fallout of any vulnerability though, of course, nothing ever can be claimed to be 100% secure.

Note that when running onsystemd systems it is recommended to use itsDynamicUser facility instead of running as root and relying on the measures above. The Debian/Ubuntu/Fedora/Arch binary packages do so.

The third concern is also a significant one. Even in absence of any bugs a completely correct implementation of WS-Discovery protocol is known to be vulnerable to these kinds of attacks. See for examplehere andhere.Bugs (always a possibility) can make things even worse. As far as I know there is no effective mitigation to this threat thatwsdd-native can implement in code. The only way to prevent these kinds of attacks is tonever exposewsdd-native ports to open internet viafirewall configuration. Given that the whole purpose of this daemon is to enable interoperability with Windows via SMB protocol there is probably never a goodreason to let it accept and send traffic outside of a local network.

The fourth concern, while also present, is less severe than the above.wsdd-native is single threaded and so, even if overwhelmed by traffic, will not stress more than 1 CPU core. Its memory consumption is bounded so, in absence of bugs, it will not stress system memory either. It can itself be rendered unresponsive, of course, by too much traffic but, considering that it probably isn't a vital service for anyone, this isn't something that would excite any attacker. Possible bugs change this picture, however. If the network process is hijacked, even if mitigations for the 1st concern prevent further system penetration, the attacker can still make the network process consume too much CPU and memory. You can try to mitigate against this possibility by limiting daemon CPU and memory usage viacgroups or other mechanisms. However, a much simpler solution to these issues is the same as the above - never expose the daemon to the open internet.

By defaultwsdd-native exposes the host it is running on as a computer in "Computer" section of Windows Explorer Network view. Clicking on a computer will attempt to access its shares via SMB protocol.

Instead of thiswsdd-native allows you to expose the host as a different kind of device among those supported by Windows Explorer, for example a media player, home security, printer etc. To do so you need to author a custom metadata XML and specify it via--metadata command line switch ormetadata field inwsddn.conf.

More details on this can be foundon this page.

wsdd-native is directly influenced bywsdd. While no source code from it was directly re-used in this project, many design and implementation ideas were; as well as command line design and some documentation content.

SeeAcknowledgements.md for information about open source libraries used in this project.

Please use the GitHubissue tracker to report any bugs or suggestions.For vulnerability disclosures or other security concerns seeSecurity Policy