diff --git a/core/commands/commands_test.go b/core/commands/commands_test.go index 2573d4cd5..04ee581e0 100644 --- a/core/commands/commands_test.go +++ b/core/commands/commands_test.go @@ -198,6 +198,7 @@ func TestCommands(t *testing.T) { "/stats/repo", "/swarm", "/swarm/addrs", + "/swarm/addrs/autonat", "/swarm/addrs/listen", "/swarm/addrs/local", "/swarm/connect", diff --git a/core/commands/swarm.go b/core/commands/swarm.go index 533ccc078..bcc11a3a0 100644 --- a/core/commands/swarm.go +++ b/core/commands/swarm.go @@ -513,8 +513,9 @@ var swarmAddrsCmd = &cmds.Command{ `, }, Subcommands: map[string]*cmds.Command{ - "local": swarmAddrsLocalCmd, - "listen": swarmAddrsListenCmd, + "autonat": swarmAddrsAutoNATCmd, + "local": swarmAddrsLocalCmd, + "listen": swarmAddrsListenCmd, }, Run: func(req *cmds.Request, res cmds.ResponseEmitter, env cmds.Environment) error { api, err := cmdenv.GetApi(env, req) diff --git a/core/commands/swarm_addrs_autonat.go b/core/commands/swarm_addrs_autonat.go new file mode 100644 index 000000000..9d69eaef7 --- /dev/null +++ b/core/commands/swarm_addrs_autonat.go @@ -0,0 +1,139 @@ +package commands + +import ( + "fmt" + "io" + + cmds "github.com/ipfs/go-ipfs-cmds" + cmdenv "github.com/ipfs/kubo/core/commands/cmdenv" + "github.com/libp2p/go-libp2p/core/network" + ma "github.com/multiformats/go-multiaddr" +) + +// reachabilityHost provides access to the AutoNAT reachability status. +type reachabilityHost interface { + Reachability() network.Reachability +} + +// confirmedAddrsHost provides access to per-address reachability from AutoNAT V2. +type confirmedAddrsHost interface { + ConfirmedAddrs() (reachable, unreachable, unknown []ma.Multiaddr) +} + +// autoNATResult represents the AutoNAT reachability information. +type autoNATResult struct { + Reachability string `json:"reachability"` + Reachable []string `json:"reachable,omitempty"` + Unreachable []string `json:"unreachable,omitempty"` + Unknown []string `json:"unknown,omitempty"` +} + +func multiaddrsToStrings(addrs []ma.Multiaddr) []string { + out := make([]string, len(addrs)) + for i, a := range addrs { + out[i] = a.String() + } + return out +} + +func writeAddrSection(w io.Writer, label string, addrs []string) { + if len(addrs) > 0 { + fmt.Fprintf(w, " %s:\n", label) + for _, addr := range addrs { + fmt.Fprintf(w, " %s\n", addr) + } + } +} + +var swarmAddrsAutoNATCmd = &cmds.Command{ + Helptext: cmds.HelpText{ + Tagline: "Show address reachability as determined by AutoNAT V2.", + ShortDescription: ` +'ipfs swarm addrs autonat' shows the reachability status of your node's +addresses as determined by AutoNAT V2. +`, + LongDescription: ` +'ipfs swarm addrs autonat' shows the reachability status of your node's +addresses as verified by AutoNAT V2. + +AutoNAT V2 probes your node's addresses to determine if they are reachable +from the public internet. This helps understand whether other peers can +dial your node directly. + +The output shows: +- Reachability: Overall status (Public, Private, or Unknown) +- Reachable: Addresses confirmed to be publicly reachable +- Unreachable: Addresses that failed reachability checks +- Unknown: Addresses that haven't been tested yet + +For more information on AutoNAT V2, see: +https://github.com/libp2p/specs/blob/master/autonat/autonat-v2.md + +Example: + + > ipfs swarm addrs autonat + AutoNAT V2 Status: + Reachability: Public + + Per-Address Reachability: + Reachable: + /ip4/203.0.113.42/tcp/4001 + /ip4/203.0.113.42/udp/4001/quic-v1 + Unreachable: + /ip6/2001:db8::1/tcp/4001 + Unknown: + /ip4/203.0.113.42/udp/4001/webrtc-direct +`, + }, + Run: func(req *cmds.Request, res cmds.ResponseEmitter, env cmds.Environment) error { + nd, err := cmdenv.GetNode(env) + if err != nil { + return err + } + + if !nd.IsOnline { + return ErrNotOnline + } + + result := autoNATResult{ + Reachability: network.ReachabilityUnknown.String(), + } + + // Get per-address reachability from AutoNAT V2. + // The host embeds *BasicHost (closableBasicHost, closableRoutedHost) + // which implements ConfirmedAddrs. + if h, ok := nd.PeerHost.(confirmedAddrsHost); ok { + reachable, unreachable, unknown := h.ConfirmedAddrs() + result.Reachable = multiaddrsToStrings(reachable) + result.Unreachable = multiaddrsToStrings(unreachable) + result.Unknown = multiaddrsToStrings(unknown) + } + + // Get overall reachability status. + if h, ok := nd.PeerHost.(reachabilityHost); ok { + result.Reachability = h.Reachability().String() + } + + return cmds.EmitOnce(res, result) + }, + Type: autoNATResult{}, + Encoders: cmds.EncoderMap{ + cmds.Text: cmds.MakeTypedEncoder(func(req *cmds.Request, w io.Writer, result autoNATResult) error { + fmt.Fprintln(w, "AutoNAT V2 Status:") + fmt.Fprintf(w, " Reachability: %s\n", result.Reachability) + + fmt.Fprintln(w) + fmt.Fprintln(w, "Per-Address Reachability:") + + writeAddrSection(w, "Reachable", result.Reachable) + writeAddrSection(w, "Unreachable", result.Unreachable) + writeAddrSection(w, "Unknown", result.Unknown) + + if len(result.Reachable) == 0 && len(result.Unreachable) == 0 && len(result.Unknown) == 0 { + fmt.Fprintln(w, " (no address reachability data available)") + } + + return nil + }), + }, +} diff --git a/docs/changelogs/v0.40.md b/docs/changelogs/v0.40.md index f99ca0e95..c5f6023e9 100644 --- a/docs/changelogs/v0.40.md +++ b/docs/changelogs/v0.40.md @@ -18,6 +18,7 @@ This release was brought to you by the [Shipyard](https://ipshipyard.com/) team. - [IPIP-524: Gateway codec conversion disabled by default](#ipip-524-gateway-codec-conversion-disabled-by-default) - [Improved IPNS over PubSub validation](#improved-ipns-over-pubsub-validation) - [New `ipfs diag datastore` commands](#new-ipfs-diag-datastore-commands) + - [🔍 New `ipfs swarm addrs autonat` command](#-new-ipfs-swarm-addrs-autonat-command) - [🚇 Improved `ipfs p2p` tunnels with foreground mode](#-improved-ipfs-p2p-tunnels-with-foreground-mode) - [Improved `ipfs dag stat` output](#improved-ipfs-dag-stat-output) - [🔑 `ipfs key` improvements](#-ipfs-key-improvements) @@ -129,6 +130,38 @@ New experimental commands for low-level datastore inspection: The daemon must not be running when using these commands. Run `ipfs diag datastore --help` for usage examples. +#### 🔍 New `ipfs swarm addrs autonat` command + +The new `ipfs swarm addrs autonat` command shows the network reachability status of your node's addresses as verified by AutoNAT V2. AutoNAT V2 leverages other nodes in the IPFS network to test your node's external public reachability, providing a self-service way to debug connectivity. + +Public reachability is important for: + +- **Direct data fetching**: Other nodes can fetch data directly from your node without NAT hole punching. +- **Browser access**: Web browsers can connect to your node directly for content retrieval. +- **DHT participation**: Your node can act as a DHT server, helping to maintain the distributed hash table and making content routing more robust. + +The command displays: + +- Overall reachability status (public, private, or unknown) +- Per-address reachability showing which specific addresses are reachable, unreachable, or unknown + +Example output: +``` +AutoNAT V2 Status: + Reachability: public + +Per-Address Reachability: + Reachable: + /ip4/203.0.113.42/tcp/4001 + /ip4/203.0.113.42/udp/4001/quic-v1 + Unreachable: + /ip6/2001:db8::1/tcp/4001 + Unknown: + /ip4/203.0.113.42/udp/4001/webrtc-direct +``` + +This helps diagnose connectivity issues and understand if your node is publicly reachable. See the [AutoNAT V2 spec](https://github.com/libp2p/specs/blob/master/autonat/autonat-v2.md) for more details. + #### 🚇 Improved `ipfs p2p` tunnels with foreground mode P2P tunnels can now run like SSH port forwarding: start a tunnel, use it, and it cleans up automatically when you're done. diff --git a/test/cli/swarm_test.go b/test/cli/swarm_test.go index 56c484ae1..965484fc0 100644 --- a/test/cli/swarm_test.go +++ b/test/cli/swarm_test.go @@ -92,4 +92,35 @@ func TestSwarm(t *testing.T) { assert.ElementsMatch(t, outputIdentify.Addresses, otherNodeIDOutput.Addresses) assert.ElementsMatch(t, outputIdentify.Protocols, otherNodeIDOutput.Protocols) }) + + t.Run("ipfs swarm addrs autonat returns valid reachability status", func(t *testing.T) { + t.Parallel() + node := harness.NewT(t).NewNode().Init().StartDaemon() + defer node.StopDaemon() + + res := node.RunIPFS("swarm", "addrs", "autonat", "--enc=json") + assert.NoError(t, res.Err) + + var output struct { + Reachability string `json:"reachability"` + Reachable []string `json:"reachable"` + Unreachable []string `json:"unreachable"` + Unknown []string `json:"unknown"` + } + err := json.Unmarshal(res.Stdout.Bytes(), &output) + assert.NoError(t, err) + + // Reachability must be one of the valid states + // Note: network.Reachability constants use capital first letter + validStates := []string{"Public", "Private", "Unknown"} + assert.Contains(t, validStates, output.Reachability, + "Reachability should be one of: Public, Private, Unknown") + + // For a newly started node, reachability is typically Unknown initially + // as AutoNAT hasn't completed probing yet. This is expected behavior. + // The important thing is that the command runs and returns valid data. + totalAddrs := len(output.Reachable) + len(output.Unreachable) + len(output.Unknown) + t.Logf("Reachability: %s, Total addresses: %d (reachable: %d, unreachable: %d, unknown: %d)", + output.Reachability, totalAddrs, len(output.Reachable), len(output.Unreachable), len(output.Unknown)) + }) }