190 lines
7.9 KiB
Markdown
190 lines
7.9 KiB
Markdown
# Kaya
|
|
|
|
[](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.
|
|
|
|
## Supported Platforms
|
|
|
|
Kaya works on a number of platforms, including Linux, macOS, Ubiquiti
|
|
EdgeRouter, VyOS, Windows, FreeBSD, OpenBSD and OpenWrt.
|
|
|
|
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
|
|
|
|
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):
|
|
|
|
```
|
|
./kaya -genconf > /path/to/kaya.conf
|
|
```
|
|
|
|
... or generate a plain JSON file (which is easy to manipulate
|
|
programmatically):
|
|
|
|
```
|
|
./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.
|
|
|
|
### Run Kaya
|
|
|
|
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
|
|
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`,
|
|
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.
|
|
|
|
## Documentation
|
|
|
|
Documentation is available [on our website](https://yggdrasil-network.github.io).
|
|
|
|
- [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)
|
|
|
|
## Extended Features in This Repository
|
|
|
|
This repository includes a substantial set of enhancements on top of the baseline Kaya behavior, focused on performance, operability, observability, and operator UX.
|
|
|
|
### 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.
|
|
- **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
|
|
|
|
The runtime now provides stronger operator controls for CPU/thread behavior and process hardening:
|
|
|
|
- `--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.
|
|
|
|
### 3) Colorized, High-Signal Terminal Logging
|
|
|
|
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.
|
|
|
|
### 4) Admin API Extensions for Traffic Control
|
|
|
|
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).
|