Skip to main content

Using Husarnet Hooks

This quick start guide describes how to utilize the hooking mechanism that was added to Husarnet Daemon that allows users to expand the client behavior in an easy and modular way.

I. What are Husarnet Hooks​

Simply put, Husarnet Hooks are user defined scripts that the Husarnet client should run when a specific type of event happens, for example, when a client joins a Husarnet network.

That's basically all, however there are some differences in behavior between specific platforms and some implementation caveats that should be taken into account when one uses this mechanism. It will all be described in more detail in this article.

It is also worth noting that this feature was designed with more advanced Husarnet users in mind and as such some users may find hooks to be a bit demanding to use. Shall you encounter any problems or have any questions do not hesitate to contact our team.

II. Types of Hooks​

Currently there are several types of hooks that are defined inside the client and for which user my define scripts:

  • joined - when client joins a network
  • whitelist_changed - when there is a change made to the client whitelist
  • hosttable_changed - when there is a change made to the client host table
  • rw_request - when client is going to need to access the filesystem in write mode
  • rw_release - when client finished accessing hte filesystem in write mode

The rw_request and rw_release hooks are in a way an anwser for some users who struggled with using Husarnet client on read-only filesystems since Husarnet requires a writeable persistent storage at some points of execution. Those hooks are called right before and right after those points in code so they enable users with such setups to temporarly allow client a read-write access to filesystem. Please have in mind that those two hooks will completely suspend client execution until user defined scripts finish.

III. How to enable Hooks​

By default hook execution is disabled as it is considered an advanced feature. Because of that in order for your client to call provided scripts you need to enable them using our CLI as such:

husarnet daemon hooks enable

this configuration is persistent so if you wish to disable hooks you need to do it manually:

husarnet daemon hooks disable

To check if hooks are currently enabled or not one can use following command:

husarnet daemon hooks check

IV. How to define scripts​

In order for a Husarnet Daemon to run your scripts you need to actually define them and place them in a specific directory inside the Husarnet configuration directory (if the directory specified does not exist inside the configuration one, create it). This is somewhat platform dependant and as such actions needed differ between unix based builds and Windows ones.

Linux scripts​

For Linux based clients the Husarnet configuration directory is /var/lib/husarnet and there user should create needed directories named after specific hooks (e.g. you should create a directory with path /var/lib/husarnet/hook.joined.d and inside it store scripts to be run when join event happens).

For Linux implementation it is worth noting that the scripts are run as executables thanks to utilization of the shebang interpreter directive. As such not only bash or other interpreter scripts can be stored and run with Husarnet hooks but also other executables. The only assertion that is checked at runtime is whether or not the files have the executable flag set. It is up to the user to ensure that the provided executables are valid and run as expected.

Windows scripts​

For windows based clients the Husarnet configuration directory should be %PROGRAMDATA%\Husarnet and inside of it user should create needed directories (e.g. %PROGRAMDATA%\Husarnet\hook.joined.d). In most configurations this should be C:\ProgramData\Husarnet\….

In the case of Windows the files the user wants to run need to be valid powershell scripts. Due to how running the scripts is handled it is up to the user to either configure appropriate execution policies and/or sign the scripts so that the Husarnet Daemon will be able to properly execute them. The simplest way is to configure an RemoteSigned execution policy for LocalMachine scope, this however may not be feasible for certain users from a security standpoint. You can learn more about execution policies on Microsoft Docs.

Platform independent aspects​

Inside the specified configuration directories Husarnet Daemon will look for certain directories named after specific hook types in order to locate scripts. Those directory names are identical for all platforms:

  • joined - hook.joined.d
  • whitelist_changed - hook.whitelist_changed.d
  • hosttable_changed - hook.hosttable_changed.d
  • rw_request - hook.rw_request.d
  • rw_release - hook.rw_release.d

V. Important details​

There are some details that need to be taken into consideration when using hooks. Firstly, Husarnet will not inform user if provided scripts fail in one way or another and it is up to the user to verify if the used scripts are working as intended and are valid.

A second important note to take is that, although not all hooks suspend execution, all hooks utilize the same separate thread that is also called to accomplish other tasks and as such the user defined scripts should finish execution in a reasonable timeframe. If one wishes to start some long running task (for example start some monitoring script on join) it is paramount to use the hook script to start a separate thread/task so that the script itself finishes as fast as possible.