racks/kaya-go
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

push

Browse source
This commit is contained in:
Racks 2026-03-01 17:29:18 +01:00
parent 1d167420c3
commit f5ad49facb
2 changed files with 95 additions and 144 deletions
Download patch file Download diff file Expand all files Collapse all files

239
README.md
View file

@ -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.