Fubuki

中文 | English

Fubuki is a mesh VPN: it connects machines in different networks (home, office, cloud) into one virtual network. Each machine runs a node and gets a stable virtual IP. Nodes discover each other and connect via a central server; when possible they talk directly (P2P), otherwise traffic is relayed through the server.

Use cases: remote access to home/office devices, linking servers across regions, gaming or tools that assume a single LAN.

Community

• Fubukidaze — Community Android client for Fubuki.

---

Table of contents

• Community
• Quick start
• Prerequisites
• Configuration
• Running server and nodes
• Using the network
• Web UI and TUI
• Build from source
• Features

---

Quick start

1. Prepare

   • One machine with a public IP (or port forwarding) to run the server.
   • One or more machines that will join the mesh as nodes.

2. Create server config server.json:

   {
     "groups": [{
       "name": "mygroup",
       "key": "your-secret-key",
       "listen_addr": "0.0.0.0:12345",
       "address_range": "10.0.0.0/24"
     }]
   }

3. Start the server (on the machine with public IP):

   fubuki server daemon -c ./server.json

4. Create node config node.json on each machine that should join (replace SERVER_IP with the server’s public IP):

   {
     "groups": [{
       "node_name": "alice",
       "server_addr": "SERVER_IP:12345",
       "key": "your-secret-key"
     }]
   }

5. Start each node (as root/admin if required by your OS):

   fubuki node daemon -c ./node.json

6. Test: from one node, ping another by name or by virtual IP:

   ping bob.mygroup
   # or use the virtual IP shown in logs / Web UI

The key and group name must match between server and nodes; node_name must be unique per group.

---

Prerequisites

Platform	Notes
Windows	Run as Administrator. Put wintun DLL next to fubuki.exe or in System32. Windows 7 needs KB3063858 and KB4474419.
Linux	Run as root (or equivalent). Kernel must support TUN.
macOS	Run as root. Kernel must support TUN.

Server: must be reachable from all nodes (open the listen_addr port on the firewall and/or router).

---

Configuration

All options are in JSON config files passed to fubuki server daemon -c <path> or fubuki node daemon -c <path>.

For complete and advanced examples (all supported fields, multiple groups, optional tuning), see the cfg-example directory (GitHub).

Server config

Field	Required	Description
groups	Yes	List of groups. Each group is one virtual network.
groups[].name	Yes	Group name (e.g. mygroup). Nodes use this to join.
groups[].key	No	Pre-shared key. Omit for no encryption; set the same on nodes to authenticate.
groups[].listen_addr	Yes	IP:PORT the server listens on (e.g. 0.0.0.0:12345). Use a public IP or 0.0.0.0.
groups[].address_range	Yes	Virtual subnet for this group (e.g. 10.0.0.0/24).
api_addr	No	HTTP API address (default 127.0.0.1:3031). Used for Web UI / status.
tcp_heartbeat_interval_secs	No	Default 5.
udp_heartbeat_interval_secs	No	Default 5.

Example with two groups:

{
  "groups": [
    {
      "name": "home",
      "key": "secret1",
      "listen_addr": "0.0.0.0:12345",
      "address_range": "10.0.0.0/24"
    },
    {
      "name": "office",
      "key": "secret2",
      "listen_addr": "0.0.0.0:12346",
      "address_range": "10.0.1.0/24"
    }
  ]
}

Node config

Field	Required	Description
groups	Yes	List of groups this node joins (can join multiple).
groups[].node_name	Yes	Unique name in that group (e.g. alice, laptop).
groups[].server_addr	Yes	Server address: IP:PORT (must match server’s listen_addr).
groups[].key	No	Pre-shared key; must match the server group’s key.
api_addr	No	HTTP API address (default 127.0.0.1:3030). Web UI / TUI use this.

Example (one node, one group):

{
  "groups": [{
    "node_name": "alice",
    "server_addr": "203.0.113.10:12345",
    "key": "secret1"
  }]
}

Example (one node, two groups):

{
  "groups": [
    {
      "node_name": "alice",
      "server_addr": "203.0.113.10:12345",
      "key": "secret1"
    },
    {
      "node_name": "alice",
      "server_addr": "203.0.113.10:12346",
      "key": "secret2"
    }
  ]
}

---

Running server and nodes

fubuki server daemon -c /path/to/server.json   # start server (alias: start)
fubuki server info                             # status TUI  (alias: status, default API: 127.0.0.1:3031)
fubuki server restart                          # restart server

fubuki node daemon -c /path/to/node.json       # start node   (alias: start)
fubuki node info                               # status TUI  (alias: status, default API: 127.0.0.1:3030)
fubuki node restart                            # restart node

fubuki update                                  # self-update to latest release

Use -a <ADDR> / --api <ADDR> with info and restart to target a non-default API address.

Use the same group name and key on server and nodes. Each node’s node_name must be unique within that group. You can run multiple nodes on the same machine with different configs (different node_name and/or config file).

---

Using the network

• By hostname: ping <node_name>.<group_name> (e.g. ping bob.mygroup). Fubuki updates the hosts file (or you can resolve manually) so that name points to the node’s virtual IP.
• By virtual IP: each node gets an IP from the group’s address_range (e.g. 10.0.0.2). Use this IP like any other: SSH, HTTP, game servers, etc.
• Routing: ensure your OS routes traffic for the group’s address_range via the TUN device Fubuki creates (Fubuki typically sets this up for you on supported platforms).

---

Web UI and TUI

• Web UI (build with --features web): While the node or server is running, open http://API_ADDR in a browser. Defaults: node http://127.0.0.1:3030, server http://127.0.0.1:3031. The dashboard shows groups, nodes, virtual IPs, latency, and loss.
• TUI (terminal UI): Run fubuki node info or fubuki server info to open the status TUI. Use -a/--api to target a non-default API address.

Set api_addr in the server or node config to change where the API (and Web UI) listens.

---

Build from source

• Rust: nightly toolchain.
• Windows: MSVC toolchain.

cargo +nightly build --release

With Web UI (bundled dashboard):

cd fubuki-webui && npm install && npm run build && cd ..
cargo +nightly build --release --features "web"

With desktop GUI:

cargo +nightly build --release --features "gui"

Android (FFI library):

export RUSTUP_TOOLCHAIN=nightly
cargo install cross --git https://github.com/cross-rs/cross
cross build --lib --release --no-default-features --features "ffi-export" --target aarch64-linux-android

---

Features

Feature	Cargo flag	Description
mimalloc	default	Alternative allocator.
web	--features web	Embed and serve Web UI from the API.
gui	--features gui	Desktop GUI (klask).
cross-nat	--features cross-nat	netstack-lwip for cross-NAT.
ffi-export	--features ffi-export	FFI for use as a library (e.g. Android).