Agent Mesh
Go a2aa2a-protocolagent-meshagentic-aiinferencemcpmeshmesh-networknetwork-securitynetworking-aip2p-network
node: --reachability, private by default or left to AutoNAT
Antonio Ojeaabe90753dee8
diff --git a/cmd/sam-node/main.go b/cmd/sam-node/main.goindex 4b31a014..043ca0cb 100644--- a/cmd/sam-node/main.go+++ b/cmd/sam-node/main.go@@ -86,6 +86,7 @@ var (keyGracePeriodFlag time.DurationallowLoopbackFlag boolannouncePrivateFlag bool+ reachabilityFlag stringmonitorBootstrapFlag time.DurationmonitorCheckIntervalFlag time.DurationautoRelayMinIntervalFlag 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.goindex 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-punchingif len(staticRelays) > 0 {diff --git a/internal/node/options.go b/internal/node/options.goindex 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 ReachabilityMonitorBootstrap time.DurationMonitorInterval time.DurationAutoRelayMinInterval 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.goindex 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.mdindex 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. |