diff --git a/README.md b/README.md index a3ccacd..fe47d9f 100644 --- a/README.md +++ b/README.md @@ -1,190 +1,141 @@ # Kaya -[![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) +![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) + +------------------------------------------------------------------------ ## Introduction -Kaya is an early-stage implementation of a fully end-to-end encrypted IPv6 -network. It is lightweight, self-arranging, supported on multiple platforms and -allows pretty much any IPv6-capable application to communicate securely with -other Kaya nodes. Kaya does not require you to have IPv6 Internet -connectivity - it also works over IPv4. +Kaya is an enhanced 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. + +This repository extends the baseline behavior with significant +improvements in: + +- Observability\ +- Runtime control\ +- Performance\ +- Transport efficiency\ +- Operator UX + +------------------------------------------------------------------------ ## Supported Platforms -Kaya works on a number of platforms, including Linux, macOS, Ubiquiti -EdgeRouter, VyOS, Windows, FreeBSD, OpenBSD and OpenWrt. +- Linux\ +- macOS\ +- Windows\ +- FreeBSD / OpenBSD\ +- OpenWrt\ +- Ubiquiti EdgeRouter\ +- VyOS -Please see our [Installation](https://yggdrasil-network.github.io/installation.html) -page for more information. You may also find other platform-specific wrappers, scripts -or tools in the `contrib` folder. +------------------------------------------------------------------------ -## Building +# Building -If you want to build from source, as opposed to installing one of the pre-built -packages: - -1. Install [Go](https://golang.org) (requires Go 1.22 or later) -2. Clone this repository -2. Run `./build` - -Note that you can cross-compile for other platforms and architectures by -specifying the `GOOS` and `GOARCH` environment variables, e.g. `GOOS=windows -./build` or `GOOS=linux GOARCH=mipsle ./build`. - -## Running - -### Generate configuration - -To generate static configuration, either generate a HJSON file (human-friendly, -complete with comments): +Requires **Go 1.22 or later**. +``` bash +go build -o kaya ./cmd/yggdrasil +go build -o kayactl ./cmd/yggdrasilctl ``` + +Cross-compile example: + +``` bash +GOOS=windows GOARCH=amd64 go build -o kaya.exe ./cmd/yggdrasil +``` + +------------------------------------------------------------------------ + +# Running + +## Generate Configuration + +``` bash ./kaya -genconf > /path/to/kaya.conf ``` -... or generate a plain JSON file (which is easy to manipulate -programmatically): - -``` +``` bash ./kaya -genconf -json > /path/to/kaya.conf ``` -You will need to edit the `kaya.conf` file to add or remove peers, modify -other configuration such as listen addresses or multicast addresses, etc. +## Start Kaya -### Run Kaya - -To run with the generated static configuration: - -``` +``` bash ./kaya -useconffile /path/to/kaya.conf ``` -To run in auto-configuration mode (which will use sane defaults and random keys -at each startup, instead of using a static configuration file): - -``` +``` bash ./kaya -autoconf ``` -You will likely need to run Kaya as a privileged user or under `sudo`, -unless you have permission to create TUN/TAP adapters. On Linux this can be done -by giving the Kaya binary the `CAP_NET_ADMIN` capability. +Kaya requires permission to create TUN/TAP interfaces.\ +On Linux, run under `sudo` or grant `CAP_NET_ADMIN`. -## Documentation +------------------------------------------------------------------------ -Documentation is available [on our website](https://yggdrasil-network.github.io). +# Extended Features -- [Installing Kaya](https://yggdrasil-network.github.io/installation.html) -- [Configuring Kaya](https://yggdrasil-network.github.io/configuration.html) -- [Frequently asked questions](https://yggdrasil-network.github.io/faq.html) -- [Version changelog](CHANGELOG.md) +## Built-in Operator Dashboard -## Extended Features in This Repository +- Live telemetry (identity, routing, peers, flows, tree) +- Real-time bandwidth visualization +- Peer traffic control +- Optional authentication +- Public read-only mode (`--public-interface`) -This repository includes a substantial set of enhancements on top of the baseline Kaya behavior, focused on performance, operability, observability, and operator UX. +## 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: - - node/self identity and routing metadata, - - peer links and per-peer health, - - session/flow activity, - - path and tree information. -- **Peer control actions** from the UI (e.g. disconnect/traffic control via the daemon APIs). -- **Optional authentication** for the private dashboard listener. -- **Public read-only dashboard mode** (`--public-interface`) for safe external observability exposure. -- **Real-time bandwidth visualization** and rate rendering in human units (Mbit/s), including directional indicators. -- **Responsive, overflow-safe layout** so long URIs/IP addresses remain contained and readable. +- Improved peer listings +- Clear topology tree +- Integrated traffic control -### 2) Runtime Control and Safety Hardening +## Performance & Transport Improvements -The runtime now provides stronger operator controls for CPU/thread behavior and process hardening: +- Reduced timer churn +- Optimized peer snapshots +- Faster authorization lookups +- QUIC and TCP dialing improvements +- TLS correctness fixes -- `--threads` controls scheduler parallelism (`GOMAXPROCS`) explicitly. -- `--max-threads` provides an additional hard cap for runtime OS threads. -- `--sandbox` enables Linux hardening measures early in runtime startup: - - no-new-privileges, - - non-dumpable process mode, - - core-dump suppression. +------------------------------------------------------------------------ -These options are intended for predictable behavior on constrained systems and for hardened production deployments. +## Practical Outcome -### 3) Colorized, High-Signal Terminal Logging +- Better operator visibility\ +- Stronger runtime control\ +- Lower CPU and memory overhead\ +- Safer production deployments -Interactive stdout logs are rendered with contextual colorization to improve readability and triage speed: +------------------------------------------------------------------------ -- different color classes for errors, warnings, link lifecycle, addressing/interface messages, and sandbox messages, -- improved per-line rendering for TTY operation, -- better at-a-glance operator diagnostics during startup and runtime events. +## Topics / Tags -### 4) Admin API Extensions for Traffic Control +`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` -The admin control surface includes enhanced peer traffic operations: - -- **`setPeerTraffic` support** to toggle whether traffic is routed via specific peers, -- stricter boolean parsing/validation in control requests, -- integration with dashboard and CLI control workflows. - -### 5) `kayactl` UX and Topology Visibility Improvements - -CLI output and control ergonomics were expanded: - -- improved peer listing with a direct **Remote** endpoint/host view, -- significantly clearer tree/topology presentation with hierarchical formatting, -- tighter integration with peer traffic control operations. - -### 6) Core Performance Optimizations - -Multiple datapath-adjacent and control-path optimizations were added to reduce CPU and allocation pressure without changing protocol semantics: - -- periodic link average updates moved to persistent ticker-style processing (reduced timer churn), -- peer snapshot collection optimized with better preallocation and reduced repeated work, -- optimized inbound allowed-key authorization path using faster lookup strategy, -- reduced atomic overhead in hot accounting paths by skipping zero-byte updates, -- debug protocol response assembly/lifecycle improvements to reduce transient allocations and bound payload behavior, -- URI parsing and formatting optimizations in CLI/control surfaces. - -### 7) Transport and Dialing Efficiency Enhancements - -Connection setup paths were tuned for performance and reliability across transports: - -- better TCP source-interface handling with short-lived interface metadata caching, -- improved address selection and error behavior in dial suitability checks, -- WS/WSS transport setup refinements to reduce repetitive per-dial overhead, -- QUIC dialing/configuration improvements for throughput-oriented behavior and lower overhead in this usage profile, -- correctness fixes to ensure intended TLS configuration usage in QUIC dial paths. - -### 8) Process-Model and Platform Behavior Tightening - -Additional reliability and deployment refinements include: - -- stronger single-process behavior expectations in runtime paths, -- FreeBSD TUN setup behavior tightened to return direct ioctl failures instead of shelling out to external fallback tooling, -- clearer startup/runtime wiring for dashboard lifecycle and shutdown handling. - -### 9) Practical Outcome - -Taken together, these enhancements provide: - -- better **operator visibility** (dashboard + improved CLI), -- stronger **runtime control** (`--threads`, `--max-threads`, sandboxing), -- lower **operational overhead** in frequent control/network paths, -- improved **day-2 usability** for debugging, monitoring and peer management, -- preserved core functionality with a focus on safer and faster default operation. - -## Communities - -A number of IRC communities exist, including the `#kaya` IRC channel on [libera.chat](https://libera.chat) and various others on [Kaya-internal IRC networks](https://yggdrasil-network.github.io/services.html#irc). +------------------------------------------------------------------------ ## License -This code is released under the terms of the LGPLv3, but with an added exception -that was shamelessly taken from [godeb](https://github.com/niemeyer/godeb). -Under certain circumstances, this exception permits distribution of binaries -that are (statically or dynamically) linked with this code, without requiring -the distribution of Minimal Corresponding Source or Minimal Application Code. -For more details, see: [LICENSE](LICENSE). +LGPLv3 with linking exception. See LICENSE for details. diff --git a/repo/4fa5ff31-c9d5-4aa5-bea6-97b81f3daf78.png b/repo/4fa5ff31-c9d5-4aa5-bea6-97b81f3daf78.png new file mode 100644 index 0000000..0d652ee Binary files /dev/null and b/repo/4fa5ff31-c9d5-4aa5-bea6-97b81f3daf78.png differ