Skip to content

Agent Mesh

node: --reachability, private by default or left to AutoNAT

Antonio Ojeaabe90753dee8
diff --git a/cmd/sam-node/main.go b/cmd/sam-node/main.go
index 4b31a014..043ca0cb 100644
--- a/cmd/sam-node/main.go
+++ b/cmd/sam-node/main.go
@@ -86,6 +86,7 @@ var (
keyGracePeriodFlag time.Duration
allowLoopbackFlag bool
announcePrivateFlag bool
+ reachabilityFlag string
monitorBootstrapFlag time.Duration
monitorCheckIntervalFlag time.Duration
autoRelayMinIntervalFlag time.Duration
@@ -453,6 +454,7 @@ func main() {
KeyGracePeriod: keyGracePeriodFlag,
AllowLoopback: allowLoopbackFlag,
AnnouncePrivateAddrs: &announcePrivateFlag,
+ Reachability: node.Reachability(reachabilityFlag),
MonitorBootstrap: monitorBootstrapFlag,
MonitorInterval: monitorCheckIntervalFlag,
AutoRelayMinInterval: autoRelayMinIntervalFlag,
@@ -862,6 +864,7 @@ func main() {
runCmd.Flags().DurationVar(&keyGracePeriodFlag, "key-grace-period", 24*time.Hour, "Key grace period for old keys (e.g. 24h)")
runCmd.Flags().BoolVar(&allowLoopbackFlag, "allow-loopback", false, "Allow publishing and connecting to loopback/link-local addresses")
runCmd.Flags().BoolVar(&announcePrivateFlag, "announce-private", true, "Publish this host's private (RFC1918/ULA) addresses to the mesh; keep enabled for LAN or on-premises meshes, disable when peers are only reachable through routers or public addresses")
+ runCmd.Flags().StringVar(&reachabilityFlag, "reachability", string(node.ReachabilityPrivate), "private: always hold a relay reservation and be reached through the routers, which works behind any NAT. auto: let AutoNAT v2 decide; a node the routers can dial on a public address advertises it and skips the relay. Use auto only where the routers are on the public side of every NAT this node is behind")
runCmd.Flags().BoolVar(&offlineAccessFlag, "offline-access", false, "With --join, request OIDC offline access/refresh token for automatic renewal")
joinCmd.Flags().BoolVar(&allowLoopbackFlag, "allow-loopback", false, "Allow publishing and connecting to loopback/link-local addresses")
joinCmd.Flags().BoolVar(&announcePrivateFlag, "announce-private", true, "Publish this host's private (RFC1918/ULA) addresses to the mesh; keep enabled for LAN or on-premises meshes, disable when peers are only reachable through routers or public addresses")
diff --git a/internal/node/node.go b/internal/node/node.go
index 61abcbfa..90349691 100644
--- a/internal/node/node.go
+++ b/internal/node/node.go
@@ -558,13 +558,19 @@ func (n *SamNode) Start(ctx context.Context) error {
libp2p.ListenAddrStrings(n.config.ListenAddrs...),
libp2p.EnableNATService(),
libp2p.EnableAutoNATv2(),
- libp2p.ForceReachabilityPrivate(),
libp2p.EnableRelay(),
libp2p.EnableHolePunching(),
libp2p.ConnectionManager(cm),
libp2p.SwarmOpts(swarm.WithDialTimeout(15 * time.Second)),
libp2p.AddrsFactory(n.announceFilter),
}
+ // Private: the node holds a relay reservation whatever AutoNAT finds, so
+ // it is reachable through the routers behind any NAT. Auto: AutoNAT v2
+ // decides, and a node the routers can dial on a public address is
+ // advertised there and skips the relay; see Options.Reachability.
+ if n.config.Reachability == ReachabilityPrivate {
+ opts = append(opts, libp2p.ForceReachabilityPrivate())
+ }
// If we have routers, configure them as our static fallback relays for NAT hole-punching
if len(staticRelays) > 0 {
diff --git a/internal/node/options.go b/internal/node/options.go
index 3148fd84..7e180042 100644
--- a/internal/node/options.go
+++ b/internal/node/options.go
@@ -39,6 +39,14 @@ const (
DefaultSocketName = "sam.sock"
)
+// Reachability is the value of Options.Reachability and of --reachability.
+type Reachability string
+
+const (
+ ReachabilityPrivate Reachability = "private"
+ ReachabilityAuto Reachability = "auto"
+)
+
// Options holds all configuration options for a SamNode.
type Options struct {
PrivKey crypto.PrivKey
@@ -58,6 +66,18 @@ type Options struct {
// those addresses. Set false on nodes that are only reachable via routers or
// public addresses, so peers do not learn the host's internal topology.
AnnouncePrivateAddrs *bool
+ // Reachability is how the node decides whether peers can dial it
+ // directly. ReachabilityPrivate, the default, assumes they cannot: the
+ // node always holds a relay reservation with the routers and is reached
+ // through them, which works behind any NAT and needs nothing configured.
+ // ReachabilityAuto lets AutoNAT v2 decide from dial-backs by the routers:
+ // a node they can reach on a public address advertises that address and
+ // holds no reservation, so direct dials replace relayed ones and the
+ // routers carry only the members that need them. Auto is only right
+ // where the routers sit on the public side of every NAT the node is
+ // behind: a router in the same cluster or LAN can reach a node that the
+ // rest of the mesh cannot, and would make it unreachable.
+ Reachability Reachability
MonitorBootstrap time.Duration
MonitorInterval time.Duration
AutoRelayMinInterval time.Duration
@@ -152,6 +172,9 @@ func (o *Options) Default() {
if o.RouterRedialAttempts <= 0 {
o.RouterRedialAttempts = DefaultRouterRedialAttempts
}
+ if o.Reachability == "" {
+ o.Reachability = ReachabilityPrivate
+ }
if o.BiscuitTimeout <= 0 {
o.BiscuitTimeout = identity.DefaultAuthorizerTimeout
}
@@ -205,6 +228,11 @@ func (o *Options) Validate() error {
if o.RequiredRole == "" {
return fmt.Errorf("RequiredRole must be specified")
}
+ switch o.Reachability {
+ case "", ReachabilityPrivate, ReachabilityAuto:
+ default:
+ return fmt.Errorf("reachability %q is not %q or %q", o.Reachability, ReachabilityPrivate, ReachabilityAuto)
+ }
// ed25519 verification panics on a wrong-size key, and this one comes
// from a flag or FFI config.
if len(o.ControlPlanePubKey) > 0 && len(o.ControlPlanePubKey) != ed25519.PublicKeySize {
diff --git a/internal/node/options_test.go b/internal/node/options_test.go
index 00c8a597..a7ea5b7e 100644
--- a/internal/node/options_test.go
+++ b/internal/node/options_test.go
@@ -55,3 +55,37 @@ func TestOptionsValidateControlPlaneKeySize(t *testing.T) {
t.Errorf("31-byte key: err = %v, want size error", err)
}
}
+
+func TestOptionsReachability(t *testing.T) {
+ priv, _, err := crypto.GenerateEd25519Key(rand.Reader)
+ if err != nil {
+ t.Fatal(err)
+ }
+ store, err := NewStore(t.TempDir())
+ if err != nil {
+ t.Fatal(err)
+ }
+ defer func() { _ = store.Close() }()
+ base := Options{PrivKey: priv, Store: store, RequiredRole: api.RoleNode}
+
+ for _, ok := range []Reachability{"", ReachabilityPrivate, ReachabilityAuto} {
+ o := base
+ o.Reachability = ok
+ if err := o.Validate(); err != nil {
+ t.Errorf("reachability %q rejected: %v", ok, err)
+ }
+ }
+ o := base
+ o.Reachability = "public"
+ if err := o.Validate(); err == nil || !strings.Contains(err.Error(), "reachability") {
+ t.Errorf("reachability %q: err = %v, want rejection", o.Reachability, err)
+ }
+
+ // Unset means private: the node is reached through the routers unless
+ // the operator says otherwise.
+ o = base
+ o.Default()
+ if o.Reachability != ReachabilityPrivate {
+ t.Errorf("default reachability = %q, want %q", o.Reachability, ReachabilityPrivate)
+ }
+}
diff --git a/site/content/docs/reference/sam-node.md b/site/content/docs/reference/sam-node.md
index 04733fd3..5fd417c9 100644
--- a/site/content/docs/reference/sam-node.md
+++ b/site/content/docs/reference/sam-node.md
@@ -107,6 +107,7 @@ explains how to enroll.
|---|---|---|
| `--listen` | `/ip4/0.0.0.0/udp/5001/quic-v1`, `/ip4/0.0.0.0/tcp/5002` | libp2p listen addresses. Repeatable. |
| `--allow-loopback`, `--announce-private`, `--router-connect-timeout` | | As for `join`. |
+| `--reachability` | `private` | How the node decides whether peers can dial it directly. `private` always holds a relay reservation with the routers and is reached through them, which works behind any NAT. `auto` lets AutoNAT decide from dial-backs by the routers: a node they reach on a public address advertises it and holds no reservation, so direct dials replace relayed ones. Use `auto` only where the routers are on the public side of every NAT the node is behind; a router in the same cluster or LAN can reach a node the rest of the mesh cannot, and would make it unreachable. |
| `--enable-relay` | `false` | Relay traffic for other peers. |
| `--mesh` | `public-mesh` | Mesh federation name. Must match the routers' name. |
| `--discovery-interval` | `30s` | DHT discovery polling interval. |