example.config

# ============================================================================
# yip / yipd example configuration
# ============================================================================
#
# This is a COMPLETE, ANNOTATED reference config for the `yipd` daemon.
# Run with:   yipd /path/to/your.config
#
# Format: one `key=value` per line. Blank lines and lines starting with `#`
# are ignored; whitespace around the key and value is trimmed. Unknown keys
# are silently ignored (forward-compatibility). `[peer]` starts a peer block
# (see "Multi-peer" below).
#
# (A first-class TOML config format is a planned milestone; today yipd parses
#  this line-based format. See docs/configuration.md.)
#
# Copy this file, delete the sections you don't need, and fill in real keys.
# Generate a keypair with:   yipd --genkey
# Print a pubkey's mesh address with:   yipd --addr <public-key-hex>
# ============================================================================


# ---------------------------------------------------------------------------
# 1. CORE (required for every node)
# ---------------------------------------------------------------------------

# This node's X25519 keypair (64 hex chars = 32 bytes each). Generate with
# `yipd --genkey`, which prints `private=...` and `public=...`.
# Keep local_private SECRET.
local_private=986590d0751560e38dff71028e032c0182c6de4c327b06eda5e0a476efd13eba
local_public=c0b221a5986e7d279d9c39040a1db1721ee57f5febb2f6be4a661aa1076e9e8a

# UDP/TCP address to bind the tunnel socket to (IP:port). OPTIONAL: absent, or
# an IP with no port (e.g. `listen=0.0.0.0`), auto-selects port 443 — the
# single least-suspicious port, and the same port every transport uses (443/TCP
# for transport=tls, 443/UDP for transport=quic/raw) so a DPI engine can't
# port-match yip. Binding <1024 needs a capability; if 443 is denied (e.g.
# running unprivileged) yipd falls back to 8443 with a warning. Grant the
# capability instead of running as root:
#   setcap cap_net_bind_service+ep /path/to/yipd
# An explicit `listen=IP:port` is always honored exactly (no 8443 fallback),
# but yipd warns at config load if the port is a known DPI-fingerprinted VPN
# default (51820 WireGuard, 1194 OpenVPN, 500/4500 IPsec, 1701 L2TP, 1723
# PPTP, 655 tinc) — those port-match regardless of payload.
listen=0.0.0.0

# TUN/TAP device name to create for the tunnel.
device=yip0

# Data plane: `tun` = L3/IP tunnel (default), `tap` = L2/Ethernet bridging.
device_kind=tun

# Multi-core sharding (Way A): number of independent worker threads / physical cores
# to shard the data plane across. Default is 1 (single-core event loop). Setting
# shards > 1 allocates an IFF_MULTI_QUEUE TUN device, binds SO_REUSEPORT UDP sockets,
# and pins each worker to a physical core with lock-free inter-shard routing.
# shards=1


# ---------------------------------------------------------------------------
# 2. MULTI-PEER (static peer list)
# ---------------------------------------------------------------------------
# List each peer in its own `[peer]` block. `public_key` is required;
# `endpoint` (IP:port) is OPTIONAL — a peer with no endpoint is reachable only
# via a rendezvous server / relay (see section 4). Repeat the block per peer.

[peer]
public_key=0a6367fdcefe1e96917323dc6880f048d7a252e8626a41488a95bb79f768bf87
endpoint=203.0.113.10:443

# [peer]
# public_key=74220468afede17ffb4067f86d7f1bf3455f7b403d119bdf82600516506ff6f5
# # no endpoint => discovered/reached via rendezvous or mesh

# --- Legacy single-peer form (still supported; used only if NO [peer] blocks
# --- are present). Prefer [peer] blocks above.
# peer_public=0a6367fdcefe1e96917323dc6880f048d7a252e8626a41488a95bb79f768bf87
# peer_endpoint=203.0.113.10:443


# ---------------------------------------------------------------------------
# 3. RENDEZVOUS + NAT TRAVERSAL (optional)
# ---------------------------------------------------------------------------
# Address of a `yip-rendezvous` server. With this set, peers are brought up
# lazily along a Direct -> UDP-hole-punch -> Relay escalation path, so peers
# behind NAT (a [peer] with no endpoint) can still connect.
# rendezvous=198.51.100.5:443

# TLS relay-dial (anti-DPI milestone 3c.4): straight-to-relay over a
# persistent browser-parrot TLS connection to a `yip-rendezvous --listen-tcp`
# front, no Direct/UDP-punch attempt. Requires obf_psk (below). See
# docs/configuration.md's "TLS relay-dial client" section.
# rendezvous=tls://relay.example.com:443

# REALITY relay-dial (REALITY.4a): dial the relay with a Chrome-faithful
# REALITY ClientHello. Requires obf_psk. pbk = relay's REALITY public key (64
# hex), sid = auth short-id (16 hex), sni = the borrowed domain to present.
# The outer TLS is zero-cert-auth (the camouflage); the tunnel is secured by
# the inner peer handshake. verify=on|off (REALITY.4b, default on if omitted)
# is client-local relay verification — pins the relay's leaf key to a
# shared-secret-derived cert and fails closed on mismatch; only set
# verify=off as a deliberate downgrade (see docs/configuration.md's "REALITY
# relay-dial client" section).
# rendezvous=reality://relay.example.com:443?pbk=<64hex>&sid=<16hex>&sni=www.microsoft.com&verify=on


# ---------------------------------------------------------------------------
# 4. MESH / DECENTRALIZED DISCOVERY (optional — the "private membership mesh")
# ---------------------------------------------------------------------------
# A node is a valid mesh member iff it holds a CA-signed cert. With ALL FIVE of
# the keys below set, this node runs in mesh mode: it may carry NO [peer]
# blocks at all and discover peers purely via the signed root set + gossip.
# (See docs/user-guide.md "Mesh mode" for the offline `yip-ca` workflow.)
#
# ca_public   — trusted CA Ed25519 public key (64 hex). REPEATABLE (one line
#               per CA) to trust multiple / rotate CAs. For a threshold CA,
#               set this to the group verifying key output by `dealer-gen`.
# cert        — path to a file holding this node's CA-signed cert (hex, from
#               `yip-ca sign-cert` or `yip-ca enroll`).
# roots       — path to a file holding the CA-signed root set (hex, from
#               `yip-ca sign-roots`). Verified against ca_public at load time.
# member_sign_private — this node's Ed25519 record-signing private key (64 hex;
#               its public half is bound into the cert). SECRET.
# network_id  — 16-byte mesh network id (32 hex chars — note: HALF the length
#               of the other hex keys).
#
# threshold_ca_server — (Optional) IP:port of an online yip-ca threshold coordinator.
#               When configured, yipd automatically monitors certificate validity
#               and executes zero-touch background renewal when >= 70% of TTL has
#               elapsed. Can also be triggered via `yipd cert renew`. Alias: ca_server.
#
# ca_public=8a03a4cf43c2907041efb394c0effabad5bdb4cbbc35d17c924c0b6cbfa8ba75
# cert=/etc/yip/this-node.cert
# roots=/etc/yip/network.roots
# member_sign_private=c22239d00522843313aa03a662e8f0cb6abb7889f8f103510ebb5dee0e924857
# network_id=f11a8e0df8fa6352eeb62192de7ece47
# threshold_ca_server=198.51.100.10:4443


# ---------------------------------------------------------------------------
# 5. ANTI-DPI OBFUSCATION & TRAFFIC DEFENSE (optional, opt-in)
# ---------------------------------------------------------------------------
# A network-wide shared secret (64 hex = 32 bytes). When set, every datagram is
# wrapped so the wire looks like uniform-random UDP — no fixed bytes, sizes, or
# type discriminators. It is a LAYER over the Noise crypto: a compromised
# obf_psk makes traffic fingerprintable but STILL not decryptable.
#
# ALL participating nodes (and the rendezvous server, via `--obf-psk`) must
# share the EXACT same value; a mismatch means peers can't connect. Absent =>
# byte-identical to the non-obfuscated wire format.
#
# obf_psk=f109327c070ae10446469f13f9f78184121c261962a83e344de5fda5c7f3e2d6

# Traffic analysis defense (DAITA - Defending Against Intrusion with Traffic Analysis).
# Quantizes datagram lengths into discrete bucket sizes, injects stochastic cover traffic bursts
# during idle intervals, and applies micro-jitter delay to egress packets.
# Presets:
#   off        - No bucketing, no cover traffic, 0ms jitter (default).
#   balanced   - Buckets [256, 512, 1024, 1420], cover interval 500ms, burst max 2, jitter max 2ms.
#   paranoid   - Buckets [512, 1420], cover interval 150ms, burst max 4, jitter max 4ms.
#
# Mutually exclusive with transport=quic and transport=tls.
# traffic_defense=balanced

# Granular traffic defense overrides (optional; can override preset defaults):
# defense_buckets: Comma-separated list of ascending packet byte sizes (64..1500).
# defense_buckets=256,512,1024,1420
#
# defense_cover_interval_ms: Interval in milliseconds between cover bursts during idle periods.
# defense_cover_interval_ms=500
#
# defense_cover_burst_max: Maximum number of decoy datagrams emitted per burst (1..8).
# defense_cover_burst_max=2
#
# defense_jitter_max_ms: Maximum bounded random egress delay in milliseconds (0..10).
# defense_jitter_max_ms=2


# ---------------------------------------------------------------------------
# 6. TRANSPORT MODE (optional)
# ---------------------------------------------------------------------------
# By default the inner yip protocol runs directly over UDP (transport=raw). Two
# optional MIMICRY transports carry the UNCHANGED inner protocol inside a real,
# standard-looking wire protocol so DPI classifies it as something innocuous.
# Both dial the CONFIGURED peer endpoint and are MUTUALLY EXCLUSIVE with obf_psk
# (the mimicry layer is itself the obfuscation).
#
#   transport=raw    (default) inner protocol directly over UDP — lowest
#                    latency, the FEC/loss-recovery path. Use unless blocked.
#   transport=quic   inner protocol inside a real QUIC connection; classifies
#                    as QUIC/HTTP-3. For networks that fingerprint raw UDP.
#   transport=tls    inner protocol inside a real TLS 1.3 connection over
#                    TCP/443 with a browser-parrot ClientHello; classifies as
#                    browser HTTPS. OPT-IN LAST RESORT for UDP-blocked networks:
#                    TCP head-of-line blocking, no FEC benefit — trades yip's
#                    latency identity for reachability. Outer TLS is zero-auth
#                    (defeats classification, not an active probe).
#
# tls_sni sets the SNI + self-signed cert name for the tls costume
# (default www.apple.com; only meaningful when transport=tls).
#
# transport=tls
# tls_sni=www.apple.com


# ---------------------------------------------------------------------------
# 7. CONTROL SOCKET (optional)
# ---------------------------------------------------------------------------
# Path to UNIX domain control socket for headless inspection and dynamic peer
# management via `yipd ctl` / `yip-ctl`. When running under systemd or OpenRC,
# this is typically placed in the runtime directory (/run/yipd/yip.sock).
# Default: /run/yipd/yip.sock
#
# control_socket=/run/yipd/yip.sock