Documentation
¶
Overview ¶
Package linuxkernel is the kernel dataplane Backend (design.md 6.1, 7a.7, 7a.8 節 Phase 3): kernel WireGuard (linuxkernel/wg), nftables DNAT and admission (linuxkernel/nft), and conntrack convergence (linuxkernel/conntrack), behind the same dataplane.Backend interface the userspace Backend implements. It never imports internal/vpsd or internal/agent (design.md 7a.7 節; internal/dataplane/deps_test.go checks this), so the future agent kernel backend (Phase 7) can reuse its common kernel components: WireGuard, the platform checks, and the nft and conntrack primitives. The table built here (public ports DNATed to an agent's wg address) and the convergence of those DNATed flows are server-specific; the agent needs its own nft and conntrack path (DNAT to the LAN target, MASQUERADE toward the LAN, agent-side convergence), to be added in this package next to the server's.
One transaction (design.md 7a.2, 7a.3 節) runs as follows. Prepare adds the WireGuard peers the declaration newly needs and builds the table replacement without sending it (nft.Stage). Commit reads the drop counters of the table about to be replaced, sends the replacement as one nftables transaction (the point of no return), then removes the peers the declaration dropped and runs the conntrack convergence. The counters are handed out only when the replacement succeeded: a failed replacement keeps the old table and its counters, which the next Commit reads again, so nothing is accumulated twice. Rollback restores the peer set Prepare changed.
Index ¶
- Constants
- func ConvergeRules(plan planner.Plan, retiring []dataplane.Retiring) []conntrack.Rule
- type Backend
- func (b *Backend) Dial(network, addr string) (net.Conn, error)
- func (b *Backend) EnsureDevice(cfg dataplane.WGConfig) ([]string, error)
- func (b *Backend) Observe() (dataplane.Observed, error)
- func (b *Backend) OtherDeviceWithKey(key wgtypes.Key) (string, bool)
- func (b *Backend) PollUDPReplies() error
- func (b *Backend) Prepare(d dataplane.Desired) (dataplane.Prepared, error)
- func (b *Backend) Repair() dataplane.Committed
- func (b *Backend) UDPReplies() map[string]dataplane.UDPReply
- func (b *Backend) WGStatus() (*wgtypes.Device, error)
- func (b *Backend) Watch(ctx context.Context, wake func()) error
- type Notifications
- type Options
Constants ¶
const UDPReplyPollInterval = 10 * time.Second
UDPReplyPollInterval は、UDP の応答のカウンタを読む周期である(設計文書 10.2a 節「UDP の応答の 観測」)。応答の時刻は、カウンタが増えたことを読んだ時刻にするので、この長さまでの誤差を持つ。 パケットごとに Go を起こさないため、カーネルからの通知は使わない。
Variables ¶
This section is empty.
Functions ¶
func ConvergeRules ¶ added in v0.5.0
ConvergeRules is what the conntrack convergence judges established DNAT flows against: the Transparent ports of the published Plan, plus the previous Active value of every retiring Transparent rule, so a fail-closed rule's safe established flows are kept (design.md 7a.3 節). A retiring rule's flow is kept only while both its previous value and its new declaration admit the source.
Types ¶
type Backend ¶
type Backend struct {
// contains filtered or unexported fields
}
Backend is the kernel dataplane: kernel WireGuard, nftables DNAT and admission, and conntrack convergence (design.md 6.1 節). It implements dataplane.Backend.
func (*Backend) Dial ¶
Dial connects to addr (an agent's wg address and port). Kernel mode routes it straight over wg0 like any other kernel route, so this is a plain dial with no tunnel to go through (unlike the userspace Backend's Dial, which dials through its netstack).
func (*Backend) EnsureDevice ¶ added in v0.5.0
EnsureDevice converges the kernel wg interface, but not its peers, to cfg (design.md 4, 9 節). A refusal (someone else's interface, a port or address conflict) is returned as the *wg.StartupRefusal itself, so the caller can map it to its exit code.
func (*Backend) Observe ¶ added in v0.5.0
Observe reads the peer set the kernel wg interface has now. The interface and its peers outlive the process (design.md 9 節), so before the first Commit this is what the previous process left.
After a Commit it also compares the kernel with what that Commit left (design.md 7a.3 節: 実際の 状態への収束): table inet wgft must exist with the same nft.Fingerprint, and the wg interface must exist with the committed key, listen port, address, up flag and peers. What differs is reported in Observed.Drift. An interface of that name that wgft does not own (another link type, or a WireGuard device with another private key) is an error, not drift: the next transaction would converge it, and it is someone else's (design.md 9 節: 所有判定).
func (*Backend) OtherDeviceWithKey ¶
OtherDeviceWithKey reports another kernel WireGuard device with the same private key, if any (interface rename detection; not part of dataplane.Backend, vpsd calls it directly).
func (*Backend) PollUDPReplies ¶ added in v1.2.0
PollUDPReplies は UDP の応答のカウンタを 1 回読み、読めなかった場合はその誤りを返す。vpsd が UDPReplyPollInterval ごとに呼ぶ。テーブルの差し替えと並行しないよう、Commit と同じ錠を取る。
func (*Backend) Prepare ¶
Prepare adds the peers d newly declares and builds the table replacement without sending it (design.md 7a.2 節). The kernel backend has no rule-local failures: a Transparent rule needs no resource of its own beyond its rows in the one table, and a Relay rule's listener belongs to the frontend. Any error is backend-wide, and nothing stays changed when it is returned.
When d.Resync is set (Observe found drift), the device is converged as a whole, the way the peer changes converge it: created if it is gone, and its key, listen port, address, MTU and peers set back to d.WG (design.md 7a.3 節: 実際の状態への収束).
func (*Backend) Repair ¶ added in v0.5.0
Repair reruns the peer removal and the conntrack convergence the last Commit or Repair left failed, without replacing the table (design.md 7a.3 節: 戻れない地点の後の修復). An unknown read-back stays pending: Observe reports it as drift, and the resulting republication reads the table back.
func (*Backend) UDPReplies ¶ added in v1.2.0
UDPReplies implements dataplane.UDPReplyObserver (design.md 10.2a 節「UDP の応答の観測」): for each UDP rule of the published table, when the watch began and the read at which its reply counter last grew.
func (*Backend) Watch ¶ added in v0.5.0
Watch subscribes to the kernel's change notifications that can mean the kernel no longer has what the last Commit left (design.md 7a.3 節: 実際の状態への収束), and calls wake after each:
- nftables changes (NFNLGRP_NFTABLES on NETLINK_NETFILTER, what `nft monitor` reads), one wake per nftables transaction: a rule, set, chain or table edited or deleted, `flush ruleset`, or another process's table inet wgft released when that process exits
- link changes (RTNLGRP_LINK), such as the wg interface deleted or set down
- IPv4 address changes (RTNLGRP_IPV4_IFADDR), such as the wg interface's address removed
The notifications are never read for what they say; any of them only wakes the control plane, which then Observes. wgft's own Commits notify too, and the Observe after them finds no drift. WireGuard itself has no notifications (a peer removed with `wg set` sends none); the periodic Observe of the control plane catches those.
Watch returns nil when ctx is done. A failed subscription (a receive buffer overflow, ENOBUFS, loses notifications) wakes once more and returns the error, for the caller to restart it.
type Notifications ¶ added in v1.2.0
type Notifications struct{}
Notifications is the same subscription as Backend.Watch, for a control plane that converges the kernel without a Backend: the agent's kernel mode (design.md 7b.4 節: 変更の通知). It holds no state, so its zero value is ready to use.
type Options ¶
type Options struct {
// Interface は wg インタフェース名(既定 wgft0)。
Interface string
// AdoptExisting が真のときだけ、鍵の一致しない既存インタフェースを引き継ぐ(design.md 9 節)。
AdoptExisting bool
}
Options configures a Backend. Interface と AdoptExisting は kernel の wg インタフェースだけの 性質なので、宣言(dataplane.WGConfig)ではなく construction 時にここで固定する(dataplane.WGConfig のドキュメントコメントのとおり)。
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
Package conntrack は、外から入って DNAT されたフローを Plan に収束させる(仕様 6.1 節、 設計文書 7a.8 節 Phase 3)。
|
Package conntrack は、外から入って DNAT されたフローを Plan に収束させる(仕様 6.1 節、 設計文書 7a.8 節 Phase 3)。 |
|
Package nft は、Plan から VPS の table inet wgft を組み立てて適用する(仕様 6.1 節、設計文書 7a.2 節)。
|
Package nft は、Plan から VPS の table inet wgft を組み立てて適用する(仕様 6.1 節、設計文書 7a.2 節)。 |
|
Package wg は VPS の wg0(このファイル)と、カーネルモードのエージェントの単一ピアの インタフェース(agent.go、設計文書 7b 節)の WireGuard インタフェースを宣言に収束させる (仕様 4, 9 節、設計文書 7a.7 節)。
|
Package wg は VPS の wg0(このファイル)と、カーネルモードのエージェントの単一ピアの インタフェース(agent.go、設計文書 7b 節)の WireGuard インタフェースを宣言に収束させる (仕様 4, 9 節、設計文書 7a.7 節)。 |