Update README.md
This commit is contained in:
parent
f5ad49facb
commit
b0684540e8
1 changed files with 158 additions and 52 deletions
210
README.md
210
README.md
|
|
@ -2,40 +2,51 @@
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
[
|
||||||
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
|
## Introduction
|
||||||
|
|
||||||
Kaya is an enhanced implementation of a fully end-to-end encrypted IPv6
|
Kaya is an early-stage implementation of a fully end-to-end encrypted
|
||||||
mesh network.
|
IPv6 mesh network.
|
||||||
|
|
||||||
It is lightweight, self-arranging, multi-platform, and allows any
|
It is lightweight, self-arranging, multi-platform, and allows any
|
||||||
IPv6-capable application to communicate securely with other Kaya nodes.
|
IPv6-capable application to communicate securely with other Kaya nodes.
|
||||||
Kaya does **not** require native IPv6 Internet connectivity --- it works
|
Kaya does **not** require native IPv6 Internet connectivity --- it works
|
||||||
over IPv4 as well.
|
over IPv4.
|
||||||
|
|
||||||
This repository extends the baseline behavior with significant
|
This repository extends the baseline implementation with substantial
|
||||||
improvements in:
|
enhancements focused on:
|
||||||
|
|
||||||
- Observability\
|
- Performance
|
||||||
- Runtime control\
|
- Operability
|
||||||
- Performance\
|
- Observability
|
||||||
- Transport efficiency\
|
- Runtime safety
|
||||||
- Operator UX
|
- Operator UX
|
||||||
|
|
||||||
|
The core protocol semantics are preserved while improving deployment,
|
||||||
|
diagnostics, and control behavior.
|
||||||
|
|
||||||
------------------------------------------------------------------------
|
------------------------------------------------------------------------
|
||||||
|
|
||||||
## Supported Platforms
|
## Supported Platforms
|
||||||
|
|
||||||
- Linux\
|
Kaya runs on:
|
||||||
- macOS\
|
|
||||||
- Windows\
|
- Linux
|
||||||
- FreeBSD / OpenBSD\
|
- macOS
|
||||||
- OpenWrt\
|
- Windows
|
||||||
- Ubiquiti EdgeRouter\
|
- FreeBSD
|
||||||
|
- OpenBSD
|
||||||
|
- OpenWrt
|
||||||
|
- Ubiquiti EdgeRouter
|
||||||
- VyOS
|
- VyOS
|
||||||
|
|
||||||
------------------------------------------------------------------------
|
------------------------------------------------------------------------
|
||||||
|
|
@ -44,12 +55,14 @@ improvements in:
|
||||||
|
|
||||||
Requires **Go 1.22 or later**.
|
Requires **Go 1.22 or later**.
|
||||||
|
|
||||||
|
Build the binaries directly:
|
||||||
|
|
||||||
``` bash
|
``` bash
|
||||||
go build -o kaya ./cmd/yggdrasil
|
go build -o kaya ./cmd/yggdrasil
|
||||||
go build -o kayactl ./cmd/yggdrasilctl
|
go build -o kayactl ./cmd/yggdrasilctl
|
||||||
```
|
```
|
||||||
|
|
||||||
Cross-compile example:
|
Cross-compiling example:
|
||||||
|
|
||||||
``` bash
|
``` bash
|
||||||
GOOS=windows GOARCH=amd64 go build -o kaya.exe ./cmd/yggdrasil
|
GOOS=windows GOARCH=amd64 go build -o kaya.exe ./cmd/yggdrasil
|
||||||
|
|
@ -61,78 +74,171 @@ GOOS=windows GOARCH=amd64 go build -o kaya.exe ./cmd/yggdrasil
|
||||||
|
|
||||||
## Generate Configuration
|
## Generate Configuration
|
||||||
|
|
||||||
|
HJSON:
|
||||||
|
|
||||||
``` bash
|
``` bash
|
||||||
./kaya -genconf > /path/to/kaya.conf
|
./kaya -genconf > /path/to/kaya.conf
|
||||||
```
|
```
|
||||||
|
|
||||||
|
JSON:
|
||||||
|
|
||||||
``` bash
|
``` bash
|
||||||
./kaya -genconf -json > /path/to/kaya.conf
|
./kaya -genconf -json > /path/to/kaya.conf
|
||||||
```
|
```
|
||||||
|
|
||||||
|
Edit the configuration file to add/remove peers, adjust listen
|
||||||
|
addresses, multicast settings, etc.
|
||||||
|
|
||||||
## Start Kaya
|
## Start Kaya
|
||||||
|
|
||||||
|
With configuration:
|
||||||
|
|
||||||
``` bash
|
``` bash
|
||||||
./kaya -useconffile /path/to/kaya.conf
|
./kaya -useconffile /path/to/kaya.conf
|
||||||
```
|
```
|
||||||
|
|
||||||
|
Auto-configuration mode:
|
||||||
|
|
||||||
``` bash
|
``` bash
|
||||||
./kaya -autoconf
|
./kaya -autoconf
|
||||||
```
|
```
|
||||||
|
|
||||||
Kaya requires permission to create TUN/TAP interfaces.\
|
Kaya requires permission to create TUN/TAP adapters. On Linux, run under
|
||||||
On Linux, run under `sudo` or grant `CAP_NET_ADMIN`.
|
`sudo` or grant the binary `CAP_NET_ADMIN`.
|
||||||
|
|
||||||
------------------------------------------------------------------------
|
------------------------------------------------------------------------
|
||||||
|
|
||||||
# Extended Features
|
# Extended Features in This Repository
|
||||||
|
|
||||||
## Built-in Operator Dashboard
|
This repository includes a substantial set of enhancements on top of
|
||||||
|
baseline behavior.
|
||||||
|
|
||||||
- Live telemetry (identity, routing, peers, flows, tree)
|
------------------------------------------------------------------------
|
||||||
- Real-time bandwidth visualization
|
|
||||||
- Peer traffic control
|
|
||||||
- Optional authentication
|
|
||||||
- Public read-only mode (`--public-interface`)
|
|
||||||
|
|
||||||
## Runtime Control & Hardening
|
## 1) Operator Dashboard (Built-in HTTP UI)
|
||||||
|
|
||||||
- `--threads`
|
A built-in web dashboard is available directly from the daemon to
|
||||||
- `--max-threads`
|
monitor and manage node state.
|
||||||
- `--sandbox` (no-new-privileges, non-dumpable, core dump suppression)
|
|
||||||
|
|
||||||
## 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
|
||||||
|
|
||||||
## Performance & Transport Improvements
|
Additional capabilities:
|
||||||
|
|
||||||
- Reduced timer churn
|
- Peer control actions (disconnect / traffic control via daemon APIs)
|
||||||
- Optimized peer snapshots
|
- Optional authentication for the private dashboard listener
|
||||||
- Faster authorization lookups
|
- Public read-only dashboard mode (`--public-interface`)
|
||||||
- QUIC and TCP dialing improvements
|
- Real-time bandwidth visualization (Mbit/s) with directional
|
||||||
- TLS correctness fixes
|
indicators
|
||||||
|
- Responsive, overflow-safe layout for long URIs and IPv6 addresses
|
||||||
|
|
||||||
|
------------------------------------------------------------------------
|
||||||
|
|
||||||
|
## 2) Runtime Control and Safety Hardening
|
||||||
|
|
||||||
|
Stronger operator controls for CPU behavior and process hardening:
|
||||||
|
|
||||||
|
- `--threads` explicitly controls scheduler parallelism (`GOMAXPROCS`)
|
||||||
|
- `--max-threads` provides a hard cap for OS threads
|
||||||
|
- `--sandbox` enables Linux hardening early in startup:
|
||||||
|
- no-new-privileges
|
||||||
|
- non-dumpable process mode
|
||||||
|
- core-dump suppression
|
||||||
|
|
||||||
|
These options provide predictable behavior on constrained systems and
|
||||||
|
hardened production deployments.
|
||||||
|
|
||||||
|
------------------------------------------------------------------------
|
||||||
|
|
||||||
|
## 3) Colorized, High-Signal Terminal Logging
|
||||||
|
|
||||||
|
Interactive stdout logs are rendered with contextual colorization:
|
||||||
|
|
||||||
|
- Distinct color classes for errors, warnings, link lifecycle,
|
||||||
|
interface messages, and sandbox events
|
||||||
|
- Improved per-line TTY rendering
|
||||||
|
- Faster at-a-glance diagnostics during startup and runtime
|
||||||
|
|
||||||
|
------------------------------------------------------------------------
|
||||||
|
|
||||||
|
## 4) Admin API Extensions for Traffic Control
|
||||||
|
|
||||||
|
Enhanced peer traffic operations:
|
||||||
|
|
||||||
|
- `setPeerTraffic` support to toggle routing via specific peers
|
||||||
|
- Stricter boolean parsing and validation
|
||||||
|
- Integrated dashboard and CLI workflows
|
||||||
|
|
||||||
|
------------------------------------------------------------------------
|
||||||
|
|
||||||
|
## 5) kayactl UX and Topology Visibility Improvements
|
||||||
|
|
||||||
|
CLI enhancements include:
|
||||||
|
|
||||||
|
- Improved peer listing with direct remote endpoint view
|
||||||
|
- Clearer hierarchical tree/topology formatting
|
||||||
|
- Tight integration with peer traffic control operations
|
||||||
|
|
||||||
|
------------------------------------------------------------------------
|
||||||
|
|
||||||
|
## 6) Core Performance Optimizations
|
||||||
|
|
||||||
|
Datapath and control-path improvements without changing protocol
|
||||||
|
semantics:
|
||||||
|
|
||||||
|
- Persistent ticker-based link average updates (reduced timer churn)
|
||||||
|
- Optimized peer snapshot collection
|
||||||
|
- Faster inbound allowed-key authorization lookup
|
||||||
|
- Reduced atomic overhead in hot accounting paths
|
||||||
|
- Debug protocol response lifecycle optimizations
|
||||||
|
- URI parsing and CLI/control surface improvements
|
||||||
|
|
||||||
|
------------------------------------------------------------------------
|
||||||
|
|
||||||
|
## 7) Transport and Dialing Efficiency Enhancements
|
||||||
|
|
||||||
|
Connection setup improvements:
|
||||||
|
|
||||||
|
- Improved TCP source-interface handling with short-lived metadata
|
||||||
|
caching
|
||||||
|
- Better address selection and dial suitability behavior
|
||||||
|
- Reduced per-dial overhead in WS/WSS transports
|
||||||
|
- QUIC dialing and throughput optimizations
|
||||||
|
- TLS configuration correctness fixes in QUIC paths
|
||||||
|
|
||||||
|
------------------------------------------------------------------------
|
||||||
|
|
||||||
|
## 8) Process-Model and Platform Tightening
|
||||||
|
|
||||||
|
Reliability refinements:
|
||||||
|
|
||||||
|
- Stronger single-process behavior expectations
|
||||||
|
- FreeBSD TUN setup returns direct ioctl failures (no shell fallback)
|
||||||
|
- Clearer dashboard lifecycle and shutdown handling
|
||||||
|
|
||||||
------------------------------------------------------------------------
|
------------------------------------------------------------------------
|
||||||
|
|
||||||
## Practical Outcome
|
## Practical Outcome
|
||||||
|
|
||||||
- Better operator visibility\
|
- Better operator visibility (dashboard + CLI)
|
||||||
- Stronger runtime control\
|
- Stronger runtime control (`--threads`, `--max-threads`, sandboxing)
|
||||||
- Lower CPU and memory overhead\
|
- Lower operational overhead
|
||||||
- Safer production deployments
|
- Improved day-2 debugging and peer management
|
||||||
|
- Safer and faster default operation
|
||||||
|
|
||||||
------------------------------------------------------------------------
|
------------------------------------------------------------------------
|
||||||
|
|
||||||
## Topics / Tags
|
## Topics
|
||||||
|
|
||||||
`go` `golang` `ipv6` `mesh-network` `p2p` `overlay-network`
|
`go` `golang` `ipv6` `mesh-network` `p2p` `overlay-network`\
|
||||||
`encrypted-network`\
|
`encrypted-network` `distributed-systems` `quic` `tcp` `websocket`\
|
||||||
`networking` `distributed-systems` `quic` `tcp` `websocket` `linux`\
|
`linux` `freebsd` `openbsd` `macos` `windows` `openwrt`\
|
||||||
`freebsd` `openbsd` `macos` `windows` `openwrt`\
|
`cli` `dashboard` `observability` `performance` `security`\
|
||||||
`cli` `dashboard` `observability` `performance` `security` `sandbox`\
|
`sandbox` `infrastructure` `networking` `systems-programming`
|
||||||
`rust` `c` `systems-programming` `infrastructure` `devops`
|
|
||||||
|
|
||||||
------------------------------------------------------------------------
|
------------------------------------------------------------------------
|
||||||
|
|
||||||
|
|
|
||||||
Loading…
Add table
Add a link
Reference in a new issue