Homebrew

OS:

🐧 Linux 🍎 macOS

The easiest way to set up Desomnia on Linux or macOS is to use Homebrew. Install it with the following command:

brew install mad0x20wizard/tools/desomnia

The software will be installed according to the standard Homebrew filesystem layout. The root of this layout differs by platform. To find your Homebrew prefix, run:

brew --prefix

On macOS running on Apple Silicon, this is /opt/homebrew. All paths below are relative to this base path.

Binary distribution

Homebrew normally downloads source code and builds the project locally. Desomnia also provides pre-built binaries (known as β€œbottles”) for the following platforms:

  • linux/x64

  • linux/arm64

  • macos/sequoia/arm64

  • macos/tahoe/arm64

The availability of pre-built bottles can be checked here.

Filesystem layout

Use these locations to customise your installation of Desomnia, relative to your Homebrew installation:

/etc/desomnia

Put a suitable monitor.xml into this location, to tell Desomnia what to do. You can also create a NLog.config file here, to configure additional logging, beside the console output.

/var/lib/desomnia/plugins

Here you can drop your additional plugins, which will be loaded when the programs starts.

/var/log/desomnia

Here you will find the log files, if you enabled file logging in the NLog.config and used ${var:logDir} as base path.

Running as background service

Desomnia can only reach its full potential when run as a background service. Homebrew provides a platform-agnostic way to install and auto-start it:

sudo brew services start mad0x20wizard/tools/desomnia

To stop the service and remove it from auto-start:

sudo brew services stop mad0x20wizard/tools/desomnia

Attention

sudo is required so that Desomnia is installed and run as a system service with root privileges.

Error

A couple of problems can arise when running this on 🐧 Linux:

  • Running the brew command with sudo can fail if brew is not on the default path of the root user. Specify an absolute path to work around this:

    sudo /home/linuxbrew/.linuxbrew/bin/brew services start mad0x20wizard/tools/desomnia

  • On some platforms, it is necessary to configure sudo to preserve the HOME environment variable:

    sudo --preserve-env=HOME brew services start mad0x20wizard/tools/desomnia

Use either or both of these workarounds as needed.

Plugins included

Desomnia installed via Homebrew includes all plugins from the main repository. To install additional plugins, place the ZIP file in .../var/lib/desomnia/plugins. The file must follow the naming convention plugin-*.zip, with an optional version specifier separated from the name by _.

Logging

The location of the default output of Desomnia depends on the platform:

File

OS:

🍎 macOS

The standard output and error logs, as well as the extended logs are written to .../var/log/desomnia.

Journal

OS:

🐧 Linux

The INFO-level console output shows the most important actions Desomnia takes β€” such as waking remote hosts or sending knock packets β€” giving a quick overview of what the service is doing at any point in time. Warnings and errors are included as well.

To follow the live output from the systemd journal, run:

journalctl -u desomnia -f -n 80

Extended Logging

To enable additional file-based logging, create a log configuration at .../etc/desomnia/NLog.config. Unless configured otherwise, these logs will be written to .../var/log/desomnia.

Uninstallation

To remove Desomnia from your system:

brew uninstall mad0x20wizard/tools/desomnia

Note

This does not remove the configuration, custom plugins, or log files. Those must be deleted manually from their respective directories.