Documentation
¶
Overview ¶
Package nebula is the public entry point to this module's Nebula implementation: a mesh overlay in which every host is a peer, authenticated by a certificate its CA issued, and reachable either directly or through a lighthouse.
Like every protocol here, Dial installs no addresses, routes or DNS. It returns the negotiated client.Result and the caller applies it — the veepin command hands it to dataplane's router, and the NetworkManager plugin hands it to NM.
Importing this package registers "nebula" with the client registry, so a caller that dials by name only needs the blank import:
import _ "github.com/xen0bit/veepin/nebula" sess, res, err := client.Dial(ctx, "nebula", opts)
The protocol internals (the certificate format, the Noise handshake, the data path and the lighthouse protocol) live in internal/nebula; this package is the supported surface.
A different shape from the other protocols ¶
Nebula is the first mesh protocol in this tree, and it does not divide into a client and a server. Dial and NewServer both run the same engine; they differ only in whether the host answers lighthouse queries and whether it is expected to stay up. A host's address is not assigned by a peer — it is written into its certificate, so Result.AssignedIP is read from the certificate rather than negotiated.
Scope ¶
Version 1 certificates (protobuf, IPv4 overlay) and Curve25519 only. Current nebula still issues and accepts version 1; version 2 adds ASN.1 encoding and IPv6, and is a self-contained follow-up.
Not implemented, deliberately rather than partially: the firewall/ACL engine (this build permits any traffic a certificate's addresses allow), relays (forwarding through a third host when hole punching fails), and multi-lighthouse consensus. Each surfaces as an absent feature, not as a silent misbehaviour: without the firewall a mesh is more permissive than nebula's default, which is stated here so it is not mistaken for parity.
Index ¶
Constants ¶
const ( OptCA = "ca" // path to the CA certificate bundle (PEM) OptCert = "cert" // path to this host's certificate (PEM) OptKey = "key" // path to this host's X25519 private key (PEM) OptListen = "listen" // local UDP address to bind, e.g. "0.0.0.0:4242" OptStaticHosts = "static-hosts" // "overlay=underlay[,underlay...];..." pairs OptLighthouses = "lighthouses" // comma-separated overlay addresses OptAmLighthouse = "am-lighthouse" // "true" to answer lighthouse queries OptCipher = "cipher" // "aes" (default) or "chachapoly" OptTUN = "tun" // TUN interface name OptMTU = "mtu" // inner MTU )
Option keys accepted by client.Dial(ctx, "nebula", opts).
Variables ¶
This section is empty.
Functions ¶
func ParseStaticHosts ¶
ParseStaticHosts parses the static host map, in the form
10.42.0.1=192.0.2.10:4242,192.0.2.11:4242;10.42.0.2=198.51.100.4:4242
Several underlay addresses may be given for one host: a handshake probes all of them, which is how a peer with both a public address and a LAN address is reached by whichever works.
Types ¶
type Config ¶
type Config struct {
// CAPath is the PEM bundle of trusted certificate authorities.
CAPath string
// CertPath and KeyPath are this host's identity.
CertPath string
KeyPath string
// Listen is the local UDP address. Empty binds all addresses on the
// default port.
Listen string
// StaticHosts maps an overlay address to underlay addresses. A mesh with no
// lighthouse needs one entry per peer; with a lighthouse, only the
// lighthouse itself needs one.
StaticHosts map[netip.Addr][]netip.AddrPort
// Lighthouses are the overlay addresses to query and report to.
Lighthouses []netip.Addr
// AmLighthouse makes this host answer queries about where others are.
AmLighthouse bool
// Cipher is "aes" (default) or "chachapoly". It must match the mesh.
Cipher string
// TUNName is the interface to open. Empty picks the next free one.
TUNName string
// MTU is the inner interface MTU. Zero uses defaultMTU.
MTU int
// Logger receives operational messages. Nil discards them.
Logger *log.Logger
}
Config is the parsed form of the options above.
type Server ¶
type Server struct {
// contains filtered or unexported fields
}
Server is a running lighthouse.
func NewServer ¶
func NewServer(cfg ServerConfig) (*Server, error)
NewServer prepares a lighthouse. Nothing binds until ListenAndServe.
func (*Server) Gateway ¶
Gateway is the lighthouse's own overlay address.
A mesh has no gateway: peers reach each other directly, and nothing routes through the lighthouse. This reports its own address so callers that anchor an interface on it get something coherent.
func (*Server) ListenAndServe ¶
ListenAndServe runs the lighthouse until it is closed.
type Session ¶
type Session struct {
// contains filtered or unexported fields
}
Session is a running nebula host.
func Dial ¶
Dial starts a nebula host and returns it as a client session.
Unlike the other protocols here there is no server to connect to: the host starts, and tunnels form as traffic and discovery require. Dial returns as soon as the host is running, because in a mesh there is no single peer whose reachability would make a useful readiness signal.
Source Files