Husarnet Documentation

With Husarnet you can connect any device (laptops, servers, VMs, containers, microcontrollers etc.) with any interface (Wi-Fi, LTE/5G, Ethernet) into a peer-to-peer Virtual Private Network that works over the Internet with no configuration.

If you want to know more about the internals How Husarnet works is a great start.

Support

Our preferred way of support is through Husarnet Community.

If you want you can reach us at support@husarnet.com too.

Husarnet Dashboard

Husarnet Dashboard is a platform for managing all your Client instances. You can create groups/check statuses/rename nodes and a lot more there.

In the Husarnet Dashboard Quick Start guide, you'll find all the important bits and pieces of information to become a poweruser.

Husarnet Client

Husarnet Client is open source and available for all supported platforms at: https://github.com/husarnet/husarnet

For typical "quickstart" setup, choose your platform below and see installation instructions. Alternative approaches and extended guides for all the platforms can be found in the sidebar on the left, in the "Platforms" section.

Linux

note

Husarnet Client for Linux

Supported architectures: i386, x64 (amd64), armhf, arm64, riscv64

Choose your Linux distribution:

Debian, Ubuntu, CentOS, RHEL, Fedora, Mint or Arch

For APT, pacman and yum based Linux the simplest way to install Husarnet is to paste the following line into your terminal:

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

Now export your Join Code as environment variable:

export JOINCODE=fc94:b01d:1803:8dd8:b293:5c7d:7639:932a/XXXXXXXXXXXXXXXXXXXXXX

To join your device to Husarnet network, execute:

sudo husarnet join $JOINCODE some-hostname

Other distributions

If your Linux distribution is not supported by the one-command install method, you can also download the binary package. For most seamless experience, it is recommended to unpack it in the root directory (/):

curl https://install.husarnet.com/tgz/husarnet-latest-amd64.tar > husarnet-latest-amd64.tar
sudo tar --directory=/ --no-same-owner --dereference -xf husarnet-latest-amd64.tar

(replace -amd64 with -armhf, -arm64 or -i386 if you don't have 64-bit Intel/AMD processor)

If you are using systemd, enable and start the service:

systemctl enable husarnet
systemctl start husarnet

otherwise start the Husarnet Daemon manually:

husarnet daemon &

Now export your Join Code as environment variable:

export JOINCODE=fc94:b01d:1803:8dd8:b293:5c7d:7639:932a/XXXXXXXXXXXXXXXXXXXXXX

To join your device to Husarnet network, execute:

sudo husarnet join $JOINCODE some-hostname

Windows

note

Husarnet Client container (sidecar)

Supported architectures: x64 (amd64), armhf, arm64

Choose a preffered method for running containers:

docker run

To start a Husarnet Sidecar container execute:

docker run -it \
--name husarnet-vpn \
--env HOSTNAME='testing-container' \
--env JOINCODE='JOINCODE=fc94:b01d:1803:8dd8:b293:5c7d:7639:932a/XXXXXXXXXXXXXXXXXXXXXX' \
--volume husarnet-vol:/var/lib/husarnet \
--device /dev/net/tun \
--cap-add NET_ADMIN \
--sysctl net.ipv6.conf.all.disable_ipv6=0 \
husarnet/husarnet:latest

replace fc94:...:932a/XXX...XXXXX with your own Join Code

Now to give other containers on the same host access to your Husarnet network (using wordpress container as an example):

docker run -it \
--network container:husarnet-vpn \
--volume wordpress-vol:/var/www/html \
wordpress

Now you should be able to access a wordpress boilerplate in a browser of any computer connected to the same Husarnet network by using: http://testing-container:80 (because wordpress is hosted on port 80 by default)

docker-compose

To start a Husarnet Sidecar container that provides over-the-internet access for your application containers (in the example below - for wordpress), create a docker-compose.yml file:

version: '2.2'

services:
  my-website:
    image: wordpress
    restart: unless-stopped
    network_mode: service:husarnet
    volumes:
      - /var/www/html

  husarnet:
    image: husarnet/husarnet:latest
    restart: unless-stopped
    volumes:
      - /var/lib/husarnet
    sysctls:
      - net.ipv6.conf.all.disable_ipv6=0
    cap_add:
      - NET_ADMIN
    devices:
      - /dev/net/tun
    environment:
      HOSTNAME: testing-container
      JOINCODE: fc94:b01d:1803:8dd8:b293:5c7d:7639:932a/XXXXXXXXXXXXXXXXXXXXXX

replace fc94:...:932a/XXX...XXXXX with your own Join Code

And execute:

docker-compose up

Now you should be able to access a wordpress boilerplate in a browser of any computer connected to the same Husarnet network by using: http://testing-container:80 (because wordpress is hosted on port 80 by default)

ansible

To start a Husarnet Sidecar container that provides over-the-internet access for your application containers (in the example below - for wordpress), create a playbook.yml file:

- name: Wordpress available over Husarnet
  hosts: localhost

  tasks:
  - name: Running Husarnet
    community.docker.docker_container:
      name: husarnet
      image: husarnet/husarnet:latest
      restart_policy: unless-stopped
      volumes:
        - /var/lib/husarnet
      sysctls:
        net.ipv6.conf.all.disable_ipv6: 0
      capabilities:
        - net_admin
      devices:
        - "/dev/net/tun:/dev/net/tun:rwm"
      env:
        HOSTNAME: testing-container
        JOINCODE: fc94:b01d:1803:8dd8:b293:5c7d:7639:932a/XXXXXXXXXXXXXXXXXXXXXX
  
  - name: Running Wordpress
    community.docker.docker_container:
      name: my-website
      image: wordpress
      volumes:
        - wordpress:/var/www/html
      network_mode: "container:husarnet"

replace fc94:...:932a/XXX...XXXXX with your own Join Code

And execute:

ansible-playbook playbook.yml

Now you should be able to access a wordpress boilerplate in a browser of any computer connected to the same Husarnet network by using: http://testing-container:80 (because wordpress is hosted on port 80 by default)

Container

note

Husarnet Action for GitHub Actions

Supported runners hosted by GitHub: ubuntu-18.04, ubuntu-20.04, ubuntu-latest

To use Husarnet in your GitHub workflow, create a .github/workflows/my-husarnet-workflow.yml file with the following content in your GitHub repository:

name: Ping other peer from a VPN network

on: push

jobs:
  build:
    runs-on: ubuntu-20.04
    steps:

    - name: Connecting to Husarnet VPN network
      uses: husarnet/husarnet-action@v1
      with:
        join-code: ${{ secrets.HUSARNET_JOINCODE }}

    - name: Ping other peer
      run: ping6 -c 10 my-laptop

    - name: Stop husarnet
      run: sudo systemctl stop husarnet

Create a new GitHub secret: HUSARNET_JOINCODE and place your Join Code there.

Now after each commit, my-laptop device (we assume that it is in the same Husarnet network) will be pinged 10 times.

GitHub Actions

note

Husarnet Client SDK for ESP32

Prerequisites: Install Visual Studio Code and platformio extension first!

Let's run a simple webserver hosted on ESP32 that is based on AsyncTCP and ESPAsyncWebServer libraries. They are not required by Husarnet to work, but are faster than default ones provided in Arduino Core for ESP32.

Create a folder for your ESP32 project, eg. esp32-proj. Inside that folder create two files:

• platformio.ini
• src/simple-webserver.ino

with the following content:

src/simple-webserver.ino

#include <WiFi.h>
#include <AsyncTCP.h>
#include <ESPAsyncWebServer.h>
#include <Husarnet.h>

// WiFi credentials
const char *ssid = "my-wifi-ssid";
const char *password = "my-wifi-pass";

// Husarnet credentials
const char *hostName = "esp32-webserver";
const char *husarnetJoinCode = "fc94:b01d:1803:8dd8:b293:5c7d:7639:932a/XXXXXXXXXXXXXXXXXXXXXX";

// HTTP Server on port 8080
AsyncWebServer server(8080);

void setup(void)
{
  Serial.begin(115200);
  WiFi.mode(WIFI_STA);
  WiFi.begin(ssid, password);

  while (WiFi.status() != WL_CONNECTED) {
    delay(500);
    Serial.println("waiting for Wi-Fi...");
  }

  Husarnet.join(husarnetJoinCode, hostName);
  Husarnet.start();

  server.on("/", HTTP_GET, [](AsyncWebServerRequest *request) {
    request->send(200, "text/plain", "Hello world!!!");
  });
  server.begin();
}

void loop(void){}

platformio.ini

[env]
platform = espressif32
framework = arduino
platform_packages =
    framework-arduinoespressif32 @ https://github.com/husarnet/arduino-esp32/releases/download/1.0.4-1/arduino-husarnet-esp32.zip
lib_deps =
    https://github.com/husarnet/AsyncTCP.git  
    Husarnet ESP32
    ESP Async WebServer

[env:esp32dev]
board = esp32dev
monitor_speed = 115200
upload_speed = 921600

board_build.partitions = min_spiffs.csv

replace fc94:...:932a/XXX...XXXXX with your own Join Code and place your own Wi-Fi credentials in the *.ino file

Open the project folder using Visual Studio Code. Platformio extension should now automatically download and install locally all required tools and libraries needed to build and flash a firmware.

Click PlatformIO: Upload button in Visual Studio Code. After a few seconds your first HTTP webserver on ESP32 should be available from a level of any device from your Husarnet network under the following URL: http://esp32-webserver:8080.

Reseting IPv6 addr

Husarnet IPv6 address of each ESP32 is stored in a flash. If you want to generate a new IPv6 address for you ESP32 run: pio run --target erase inside the project folder.

ESP32

note

Husarnet Client for Windows

Caution: Only 64-bit Windows is supported.

Download latest Husarnet Windows installer and run the executable.

You are likely to get SmartScreen popup from Windows; unfortunately, Windows considers unsigned .exe files as a threat to system security. Click on [More info] and you'll be able to run the installer as you would install any software on Windows.

After installer finishes working, service will start and you should be able to use Husarnet through the command line. Run cmd.exe or PowerShell and type:

husarnet status

If you see errors, try running elevated command prompt (Right-click and Run as administrator...)

If output looks OK, use Join Code to join a network:

husarnet join <JOINCODE> my-windows-dev

MacOS

note

Husarnet Client for MacOS [ALPHA]

Caution: Our MacOS client is Work-in-Progress. Some things might not yet work exactly like in Linux client, and stability is not guaranteed. Feel welcome to report bugs and remarks on our Community Forums.

Caution: Currently, we only support Apple Silicon devices (M1 arm architecture)

The binaries are available through Homebrew. You need to add our 'nightly', tap, as MacOS client is not yet in stable.

brew tap husarnet/tap-nightly
brew install husarnet

After installation finishes, you have to start the daemon and install it into launchctl, this is done via single command (requires sudo):

sudo husarnet daemon service-install

After couple of seconds you can check the status:

husarnet status

If the output looks OK, use Join Code to join a network:

husarnet join <JOINCODE> my-windows-dev

Android ⏳

note

Husarnet Client for Android

is coming soon ... ⏳