From b0684540e8f0fb0f8e7d2d7ff43c31512a2fa569 Mon Sep 17 00:00:00 2001 From: racks Date: Sun, 1 Mar 2026 17:33:13 +0100 Subject: [PATCH] Update README.md --- README.md | 210 ++++++++++++++++++++++++++++++++++++++++-------------- 1 file changed, 158 insertions(+), 52 deletions(-) diff --git a/README.md b/README.md index fe47d9f..d6ca9cd 100644 --- a/README.md +++ b/README.md @@ -2,40 +2,51 @@ ![Kaya Dashboard](repo/4fa5ff31-c9d5-4aa5-bea6-97b81f3daf78.png) -[![Build -status](https://github.com/yggdrasil-network/yggdrasil-go/actions/workflows/ci.yml/badge.svg)](https://github.com/yggdrasil-network/yggdrasil-go/actions/workflows/ci.yml) +![Go Version](https://img.shields.io/badge/Go-1.22+-00ADD8?logo=go) +![IPv6](https://img.shields.io/badge/IPv6-Native-blue) +![Mesh](https://img.shields.io/badge/Topology-Mesh-green) +![Encryption](https://img.shields.io/badge/Encryption-End--to--End-red) +![QUIC](https://img.shields.io/badge/Transport-QUIC-purple) +![Security](https://img.shields.io/badge/Security-Hardened-black) +![License](https://img.shields.io/badge/License-LGPLv3-orange) ------------------------------------------------------------------------ ## Introduction -Kaya is an enhanced implementation of a fully end-to-end encrypted IPv6 -mesh network. +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 as well. +over IPv4. -This repository extends the baseline behavior with significant -improvements in: +This repository extends the baseline implementation with substantial +enhancements focused on: -- Observability\ -- Runtime control\ -- Performance\ -- Transport efficiency\ +- Performance +- Operability +- Observability +- Runtime safety - Operator UX +The core protocol semantics are preserved while improving deployment, +diagnostics, and control behavior. + ------------------------------------------------------------------------ ## Supported Platforms -- Linux\ -- macOS\ -- Windows\ -- FreeBSD / OpenBSD\ -- OpenWrt\ -- Ubiquiti EdgeRouter\ +Kaya runs on: + +- Linux +- macOS +- Windows +- FreeBSD +- OpenBSD +- OpenWrt +- Ubiquiti EdgeRouter - VyOS ------------------------------------------------------------------------ @@ -44,12 +55,14 @@ improvements in: Requires **Go 1.22 or later**. +Build the binaries directly: + ``` bash go build -o kaya ./cmd/yggdrasil go build -o kayactl ./cmd/yggdrasilctl ``` -Cross-compile example: +Cross-compiling example: ``` bash GOOS=windows GOARCH=amd64 go build -o kaya.exe ./cmd/yggdrasil @@ -61,78 +74,171 @@ GOOS=windows GOARCH=amd64 go build -o kaya.exe ./cmd/yggdrasil ## 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 interfaces.\ -On Linux, run under `sudo` or grant `CAP_NET_ADMIN`. +Kaya requires permission to create TUN/TAP adapters. On Linux, run under +`sudo` or grant the binary `CAP_NET_ADMIN`. ------------------------------------------------------------------------ -# Extended Features +# Extended Features in This Repository -## Built-in Operator Dashboard +This repository includes a substantial set of enhancements on top of +baseline behavior. -- Live telemetry (identity, routing, peers, flows, tree) -- Real-time bandwidth visualization -- Peer traffic control -- Optional authentication -- Public read-only mode (`--public-interface`) +------------------------------------------------------------------------ -## Runtime Control & Hardening +## 1) Operator Dashboard (Built-in HTTP UI) -- `--threads` -- `--max-threads` -- `--sandbox` (no-new-privileges, non-dumpable, core dump suppression) +A built-in web dashboard is available directly from the daemon to +monitor and manage node state. -## Enhanced CLI (`kayactl`) +**Live runtime telemetry for:** -- Improved peer listings -- Clear topology tree -- Integrated traffic control +- node/self identity and routing metadata +- peer links and per-peer health +- session/flow activity +- path and tree information -## Performance & Transport Improvements +Additional capabilities: -- Reduced timer churn -- Optimized peer snapshots -- Faster authorization lookups -- QUIC and TCP dialing improvements -- TLS correctness fixes +- 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\ -- Stronger runtime control\ -- Lower CPU and memory overhead\ -- Safer production deployments +- 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 / Tags +## Topics -`go` `golang` `ipv6` `mesh-network` `p2p` `overlay-network` -`encrypted-network`\ -`networking` `distributed-systems` `quic` `tcp` `websocket` `linux`\ -`freebsd` `openbsd` `macos` `windows` `openwrt`\ -`cli` `dashboard` `observability` `performance` `security` `sandbox`\ -`rust` `c` `systems-programming` `infrastructure` `devops` +`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` ------------------------------------------------------------------------