🐺🌐 WolfNet

Secure Private Mesh Networking

Overview

WolfNet creates a secure, encrypted private network between your machines over the internet. Think of it as your own private network layer — machines on WolfNet can see each other as if they were on the same LAN, but all traffic is encrypted with modern cryptography.

🔐

Military-Grade Encryption

X25519 key exchange + ChaCha20-Poly1305 authenticated encryption. Same crypto as WireGuard.

🌐

Mesh Networking

Every node can reach every other node directly. No single point of failure.

🎟️

Invite/Join System

Connect peers with a single token — no manual key exchange or config editing needed.

🔀

Relay Forwarding

Nodes behind NAT can communicate through a relay — no port forwarding needed.

🔄

Endpoint Roaming

Dynamic IP changes are detected automatically — connections self-heal in ~30 seconds.

🚪

Gateway Mode

Route internet traffic through a gateway node. Only WolfNet machines can access the network.

⚡

Fast & Lightweight

Built in Rust with minimal overhead. Uses kernel TUN interfaces for near-native performance.

Architecture

text

Machine A (10.0.10.1)          Machine B (10.0.10.2)
┌─────────────────┐            ┌─────────────────┐
│  wolfnet0 (TUN) │◄──────────►│  wolfnet0 (TUN) │
│  10.0.10.1/24   │  Encrypted │  10.0.10.2/24   │
│  ChaCha20-Poly  │  UDP/9600  │  ChaCha20-Poly  │
└─────────────────┘            └─────────────────┘
         ▲                              ▲
         │       Encrypted UDP          │
         └──────────┬───────────────────┘
                    │
           ┌────────▼────────┐
           │  Machine C      │
           │  (Gateway)      │
           │  10.0.10.3/24   │
           │  NAT → Internet │
           └─────────────────┘

How It Works

Each machine runs the wolfnet daemon which creates a virtual network interface (wolfnet0)
The interface gets an IP from the private range (default 10.0.10.0/24)
Traffic to other WolfNet IPs is encrypted and sent via UDP tunnels
Nodes discover each other automatically on LAN, or are configured manually for WAN
External traffic cannot enter the network — it's truly private

Quick Install

Install WolfNet with the interactive installer:

bash

curl -sSL https://raw.githubusercontent.com/wolfsoftwaresystemsltd/WolfScale/main/wolfnet/setup.sh | sudo bash

The installer will:

Check for /dev/net/tun (required for virtual interfaces)
Download and install wolfnet and wolfnetctl
Generate an X25519 keypair
Prompt for WolfNet IP address, port, and gateway mode
Create a systemd service for automatic startup

CLI Reference

wolfnet (Daemon)

Command	Description
`wolfnet`	Start the daemon (usually via systemd)
`wolfnet init --address 10.0.10.1`	Generate config and keypair
`wolfnet genkey`	Generate a new X25519 keypair
`wolfnet pubkey`	Show this node's public key
`wolfnet token`	Show join token for sharing with peers
`wolfnet invite`	Generate an invite token for a new peer
`wolfnet join <token>`	Join a network using an invite token

wolfnetctl (Control Utility)

Command	Description
`wolfnetctl status`	Show node status, IP, uptime, peer count
`wolfnetctl peers`	List all peers with hostnames, IPs, and connection status
`wolfnetctl info`	Combined status and peer list

Systemd Service

bash

# Start / stop
sudo systemctl start wolfnet
sudo systemctl stop wolfnet

# Check status
sudo systemctl status wolfnet

# View logs
sudo journalctl -u wolfnet -f

Setting Up a Remote Connection

Follow these steps to connect two machines over the internet.

Step 1: Install WolfNet on both machines

bash

curl -sSL https://raw.githubusercontent.com/wolfsoftwaresystemsltd/WolfScale/main/wolfnet/setup.sh | sudo bash

Run this on both machines. The installer will prompt for an IP address — choose a different address for each (e.g. 10.0.10.1 and 10.0.10.2).

Step 2: Generate an invite on the first machine

On the machine with a public IP or port forwarding (port 9600/UDP), run:

bash

sudo wolfnet invite

This will output a wolfnet join command with a token.

Step 3: Join from the second machine

Copy and paste the command from step 2 onto the second machine:

bash

sudo wolfnet --config /etc/wolfnet/config.toml join eyJwa...

This will output a reverse token. Copy it.

Step 4: Complete the link on the first machine

Paste the reverse token command on the first machine:

bash

sudo wolfnet --config /etc/wolfnet/config.toml join eyJlc...

Step 5: Restart WolfNet on both machines

bash

sudo systemctl restart wolfnet

Step 6: Verify the connection

bash

# Check peer status
wolfnetctl peers

# Ping the other machine
ping 10.0.10.2

💡 Dynamic IP? If your public IP changes (common with home broadband), WolfNet handles it automatically. Periodic handshakes detect IP changes and update endpoints within ~30 seconds — no manual intervention needed. A relay VPS is only required if neither machine has a reachable IP.

Easy Peer Setup (Invite/Join)

Connect two machines in seconds — no manual key exchange or config editing needed:

bash

# Step 1: On the first machine, generate an invite token:
sudo wolfnet invite

# It will output something like:
#   sudo wolfnet --config /etc/wolfnet/config.toml join eyJwa...

# Step 2: Copy that command and run it on the second machine:
sudo wolfnet --config /etc/wolfnet/config.toml join eyJwa...

# Step 3: It gives you a reverse token — run that on the first machine:
sudo wolfnet --config /etc/wolfnet/config.toml join eyJlc...

# Step 4: Restart WolfNet on both:
sudo systemctl restart wolfnet

The invite token automatically:

Detects your public IP address
Includes your public key and endpoint
Auto-assigns the next available WolfNet IP
Generates a reverse token so both sides are configured

NAT Traversal (Relay Forwarding)

WolfNet supports relay forwarding so machines behind NAT firewalls can communicate without port forwarding:

text

Laptop (behind NAT)       Server (public IP)        Home PC (behind NAT)
    10.0.10.1                10.0.10.2                 10.0.10.3
        │                        │                        │
        └── encrypted UDP ──────►│◄───── encrypted UDP ───┘
                                 │
                          Relay forwards
                         packets between
                        Laptop ◄──► Home PC

How It Works

Both the laptop and home PC connect to the server (which has a public IP)
When the laptop sends a packet to the home PC, the server detects it's not the destination
The server decrypts, re-encrypts for the home PC, and forwards it
This happens automatically — any node that both peers can reach acts as a relay
All traffic remains encrypted at every hop

💡 Tip: You only need one node with a public IP (or port forwarding). All other nodes can connect through it as a relay. A cheap VPS works perfectly for this.

Endpoint Roaming (Dynamic IPs)

WolfNet automatically handles dynamic IP changes. If your ISP assigns a new public IP, WolfNet detects the change and updates peer endpoints automatically.

How It Works

Every node sends periodic handshakes to known peers (~30 seconds)
When a handshake arrives from a peer's new IP, the endpoint is updated automatically
Data packets also trigger roaming — if a valid encrypted packet arrives from an unknown IP, WolfNet identifies the peer and updates their endpoint
Reconnection happens within ~30 seconds of an IP change

Scenario	Result
One side's IP changes	✅ Auto-recovers via handshakes (~30s)
Both sides' IPs change	⚠ Needs a relay VPS as rendezvous point
Peer moves to different network	✅ Auto-recovers once the peer sends a handshake

💡 No configuration needed. Endpoint roaming is always active. There's nothing to enable — WolfNet handles it automatically.

Real-World Scenarios

Here's how WolfNet works in three common situations. Pick the one that matches your setup — or combine them.

📋 Scenario 1: Office + Home Network

You have servers at work and want to access them securely from home. Your office has a static IP from the ISP. Your home broadband has a changing IP (like most home connections).

text


          YOUR OFFICE                              YOUR HOME
      ┌─────────────────┐                     ┌─────────────────┐
      │  Office Server   │                     │  Home PC / Laptop│
      │                  │    Encrypted        │                  │
      │  Static IP:      │◄══════════════════►│  Dynamic IP:     │
      │  82.45.100.20    │    WolfNet Tunnel   │  Changes daily   │
      │                  │                     │                  │
      │  WolfNet IP:     │                     │  WolfNet IP:     │
      │  10.0.10.1       │                     │  10.0.10.2       │
      └─────────────────┘                     └─────────────────┘

      The office server has a fixed IP          Your home IP changes, but WolfNet
      that never changes.                       finds it using your DynDNS hostname
                                                (e.g. myhome.dyndns.org).

      Result: You can access your office servers from home as if you were
      sitting at your desk. Just use the WolfNet IP (10.0.10.1) from home.

How to Set This Up

Install WolfNet on both the office server and your home machine
On the office server, run sudo wolfnet invite
Copy the invite command to your home machine and run it
Copy the reverse token back to the office server and run it
Restart WolfNet on both: sudo systemctl restart wolfnet

Office Server Config

The office knows how to find your home machine via DynDNS:

toml

[network]
address = "10.0.10.1"

[[peers]]
public_key = "YOUR_HOME_PUBLIC_KEY"
endpoint = "myhome.dyndns.org:9600"   # Your home's DynDNS hostname
allowed_ip = "10.0.10.2"
name = "home"

Home Machine Config

Your home machine knows the office's fixed IP address:

toml

[network]
address = "10.0.10.2"

[[peers]]
public_key = "OFFICE_SERVER_PUBLIC_KEY"
endpoint = "82.45.100.20:9600"   # Office's static IP address
allowed_ip = "10.0.10.1"
name = "office"

💡 DynDNS hostname support — WolfNet re-resolves hostnames every 60 seconds, so when your home ISP gives you a new IP address, WolfNet picks it up automatically. Works with DynDNS, No-IP, DuckDNS, Cloudflare, or any DNS provider. Most home routers have DynDNS built in — just enable it in your router settings.

💡 Multiple people at home? Install WolfNet on each person's machine and give them each a unique WolfNet IP (10.0.10.3, 10.0.10.4, etc.). They'll all be able to access the office servers securely.

🖥️ Scenario 2: Standalone Servers (Hetzner, OVH, etc.)

You have two or more servers rented from a hosting provider. Each server has its own static public IP, but they're on completely separate networks — no VLAN, no private network between them. WolfNet creates a private encrypted network between them.

text


      Hetzner (Germany)             OVH (France)              DigitalOcean (US)
      ┌─────────────────┐      ┌─────────────────┐      ┌─────────────────┐
      │  Server 1        │      │  Server 2        │      │  Server 3        │
      │                  │      │                  │      │                  │
      │  Public IP:      │      │  Public IP:      │      │  Public IP:      │
      │  116.203.45.10   │      │  51.178.200.30   │      │  167.99.120.50   │
      │                  │      │                  │      │                  │
      │  WolfNet IP:     │      │  WolfNet IP:     │      │  WolfNet IP:     │
      │  10.0.10.1       │      │  10.0.10.2       │      │  10.0.10.3       │
      └────────┬─────────┘      └────────┬─────────┘      └────────┬─────────┘
               │                         │                         │
               └─────── Encrypted ───────┼─────── Encrypted ──────┘
                        WolfNet          │         WolfNet
                        Tunnel           │         Tunnel
                                         │
                                  All three servers
                                  see each other as
                                  10.0.10.1, .2, .3
                                  on a private network.

      No VLAN needed. No provider-specific private networking.
      WolfNet creates the private network over the public internet.

Why Use WolfNet Instead of a VLAN?

Works across providers — Link a Hetzner server to an OVH server to a DigitalOcean droplet. VLANs only work within one provider.
No extra cost — Many providers charge for private networking. WolfNet is free.
Encrypted — VLANs are often unencrypted. WolfNet traffic is always encrypted with ChaCha20-Poly1305.
Works anywhere — Any server with a public IP and UDP access can join your WolfNet.

How to Set This Up

Install WolfNet on all three servers
On Server 1, run sudo wolfnet invite
Copy the invite command to Server 2, run it, copy the reverse token back to Server 1
On Server 1, run sudo wolfnet invite again for Server 3
Copy the invite to Server 3, run it, copy the reverse token back to Server 1
Restart WolfNet on all servers: sudo systemctl restart wolfnet

That's it. Server 2 and Server 3 will discover each other automatically via Peer Exchange (PEX) within 30 seconds — you don't need to manually link every pair.

Example Config (Server 1 — Hetzner)

toml

[network]
address = "10.0.10.1"
listen_port = 9600

[[peers]]
public_key = "SERVER_2_PUBLIC_KEY"
endpoint = "51.178.200.30:9600"     # OVH server's static IP
allowed_ip = "10.0.10.2"
name = "ovh-france"

[[peers]]
public_key = "SERVER_3_PUBLIC_KEY"
endpoint = "167.99.120.50:9600"     # DigitalOcean server's static IP
allowed_ip = "10.0.10.3"
name = "do-usa"

💡 Once connected, use your WolfNet IPs everywhere. Configure your applications to talk to 10.0.10.1, 10.0.10.2, 10.0.10.3 — just like they're on the same local network. This works perfectly with WolfScale database replication and WolfDisk file sharing.

🏠 Scenario 3: Simple Local Network (Auto-Discovery)

You have multiple machines on the same local network (same router, same office, same home) and want a private encrypted network between them. No internet access needed — everything stays local.

text


                      Your Local Network (e.g. 192.168.1.x)
      ┌──────────────────────────────────────────────────────┐
      │                                                      │
      │   PC 1               PC 2              PC 3          │
      │   ┌──────────┐       ┌──────────┐      ┌──────────┐  │
      │   │ WolfNet  │       │ WolfNet  │      │ WolfNet  │  │
      │   │ 10.0.10.1│◄─────►│ 10.0.10.2│◄────►│ 10.0.10.3│  │
      │   └──────────┘       └──────────┘      └──────────┘  │
      │                                                      │
      │         All machines auto-discover each other.        │
      │         No configuration needed beyond install.       │
      │                                                      │
      └──────────────────────────────────────────────────────┘

      Just install WolfNet on each machine. They find each
      other automatically via UDP broadcast. Zero config.

How to Set This Up

This is the simplest scenario — just install WolfNet on each machine:

bash

# Run this on every machine:
curl -sSL https://raw.githubusercontent.com/wolfsoftwaresystemsltd/WolfScale/main/wolfnet/setup.sh | sudo bash

When prompted, give each machine a different WolfNet IP:

PC 1: 10.0.10.1
PC 2: 10.0.10.2
PC 3: 10.0.10.3

That's it. No invite tokens needed. No config files to edit. WolfNet's auto-discovery uses UDP broadcast to find peers on the same network within seconds.

Verify It's Working

bash

# Check who's on the network:
wolfnetctl peers

# Ping another machine:
ping 10.0.10.2

💡 Why use WolfNet on a local network? Even on LAN, WolfNet gives you an encrypted private network that's separate from your regular network traffic. It also makes your applications portable — if you later move a server to the cloud, just change the config from auto-discovery to a static IP and your apps keep using the same WolfNet IPs.

Which Method Should I Use?

Your Situation	Method	Endpoint Config
All machines on the same LAN	Auto-Discovery	Nothing needed — automatic
Servers with fixed public IPs (VPS, cloud)	Static IP	`endpoint = "203.0.113.5:9600"`
Home broadband (IP changes)	DynDNS hostname	`endpoint = "myhome.dyndns.org:9600"`
Mix of office, home, and cloud	All of the above	Use the right method for each peer

You can freely mix all three methods in the same network. A WolfNet mesh can include auto-discovered LAN machines, cloud servers with static IPs, and home connections via DynDNS — all connected together.

⚠️ Proxmox / LXC Container Users

If you're running WolfNet inside a Proxmox LXC container, the TUN device (/dev/net/tun) is blocked by default for security. This is the same issue that affects Tailscale, WireGuard, and OpenVPN in containers.

📌 These steps must be done on the Proxmox HOST, not inside the container.

Step 1: Edit the container config

bash

# On the Proxmox host, edit /etc/pve/lxc/<CTID>.conf
# Replace <CTID> with your container ID (e.g. 100)
nano /etc/pve/lxc/100.conf

Step 2: Add TUN device permissions

Add these lines to the container config file:

conf

lxc.cgroup2.devices.allow: c 10:200 rwm
lxc.mount.entry: /dev/net dev/net none bind,create=dir

Step 3: Restart the container

bash

pct restart 100

Step 4: Verify inside the container

bash

# If /dev/net/tun still doesn't exist, create it manually:
mkdir -p /dev/net
mknod /dev/net/tun c 10 200
chmod 666 /dev/net/tun

# Verify
ls -la /dev/net/tun

💡 Note: For Proxmox VMs (not LXC containers), TUN works out of the box — no extra configuration needed.

Configuration

Edit /etc/wolfnet/config.toml:

toml

[network]
interface = "wolfnet0"       # Virtual interface name
address = "10.0.10.1"        # This node's IP on the WolfNet
subnet = 24                  # Subnet mask
listen_port = 9600           # UDP port for tunnel traffic
gateway = false              # Set true to act as internet gateway
discovery = true             # Auto-discover peers on LAN
mtu = 1400                   # MTU for tunnel interface

[security]
private_key_file = "/etc/wolfnet/private.key"

# Add peers for WAN connections (IP address or hostname):
[[peers]]
public_key = "BASE64_PUBLIC_KEY_HERE"
endpoint = "203.0.113.5:9600"           # Static IP
allowed_ip = "10.0.10.2"                # Peer's WolfNet IP
name = "server2"                         # Friendly name

[[peers]]
public_key = "ANOTHER_PUBLIC_KEY_HERE"
endpoint = "myhome.dyndns.org:9600"     # DynDNS hostname (re-resolved every 60s)
allowed_ip = "10.0.10.3"
name = "home-server"

IP Range

The default range is 10.0.10.0/24, giving you addresses 10.0.10.1 through 10.0.10.254. You can use any private IP range by changing the address and subnet settings.

Gateway Mode

A gateway node lets other WolfNet machines access the internet through it. This is useful when you want all traffic from your private network to exit through a single point.

toml

# On the gateway node:
[network]
gateway = true

When gateway mode is enabled, WolfNet automatically:

Enables IP forwarding (net.ipv4.ip_forward=1)
Detects your external network interface
Sets up iptables NAT masquerading
Blocks external inbound traffic to the WolfNet subnet

Security

Layer	Technology
Key Exchange	X25519 (Curve25519 Diffie-Hellman)
Encryption	ChaCha20-Poly1305 AEAD (256-bit)
Replay Protection	Counter-based nonces with monotonic validation
Network Isolation	iptables firewall blocks all external inbound traffic
Key Storage	Private keys stored with 0600 permissions

← WolfDisk