push

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
+Kaya is an enhanced implementation of a fully end-to-end encrypted IPv6
-network. It is lightweight, self-arranging, supported on multiple platforms and
+mesh network.
-allows pretty much any IPv6-capable application to communicate securely with
+
-other Kaya nodes. Kaya does not require you to have IPv6 Internet
+It is lightweight, self-arranging, multi-platform, and allows any
-connectivity - it also works over IPv4.
+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
+-   Linux\
-EdgeRouter, VyOS, Windows, FreeBSD, OpenBSD and OpenWrt.
+-   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
+Requires **Go 1.22 or later**.
-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):
 
+``` 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
+``` bash
-programmatically):
-
-```
 ./kaya -genconf -json > /path/to/kaya.conf
 ```
 
-You will need to edit the `kaya.conf` file to add or remove peers, modify
+## Start Kaya
-other configuration such as listen addresses or multicast addresses, etc.
 
-### Run Kaya
+``` bash
-
-To run with the generated static configuration:
-
-```
 ./kaya -useconffile /path/to/kaya.conf
 ```
 
-To run in auto-configuration mode (which will use sane defaults and random keys
+``` bash
-at each startup, instead of using a static configuration file):
-
-```
 ./kaya -autoconf
 ```
 
-You will likely need to run Kaya as a privileged user or under `sudo`,
+Kaya requires permission to create TUN/TAP interfaces.\
-unless you have permission to create TUN/TAP adapters. On Linux this can be done
+On Linux, run under `sudo` or grant `CAP_NET_ADMIN`.
-by giving the Kaya binary the `CAP_NET_ADMIN` capability.
 
-## Documentation
+------------------------------------------------------------------------
 
-Documentation is available [on our website](https://yggdrasil-network.github.io).
+# Extended Features
 
-- [Installing Kaya](https://yggdrasil-network.github.io/installation.html)
+## Built-in Operator Dashboard
-- [Configuring Kaya](https://yggdrasil-network.github.io/configuration.html)
-- [Frequently asked questions](https://yggdrasil-network.github.io/faq.html)
-- [Version changelog](CHANGELOG.md)
 
-## 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:
+-   Improved peer listings
-  - node/self identity and routing metadata,
+-   Clear topology tree
-  - peer links and per-peer health,
+-   Integrated traffic control
-  - 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.
 
-### 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,
+## Topics / Tags
-- improved per-line rendering for TTY operation,
-- better at-a-glance operator diagnostics during startup and runtime events.
 
-### 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
+LGPLv3 with linking exception. See LICENSE for details.
-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).