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 @@
|
|||
|
||||
|
||||
|
||||
[](https://github.com/yggdrasil-network/yggdrasil-go/actions/workflows/ci.yml)
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
------------------------------------------------------------------------
|
||||
|
||||
## Introduction
|
||||
|
||||
Kaya is an enhanced implementation of a fully end-to-end encrypted IPv6
|
||||
mesh network.
|
||||
Kaya is an early-stage 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.
|
||||
over IPv4.
|
||||
|
||||
This repository extends the baseline behavior with significant
|
||||
improvements in:
|
||||
This repository extends the baseline implementation with substantial
|
||||
enhancements focused on:
|
||||
|
||||
- Observability\
|
||||
- Runtime control\
|
||||
- Performance\
|
||||
- Transport efficiency\
|
||||
- Performance
|
||||
- Operability
|
||||
- Observability
|
||||
- Runtime safety
|
||||
- Operator UX
|
||||
|
||||
The core protocol semantics are preserved while improving deployment,
|
||||
diagnostics, and control behavior.
|
||||
|
||||
------------------------------------------------------------------------
|
||||
|
||||
## Supported Platforms
|
||||
|
||||
- Linux\
|
||||
- macOS\
|
||||
- Windows\
|
||||
- FreeBSD / OpenBSD\
|
||||
- OpenWrt\
|
||||
- Ubiquiti EdgeRouter\
|
||||
Kaya runs on:
|
||||
|
||||
- Linux
|
||||
- macOS
|
||||
- Windows
|
||||
- FreeBSD
|
||||
- OpenBSD
|
||||
- OpenWrt
|
||||
- Ubiquiti EdgeRouter
|
||||
- VyOS
|
||||
|
||||
------------------------------------------------------------------------
|
||||
|
|
@ -44,12 +55,14 @@ improvements in:
|
|||
|
||||
Requires **Go 1.22 or later**.
|
||||
|
||||
Build the binaries directly:
|
||||
|
||||
``` bash
|
||||
go build -o kaya ./cmd/yggdrasil
|
||||
go build -o kayactl ./cmd/yggdrasilctl
|
||||
```
|
||||
|
||||
Cross-compile example:
|
||||
Cross-compiling example:
|
||||
|
||||
``` bash
|
||||
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
|
||||
|
||||
HJSON:
|
||||
|
||||
``` bash
|
||||
./kaya -genconf > /path/to/kaya.conf
|
||||
```
|
||||
|
||||
JSON:
|
||||
|
||||
``` bash
|
||||
./kaya -genconf -json > /path/to/kaya.conf
|
||||
```
|
||||
|
||||
Edit the configuration file to add/remove peers, adjust listen
|
||||
addresses, multicast settings, etc.
|
||||
|
||||
## Start Kaya
|
||||
|
||||
With configuration:
|
||||
|
||||
``` bash
|
||||
./kaya -useconffile /path/to/kaya.conf
|
||||
```
|
||||
|
||||
Auto-configuration mode:
|
||||
|
||||
``` bash
|
||||
./kaya -autoconf
|
||||
```
|
||||
|
||||
Kaya requires permission to create TUN/TAP interfaces.\
|
||||
On Linux, run under `sudo` or grant `CAP_NET_ADMIN`.
|
||||
Kaya requires permission to create TUN/TAP adapters. On Linux, run under
|
||||
`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`
|
||||
- `--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
|
||||
- Clear topology tree
|
||||
- Integrated traffic control
|
||||
- node/self identity and routing metadata
|
||||
- peer links and per-peer health
|
||||
- session/flow activity
|
||||
- path and tree information
|
||||
|
||||
## Performance & Transport Improvements
|
||||
Additional capabilities:
|
||||
|
||||
- Reduced timer churn
|
||||
- Optimized peer snapshots
|
||||
- Faster authorization lookups
|
||||
- QUIC and TCP dialing improvements
|
||||
- TLS correctness fixes
|
||||
- Peer control actions (disconnect / traffic control via daemon APIs)
|
||||
- Optional authentication for the private dashboard listener
|
||||
- Public read-only dashboard mode (`--public-interface`)
|
||||
- Real-time bandwidth visualization (Mbit/s) with directional
|
||||
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
|
||||
|
||||
- Better operator visibility\
|
||||
- Stronger runtime control\
|
||||
- Lower CPU and memory overhead\
|
||||
- Safer production deployments
|
||||
- Better operator visibility (dashboard + CLI)
|
||||
- Stronger runtime control (`--threads`, `--max-threads`, sandboxing)
|
||||
- Lower operational overhead
|
||||
- Improved day-2 debugging and peer management
|
||||
- Safer and faster default operation
|
||||
|
||||
------------------------------------------------------------------------
|
||||
|
||||
## Topics / Tags
|
||||
## Topics
|
||||
|
||||
`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`
|
||||
`go` `golang` `ipv6` `mesh-network` `p2p` `overlay-network`\
|
||||
`encrypted-network` `distributed-systems` `quic` `tcp` `websocket`\
|
||||
`linux` `freebsd` `openbsd` `macos` `windows` `openwrt`\
|
||||
`cli` `dashboard` `observability` `performance` `security`\
|
||||
`sandbox` `infrastructure` `networking` `systems-programming`
|
||||
|
||||
------------------------------------------------------------------------
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue