Documentation
¶
Overview ¶
Package remote holds what remote access is built on: deciding who a request really comes from (and whether forwarded headers may be believed), HTTPS certificates, and the numbers behind the Remote Access settings page.
Index ¶
- Constants
- Variables
- func Ago(t, now time.Time) string
- func HomeSubnets() []netip.Prefix
- func LimitKey(a netip.Addr) string
- func LocalAddress(host string) bool
- func LocalName(host string) bool
- func ParseNets(text string) ([]netip.Prefix, error)
- func SecureHint(r *http.Request) bool
- func Throttle(ctx context.Context, w http.ResponseWriter, bitsPerSec int64) http.ResponseWriter
- func ValidDomain(d string) bool
- func WithP2P(ctx context.Context, c P2PConn) context.Context
- type CertInfo
- type Client
- type ConnLimit
- type Facts
- type HTTPS
- type HTTPSConfig
- type HTTPSStatus
- type Iface
- type P2PConn
- type Policy
- type Standing
- type VPNAddr
- type Way
- type Where
Constants ¶
const ( SubjectHomeOnly = "Home network only" SubjectYes = "Reachable from away: yes" SubjectNotYet = "Reachable from away: not yet" SubjectNo = "Reachable from away: no" )
The subjects. docs/REMOTE.md lists each one, which a test checks.
const (
// DefaultPerAddress is how many one address can hold (an IPv6 /64 counts as one address).
DefaultPerAddress = 128
)
Each open connection costs a descriptor and some memory, so a stranger holding open as many as they can is a way to stop the server for everyone.
const PlainAwayWarning = "" /* 216-byte string literal not displayed */
PlainAwayWarning is said wherever it matters while unencrypted connections from away are allowed: the status card, the dashboard and the apps.
Variables ¶
var Subjects = []string{SubjectHomeOnly, SubjectYes, SubjectNotYet, SubjectNo}
Subjects are all of them, for the docs test.
Functions ¶
func HomeSubnets ¶
HomeSubnets returns homeSubnetsOf for this machine, looked up at most once a minute (and only ever for clients with global IPv6 addresses).
func LimitKey ¶
LimitKey is the unit a limit applies to: one IPv4 address, or one IPv6 /64 (a single home or server is usually given a whole /64, so counting single IPv6 addresses would limit nobody).
func LocalAddress ¶
LocalAddress says what someone typed names something at home or on their VPN.
func LocalName ¶
LocalName says a host name is one only a local network can resolve: a computer's own name, or one under a suffix nobody can register. A name anyone can register can point anywhere.
func ParseNets ¶
ParseNets reads a list of addresses and networks (separated by commas, spaces or new lines). A network wider than /8 (IPv4) or /32 (IPv6) is refused: trusting that much of the internet is never what anyone means.
func SecureHint ¶
SecureHint: the connection is encrypted, or a header claims a proxy in front of this server encrypts it. The header is only good enough for choices that can harm nobody but whoever forged it, such as marking a cookie Secure.
func Throttle ¶
func Throttle(ctx context.Context, w http.ResponseWriter, bitsPerSec int64) http.ResponseWriter
Throttle limits what one response sends, in bits per second. Players read ahead, so the first seconds' worth goes out at once and only after that does the limit bite.
func ValidDomain ¶
ValidDomain checks a name Let's Encrypt could issue for.
Types ¶
type CertInfo ¶
type CertInfo struct {
Names []string `json:"names"`
Issuer string `json:"issuer"`
NotAfter int64 `json:"notAfter"`
DaysLeft int `json:"daysLeft"`
SelfSigned bool `json:"selfSigned"`
}
CertInfo describes the certificate in use.
type Client ¶
type Client struct {
IP netip.Addr // the client's address as far as it can be known
Peer netip.Addr // who opened the connection to this server
Where Where
// Proxied: a trusted proxy passed this request on and named the client.
Proxied bool
// Unverified: the request carries forwarded headers but did not come from
// a trusted proxy. They are ignored, and it counts as coming from the
// internet, which is the safe direction for everything that uses this.
Unverified bool
// Secure: the connection from the browser is encrypted. Direct TLS, or a
// trusted proxy says so.
Secure bool
// ForwardedHost is the address the browser used, from a trusted proxy only.
ForwardedHost string
// P2P: the request came over a peer-to-peer connection (see p2p.go), from
// the device with this key. Where is then always Internet.
P2P bool
P2PDevice string
P2PRelayed bool
}
Client is what a request says about its sender, after deciding how much of it can be believed.
type ConnLimit ¶
type ConnLimit struct {
Total int
PerAddress int
// Policy is the owner's current choices: a trusted reverse proxy is many visitors, so
// it isn't limited as one address.
Policy func() *Policy
Log *slog.Logger
// contains filtered or unexported fields
}
ConnLimit counts open connections. One ConnLimit covers every listener wrapped with it.
type Facts ¶
type Facts struct {
On bool // connections from away are allowed
LocalOnly bool // the server listens on this computer only
PlainAway bool // the owner lets the internet in without encryption
Ways []Way
Proof time.Time // when the outside test last passed (zero: never, or too long ago)
Now time.Time
}
Facts are what Describe needs to know.
type HTTPS ¶
type HTTPS struct {
// Conns counts this port's connections with the home port's; set before Apply.
Conns *ConnLimit
// contains filtered or unexported fields
}
HTTPS owns the listener and certificates.
func (*HTTPS) Apply ¶
func (h *HTTPS) Apply(cfg HTTPSConfig) error
Apply brings the port in line with cfg. Unchanged settings leave it running. A certificate that can't be used is reported, and the port stays closed.
type HTTPSConfig ¶
type HTTPSConfig struct {
Mode string // off | acme | cert
Host string // address to listen on ("" = every network card)
Port int // 0 picks a free port (tests)
Domain string // acme
Email string // acme, optional
CertFile string // cert
KeyFile string // cert
}
HTTPSConfig is what the HTTPS port should be doing.
type HTTPSStatus ¶
type HTTPSStatus struct {
Mode string `json:"mode"`
Running bool `json:"running"`
Port int `json:"port"`
Error string `json:"error,omitempty"`
Obtaining bool `json:"obtaining,omitempty"`
Cert *CertInfo `json:"cert,omitempty"`
}
HTTPSStatus is what Settings shows.
type Iface ¶
Iface is one address of one of this machine's network cards.
func Interfaces ¶
func Interfaces() []Iface
Interfaces lists the addresses of the network cards that are up.
type P2PConn ¶
type P2PConn struct {
// Addr is the address the connection is counted under: the other end's
// public address when it is direct, otherwise one made up for it. It is
// never an address of this computer or of the home network.
Addr netip.Addr
// Device is the other end's key, as its ID.
Device string
Relayed bool
// Known: the device is on the server's list.
Known bool
}
P2PConn is what is known about a peer-to-peer connection.
type Policy ¶
type Policy struct {
Trusted []netip.Prefix // reverse proxies whose forwarded headers are believed
Home []netip.Prefix // extra networks that count as the home network
Away []netip.Prefix // networks that count as away, even if private (a VPN of your own)
// LocalV6 lists this machine's own IPv6 home subnets; nil uses HomeSubnets.
LocalV6 func() []netip.Prefix
}
Policy is the owner's choices about networks. A nil Policy trusts no proxy and knows only the built-in ranges.
func (*Policy) Classify ¶
Classify says where an address is. The owner's lists win over the built-in ranges, and "away" wins over everything: a private VPN address must not count as the home network if the owner says it doesn't.
func (*Policy) Resolve ¶
Resolve works out who sent a request. Forwarded headers are read only when the connection itself comes from a trusted proxy, and then from the right (the entry that proxy added) until the first address that is not a trusted proxy: everything further left was written by the client and may be made up.
RFC 7239's Forwarded header is never read: proxies that only maintain X-Forwarded-For pass a client's made-up Forwarded through untouched.
type Standing ¶
type Standing struct {
// Level is the colour: good (working as chosen, green), waiting (asked
// for, not working yet, amber) or fault (something is broken, red).
Level string `json:"level"`
Subject string `json:"subject"` // what it's about, with the short answer
Summary string `json:"summary"` // the whole answer, in a sentence or two
Home string `json:"home"` // devices at home
Away string `json:"away"` // devices away from home
Checked string `json:"checked"` // how that is known
// Warning stays while the owner lets the internet in unencrypted.
Warning string `json:"warning,omitempty"`
}
Standing is how remote access stands right now.
type VPNAddr ¶
type VPNAddr struct {
Kind string `json:"kind"` // Tailscale | NetBird | VPN
IP string `json:"ip"`
}
VPNAddr is an address of this machine on a private overlay network.
type Way ¶
type Way struct {
Kind string // vpn | https | proxy | plain
Label string // Tailscale, NetBird, VPN, "the internet, over HTTPS", "your reverse proxy"
URL string // where to connect, if known
State string // ok | waiting | problem
Detail string // what is wrong, for a problem
LastSeen time.Time
}
Way is one way in from away, as the status found it.