Documentation
¶
Index ¶
Constants ¶
const ( ReasonNoName = "no-name" // no SNI / no Host ReasonIPName = "ip-name" // the name is an IP address (literal, decimal, hex, bracketed) ReasonBadName = "bad-name" // not a host name ReasonECH = "ech" // the ClientHello hides its name ReasonDenied = "tunnel" // a known tunnel service ReasonResolve = "resolve" // the name does not resolve to a public address ReasonHostRate = "host-rate" // too many new connections of a lab to one name ReasonHostGatewayRate = "host-gateway-rate" // too many new connections of all the labs of a gateway to one name ReasonLabRate = "lab-rate" // the lab is at its caps ReasonNotTLS = "not-tls" ReasonNotHTTP = "not-http" ReasonUnknown = "unknown-lab" )
Why a connection is refused. The words are the labels of the summaries and of the log.
Variables ¶
var DefaultTunnelSuffixes = []string{
"ngrok.io", "ngrok.com", "ngrok.app", "ngrok-free.app", "ngrok-free.dev", "ngrok.dev", "ngrok.pizza", "ngrok.pro",
"trycloudflare.com", "loca.lt", "localtunnel.me", "serveo.net", "localhost.run", "lhr.life", "pinggy.io", "pinggy.link", "pagekite.me",
"tailscale.com", "tailscale.io", "ts.net", "zerotier.com",
}
DefaultTunnelSuffixes are the names of services whose purpose is to carry a lab's traffic somewhere else (a reverse tunnel out, a VPN control plane). A name equal to an entry or under it is refused. The list is configurable and small on purpose: the web is open.
var ErrNoPublicAddress = errors.New("the name has no public IPv4 address")
ErrNoPublicAddress is the error of a name with no public IPv4 address.
Functions ¶
func NormalizeName ¶
NormalizeName lower-cases a name, drops the trailing dot and any port, and says whether it may be looked up: not an IP address in any notation, not empty, made of host-name labels. The reason is one of the Reason* words.
Types ¶
type CapHit ¶
type CapHit struct {
Lab string `json:"lab"`
Reason string `json:"reason"`
Hits int64 `json:"hits"`
}
CapHit counts how often a lab sat at one of its caps in a minute (reason: lab-rate, dns-rate, ...).
type ClientHello ¶
type ClientHello struct {
// ServerName is the host_name of the server_name extension, lower case, "" when there is none.
ServerName string
// ECH is true when the client sent an encrypted_client_hello extension.
ECH bool
// Raw are the bytes read from the connection, to be sent on to the server unchanged.
Raw []byte
}
ClientHello is what was read from the first flight.
func ReadClientHello ¶
func ReadClientHello(r io.Reader) (*ClientHello, error)
ReadClientHello reads TLS records from r until one handshake message (the ClientHello) is complete, and parses it. The bytes it consumed are in Raw. A flight that is not a ClientHello, or is larger than 64 kB, is an error.
type Collector ¶
type Collector struct {
Gateway string
Keep int
Now func() time.Time
// contains filtered or unexported fields
}
Collector keeps per-minute summaries and serves the finished ones. It keeps the last Keep minutes (default 60, an hour) and nothing else: the operator pulls them every minute and keeps the log.
func NewCollector ¶
func (*Collector) End ¶
End adds the bytes of a finished connection (up: from the lab, down: to the lab).
func (*Collector) Handler ¶
Handler serves GET /summaries?since=<RFC 3339>. It is plain HTTP on the pod network: the network policy of the group lets the operator in, and the lab side of the pod answers nothing (the INPUT policy).
type DNS ¶
type DNS struct {
Labs *LabMap
Resolver *Resolver
Deny *Denylist
Stats *Collector
Log logr.Logger
// QueriesPerSecond is the rate cap of a lab (default 50; negative = no cap).
QueriesPerSecond float64
// AnswerTTL is the TTL of the answers (default 30 s).
AnswerTTL uint32
// contains filtered or unexported fields
}
DNS is the small resolver of the gateway. The gateway redirects every packet to port 53 of a lab, to whatever address, to it: a lab that names a DNS server of its own talks to this one all the same. It answers A queries with the real, public IPv4 addresses of the name (looked up through the gateway's own upstream servers), and nothing else: AAAA, HTTPS and SVCB queries get an empty answer (no ECH keys reach the browsers, and no IPv6 address the gateway cannot route), the other types too. A name that is an IP address, a tunnel service, or has no public address does not resolve. Each lab may ask QueriesPerSecond questions a second.
func (*DNS) Handle ¶
Handle answers one query packet; nil means no answer (a lab over its cap, or not a query).
type Denial ¶
type Denial struct {
Lab string `json:"lab"`
Reason string `json:"reason"`
Count int64 `json:"count"`
}
Denial counts the refused connections of a lab by reason.
type Denylist ¶
type Denylist struct {
// contains filtered or unexported fields
}
Denylist is the set of tunnel-service suffixes.
func NewDenylist ¶
NewDenylist lower-cases the suffixes; an empty list denies nothing.
type LabMap ¶
type LabMap struct {
// contains filtered or unexported fields
}
LabMap says which lab a source address belongs to: the lab of the /24 it sits in (every lab of a group has its own subnet of the internet network). The gateway reconciler keeps it current.
type Minute ¶
type Minute struct {
Start time.Time `json:"start"`
Rows []Row `json:"rows,omitempty"`
Caps []CapHit `json:"caps,omitempty"`
Denials []Denial `json:"denials,omitempty"`
}
Minute is a finished minute.
type Proxy ¶
type Proxy struct {
Labs *LabMap
Resolver *Resolver
Deny *Denylist
Stats *Collector
Log logr.Logger
// MaxConnAge is the longest a connection lives (default 10 minutes).
MaxConnAge time.Duration
// HostNewPerSecond is the most new connections per second one lab opens to one host name (0 = no limit); HostGatewayNewPerSecond the most
// all the labs of this gateway together open to it (0 = no limit).
HostNewPerSecond, HostGatewayNewPerSecond float64
// LabMaxConns is the most connections a lab holds open, LabNewPerSecond the most it opens in a second (0 = no limit).
LabMaxConns, LabNewPerSecond int
// DialTimeout is how long a connection to the server may take (default 10 s).
DialTimeout time.Duration
// HelloTimeout is how long a client may take to send its first flight (default 10 s).
HelloTimeout time.Duration
// Dial replaces the dialer (tests); it must refuse what Resolver.Denied refuses.
Dial func(ctx context.Context, addr string) (net.Conn, error)
// contains filtered or unexported fields
}
Proxy is the transparent web proxy of the gateway. The gateway redirects the TCP 80 and 443 of a lab to it (whatever address the lab chose); it reads the name from the TLS server name or the HTTP Host, looks the name up itself, and connects there. The address the lab chose is never used, so a name in /etc/hosts, a DNS server of the lab's own or a bare address change nothing. TLS is not terminated.
type Resolver ¶
type Resolver struct {
// TTL is how long an answer is kept (default 60 s), NegativeTTL how long a name that did not resolve is remembered (default 10 s).
TTL, NegativeTTL time.Duration
// Now is the clock (tests).
Now func() time.Time
// contains filtered or unexported fields
}
Resolver looks a name up for real, through its own upstream servers and never through the pod's resolv.conf (the cluster's DNS answers internal names, and the lab chooses nothing here). An address in a range a lab may never reach (internal/egress) is dropped from the answer: the proxy never connects there and the DNS server never tells it.
func NewResolver ¶
NewResolver makes a resolver that asks the upstream servers ("ip" or "ip:port"; UDP, and TCP when the answer is truncated).
func (*Resolver) LookupIPv4 ¶
LookupIPv4 returns the public IPv4 addresses of a name (the name is already normalized).
type Row ¶
type Row struct {
Lab string `json:"lab"`
Host string `json:"host"`
Conns int64 `json:"conns"`
Up int64 `json:"up"`
Down int64 `json:"down"`
Denied int64 `json:"denied,omitempty"`
}
Row is one lab's traffic to one host name in one minute. Bytes are counted when a connection ends, in the minute it ends; Conns when it starts. No address of a participant, no content: the lab (its name) and the host name asked for.