# 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)

## 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).