Public Beta documentation

As some of the things will differ between the main and beta instances here you'll find a "tldr" version of the important parts. For things that are not explained in this document feel free to fallback to our regular documentation and https://community.husarnet.com.

This document will also serve as an early technical migration guide as it will explain changes that will become "the new norm" eventually.

Wording changes

First of all we'd like to address some wording changes. Each of them has a slightly different reason so we'll explain them one by one.

• Element -> Device - Husarnet Devices used to be called Elements because long time ago Husarnet internally supported various other types of... elements which are now provided by other products. This is why we've decided to use the word Device now - most people find it much more intuitive in this context. We've rejected the term Peer (despite being a Peer to Peer network) as it weren't as clear to out test group.
• Network -> Group - the word Network was too overloaded in the, well... networking context. Group is a little bit more vague and does not come with any networking concepts like "network masks" and so on - which are handled completely differently in Husarnet.
• Websetup -> EventBus - unless you're using API this part of the system will disappear from your purview. Websetup used to be the thing that every time you change something on the dashboard notifies Daemons about the new setup. Now - all changes are saved to the database and EventBus is notified only about the entities they're about. Then, every live entity, that's subscribed to it's own topic will get a notification and will be responsible for synchronizing it's state to the one in the database/"API".

Authentication changes

We've decided to move the authentication to a separate system - https://login.husarnet.com - eventually - now it will be under https://login.beta.husarnet.com - and will be guarding all new subsystems - starting from the Dashboard, but eventually other parts will be migrated there - like the https://community.husarnet.com and so on.

This change allowed us to finally integrate social-logins - initially via Github and Google.

Dashboard changes

Dashboard is now dark-themed and supports live updates for some of the views. We plan on keeping is roughly this simple for free accounts.

We hope that this layout will more clearly convey concepts that drive Husarnet under the hood and will make the whole experience less stressful.

Claim Codes and Join Codes

There are two types of codes you can utilize to connect your devices to Husarnet network - Claim Codes and Join Codes. They both look like this:

email@example.com/R4nd0ML3tt3RSAndNumb3R5

They consist of email prefix (pointing to associated account) and the actual code, separated by a slash.

Claim Code is simple - using the code assigns the device to your Husarnet account. Your device will appear on the devices list, and from now on you can attach it to groups and manage it in the Dashboard.

Join Code, on the other hand is always associated with some group. Whenever you create a group, Join Code is created as well. Using Join Code will attach a device to some group, considering that:

• if the device was not claimed before, it gets claimed to the account associated with the code (see email prefix) and only then attached to the group;
• if the device is already claimed to your account and the Join Code you are using is associated with your own group, the device will simply be attached to this group (the operation is equivalent to simple attach)
• if the device is already claimed to your account and the Join Code is associated with group of someone else, the group will be shared to you and the device will be attached to it. This is the situation where someone shares their own Join Code with you to invite you to collaboration in one group.

Using the codes

husarnet claim <CODE>
husarnet join <CODE>

Both commands are functionally equivalent, you can use any of them with any type of the code. Note that using the codes always requires administrative privileges (sudo on Linux systems, for example).

A word on older codes

In previous Husarnet Dashboard version there were no Claim Codes, and Join Codes looked like this:

fc94:b01d:1803:8dd8:b293:5c7d:7639:932a/R4nd0ML3tt3RSAndNumb3R5

For backward-compatibility email prefix can be omitted or replaced with fc94:b01d:1803:8dd8:b293:5c7d:7639:932a, which was Websetup address for primary Husarnet network. Such codes are still accepted and usable, since the part after the slash is unique anyway. We recommend however to gradually update the codes in your scripts/setups to use the new form, since the old form will be discontinued at some point.

Husarnet Daemon

Platforms supported on Beta

We will start with Linux only and gradually add more platforms (builds for other platforms may already be available but do not expect them to be fully functional yet).

Daemon versions

On the beta instance both stable and nightly channels will work.

On the current main instance only stable channel will work.

On the upcoming main both nightly and stable (including the pre-migration versions) will work.

So technically there's no need to upgrade your clients for the Beta phase but we highly recommend giving the nightly version a go in order to actually test all of the new features.

---

Some explanation - changes that are now on the nightly channel do not include any backwards compatibility in them. This is why they will only work on the "post-changes" infrastructure (beta right now and main but after migration). The compatibility layer is included on the infrastructure side this is why both on the Beta instance and on the main instance (even after the migration) any stable Daemon (even these released before the upcoming migration) will work.

The compatibility layer on the infrastructure side will be operational for "some time after the migration ends". We do not want to give any guarantees yet, but the current internal goal is to keep it on for roughly a year. During that time we will be adding features to the new clients and slowly reminding users about the upgrade.

Have in mind that this compatibility layer is not fully featured due to the vast amount of areas that would have been needed to backport. Basic operation (like joining, communication with other peers, etc) are obviously supported.

There will also be a migration step in the Daemon itself - this migration will be done automatically during the first startup on the new version. For obvious reasons - this migration can be only done "forward", so while we do not intend to completely remove old data during that process, the state of the Daemon will be moved forward and downgrade may not be possible. This is one of the reasons why participation the Beta phase is so important - you will be able to test your setups on your own conditions.

Best option for migrating back-and forth would be to expect re-joins any time change is made.

Linux setup

Linux setup is done in a very similar way to the previous versions. You can use the same script as before, just with the nightly instead of install in the URL.

curl -s https://nightly.husarnet.com/install.sh | sudo bash -

Pointing your Daemon to Beta

By default all Daemon instances will try connecting to the main instance. This can be easily changed, but the method will differ depending on the version od the Daemon.

---

Why we've switched the method? Previously we've allowed changing some fundamental options while the Daemon was running. This may have seemed like a user-oriented design while in practice it made the Deamon code needlessly complicated and as an effect more error prone, leaving the Daemon in unknown state from time to time.

This is why new version accept all crucial parameters only as environment variables. This makes the need to restart the whole Daemon obvious to the user and also allowed us to remove lots of fragile code.

stable branch

On stable (2.0.180 and older) versions of Husarnet, you have to execute:

sudo husarnet setup-server beta.husarnet.com

and restart husarnet-daemon immediately after (the CLI will prompt to do it for you) if not, you can use:

sudo systemctl restart husarnet

nightly branch

There has been a change in husarnet.service for SystemD. It now accepts an optional environment variable file /etc/default/husarnet. All critical configuration overrides should be placed there.

In order to use Beta environment you need to set it's contents to:

HUSARNET_INSTANCE_FQDN=beta.husarnet.com

...and then restart the daemon:

sudo systemctl restart husarnet

Other environment variables

Put overrides in /etc/default/husarnet.

Environment variable	Data type	Default value	Meaning
HUSARNET_INSTANCE_FQDN	FQDN	prod.husarnet.com	Top level domain for figuring out which infrastructure to use. Use beta.husarnet.com for the Beta phase
HUSARNET_LOG_VERBOSITY	enum name	debug for nightly builds (used during beta), info for stable builds	Verbosity of the Husarnet Daemon. As Beta is running mostly nightly builds - they'll be more verbose than usual
HUSARNET_ENABLE_HOOKS	boolean	false	Hooks are a way of triggering user scripts on certain events generated by the Daemon or Dashboard. They're currently undergoing a slight reorganization so beware
HUSARNET_ENABLE_CONTROLPLANE	boolean	true	This is mostly an internally used variable that allows us to run vanilla Husarnet builds... to provide some services over Husarnet - like Event Bus, etc
HUSARNET_DAEMON_INTERFACE"	interface name	hnet0	Name of the interface to create for Husarnet
HUSARNET_DAEMON_API_INTERFACE	interface name	empty	Interface name where local Husarnet Daemon API should be listening on
HUSARNET_DAEMON_API_HOST	IP address	127.0.0.1	Same as above but specified using the bind IP address. Interface name has a higher priority than the bind IP
HUSARNET_DAEMON_API_PORT	port	16216	Port where local Husarnet Daemon API should be listening on

Payments, pricing

Payment system changes are out of scope of the Beta announcement - in general we will still be using Stripe as a payment provider.

There will be some changes to plans - but in general we will be merging them and making the whole process simpler and less granular. Expect things like API to be available for everyone.

Quota/device count changes - in previous/current pricing we've only counted devices you've owned towards your quota. We're changing this to "the number of devices reachable from your account", regardless of their ownership. This may seem like a huge change but at the end of the day it only affects those who misused our free plan. Corporate plans will have an option for grouping their accounts under a single entity and in that case the quota will be counted towards that entity - effectively removing any potential duplicate charges.

CLI status/argument changes

Status command output (husarnet status) underwent a makeover. The "traffic light" type emojis are out, and the default (non-verbose) output is limited to:

• info if the device is claimed already or not
• info if the Daemon is healthy (this regards Base Server and Event Bus connectivity)
• peer list

This results in leaner output with less visual clutter. Old information is accessible via the --verbose flag, which is turned on automatically if the state of the Daemon is unhealthy in any way.

With new rendition of the CLI we are moving towards more script-friendly approach, therefore for each and every command you can turn on --json flag to make the output guaranteed to be JSON document (which you can further process with jq or feed it to your scripts). You still can use the local Daemon API directly if it's easier for your particular case.

CLI management changes

Previously, there was possibility to use Husarnet CLI to manage groups and devices without the need to go into the Dashboard. You would execute husarnet dashboard login and provide your email and password, just like in the web browser. Now, this workflow is completely passwordless and is based on the assumption that you own the device running Husarnet Daemon. You just set AccountAdmin flag in the Dashboard (you will find the on/off switch on your Device page), and that authorizes the device to utilize Dashboard API commands, like husarnet group create, husarnet device unclaim and similar ones (full documentation is coming later). Note: as any "dangerous" command you need administrative privileges to run this (as you need to prove yourself as the administrator/owner of the device).

More sections to come

Consider this document a work in progress. We will be adding more sections as Beta phase progresses.