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.

Read how Husarnet works and find all relevant documentation and tutorials here.

IT'S OPEN!

Husarnet Client is open source and available here: https://github.com/husarnet/husarnet

If you want to start right away, find an instruction for your target platform in the section below.

Using Husarnet

Before you go to the Installation procedure, get your Husarnet Join Code first. Join Code allows you to connect your devices to the same Husarnet network.

info

To get your Join Code:

1. Setup a free account at Husarnet Dashboard: https://app.husarnet.com/accounts/register/
2. Create a new network, click [ Add element ] button and go to Join Code tab
3. Join Code looks like that: fc94:b01d:1803:8dd8:b293:5c7d:7639:932a/XXXXXXXXXXXXXXXXXXXXXX

Linux

note

Husarnet Client for Linux

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

Choose your Linux distribution:

Debian, Ubuntu, CentOS, RHEL, Fedora or Mint

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

curl -s 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='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 [BETA]

Caution: Our Windows 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. 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

Remember that You need to have a refreshed PATH after installation. Otherwise the husarnet command will not be recognized. The easiest way to do this is to simply restart Your console session.

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

is coming soon ... ⏳

Android ⏳

note

Husarnet Client for Android

is coming soon ... ⏳

Tutorials & examples

We provide example applications for Husarnet on our blog, like:

• Making Raspberry Pi Internet connected on 1st boot
• WebRTC server hosted on RaspberryPi with connected USB camera
• Using Husarnet with Kata containers
• Configure reverse proxy for public access to services hosted by Husarnet connected
• Using Husarnet VPN for low-latency remote desktop (VNC) connections
• Using Husarnet VPN with Cyclone DDS and ROS 2

There is also a Husarnet Hackster profile where you can find sample applications for ESP32 powered IoT.

Troubleshooting

Read Husarnet CLI Manual to understand how to use Husarnet CLI to manage the system.

Common issues and ways to solve or report them are covered in this guide.