Wake-on-LAN: Client

OS:

πŸͺ Platform-independent

In client mode, Desomnia runs on the machine you use to connect to other hosts β€” your laptop, desktop, or workstation. It monitors your outgoing network traffic and automatically sends a Magic Packet to wake a sleeping host the moment you try to connect to one of its services.

This mode requires no dedicated device. If you have a machine in your network that runs around the clock β€” such as a Raspberry Pi or a NAS β€” consider the Wake-on-LAN: Proxy guide instead, which provides Wake-on-LAN coverage for your entire network from a single installation.

Note

The configuration for both modes is nearly identical. The only difference is where you install and run Desomnia. If you later decide to switch to proxy mode, your existing configuration carries over with minimal changes.

Before you begin

Make sure the following are in place before writing your first configuration:

  • Desomnia is installed on the machine you connect from. Refer to the Installation section of this documentation for your platform.

  • Wake-on-LAN is enabled on the target host. This typically requires enabling it in the BIOS / UEFI firmware of the target machine and ensuring that the network adapter remains powered while the system is suspended. The exact setting is often labelled Wake-on-LAN, Wake on Magic Packet, or Power On By PCI-E, depending on the firmware vendor.

  • You have the MAC address of the target host. Magic Packets are addressed by MAC, not by IP, so this is always required. If the host is currently awake, run arp -a from any machine on the same network, or look it up in your router’s device list.

Verifying Wake-on-LAN capabilities

To verify that Wake-on-LAN is working on a target host independently of Desomnia, you can send a Magic Packet manually using the wakeonlan utility, available for Linux and macOS via common package managers:

# Debian / Ubuntu
sudo apt install wakeonlan

# macOS
brew install wakeonlan

wakeonlan 00:1A:2B:3C:4D:5E

If the host wakes up, its firmware and network adapter are configured correctly. If it does not, the issue lies with the target host’s configuration rather than with Desomnia.

Minimum working configuration

The following configuration tells Desomnia to watch your network and send a Magic Packet to "server" whenever an outgoing connection to it is detected:

<?xml version="1.0" encoding="UTF-8"?>
<SystemMonitor version="1">

  <NetworkMonitor>
    <RemoteHost name="server" MAC="00:1A:2B:3C:4D:5E" IPv4="192.168.1.10" />
  </NetworkMonitor>

</SystemMonitor>

Replace 00:1A:2B:3C:4D:5E with the MAC address of your target host and 192.168.1.10 with its IP address.

The <NetworkMonitor> element here specifies neither an interface nor a network attribute, which tells Desomnia to automatically bind to all interfaces that have a default gateway configured β€” normally just the interface connected to your local network. If you have multiple active network connections and need to target a specific one, see Interface selection.

The IPv4 attribute on <RemoteHost> is optional in many environments. If your router provides DNS for local hosts, Desomnia can resolve the address automatically β€” see Auto-configuration to learn how to remove static address mappings from your configuration once you have a working baseline.

Note

With this configuration, Desomnia reacts to any outgoing connection directed at "server" β€” including background traffic from your operating system or other applications. The filtering section below explains how to restrict this to only the services you use.

Verifying it works

Start the Desomnia service, then try connecting to a service on the target host while it is suspended. Desomnia logs a message each time it detects a connection attempt and each time it sends a Magic Packet.

To see the full detail of what is being detected, enable debug-level logging β€” see Logging.

If the host does not wake up, check the following:

  • Wake-on-LAN is enabled in the BIOS / UEFI settings of the target host.

  • The network adapter on the target host is configured to remain powered while suspended.

  • The MAC address and IP address in the configuration match the target host exactly.

  • Desomnia is monitoring the correct network interface β€” confirm with Interface selection.

Filtering unwanted wake-ups

With the minimal configuration in place, Desomnia reacts to any connection directed at the watched host’s IP address. Depending on your operating system and running applications, background traffic β€” such as network discovery, address resolution, or periodic health checks β€” can occasionally match and trigger an unwanted wake-up.

The following sections explain how to narrow this down to the connections you actually care about.

Filter by service

The most reliable way to prevent unwanted wake-ups is to restrict Desomnia to specific services by port number. Adding a <ServiceFilterRule> with type="Must" makes it an inclusive filter: only connections to that specific port will trigger a wake-up.

<RemoteHost name="server" MAC="00:1A:2B:3C:4D:5E" IPv4="192.168.1.10">
  <ServiceFilterRule name="SSH" port="22" type="Must" />
</RemoteHost>

This configuration wakes "server" only when a TCP connection to port 22 is detected. All other connections to that host are ignored.

To react to multiple services, add one rule per port:

<RemoteHost name="server" MAC="00:1A:2B:3C:4D:5E" IPv4="192.168.1.10">
  <ServiceFilterRule name="SSH"  port="22"   type="Must" />
  <ServiceFilterRule name="SMB"  port="445"  type="Must" />
  <ServiceFilterRule name="RDP"  port="3389" type="Must" />
  <ServiceFilterRule name="HTTP" port="80"   type="Must" />
</RemoteHost>

As long as at least one inclusive rule is present, any connection to a port not listed is automatically ignored.

For UDP-based services, set protocol="UDP" explicitly:

<ServiceFilterRule name="DNS" protocol="UDP" port="53" type="Must" />

Hint

The name attribute on a <ServiceFilterRule> is optional and purely descriptive. It appears in log output and helps identify which rule triggered an event.

Excluding specific services

If only a small number of services cause unwanted noise, you may prefer the opposite approach: leave the default behaviour in place β€” wake on any connection β€” and explicitly exclude the services you want to ignore using type="MustNot":

<RemoteHost name="server" MAC="00:1A:2B:3C:4D:5E" IPv4="192.168.1.10">
  <ServiceFilterRule name="Monitoring" port="8080" type="MustNot" />
</RemoteHost>

Connections to port 8080 are ignored; all other connections to this host can still trigger a wake-up.

Note

type="MustNot" is the default for all filter rules when no type is set explicitly. The two approaches β€” whitelisting with type="Must" and blacklisting with type="MustNot" β€” can be mixed, but the interaction can be difficult to reason about: as soon as at least one type="Must" rule is present, the filter switches to whitelist mode and type="MustNot" rules act only as exclusions within that whitelist.

Filter ping traffic

Some operating systems and network tools send ICMP echo requests (pings) to check whether a host is reachable. These operate at the IP layer, before any TCP or UDP connection is established, and can trigger an unwanted wake-up if they happen to target a watched host.

If you have already configured at least one type="Must" service filter, or used <Service> declarations, ping traffic is automatically excluded β€” no further configuration is needed.

Without any inclusive service filter, you can suppress pings explicitly:

<NetworkMonitor>
  <PingFilterRule />
  <RemoteHost name="server" MAC="00:1A:2B:3C:4D:5E" IPv4="192.168.1.10" />
</NetworkMonitor>

Placing the rule at the <NetworkMonitor> level applies it to all watched hosts. To limit it to a specific host, place the rule inside the corresponding <RemoteHost> element.