racks/kaya-go
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
kaya-go/README.md
racks b0684540e8 Update README.md
2026-03-01 17:33:13 +01:00

6.9 KiB
Raw Blame History

Kaya

Kaya Dashboard

Go Version IPv6 Mesh Encryption QUIC Security License

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.