Husarnet Client usage

This manual describes how to use Husarnet CLI (Command Line Interface). Husarnet CLI is powerful tool which allows you to:

1. Manage Husarnet daemon running on the device i.e. examine current connectivity status, display and modify the whitelist, see software version and other typical tasks;
2. Manage all your Husarnet devices and groups via intuitive and simple to use Dashboard API. You will only need to authenticate with your Husarnet account credentials.

Your devices with Husarnet daemon installed communicate with each other directly, without any central server forwarding traffic. That is a true low latency, peer-to-peer connection over the internet. Your devices see each other like they were in the same LAN.

Managing Husarnet Daemon via CLI

Open your terminal emulator and type:

husarnet status

You will see if your Husarnet Daemon is running, what is your Husarnet IP, what version you have installed and if there are any connectivity problems. The majority of the displayed information should be self-explanatory. If you are curious and/or see some issues, scroll down to Checking current status of the service section, which describes the output in great detail.

info

Hint: husarnet status is actually an alias for longer command - husarnet daemon status. Husarnet's CLI has a lot of aliases - be sure to type husarnet help, and then husarnet help <command> to discover how you can use the CLI in a way that is more intuitive for you.

Joining a group

The purpose of Husarnet is to quickly and securely connect your devices together. This is achieved via joining a group. To join a group you will need the Join Code. Login to your account at https://app.husarnet.com, select a group, click Add element button and go to a join code tab. Join Code is unique for each group. Alternatively, you can login via command line, as described in Managing your devices and device groups via CLI below.

Once you have the Join Code, type:

husarnet join [JOIN_CODE] [HOSTNAME]

Where [HOSTNAME] is the hostname of given device. If omitted, Husarnet will use the local hostname.

danger

Keep your join code secret! If you consider your join code might be compromised, click [Reset join code] button in a [join code] tab. Devices that already were connected using previous join code, still will be in your Husarnet groups, however previous join code will not be valid for adding new devices to your groups.

Checking current status of the service

In this part, we will describe information you can get from the output of husarnet status command. Let's see the example output:

$ husarnet status
Version
🟢 CLI:                       2022.10.20.2
🟢 Daemon (running):          2022.10.20.2
🟢 Daemon (binary):           2022.10.20.2

Dashboard URL
🟢 CLI:                       app.husarnet.com
🟢 Daemon:                    app.husarnet.com

Connection status
🟢 Base Server:               188.165.23.196:5582 (UDP)

Readiness
🟢 Is ready to handle data?   yes
🟢 Is ready to join?          yes
🟢 Is joined?                 yes

Local
⚪ Husarnet IP:
fc94:d797:bcdf:d20a:e2dc:c25e:2536:c1cd

Whitelist
fc94:41c9:86b6:7570:897f:b86f:7b5b:9818 husarnet-win11
⚪ inactive   🟢 secure         🟡 tunelled

fc94:b01d:1803:8dd8:b293:5c7d:7639:932a (websetup)
⚪ inactive   🟢 secure         🟡 tunelled

fc94:cff2:8a4b:0197:50cd:0b08:14ac:cc7b aws-test-husarnet
⚪ inactive   🟢 secure         🟡 tunelled

fc94:d797:bcdf:d20a:e2dc:c25e:2536:c1cd (localhost) gnaarmok
⚪ inactive   ⚪ no data flow   🟡 tunelled

Red/Yellow/Green dot emojis are basic indicator of health of particular part of the system. Green dot means the value is as expected. Yellow typically means that something might be a problem (but Husarnet still works). Red is for errors, and white is neutral information.

Below we will dive deeper into each section.

info

Hint: husarnet status has a verbose flag. Type husarnet status -v to get even more info. This is useful, for example while posting a support request on our Community Forums, or just if feeling curious.

Version

Here we can see the version of the software.

Why three version strings? Husarnet comes in two binaries - husarnet, which is CLI program you will use on day-to-day basis, and husarnet-daemon, which is typically managed by systemd (or platforms' equivalent) and is not intended to be used directly. First on the list is the version of CLI app, second is currently running daemon and the third is daemon binary as it is on the disk. All three versions should match. There might be situations, like for example when software update does not apply cleanly, that can cause divergence in version numbers. The CLI will inform you in this case.

Dashboard URL

This sections informs you what to type into web browser address bar to see Husarnet Dashboard web app. For majority of users, it will be app.husarnet.com. It can, however, be different for users of self-hosted Husarnet plans.

Connection status

In this section you can see the address of the Base Server your device is connected to at the moment and which transport method it is using. If you see UDP and green dot here, everything is good.

If you see yellow dot and information as below you are connected to Base Server via TCP:

Connection status
🟡 Base Server:               188.165.23.196:443 (TCP)
🟡 TCP is a fallback connection method. You'll get better results on UDP

Husarnet will work, but latency and performance will be negatively impacted.

If you see red dot, there is no connection to Base Server and establishing new connections over Husarnet will not be possible (except for the local network).

See Linux Troubleshooting Guide or Windows Troubleshooting Guide to find out how to deal with these problems. If you want, you can also read what is the purpose of Base Server to gain better understanding of the role of Base Servers in the system.

Readiness

Readiness flags will inform you if Husarnet Daemon is properly initialized. They are as follows:

🟢 Is ready to handle data?   yes

This flag will be green if Husarnet Daemon is able to contact the Base Server.

🟢 Is ready to join?          yes

This flag will be green if connection to Websetup, therefore joining, is possible. If you see "yes" here, but "no" down below on "Is joined" flag, you can join a group

🟢 Is joined?                 yes

This flag will be green if successful join already happened for this device, and will be red otherwise.

Husarnet IP

In this section you can see the IPv6 address of current device in Husarnet network.

Whitelist

Each instance of Husarnet Daemon maintains a whitelist. The concept is simple: if given IPv6 address is on the whitelist, then it can send packets to current device. Typically whitelist is managed by the Dashboard (i.e. if you add your device to a group in the Dashboard, all of the devices are notified of new member and will add it to their own whitelists); in some rare cases, however, it can be useful to manage it manually (you can read how to do it in Managing the whitelist section below).

info

Note: if you are using official Husarnet infrastructure, i.e. https://app.husarnet.com, our Websetup Server will always be on your whitelist, probably as the first device whitelist contains. It's address is fc94:b01d:1803:8dd8:b293:5c7d:7639:932a.

Each whitelist entry will contain IPv6 address and hostname of the device. Additionally, there will be flags indicating status of the connection:

• Activity: you will see ⚪ inactive if the peer is acknowledged, but the connection to given peer is not established yet. You will see 🟢 active if there is a connection.

• Data flow: you will see ⚪ no data flow if the peer is known, but the data is not exchanged at the moment (peer is idle). You will see 🟢 secure if data is transmitted through Husarnet link.

• P2P status: you will see 🟢 peer to peer if there is direct link between current device and given peer (Base Server does not take part in data exchange) and 🟡 tunelled if the data has to be forwared through Base Server (because P2P link was not obtainable).

Managing the whitelist

To see what devices are on your whitelist, type:

husarnet daemon whitelist ls

Example output:

PS C:\Users\husarnetman> husarnet daemon whitelist ls
fc94:5947:c16d:788d:26d7:74e0:dead:beef (localhost) husarnet-win11 master
⚪ inactive   ⚪ no data flow   🟢 peer to peer

fc94:aff1:a4fb:2375:bf2c:25be:7639:932a (websetup)
🟢 active     🟢 secure         🟡 tunelled

fc94:d797:bcdf:d20a:e2dc:c25e:dead:beef testing_machine
⚪ inactive   ⚪ no data flow   🟡 tunelled

To add/remove IPv6 addresses, use following commands:

husarnet daemon whitelist add <IPv6_address>
husarnet daemon whitelist rm <IPv6_address>

You can also enable the whitelist (the default) or disable it completely. Disabling whitelist is highly discouraged, as it makes our device open for connections from any other Husarnet device. Anyone doing this is expected to have very good reason to do so, and is required to properly set up some firewall by themselves (on top of Husarnet).

husarnet daemon whitelist enable
husarnet daemon whitelist disable

Turning the daemon on and off

You can use the CLI to start, restart and stop Husarnet Daemon. Note that on Windows, these will only work if you are running them from elevated command prompt (as Administrator). On Linux, these are equivalent to starting/stopping the service via systemctl (if you are not on root, the CLI will try to rerun the command with sudo)

husarnet daemon restart
husarnet daemon start
husarnet daemon stop

Switching to another instance of Husarnet Infrastructure

info

This command is applicable only to self-hosted plans of Husarnet.

In Husarnet self-hosted plans, your Dashboard instance is not on https://app.husarnet.com - it resides under your custom domain. Each instance of Husarnet Daemon must know this address. This is how you set it up:

husarnet daemon change-dashboard <MY_DASHBOARD_ADDRESS>

The address has to be provided without the scheme (i.e. app.husarnet.com, not https://app.husarnet.com)

To connect back to official production infrastructure, type simply:

husarnet daemon change-dashboard app.husarnet.com

Executing this command requires restarting the daemon. The CLI will prompt for restart.

Managing your devices and device groups via CLI

You can use Husarnet CLI as a replacement for using the Dashboard web app. If you feel more comfortable in your terminal emulator than in the web interface, this is section for you.

info

Everything (and more) that can be done in the Dashboard web app, can also be done via the CLI. CLI is first-class citizen in Husarnet.

In order to query against Dashboard API, you will need to authenticate first with your Dashboard account credentials. You can do it explicitly, by executing husarnet dashboard login, but this can be skipped, because the program will ask you for credentials whenever you will try to query the API unauthenticated.

After successful login, an auth token is created and saved on your device. The token is valid for 30 minutes, so you don't need to login again on subsequent queries. Any query you execute gives you a new token, so the timer is reset with every API-utilizing command. The program will prompt for password again in case your token expires.

Examining your groups

Start by simply listing all your device groups:

husarnet dashboard group ls

Example output:

⎯⎯⎯ Your groups ⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯
ID  | Name        | DeviceCount | JoinCode
112 | some group  | 2           | WspSomeJCztzaiQCdyW7st
234 | empty group | 0           | beUC39nh6SomeJCx3xF4kL
356 | my_devices  | 4           | ZD47XPYiop85SomeJCYsfM
⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯

You should see the same groups as in the Dashboard. To see details about specific group, type:

husarnet dashboard group show <ID>

ID parameter is optional. When omitted, CLI will display interactive prompt allowing you to choose the group you want to see. Type fragment to narrow the search:

Loading asciinema cast...

info

This interactive prompt is available for any command where typically you would pass an ID, so rename and remove too. Try it out!

Creating, renaming and removing groups

To add a new group interactively, type:

husarnet dashboard group create

The program will prompt for group name, and after group is created will display it's ID. You can also do it non-interactively by passing name as a parameter:

husarnet dashboard group create <NAME>

To remove a group interactively, type:

husarnet dashboard group remove

To remove a group non-interactively, you must provide an ID or name:

husarnet dashboard group remove <ID or NAME>

To rename a group interactively, type:

husarnet dashboard group rename

You will be prompted to type new name.

To do it in one command, provide ID or name as first argument, and new name as second:

husarnet dashboard group rename <ID or NAME>

info

Hint: if the name of your group has spaces, wrap it around with quotation marks e.g. husarnet dashboard group rename "my old group" "my new group"

Listing your devices

To see all devices assigned to your account, type:

husarnet dashboard device ls

Example output:

⎯⎯⎯ Your devices ⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯
ID(ipv6)                                | Name      | Version      | UserAgent                  | Groups containing device
⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯
fc94:a2d1:1a9b:1cf3:85d8:e999:deaf:cafe | raspberry | 2022.07.13.2 | Husarnet,Unix,2022.07.13.2 | test-group1
fc94:b9e8:a45e:14f8:483d:b0f0:fade:deaf | laptop    | 2021.12.29.1 | Linux daemon               | test-group1, test2
fc94:0a66:d26c:803e:395f:f935:dead:beef | motorola  | 2019.04.24.1 | Android VPN                | test2
⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯

Displayed information includes:

• IPv6 address of the device
• name (hostname)
• Husarnet Daemon version installed
• User Agent (UA) string, which is basically platform/OS information
• Names of all groups the device is assigned to

Assigning/Unassigning a device to a group

Warning: Your device must be joined first!

To assign a device to a new group interactively, type:

husarnet dashboard assign

The program will let you to select the device from the list first, and in the second step which group should the device be assigned to.

To do it in one command, type:

husarnet dashboard assign <DEVICE_NAME> <GROUP_NAME>

To reverse the operation, i.e. unassign, analogous commands apply. Interactive version:

husarnet dashboard unassign

Non-interactive version:

husarnet dashboard unassign <DEVICE_NAME> <GROUP_NAME>

Note: after this operation, the device is still joined to the account, even if you unassign it from all groups. There is never a need to join the device more than once.

I can't find the info I'm looking for in the docs!

Let us know! Describe your problem and post it on Husarnet Community Forums.