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
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.
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.
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
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:
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.