Kaya

---

Introduction

Kaya is an early-stage implementation of a fully end-to-end encrypted IPv6 mesh network.

It is lightweight, self-arranging, multi-platform, and allows any IPv6-capable application to communicate securely with other Kaya nodes. Kaya does not require native IPv6 Internet connectivity --- it works over IPv4.

This repository extends the baseline implementation with substantial enhancements focused on:

• Performance
• Operability
• Observability
• Runtime safety
• Operator UX

The core protocol semantics are preserved while improving deployment, diagnostics, and control behavior.

---

Supported Platforms

Kaya runs on:

• Linux
• macOS
• Windows
• FreeBSD
• OpenBSD
• OpenWrt
• Ubiquiti EdgeRouter
• VyOS

---

Building

Requires Go 1.22 or later.

Build the binaries directly:

go build -o kaya ./cmd/yggdrasil
go build -o kayactl ./cmd/yggdrasilctl

Cross-compiling example:

GOOS=windows GOARCH=amd64 go build -o kaya.exe ./cmd/yggdrasil

---

Running

Generate Configuration

HJSON:

./kaya -genconf > /path/to/kaya.conf

JSON:

./kaya -genconf -json > /path/to/kaya.conf

Edit the configuration file to add/remove peers, adjust listen addresses, multicast settings, etc.

Start Kaya

With configuration:

./kaya -useconffile /path/to/kaya.conf

Auto-configuration mode:

./kaya -autoconf

Kaya requires permission to create TUN/TAP adapters. On Linux, run under sudo or grant the binary CAP_NET_ADMIN.

---

Extended Features in This Repository

This repository includes a substantial set of enhancements on top of baseline behavior.

---

1) Operator Dashboard (Built-in HTTP UI)

A built-in web dashboard is available directly from the daemon to monitor and manage node state.

Live runtime telemetry for:

• node/self identity and routing metadata
• peer links and per-peer health
• session/flow activity
• path and tree information

Additional capabilities:

• Peer control actions (disconnect / traffic control via daemon APIs)
• Optional authentication for the private dashboard listener
• Public read-only dashboard mode (--public-interface)
• Real-time bandwidth visualization (Mbit/s) with directional indicators
• Responsive, overflow-safe layout for long URIs and IPv6 addresses

---

2) Runtime Control and Safety Hardening

Stronger operator controls for CPU behavior and process hardening:

• --threads explicitly controls scheduler parallelism (GOMAXPROCS)
• --max-threads provides a hard cap for OS threads
• --sandbox enables Linux hardening early in startup:
  • no-new-privileges
  • non-dumpable process mode
  • core-dump suppression

These options provide predictable behavior on constrained systems and hardened production deployments.

---

3) Colorized, High-Signal Terminal Logging

Interactive stdout logs are rendered with contextual colorization:

• Distinct color classes for errors, warnings, link lifecycle, interface messages, and sandbox events
• Improved per-line TTY rendering
• Faster at-a-glance diagnostics during startup and runtime

---

4) Admin API Extensions for Traffic Control

Enhanced peer traffic operations:

• setPeerTraffic support to toggle routing via specific peers
• Stricter boolean parsing and validation
• Integrated dashboard and CLI workflows

---

5) kayactl UX and Topology Visibility Improvements

CLI enhancements include:

• Improved peer listing with direct remote endpoint view
• Clearer hierarchical tree/topology formatting
• Tight integration with peer traffic control operations

---

6) Core Performance Optimizations

Datapath and control-path improvements without changing protocol semantics:

• Persistent ticker-based link average updates (reduced timer churn)
• Optimized peer snapshot collection
• Faster inbound allowed-key authorization lookup
• Reduced atomic overhead in hot accounting paths
• Debug protocol response lifecycle optimizations
• URI parsing and CLI/control surface improvements

---

7) Transport and Dialing Efficiency Enhancements

Connection setup improvements:

• Improved TCP source-interface handling with short-lived metadata caching
• Better address selection and dial suitability behavior
• Reduced per-dial overhead in WS/WSS transports
• QUIC dialing and throughput optimizations
• TLS configuration correctness fixes in QUIC paths

---

8) Process-Model and Platform Tightening

Reliability refinements:

• Stronger single-process behavior expectations
• FreeBSD TUN setup returns direct ioctl failures (no shell fallback)
• Clearer dashboard lifecycle and shutdown handling

---

Practical Outcome

• Better operator visibility (dashboard + CLI)
• Stronger runtime control (--threads, --max-threads, sandboxing)
• Lower operational overhead
• Improved day-2 debugging and peer management
• Safer and faster default operation

---

Topics

go golang ipv6 mesh-network p2p overlay-network
encrypted-network distributed-systems quic tcp websocket
linux freebsd openbsd macos windows openwrt
cli dashboard observability performance security
sandbox infrastructure networking systems-programming

---

License

LGPLv3 with linking exception. See LICENSE for details.