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=0000000000000000000000000000000000000000000000000000000000000001
local_public=0000000000000000000000000000000000000000000000000000000000000002

# 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=00000000000000000000000000000000000000000000000000000000000000bb
endpoint=203.0.113.10:443

# [peer]
# public_key=00000000000000000000000000000000000000000000000000000000000000cc
# # 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=00000000000000000000000000000000000000000000000000000000000000bb
# 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:51821

# 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.
# cert        — path to a file holding this node's CA-signed cert (hex, from
#               `yip-ca sign-cert`).
# 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).
#
# ca_public=<64hex CA pubkey>
# cert=/etc/yip/this-node.cert
# roots=/etc/yip/network.roots
# member_sign_private=<64hex Ed25519 signing key>
# network_id=00112233445566778899aabbccddeeff


# ---------------------------------------------------------------------------
# 5. ANTI-DPI OBFUSCATION (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=00112233445566778899aabbccddeeff00112233445566778899aabbccddeeff


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