Configuration

This reference has been created to allow you to easily see all the available configuration options of Desomnia at a glance, as opposed to the rather prosaic explanations on the other pages.

Style

⏳ Please note: For every attribute describing a span of time, you may decide to use one of the following formats:

an easily readable notation with English time units “h” for hours, “min” for minutes, “s” for seconds and “ms” for milliseconds; for example: 3h20min or 100ms
the ISO 8601 notation for durations: PT3H20M0.1S
the C# TimeSpan format: 03:20:0.1

This choice has no further technical implications and is merely an expression of personal taste.

NetworkMonitor

Desomnia provides support for monitoring any number of installed network interfaces. You can specify which configuration should be used with which interface by using the interface and/or network attribute. If none of them is declared, the configuration will be valid for all interfaces with a gateway configured. See Interface selection to learn more about this.

<SystemMonitor version="1">

  <NetworkMonitor interface="eth0" network="192.168.178.0/24"

    autoDetect="IPv4|IPv6|Router|..."
    autoTimeout="5s"
    autoRefresh="1h"

    advertise="lazy"
    advertiseIfStopped="true"

    demandTimeout="5s"
    demandForward="true"
    demandParallel="1"

    knockMethod="plain"
    knockPort="62201"
    knockProtocol="UDP"
    knockDelay="500ms"
    knockRepeat="2s"
    knockTimeout="10s"
    knockSecret="changeme"
    knockSecretAuth="..."
    knockSecretAuthType="SHA256"
    knockEncoding="UTF-8"

    pingTimeout="500ms"
    pingFrequency="1min"

    wakeType="auto"
    wakePort="9"
    wakeRepeat="2s"
    wakeTimeout="10s"

    watchMode="normal"
    watchDeviceTimeout="10s"
    watchUDPPort="9"
    watchYield="false"

    allowWakeOnLAN="MagicPacket"

    onConnect="..."
    onDisconnect="...">

    <!-- network entities -->

    <Host ... />
    <LocalHost ... /> <!-- or use it inline -->
    <RemoteHost ... />
    <Router ... />

    <HostRange ... />
    <DynamicHostRange ... />

    <!-- global packet filters -->

    <HostFilterRule ... />
    <HostRangeFilterRule ... />
    <ForeignHostFilterRule ... />
    <ServiceFilterRules ... />
    <ServiceFilterRule ... />
    <HTTPFilterRule ... />
    <PingFilterRule ... />

  </NetworkMonitor>

  <NetworkMonitor interface="eth1">
     <!-- optionally, watch additional network interfaces -->
  </NetworkMonitor>

</SystemMonitor>

interface

Describes the name of the network interface to capture traffic on.

network

Describes the network to capture traffic on. You can specify a single IP address or describe a whole subnet in the CIDR notation. The local network device must be configured accordingly for this configuration to become active.

autoDetect

inherited:
default:: nothing

Desomnia can try to automatically discover the shape of your network. The values MAC, IPv4, IPv6 and Services are inherited by all the configured hosts, while Router and SleepProxy tell Desomnia to discover the respective network entities. You can freely combine all the different values with the pipe operator. The outcome of the discovery process will vary according to the installed plugins and the possibilities of your individual network.

The following entities are available for auto-configuration:

MAC: Attempt to discover the MAC address of configured hosts and routers.
IPv4: Attempt to discover the IPv4 address of configured hosts and routers.
IPv6: Attempt to discover the IPv6 address(es) of configured hosts and routers.
Router: Attempt to locate the acting network router automatically, so that you can omit a <Router> element from your configuration.
🚧 VPN: Attempt to discover VPN devices connected to your router (if possible).
🚧 SleepProxy: Attempt to discover sleep proxies on the network, in order to register local services before sleep.
🚧 Services: Attempt to discover services advertised by remote hosts.

You may also use nothing to disable all discovery, or everything to enable all available options.

autoTimeout

default:: 5s

Sets the timeout, after which a single request to a name or address resolution authority (e.g. ARP, NDP, DNS, WINS, etc.) will be cancelled and the configurable entity considered as unknown.

autoRefresh

If you define this attribute, Desomnia will scan repeatedly for a changed configuration, waiting for the specified duration each time.

advertise

inherited:
default:: lazy

This option controls when your system should advertise an IP address, that is not it’s own. This only makes sense when the Network Monitor is in promiscuous mode, or when there are offline/suspended virtual machines. You can mix and match all the options using the pipe operator.

The following options are available to specify which address procotols should be advertised:

IPv4: advertise IPv4 addresses
IPv6: advertise IPv6 addresses
IP: advertise IPv4 and IPv6 addresses

The following options are available to specify when addresses should be advertised:

Demand: advertise addresses when the remote host is requested
Suspend: advertise addresses after the remote host has been suspended
Stop: advertise addresses after the remote host has been stopped (manually or on disconnect)
Resume: advertise addresses when the local host resumes from suspend

For your convenience there are two practical short hand notations:

lazy = IP|Demand

(remote) hosts are only advertised when requested

eager = IP|Demand|Suspend|Resume

(remote) hosts are advertised as soon as possible

This may be useful in situations where hosts are frequently resuming and suspending (less than 5min).

advertiseIfStopped

inherited:
default:: true

This options only affects remote hosts. Because there is no standard way of determining whether a remote host has been suspended or turned off without the host itself informing us, we have to assume that it stopped per default. A suspension can only reliably be detected if the remote host is running an instance of Desomnia or a Sleep Proxy client. You can then turn this off in order to prevent addresses for offline systems from being advertised.

demandForward

inherited:
default:: true

This controls, if the original request should be forwarded to the target host, after a successful wake-up. A TCP client usually repeats it’s SYN a couple of times before giving up, waiting each time a little longer. Resending the SYN immediately after the target host signals that it is ready to receive can reduce the time it takes to establish the connection. If the target host takes more than a few seconds, it can prevent a timeout on the client side in some cases. It should be safe to leave this enabled by default.

demandTimeout

inherited:
default:: 5s

Sets the timeout, for how long Desomnia waits to confirm a particular demand request. This is mainly relevant if you use the Network Monitor in promiscuous mode and more than one packet is required to establish whether the host in question should be woken up. The request holds some resources which will not be released until either the request succeeds or the timeout period elapses. If you do not configure Desomnia to process more than one request at a time, this will also prevent further requests from different clients. This may lead to a reduced responsiveness, if the timeout is set too high.

demandParallel

inherited:
default:: 1

This value determines how many demand requests can be processed in parallel for any given host. For safety reasons, the default setting allows no more than one request to run in parallel, which should be sufficient for most setups. To accommodate more complex setups involving local virtual machines and a remote host running Desomnia in promiscuous mode, it may be necessary to increase this to at least 2.

watchTimeout

⏱️ duration:
default:: 1min

The packet capture device can sometimes become unresponsive. If you select this option, the Network Monitor will restart if no packets have been captured for the specified duration.

knockMethod

inherited:
default:: plain

This option determines which method Desomnia should use for the Single Packet Authorization (SPA), if knock is configured as a onDemand action for a particular service. The core includes the plain method to quickly configure a password, that will be transmitted in clear text to the configured knockPort. Please consider to install additional plugins (e.g. Firewall Knock Operator) to unlock more secure knock methods.

knockPort

inherited:
default:: 62201

This option configures the port against which a Single Packet Authorization will be performed.

knockProtocol

inherited:
default:: UDP

This option configures the protocol that will be used to perform a Single Packet Authorization.

knockDelay

inherited:
default:: 500ms

This option specifies the amount of time to wait before performing a Single Packet Authorisation if the remote host does not respond.

knockRepeat

inherited:

This option specifies whether to repeat the Single Packet Authorisation process and how long to wait between each attempt.

knockTimeout

inherited:
default:: 10s

This option specifies how long to wait before considering the Single Packet Authorisation as failed, and when to stop sending packets.

knockSecret

inherited:

This option specifies either the secret password to be sent to the remote host, or the key to be used to encrypt the SPA packet.

knockSecretAuth

inherited:

This option specifies the key to be used for authenticating the SPA packet. If this option is not set, authentication will not be performed, which could compromise the security of the SPA.

knockSecretAuthType

inherited:
default:: depends on the knock method

This option specifies the hashing algorithm used to authenticate the SPA packet. Possible values are:

MD5
SHA1
SHA256
SHA384
SHA512
SHA3_256
SHA3_512

Note

If you do not specify a concrete hashing algorithm, the selected knock method may use a certain default.

knockEncoding

inherited:
default:: UTF-8

This option specifies the encoding to be used to build the knockSecret and knockSecretAuth from the configuration file. Possible formats are UTF-8 and Base64.

pingTimeout

inherited:
default:: 500ms

Defines the timeout, after which a remote host will be considered unreachable, after a ARP request, NDP solicitation or ICMP echo request remains without reply. Decrease this value to accelerate demand requests in general. Increase this timeout to reduce unnecessarily executed demand requests on a lagging network.

pingFrequency

inherited:

This defines the frequency at which a remote host will be checked to determine whether it is operational. In order to advertise the changed IP ownership of a remote host early, the respective host has to be checked regularly. If you don’t configure this value, no regular checks will be performed.

wakeType

inherited:
default:: auto

Specifies, how Magic Packets should be sent. Possible values are:

auto: Checks if the requested IP address is in the same subnet as the configured network interface. If both hosts reside in the same network (meaning they share the same range of IP addresses), link will be used. Otherwise a combination of network|unicast will be used, because it will be unlikely then, that the target host can be reached with a link layer packet.
link: Uses ethernet packets with an an EtherType of 0x0842, that operate below the threshold of user space applications, to prevent interference with actual network services. For this to work, the target host has to be on the same subnet.
network: Uses UDP packets with the Magic Packet as payload, which can be routed over the internet or a tunnel connection (VPN). It may be necessary to configure a static address mapping on the router or VPN server, to reach the sleeping host. Can be observed by user space applications, that listen on the specified port number.
unicast: Send the Magic Packet directly to the device to wake up, without using a broad- or multicast. The link layer packet will be directed at the Ethernet address of the device and potentially all the known IP addresses of the host, if configured with network.
none: Do not send any Magic Packets. This setting is used to temporarily prevent a host from waking up.

wakePort

inherited:
default:: 9

Specifies the port number for Magic Packets encapsulated in UDP packets, if wakeType was configured with network. If wakeType is configure with link, this attribute has no meaning.

Typical port numbers used for this are 7 (Echo) or 9 (Discard).

wakeTimeout

inherited:
default:: 10s

Defines the timeout, after that a wake up will be considered as failed, if we haven’t received any response from the target host after the Magic Packet has been sent. There will be a warning in the log file, if this happens. Also buffered packets will only be forwarded to the target host, if the demand request succeeds.

wakeRepeat

inherited:

This option specifies whether to resend the Magic Packet and how long to wait between each attempt, until the configured wakeTimeout has elapsed.

wakePing

inherited:
default:: false

This option specifies whether to actively ping the target host during a wake operation. Each individual ping will timeout after the configured pingTimeout, until the configured wakeTimeout has elapsed. If you do not configure this parameter, the NetworkMonitor will try to passively listen for a sign that the target host has successfully been woken up. The target host will actively pinged in any case, if it is not part of the local subnet.

watchMode

default:: normal

This option determines the desired mode of operation:

normal: The Network Monitor will only concern itself with outgoing packets, sent by the local host. In this mode remote hosts will automcatically woken up with a Magic Packet, when a program tries to access any of their services.

Note

Your local host will never advertise an IP address that does not belong to it.
promiscuous: The Network Monitor will also react to incoming (multicast) packets, that where sent by remote hosts. In this mode you can watch an entire broadcast domain and transparently do Wake-on-LAN, without modifying either client nor server.

Warning

If necessary the local host may advertise IP addresses that does not belong to it.

watchUDPPort

Desomnia typically uses an EtherType of 0x0842 to send and receive Magic Packets to do Wake-on-LAN, to prevent interference with actual network services. Use this attribute, to make it aware of Magic Packets encapsulated in (probably broadcasted) UDP packets on the given port. If you do not configure this and don’t monitor any other UDP services, UDP packets can be filtered entirely inside the kernel space, which can dramatically reduce the CPU load in heavy UDP scenarios.

Typical port numbers used for this are 7 (Echo) or 9 (Discard).

watchYield

default:: false

Setting this option instructs Desomnia to notify the other nodes on the network before suspending the system. Since there is no standard way to communicate this in a computer network, various techniques will be used:

For now Desomnia will send a special “Unmagic Packet” as an ethernet broadcast, which contains it’s own MAC address as sender and target. Other instances of Desomnia (presumable running in promiscuous mode) can detect this and potentially take over the local IP addresses, to ensure that the next request will wake up the local host immediately, without waiting for the IP caches of the other network nodes to expire.

Work in progress

Later, Desomnia will be able to register the local services it is watching with a Sleep Proxy on the network. The Proxy will then be responsible for advertising their presence without interruption and for waking up the local host again if any remote host tries to access them.

allowWakeOnLAN

default:: 🐧 MagicPacket

Controls which Wake-on-LAN mode Desomnia should ensure is set on the interface. If the current mode differs — and the hardware supports it — Desomnia changes it temporarily and restores the previous state on shutdown. Setting this to None disables Wake-on-LAN on the network interface. Multiple modes can be combined with |. You also find here the corresponding ethtool constants:

MagicPacket = g ⭐️: Wakes the system when a Magic Packet addressed to the NIC’s MAC is received. The standard Wake-on-LAN method — this is what Desomnia sends to sleeping hosts.
PHY = p: Wakes on any physical layer event, such as a cable being connected or a link speed change. Very broad; use with caution on always-connected interfaces.
Unicast = u: Wakes on any unicast packet addressed to the NIC’s MAC address. Will trigger on ordinary traffic from any sender.
Multicast = m: Wakes on multicast packets.
Broadcast = b: Wakes on broadcast packets, including ARP requests and DHCP traffic.
ARP = a: Wakes specifically on ARP requests.
SecureOn = s: Adds password protection to the Magic Packet mechanism. The sender must include the correct six-byte password in the Magic Packet. The password itself is configured in the NIC driver, not in Desomnia.
Filter = s: Wakes based on custom hardware-level packet filters defined in the NIC driver. The filter rules are driver-specific.

See Wake-on-LAN for details on platform support.

onConnect

⚡️ event:

An action configured for this event will be executed when a network interface identififed by this configuration has connected to the network.

onDisconnect

⚡️ event:

An action configured for this event will be executed when a network interface identififed by this configuration has discconnected from the network.

Host

These basic properties are configured the same for every type of host:

<Host name="laptop" hostName="DESKTOP-HUVAVK6"
  autoDetect="IPv4|IPv6"
  MAC="00:11:22:33:44:55"
  IPv4="192.168.178.10"
  IPv6="192.168.178.20">

</Host>

name

This is the logical name of the host, to be referenced by filters and written to the logs. You can name this anything you like.

hostName

default:: the logical name

This is the actual hostname as it is known to the available name resolution authorities. In other words: It’s the name, by that your operating system can resolve the host. If you don’t set this explicitly, the logical name will be used.

autoDetect

Configure to auto detect MAC or IP addresses. The possible values are MAC, IPv4 and IPv6, which you can freely combine with the pipe operator. If you do not configure this, the value of the network is used.

MAC

Configure the link layer address of this host. Possible formats are:

001122334455
F0-E1-D2-C3-B4-A5
00:11:22:33:44:55

IPv4

Configure a static IPv4 address for this host. Use the following format: 192.168.178.10

IPv6

Configure a static IPv6 address for this host. Use the following format: 2001:0db8:85a3:0000:0000:8a2e:0370:7334

Warning

You probably don’t want to configure this manually. See Auto-configuration and IPv6 support for more information.

HostRange

With this type you can declare an entire range of hosts. You can further include nested host ranges and individual hosts, identified by their name or IP address.

<HostRange name="anything"
  network="192.168.178.0/24"
  firstIP="192.168.178.10"
  lastIP="2001:0db8:85a3:0000:0000:8a2e:0370:7334">

  <Host name="morpheus" ... />
  <HostRange name="something" ... />

 </HostRange>

name

This is the logical name of the host range, to be referenced by filters. You can name this anything you like.

network

This represents the host range in the CIDR notation. You can use either specify the range by it’s CIDR notation or first and last IP address, but not both. If both are specified, the network attribute takes precedence.

firstIP

This represents the first IP address in the host range.

lastIP

This represents the last IP address in the host range.

DynamicHostRange

A <DynamicHostRange> can be configured exactly like a normal <HostRange>, but has the ability to temporarily include additonal hosts, after a successful Singe Packet Authorisation (SPA). If you don’t specify the knock attributes, they will be inherited from the Network Monitor configuration.

<DynamicHostRange name="anything" ...

  knockMethod="plain"
  knockProtocol="UDP"
  knockPort="62201"
  knockTimeout="10s"

  proofIP="true"
  proofTime="10s">

  <Host name="morpheus" ... />
  <HostRange name="something" ... />

  <SharedSecret label="simple" ... />
  <SharedSecret label="better" ... />

</DynamicHostRange>

knockMethod

default:: plain

This option determines which method Desomnia should use for the Single Packet Authorization (SPA). The core includes the plain method to quickly configure a password, that will be transmitted in clear text to the configured knockPort. Please consider to install additional plugins (e.g. Firewall Knock Operator) to unlock more secure knock methods.

knockProtocol

default:: UDP

This option configures the protocol with which Desomnia will listen for a SPA packet.

knockPort

default:: 62201

This option configures the port at which Desomnia will listen for a SPA packet.

knockTimeout

default:: 10s

This option specifies how long the remote host will be included in the <DynamicHostRange>, after a successfull Single Packet Authorisation.

proofIP

default:: false

This specifies whether or not the remote IP address should be included in the encrypted payload.

proofTime

duration:

This specifies whether the time must be included in the encrypted payload, and the acceptable deviation to accommodate minor differences in the clock times of the local and remote hosts.

SharedSecret

The shared secret for the authenticating can be specified either inline with a single value or as a complex key pair, consisting of two distinct cryptographically byte sequences:

<SharedSecret label="simple" encoding="UTF-8">password</SharedSecret>

<SharedSecret label="secure" encoding="Base64" passthrough="false">
  <Key>RqBObjFUM9lguaZin1CjJEK0a4FQamAB9ivXHq0/z6w=</Key>
  <AuthKey type="SHA256">AsJ0GS2IMgqbCf1hc9BfKpCK5vXiXs/J2ZLri+XdHCdZsarOTPTbPnwGT1bu7Q5+yjOlnK5oNHe3zyJf7A9J1g==</AuthKey>
</SharedSecret>

label

A custom label, to further reference the shared secret.

type

default:: depends on the knock method

This option specifies the hashing algorithm used to authenticate the SPA packet. Possible values are:

MD5
SHA1
SHA256
SHA384
SHA512
SHA3_256
SHA3_512

Note

If you do not specify a concrete hashing algorithm, the selected knock method may use a certain default.

encoding

Possible values are UTF-8 and Base64.

passthrough

default:: false

Work in progress

Future versions of Desomnia will allow for the received SPA packet to be forwared to a host further down the connection, if the Network Monitor is configured to do a Single Packet Authorisation itself.

LocalHost

Inside <LocalHost> you can declare the services and virtual machines, that should be watched for local sleep management:

<NetworkMonitor interface="eth0" ... >

  <LocalHost minTraffic="1MB/s"
    demandTimeout="5s"
    demandParallel="1">

    <Service name="SSH" ... />
    <HTTPService name="HTTP" ... />

    <HostFilterRule ... />
    <HostRangeFilterRule ... />

    <VirtualHost name="gitlab" ... />

  </LocalHost>

</NetworkMonitor>

To simplify your configuration and reduce unnecessary verbosity, you are allowed to omit the <LocalHost> tags, and include your services and virtual hosts directly under the <NetworkMonitor>. The following configuration is behaviourally equivalent to the previous one:

<NetworkMonitor interface="eth0" ...
  minTraffic="1MB/s"

  demandTimeout="5s"
  demandParallel="1">

  <Service name="SSH" ... />
  <HTTPService name="HTTP" ... />

  <HostFilterRule ... />
  <HostRangeFilterRule ... />

  <VirtualHost name="gitlab" ... />

</NetworkMonitor>

Attention

Since some of the attributes of <LocalHost> also exist on the <NetworkMonitor> there is a slight difference, if you include some <RemoteHost> in your configuration. This is because the ambiguous attributes are actually interpreted as attributes of the <NetworkMonitor>, which are inherited as defaults by all hosts of the configuration. If this is undesired, you can always use the first notation.

minTraffic

When using Desomnia as a local sleep manager, you can control the cumulative traffic threshold under which the node will be considered idle. The following formats are valid:

10: A number specified without any unit declares an amount of raw packets that have to be counted during the configured timeout of the System Monitor, otherwise the node will be considered idle.
100/s: A number specified with a time period but without a binary unit declares an amount of raw packets that have to be counted in average during the configured timeout of the System Monitor, otherwise the node will be considered idle.
1MB/s: A number specified with both a time period and a binary unit declares an amount of bytes that have to be counted in average during the configured timeout of the System Monitor, otherwise the node will be considered idle.
100kb: A number specified without a time period, but with a binary unit declares an amount of bytes that have to be counted during the configured timeout of the System Monitor, otherwise the node will be considered idle.

demandTimeout

inherited:
default:: 5s

Sets the timeout, for how long Desomnia waits to confirm a particular demand request. This is mainly relevant if you use the Network Monitor in promiscuous mode and more than one packet is required to establish whether the host in question should be woken up. The request holds some resources which will not be released until either the request succeeds or the timeout period elapses. If you do not configure Desomnia to process more than one request at a time, this will also prevent further requests from different clients. This may lead to a reduced responsiveness, if the timeout is set too high.

demandParallel

inherited:
default:: 1

This value determines how many demand requests can be processed in parallel for any given host. For safety reasons, the default setting allows no more than one request to run in parallel, which should be sufficient for most setups. To accommodate more complex setups involving local virtual machines and a remote host running Desomnia in promiscuous mode, it may be necessary to increase this to at least 2.

Watched hosts

Watched hosts (<RemoteHost> and <VirtualHost>) extend the <Host> and both share these additional properties:

<RemoteHost name="morpheus" ...
  minTraffic="1MB/s"

  advertise="lazy"

  demandTimeout="5s"
  demandForward="true"
  demandParallel="1"

  onMagicPacket="wake"
  onServiceDemand="knock"
  onDemand="wake"
  onIdle="suspend"
  onStart=""
  onSuspend=""
  onStop="">

  <Service name="SSH" ... />
  <HTTPService name="HTTP" ... />

  <HostFilterRule ... />
  <HostRangeFilterRule ... />
  <ServiceFilterRule ... />
  <HTTPFilterRule ... />

  <PingFilterRule ... />

  <VirtualHost name="remote" ... />

</RemoteHost>

<VirtualHost name="local" ... />

minTraffic

When using Desomnia as a local sleep manager, you can control the cumulative traffic threshold under which the node will be considered idle. The following formats are valid:

10: A number specified without any unit declares an amount of raw packets that have to be counted during the configured timeout of the System Monitor, otherwise the node will be considered idle.
100/s: A number specified with a time period but without a binary unit declares an amount of raw packets that have to be counted in average during the configured timeout of the System Monitor, otherwise the node will be considered idle.
1MB/s: A number specified with both a time period and a binary unit declares an amount of bytes that have to be counted in average during the configured timeout of the System Monitor, otherwise the node will be considered idle.
100kb: A number specified without a time period, but with a binary unit declares an amount of bytes that have to be counted during the configured timeout of the System Monitor, otherwise the node will be considered idle.

advertise

inherited:
default:: lazy

This option controls when your system should advertise an IP address, that is not it’s own. This only makes sense when the Network Monitor is in promiscuous mode, or when there are offline/suspended virtual machines. You can mix and match all the options using the pipe operator.

The following options are available to specify which address procotols should be advertised:

IPv4: advertise IPv4 addresses
IPv6: advertise IPv6 addresses
IP: advertise IPv4 and IPv6 addresses

The following options are available to specify when addresses should be advertised:

Demand: advertise addresses when the remote host is requested
Suspend: advertise addresses after the remote host has been suspended
Stop: advertise addresses after the remote host has been stopped (manually or on disconnect)
Resume: advertise addresses when the local host resumes from suspend

For your convenience there are two practical short hand notations:

lazy = IP|Demand

(remote) hosts are only advertised when requested

eager = IP|Demand|Suspend|Resume

(remote) hosts are advertised as soon as possible

This may be useful in situations where hosts are frequently resuming and suspending (less than 5min).

advertiseIfStopped

inherited:
default:: true

This options only affects remote hosts. Because there is no standard way of determining whether a remote host has been suspended or turned off without the host itself informing us, we have to assume that it stopped per default. A suspension can only reliably be detected if the remote host is running an instance of Desomnia or a Sleep Proxy client. You can then turn this off in order to prevent addresses for offline systems from being advertised.

demandForward

inherited:
default:: true

This controls, if the original request should be forwarded to the target host, after a successful wake-up. A TCP client usually repeats it’s SYN a couple of times before giving up, waiting each time a little longer. Resending the SYN immediately after the target host signals that it is ready to receive can reduce the time it takes to establish the connection. If the target host takes more than a few seconds, it can prevent a timeout on the client side in some cases. It should be safe to leave this enabled by default.

demandTimeout

inherited:
default:: 5s

Sets the timeout, for how long Desomnia waits to confirm a particular demand request. This is mainly relevant if you use the Network Monitor in promiscuous mode and more than one packet is required to establish whether the host in question should be woken up. The request holds some resources which will not be released until either the request succeeds or the timeout period elapses. If you do not configure Desomnia to process more than one request at a time, this will also prevent further requests from different clients. This may lead to a reduced responsiveness, if the timeout is set too high.

demandParallel

inherited:
default:: 1

This value determines how many demand requests can be processed in parallel for any given host. For safety reasons, the default setting allows no more than one request to run in parallel, which should be sufficient for most setups. To accommodate more complex setups involving local virtual machines and a remote host running Desomnia in promiscuous mode, it may be necessary to increase this to at least 2.

onMagicPacket

⚡️ event:

An action configured for this event will be executed when the Network Monitor detects a Magic Packet targeted at the host that originated from a different source.

onServiceDemand

⚡️ event:
inherited:

An action configured for this event will be executed when the Network Monitor detects, that a configured service on this host is being accessed.

onDemand

⚡️ event:
default:: wake

An action configured for this event will be executed when the Network Monitor detects, that the host is offline and being accessed.

onIdle

⚡️ event:

An action configured for this event will be executed when Desomnia identifies the host as idle.

onStart

⚡️ event:

An action configured for this event will be executed when the Network Monitor detects that the host has started up.

onSuspend

⚡️ event:

An action configured for this event will be executed when the Network Monitor detects that the host has suspended itself. This only works if the host sends an appropriate notification before going to sleep.

onStop

⚡️ event:

An action configured for this event will be executed when the Network Monitor detects that the host has disconnected from the network without providing a reason.

RemoteHost

For remote hosts you can configure these additional properties:

<RemoteHost name="morpheus" ...
   advertiseIfStopped="true"

   knockMethod="plain"
   knockPort="62201"
   knockProtocol="UDP"
   knockDelay="500ms"
   knockRepeat="2s"
   knockTimeout="10s"
   knockSecret="changeme"
   knockSecretAuth="..."
   knockSecretAuthType="SHA256"
   knockEncoding="UTF-8"

   pingTimeout="500ms"
   pingFrequency="1min"

   wakeType="auto"
   wakePort="9"
   wakeRepeat="2s"
   wakeTimeout="10s">

  <VirtualHost name="gitlab" ... />

</RemoteHost>

knockMethod

inherited:
default:: plain

This option determines which method Desomnia should use for the Single Packet Authorization (SPA), if knock is configured as a onDemand action for a particular service. The core includes the plain method to quickly configure a password, that will be transmitted in clear text to the configured knockPort. Please consider to install additional plugins (e.g. Firewall Knock Operator) to unlock more secure knock methods.

knockPort

inherited:
default:: 62201

This option configures the port against which a Single Packet Authorization will be performed.

knockProtocol

inherited:
default:: UDP

This option configures the protocol that will be used to perform a Single Packet Authorization.

knockDelay

inherited:
default:: 500ms

This option specifies the amount of time to wait before performing a Single Packet Authorisation if the remote host does not respond.

knockRepeat

inherited:

This option specifies whether to repeat the Single Packet Authorisation process and how long to wait between each attempt.

knockTimeout

inherited:
default:: 10s

This option specifies how long to wait before considering the Single Packet Authorisation as failed, and when to stop sending packets.

knockSecret

inherited:

This option specifies either the secret password to be sent to the remote host, or the key to be used to encrypt the SPA packet.

knockSecretAuth

inherited:

This option specifies the key to be used for authenticating the SPA packet. If this option is not set, authentication will not be performed, which could compromise the security of the SPA.

knockSecretAuthType

inherited:
default:: depends on the knock method

This option specifies the hashing algorithm used to authenticate the SPA packet. Possible values are:

MD5
SHA1
SHA256
SHA384
SHA512
SHA3_256
SHA3_512

Note

If you do not specify a concrete hashing algorithm, the selected knock method may use a certain default.

knockEncoding

inherited:
default:: UTF-8

This option specifies the encoding to be used to build the knockSecret and knockSecretAuth from the configuration file. Possible formats are UTF-8 and Base64.

pingTimeout

inherited:
default:: 500ms

Defines the timeout, after which a remote host will be considered unreachable, after a ARP request, NDP solicitation or ICMP echo request remains without reply. Decrease this value to accelerate demand requests in general. Increase this timeout to reduce unnecessarily executed demand requests on a lagging network.

pingFrequency

inherited:

This defines the frequency at which a remote host will be checked to determine whether it is operational. In order to advertise the changed IP ownership of a remote host early, the respective host has to be checked regularly. If you don’t configure this value, no regular checks will be performed.

wakeType

inherited:
default:: auto

Specifies, how Magic Packets should be sent. Possible values are:

auto: Checks if the requested IP address is in the same subnet as the configured network interface. If both hosts reside in the same network (meaning they share the same range of IP addresses), link will be used. Otherwise a combination of network|unicast will be used, because it will be unlikely then, that the target host can be reached with a link layer packet.
link: Uses ethernet packets with an an EtherType of 0x0842, that operate below the threshold of user space applications, to prevent interference with actual network services. For this to work, the target host has to be on the same subnet.
network: Uses UDP packets with the Magic Packet as payload, which can be routed over the internet or a tunnel connection (VPN). It may be necessary to configure a static address mapping on the router or VPN server, to reach the sleeping host. Can be observed by user space applications, that listen on the specified port number.
unicast: Send the Magic Packet directly to the device to wake up, without using a broad- or multicast. The link layer packet will be directed at the Ethernet address of the device and potentially all the known IP addresses of the host, if configured with network.
none: Do not send any Magic Packets. This setting is used to temporarily prevent a host from waking up.

wakePort

inherited:
default:: 9

Specifies the port number for Magic Packets encapsulated in UDP packets, if wakeType was configured with network. If wakeType is configure with link, this attribute has no meaning.

Typical port numbers used for this are 7 (Echo) or 9 (Discard).

wakeTimeout

inherited:
default:: 10s

Defines the timeout, after that a wake up will be considered as failed, if we haven’t received any response from the target host after the Magic Packet has been sent. There will be a warning in the log file, if this happens. Also buffered packets will only be forwarded to the target host, if the demand request succeeds.

wakeRepeat

inherited:

This option specifies whether to resend the Magic Packet and how long to wait between each attempt, until the configured wakeTimeout has elapsed.

wakePing

inherited:
default:: false

This option specifies whether to actively ping the target host during a wake operation. Each individual ping will timeout after the configured pingTimeout, until the configured wakeTimeout has elapsed. If you do not configure this parameter, the NetworkMonitor will try to passively listen for a sign that the target host has successfully been woken up. The target host will actively pinged in any case, if it is not part of the local subnet.

VirtualHost

Virtual hosts can only be configured in the context of a <RemoteHost> or the <LocalHost>. Apart from that, everything is configured like any watched host:

 <RemoteHost name="morpheus" ... >
  <VirtualHost name="gitlab" ... />
 </RemoteHost>

 <LocalHost>
  <VirtualHost name="gitlab" ...
    onMagicPacket="wake" />
 </LocalHost>

onMagicPacket

⚡️ event:
default:: wake

Note

Take notice, that the default action for local virtual machines will be to wake the host. This will allow the virtual host to be waken by a Magic Packet, like any physical host.

Router

A router shares the same attributes as any other host on the network, but has the following additional attributes:

<Router name="fritz.box" IPv4="192.168.178.1" ...
  allowWake="false"
  allowWakeByRemote="false"
  allowWakeOnLAN="true"

  vpnTimeout="500ms"
  vpnFrequency="1min">

  <VPNClient name="WireGuard VPN" IPv4="192.168.178.201" ... />

</Router>

allowWake

default:: false

Specifies whether the router will be allowed to complete demand requests. The default value is false, meaning all packets originating from the router fill be filtered. Setting this value to true renders all subsequent attributes unnecessary.

allowWakeByProxy

default:: false

Specifies whether or not remote systems, whose packets are forwarded by this router, will be allowed to complete demand requests. Setting this value to true renders all subsequent attributes unnecessary.

The difference to the previous setting is, that the router still won’t be allowed to successfully trigger a wake on it’s own, but will receive responses to address resolution requests in order to enable it to forward IP packets from outside of the local network to a sleeping watched host.

allowWakeOnLAN

default:: true

Specifies if an exception should be made, regarding the previous settings, if we receive a MagicPacket from the router prior to a connection attempt.

vpnTimeout

default:: 500ms

Specifies the timeout after it should be assumed that no VPN clients are connected. If no VPN clients are configured, this attribute has no effect.

vpnFrequency

Specifies the interval at which the presence of VPN clients should be checked. This is an optional feature, so there is no default value. If no VPN clients are configured, this attribute has no effect.

Work in progress

Periodic checking of VPN clients is currently not implemented, which is why this attribute has no effect. Meanwhile please use vpnTimeout instead.

VPNClient

VPN clients can only be configured in the context of a router. Apart from that, everything is configured like any <Host>:

Caution

Depending on the type of VPN server you have, it probably won’t be possible to resolve VPN clients by name, which is why you should provide a static IP mapping, in order to successfully check the reachability of the client. For more information about VPN support, read the corresponding wiki page.

HostFilterRule

This rule configures the embedded packet filter to either include or exclude requests that originate from the specified network host:

<HostFilterRule name="pie" type="MustNot"
  IPv4="192.168.178.10"
  IPv6="2001:0db8:85a3:0000:0000:8a2e:0370:7334">

</HostFilterRule>

type

default:: MustNot

This attribute determines if this is an inclusive or exclusive filter rule.

Must: Inclusive filters reduce the set of monitored resources to include only those that match at least one of the filters.
MustNot: Exclusive filters reduce the set of monitored resources by those that match with them.

name

This is the logical name of the host, to be referenced by this filter. In order to use a shared <Host> entry, all other host related attributes have to be omitted.

IPv4

Configure a static IPv4 address for this host. Use the following format: 192.168.178.10

IPv6

Configure a static IPv6 address for this host. Use the following format: 2001:0db8:85a3:0000:0000:8a2e:0370:7334

Warning

You probably don’t want to configure this manually. See Auto-configuration and IPv6 support for more information.

HostRangeFilterRule

This rule configures the embedded packet filter to either include or exclude requests that originate from the specified network host range:

<HostRangeFilterRule name="anything" type="MustNot"
  network="192.168.178.0/24"
  firstIP="192.168.178.10"
  lastIP="192.168.178.20">

</HostRangeFilterRule>

type

default:: MustNot

This attribute determines if this is an inclusive or exclusive filter rule.

Must: Inclusive filters reduce the set of monitored resources to include only those that match at least one of the filters.
MustNot: Exclusive filters reduce the set of monitored resources by those that match with them.

name

This is the logical name of the host range, to be referenced by this filter. In order to use a shared <HostRange> entry, all other host range related attributes have to be omitted.

network

This represents the host range in the CIDR notation. You can use either specify the range by it’s CIDR notation or first and last IP address, but not both. If both are specified, the network attribute takes precedence.

firstIP

This represents the first IP address in the host range.

lastIP

This represents the last IP address in the host range.

ForeignHostFilterRule

The <ForeignHostFilterRule> does not have any attributes, besides the mandatory type, because it derives its configuration from the contextual network interface and matches with all hosts, that are not part of the local subnet:

<ForeignHostFilterRule type="MustNot">

  <HostFilterRule ... />
  <HostRangeFilterRule ... />

  <DynamicHostRange name="dynamic" ... /> <!-- this is a shortcut -->

</ForeignHostFilterRule>

type

default:: MustNot

This attribute determines if this is an inclusive or exclusive filter rule.

Must: Inclusive filters reduce the set of monitored resources to include only those that match at least one of the filters.
MustNot: Exclusive filters reduce the set of monitored resources by those that match with them.

Note

You are usually not allowed to put network entities directly inside a filter. However, since this is such a common use case, you can put a <DynamicHostRange> directly inside the <ForeignHostFilterRule>. This is considered to be as if declared seperately and then referenced from inside the <ForeignHostFilterRule> via a <HostRangeFilterRule>. In any case, you must always specify a name for the <DynamicHostRange>.

<DynamicHostRange name="dynamic" ... />

<ForeignHostFilterRule>
  <HostRangeFilterRule name="dynamic" ... />
</ForeignHostFilterRule>

ServiceFilterRule

This rule configures the embedded packet filter to either include or exclude requests that target the specified network service. You can include any number of <HostFilterRule> and <HostRangeFilterRule> in order to make the filter more specific:

<ServiceFilterRule name="SSH" type="MustNot"
  protocol="TCP"
  port="22">

  <HostFilterRule ... />
  <HostRangeFilterRule ... />

</ServiceFilterRule>

type

default:: MustNot

This attribute determines if this is an inclusive or exclusive filter rule.

Must: Inclusive filters reduce the set of monitored resources to include only those that match at least one of the filters.
MustNot: Exclusive filters reduce the set of monitored resources by those that match with them.

name

To document which service this filter targets, you can specify a custom name here.

protocol

default:: TCP

Filter packets to services using the specified IP protocol. Possible values are:

TCP: Transmission Control Protocol
UDP: User Datagram Protocol

port

required:

Filter packets to services listening at the specified port number.

🚧 HTTPFilterRule

This filter can be configured with the same attributes as ServiceFilterRule, except that the port attribute will have the default value of 80.

Additionally you can configure any number of RequestFilterRule to inspect the payload of the packet. All attributes of RequestFilterRule and it’s children will be matched as a regular expression to the corresponding packet field.

Work in progress

This rule is a work in progress and will be released in a future version of Desomnia.

<HTTPFilterRule name="HTTP" type="MustNot"
  protocol="TCP"
  port="80">

  <RequestFilterRule ... />

</HTTPFilterRule>

RequestFilterRule

<RequestFilterRule type="MustNot"
  method="GET"
  path="/to/document.html"
  version="1.1"
  host="www.example.com">

  <Header name="Accept-Language">de-DE</Header>
  <Cookie name="logged_in">yes</Cookie>

</RequestFilterRule>

type

default:: MustNot

This attribute determines if this is an inclusive or exclusive filter rule.

Must: Inclusive filters reduce the set of monitored resources to include only those that match at least one of the filters.
MustNot: Exclusive filters reduce the set of monitored resources by those that match with them.

method

The HTTP method of the request. This can be set to GET, POST, DELETE, etc.

path

The requested path, starting with /.

version

The requested HTTP version, like HTTP/1.1 or 2.0.

host

The requested domain name.

PingFilterRule

This filter checks for the presence of an ICMP echo request. There are no further attributes beside the mandatory type.

<PingFilterRule type="MustNot" />

type

default:: MustNot

This attribute determines if this is an inclusive or exclusive filter rule.

Must: Inclusive filters reduce the set of monitored resources to include only those that match at least one of the filters.
MustNot: Exclusive filters reduce the set of monitored resources by those that match with them.

Service

When you configure a <Service> you can configure all the attributes of a <ServiceFilterRule>, except of type. An equivalent <ServiceFilterRule> will automatically be created then, but which will always have type="Must".

<Service name="SSH" ...
  serviceName="ssh"

  minTraffic="10kb/s"

  knockMethod="plain"
  knockPort="62201"
  knockProtocol="UDP"
  knockDelay="500ms"
  knockRepeat="2s"
  knockTimeout="10s"
  knockSecret="changeme"
  knockSecretAuth="..."
  knockSecretAuthType="SHA256"
  knockEncoding="UTF-8"

  onDemand="knock"
  onIdle="?">

  <HostFilterRule ... />
  <HostRangeFilterRule ... />

</Service>

serviceName

default:: the logical name, but all lowercase

Work in progress

Here you will be able to define a custom service name, that will be advertised with mDNS in a later version. Ideally this name should match with it’s counterpart in the Service Name and Transport Protocol Port Number Registry, managed by IANA. If you don’t configure this property, the name will be derived from the basic name property, but with all letters lowercase.

minTraffic

When using Desomnia as a local sleep manager, you can control the cumulative traffic threshold under which the node will be considered idle. The following formats are valid:

10: A number specified without any unit declares an amount of raw packets that have to be counted during the configured timeout of the System Monitor, otherwise the node will be considered idle.
100/s: A number specified with a time period but without a binary unit declares an amount of raw packets that have to be counted in average during the configured timeout of the System Monitor, otherwise the node will be considered idle.
1MB/s: A number specified with both a time period and a binary unit declares an amount of bytes that have to be counted in average during the configured timeout of the System Monitor, otherwise the node will be considered idle.
100kb: A number specified without a time period, but with a binary unit declares an amount of bytes that have to be counted during the configured timeout of the System Monitor, otherwise the node will be considered idle.

knockMethod

inherited:
default:: plain

This option determines which method Desomnia should use for the Single Packet Authorization (SPA), if knock is configured as a onDemand action for a particular service. The core includes the plain method to quickly configure a password, that will be transmitted in clear text to the configured knockPort. Please consider to install additional plugins (e.g. Firewall Knock Operator) to unlock more secure knock methods.

knockPort

inherited:
default:: 62201

This option configures the port against which a Single Packet Authorization will be performed.

knockProtocol

inherited:
default:: UDP

This option configures the protocol that will be used to perform a Single Packet Authorization.

knockDelay

inherited:
default:: 500ms

This option specifies the amount of time to wait before performing a Single Packet Authorisation if the remote host does not respond.

knockRepeat

inherited:

This option specifies whether to repeat the Single Packet Authorisation process and how long to wait between each attempt.

knockTimeout

inherited:
default:: 10s

This option specifies how long to wait before considering the Single Packet Authorisation as failed, and when to stop sending packets.

knockSecret

inherited:

This option specifies either the secret password to be sent to the remote host, or the key to be used to encrypt the SPA packet.

knockSecretAuth

inherited:

This option specifies the key to be used for authenticating the SPA packet. If this option is not set, authentication will not be performed, which could compromise the security of the SPA.

knockSecretAuthType

inherited:
default:: depends on the knock method

This option specifies the hashing algorithm used to authenticate the SPA packet. Possible values are:

MD5
SHA1
SHA256
SHA384
SHA512
SHA3_256
SHA3_512

Note

If you do not specify a concrete hashing algorithm, the selected knock method may use a certain default.

knockEncoding

inherited:
default:: UTF-8

This option specifies the encoding to be used to build the knockSecret and knockSecretAuth from the configuration file. Possible formats are UTF-8 and Base64.

onDemand

⚡️ event:

An action configured for this event will be executed when the Network Monitor detects, that the service is being accessed.

onIdle

⚡️ event:

An action configured for this event will be executed when Desomnia identifies the service as idle.

HTTPService

When you configure a <HTTPService> you can configure all the attributes of a <HTTPFilterRule>, except of type. An equivalent <HTTPFilterRule> will automatically be created then, but which will always have type="Must". It also shares all additional attributes from <Service>, but has the ability to declare any number of RequestFilterRule as child filters:

<HTTPService name="HTTP" ...
  serviceName="http"

  protocol="TCP"
  port="80"

  minTraffic="10kb/s"

  onDemand="knock"
  onIdle="?">

  <HostFilterRule ... />
  <HostRangeFilterRule ... />

  <RequestFilterRule ... />

</HTTPService>