247 lines
6.9 KiB
Markdown
247 lines
6.9 KiB
Markdown
# 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:
|
|
|
|
``` bash
|
|
go build -o kaya ./cmd/yggdrasil
|
|
go build -o kayactl ./cmd/yggdrasilctl
|
|
```
|
|
|
|
Cross-compiling example:
|
|
|
|
``` bash
|
|
GOOS=windows GOARCH=amd64 go build -o kaya.exe ./cmd/yggdrasil
|
|
```
|
|
|
|
------------------------------------------------------------------------
|
|
|
|
# Running
|
|
|
|
## Generate Configuration
|
|
|
|
HJSON:
|
|
|
|
``` bash
|
|
./kaya -genconf > /path/to/kaya.conf
|
|
```
|
|
|
|
JSON:
|
|
|
|
``` bash
|
|
./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:
|
|
|
|
``` bash
|
|
./kaya -useconffile /path/to/kaya.conf
|
|
```
|
|
|
|
Auto-configuration mode:
|
|
|
|
``` bash
|
|
./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.
|