Merge pull request #1359 from nerdalert/rename-child-prefix

Deprecation warnings for child-prefix and add advertise-cidr

cmd/nexctl/device.go

@@ -54,7 +54,7 @@ func deviceTableFields(cCtx *cli.Context) []TableField {
 				return ""
 			},
 		})
-		fields = append(fields, TableField{Header: "ALLOWED IPS",
+		fields = append(fields, TableField{Header: "ADVERTISED CIDR",
 			Formatter: func(item interface{}) string {
 				dev := item.(public.ModelsDevice)
 				return strings.Join(dev.AllowedIps, ", ")

cmd/nexd/main.go

@@ -99,12 +99,17 @@ func nexdRun(cCtx *cli.Context, logger *zap.Logger, logLevel *zap.AtomicLevel, m
 
 	userspaceMode := false
 	relayNode := false
-	var childPrefix []string
+	var advertiseCidr []string
 	switch mode {
 	case nexdModeAgent:
 		logger.Info("Starting node agent with wireguard driver")
 	case nexdModeRouter:
-		childPrefix = cCtx.StringSlice("child-prefix")
+		advertiseCidr = cCtx.StringSlice("advertise-cidr")
+		// Check if child-prefix is set and log a deprecation warning.
+		if cCtx.IsSet("child-prefix") {
+			logger.Warn("DEPRECATION WARNING: The 'child-prefix' flag is deprecated. In the future, please use 'advertise-cidr' instead.")
+			advertiseCidr = append(advertiseCidr, cCtx.StringSlice("child-prefix")...)
+		}
 		logger.Info("Starting node agent with wireguard driver and router function")
 	case nexdModeRelay:
 		relayNode = true
@@ -141,7 +146,7 @@ func nexdRun(cCtx *cli.Context, logger *zap.Logger, logLevel *zap.AtomicLevel, m
 		cCtx.Int("listen-port"),
 		cCtx.String("request-ip"),
 		cCtx.String("local-endpoint-ip"),
-		childPrefix,
+		advertiseCidr,
 		cCtx.Bool("stun"),
 		relayNode,
 		cCtx.Bool("relay-only"),
@@ -258,20 +263,33 @@ func main() {
 			},
 			{
 				Name:  "router",
-				Usage: "Enable child-prefix function of the node agent to enable prefix forwarding.",
+				Usage: "Enable advertise-cidr function of the node agent to enable prefix forwarding.",
 				Action: func(cCtx *cli.Context) error {
 					return nexdRun(cCtx, logger, logLevel, nexdModeRouter)
 				},
 				Flags: []cli.Flag{
 					&cli.StringSliceFlag{
-						Name:     "child-prefix",
+						Name:     "advertise-cidr",
 						Usage:    "Request a `CIDR` range of addresses that will be advertised from this node (optional)",
-						EnvVars:  []string{"NEXD_REQUESTED_CHILD_PREFIX"},
-						Required: true,
-						Action: func(ctx *cli.Context, childPrefixes []string) error {
-							for _, prefix := range childPrefixes {
-								if err := nexodus.ValidateCIDR(prefix); err != nil {
-									return fmt.Errorf("Child prefix CIDRs passed in --child-prefix %s is not valid: %w", prefix, err)
+						EnvVars:  []string{"NEXD_REQUESTED_ADVERTISE_CIDR"},
+						Required: false,
+						Action: func(ctx *cli.Context, advertiseCidr []string) error {
+							for _, cidr := range advertiseCidr {
+								if err := nexodus.ValidateCIDR(cidr); err != nil {
+									return fmt.Errorf("advertise prefix CIDR(s) passed in --advertise-cidr %s is not valid: %w", cidr, err)
+								}
+							}
+							return nil
+						},
+					},
+					&cli.StringSliceFlag{
+						Name:   "child-prefix",
+						Usage:  "(DEPRECATED WARNING) please use --advertise-cidr instead.",
+						Hidden: true,
+						Action: func(ctx *cli.Context, advertiseCidr []string) error {
+							for _, cidr := range advertiseCidr {
+								if err := nexodus.ValidateCIDR(cidr); err != nil {
+									return fmt.Errorf("advertise prefix CIDR(s) passed in --advertise-cidr %s is not valid: %w", cidr, err)
 								}
 							}
 							return nil
@@ -423,8 +441,8 @@ func main() {
 				if runtime.GOOS != nexodus.Linux.String() {
 					return fmt.Errorf("network-router mode is only supported for Linux operating systems")
 				}
-				if len(c.StringSlice("child-prefix")) == 0 {
-					return fmt.Errorf("--child-prefix is required for a device to be a network-router")
+				if len(c.StringSlice("advertise-cidr")) == 0 {
+					return fmt.Errorf("--advertise-cidr is required for a device to be a network-router")
 				}
 			}
 			return nil

docs/development/design/dual-stack.md

@@ -23,7 +23,7 @@ While `local_ip_v6` (v6 tunnel endpoint) is not used in the dual stack implement
 
 ### CLI Changes
 
-The only CLI changes are some details in descriptions specifically calling out IPv4 only support to features such as `router --child-prefix` and `tunnel-ip` that are not implemented in the initial work. Ideally we don't add flag bloat here and accept v4/v6 in applicable fields rather than net new fields for v6. For example, `--child-prefix=172.17.20.0/24,2001:db8:abcd:0012::0/64`.
+The only CLI changes are some details in descriptions specifically calling out IPv4 only support to features such as `router --advertise-cidr` and `tunnel-ip` that are not implemented in the initial work. Ideally we don't add flag bloat here and accept v4/v6 in applicable fields rather than net new fields for v6. For example, `--advertise-cidr=172.17.20.0/24,2001:db8:abcd:0012::0/64`.
 
 ### IPv4 Only Support
 

docs/development/design/network-router.md

@@ -21,10 +21,10 @@ This is a zero touch provisioning for the non-nexodus device since the edge nexd
 
 ```shell
 nexd --username admin --password floofykittens --service-url https://try.nexodus.127.0.0.1.nip.io \
-    router --child-prefix 192.168.100.0/24 --network-router  
+    router --advertise-cidr 192.168.100.0/24 --network-router  
 ```
 
-The child-prefix subnet specified will get distributed to all Nexodus peers. Those peers will get a route with a next hop of the Wireguard interface. In the following, you can view the child-prefix routes in the routing tables of nexd-node2 in the diagram.
+The advertise-cidr subnet specified will get distributed to all Nexodus peers. Those peers will get a route with a next hop of the Wireguard interface. In the following, you can view the advertise-cidr routes in the routing tables of nexd-node2 in the diagram.
 
 ```shell
 # Linux
@@ -74,10 +74,10 @@ sudo ip route add 100.100.0.0/16 via 192.168.100.5
 Start the daemon with the additional `--disable-nat` parameter:
 
 ```shell
-nexd  --username admin --password floofykittens router --child-prefix 192.168.100.0/24 --network-router --disable-nat  https://try.nexodus.127.0.0.1.nip.io
+nexd  --username admin --password floofykittens router --advertise-cidr 192.168.100.0/24 --network-router --disable-nat  https://try.nexodus.127.0.0.1.nip.io
 ```
 
-The child-prefix subnet specified will get distributed to all Nexodus peers. Those peers will get a route with a next hop of the Wireguard interface. In the following, you can view the child-prefix routes in the routing tables of nexd-node2 in the diagram.
+The advertise-cidr subnet specified will get distributed to all Nexodus peers. Those peers will get a route with a next hop of the Wireguard interface. In the following, you can view the advertise-cidr routes in the routing tables of nexd-node2 in the diagram.
 
 ```shell
 # Linux
@@ -112,9 +112,9 @@ table inet nexodus-net-router {
 
 ### Security Considerations
 
-- Since devices are forwarding traffic from non-nexodus devices, nexodus restricts the allowed traffic to the IP prefix specified in the `--child-prefix`. This prevents arbitrary hosts from gaining access to the nexodus device peers.
+- Since devices are forwarding traffic from non-nexodus devices, nexodus restricts the allowed traffic to the IP prefix specified in the `--advertise-cidr`. This prevents arbitrary hosts from gaining access to the nexodus device peers.
 - Additional compensating controls can be added via nexodus security groups to further restrict what traffic is permitted to be allowed in or out of the peerings from non-nexd devices.
 
 ## Future Enhancements
 
-- Add a future enhancement idea of a flag that allows routing traffic into a Nexodus network with SNAT but without specifying any prefixes to advertise. This would allow a user to use Nexodus as a router for external traffic without having to specify any prefixes to advertise. This would be useful for scenarios where a user wants to use Nexodus as a router for external traffic but does not want to advertise any prefixes to the Nexodus network.
+- Add a future enhancement idea of a flag that allows routing traffic into a Nexodus network with SNAT but without specifying any prefixes to advertise. This would allow a user to use Nexodus as a router for external traffic without having to specify any prefixes to advertise. This would be useful for scenarios where a user wants to use Nexodus as a router for external traffic but does not want to advertise any prefixes to the Nexodus network.

docs/development/design/userspace-mode.md

@@ -39,7 +39,7 @@ Once the current mode has been moved under an `agent` subcommand, a new `proxy`
 Only a subset of the flags used in `agent` mode apply to `proxy` mode. The following flags will not be present under the `proxy` mode:
 
 ```text
-   --child-prefix value [ --child-prefix value ]  Request a CIDR range of addresses that will be advertised from this node (optional) [$NEXD_REQUESTED_CHILD_PREFIX]
+   --advertise-cidr value [ --advertise-cidr value ]  Request a CIDR range of addresses that will be advertised from this node (optional) [$NEXD_REQUESTED_CHILD_PREFIX]
    --relay-node                                   Set if this node is to be the relay node for a hub and spoke scenarios (default: false) [$NEXD_RELAY_NODE]
    --discovery-node                               Set if this node is to be the discovery node for NAT traversal in an organization (default: false) [$NEXD_DISCOVERY_NODE]
    --relay-only                                   Set if this node is unable to NAT hole punch or you do not want to fully mesh (Nexodus will set this automatically if symmetric NAT is detected) (default: false) [$NEXD_RELAY_ONLY]

docs/user-guide/network-routers.md

@@ -11,7 +11,7 @@ The situations where this can be useful are wide-ranging. They can span from con
 - You simply specify the network prefix you want to advertise and Nexodus will use the physical interface that contains the default route to connect to the non-Nexodus nodes.
 
 ```terminal
-nexd router --child-prefix 192.168.100.0/24 --network-router
+nexd router --advertise-cidr 192.168.100.0/24 --network-router
 ```
 
 - If you are running nexd in a container, additional capabilities need to be added to the container at runtime. Here is an example on how to start a container with IPv4/IPv6 forwarding capabilities enabled.
@@ -27,7 +27,7 @@ quay.io/nexodus/nexd
 ![no-alt-text](../images/network-router-simple-example-1.png)
 
 > **Note**
-> Nexodus accepts as many networks as you want to specify in the `--child-prefix=192.168.1.0/24 --child-prefix 192.168.100.0/24 --child-prefix 172.16.100.0/24 ...` configuration. This means you can advertise as many subnets as you want from the Nexodus device running as a network router.
+> Nexodus accepts as many networks as you want to specify in the `--advertise-cidr=192.168.1.0/24 --advertise-cidr 192.168.100.0/24 --advertise-cidr 172.16.100.0/24 ...` configuration. This means you can advertise as many subnets as you want from the Nexodus device running as a network router.
 
 By default, Nexodus network routers perform NAT, specifically, source NAT for devices coming from a Nexodus mesh with a destination of one of the devices not running the Nexodus agent. This enables connectivity to those devices without any configuration on the devices.
 

docs/user-guide/nexd.md

@@ -17,13 +17,13 @@ USAGE:
 COMMANDS:
    version  Get the version of nexd
    proxy    Run nexd as an L4 proxy instead of creating a network interface
-   router   Enable child-prefix function of the node agent to enable prefix forwarding.
+   router   Enable advertise-cidr function of the node agent to enable prefix forwarding.
    relay    Enable relay and discovery support function for the node agent.
    help, h  Shows a list of commands or help for one command
 
 GLOBAL OPTIONS:
    --help, -h           Show help
-   --unix-socket value  Path to the unix socket nexd is listening against (default: "/Users/chirino/.nexodus/nexd.sock")
+   --unix-socket value  Path to the unix socket nexd is listening against (default: "~/.nexodus/nexd.sock")
 
    Agent Options
 
@@ -36,7 +36,7 @@ GLOBAL OPTIONS:
    --organization-id value                      Organization ID to use when registering with the nexodus service [$NEXD_ORG_ID]
    --password string                            Password string for accessing the nexodus service [$NEXD_PASSWORD]
    --service-url value                          URL to the Nexodus service (default: "https://try.nexodus.127.0.0.1.nip.io") [$NEXD_SERVICE_URL]
-   --state-dir value                            Directory to store state in, such as api tokens to reuse after interactive login. Defaults to'/Users/chirino/.nexodus' (default: "/Users/chirino/.nexodus") [$NEXD_STATE_DIR]
+   --state-dir value                            Directory to store state in, such as api tokens to reuse after interactive login. Defaults to'~/.nexodus' (default: "~/.nexodus") [$NEXD_STATE_DIR]
    --stun-server value [ --stun-server value ]  stun server to use discover our endpoint address.  At least two are required. [$NEXD_STUN_SERVER]
    --username string                            Username string for accessing the nexodus service [$NEXD_USERNAME]
 
@@ -67,16 +67,16 @@ OPTIONS:
 
 ```text
 NAME:
-   nexd router - Enable child-prefix function of the node agent to enable prefix forwarding.
+   nexd router - Enable advertise-cidr function of the node agent to enable prefix forwarding.
 
 USAGE:
    nexd router [command options] [arguments...]
 
 OPTIONS:
-   --child-prefix CIDR [ --child-prefix CIDR ]  Request a CIDR range of addresses that will be advertised from this node (optional) [$NEXD_REQUESTED_CHILD_PREFIX]
-   --network-router                             Make the node a network router node that will forward traffic specified by --child-prefix through the physical interface that contains the default gateway (default: false) [$NEXD_NET_ROUTER_NODE]
-   --disable-nat                                disable NAT for the network router mode. This will require devices on the network to be configured with an ip route (default: false) [$NEXD_DISABLE_NAT]
-   --help, -h                                   Show help
+   --advertise-cidr CIDR [ --advertise-cidr CIDR ]  Request a CIDR range of addresses that will be advertised from this node (optional) [$NEXD_REQUESTED_ADVERTISE_CIDR]
+   --network-router                                 Make the node a network router node that will forward traffic specified by --child-prefix through the physical interface that contains the default gateway (default: false) [$NEXD_NET_ROUTER_NODE]
+   --disable-nat                                    disable NAT for the network router mode. This will require devices on the network to be configured with an ip route (default: false) [$NEXD_DISABLE_NAT]
+   --help, -h                                       Show help
 ```
 
 #### nexd relay

docs/user-guide/scenarios/containers-on-nodes.md

@@ -1,19 +1,19 @@
 # Mesh network between containers running on connected nodes
 
 Imagine a user wants to not only communicate between the node address each member of the mesh but also want to advertise
-some additional IP prefixes for additional services running on a node. This can be accomplished with the `--child-prefix` flag
+some additional IP prefixes for additional services running on a node. This can be accomplished with the `--advertise-cidr` flag
 of `router` subcommand. Prefixes have to be unique within an organization but can overlap between separate organizations.
 
 The following example allows a user to connect Docker container directly to one another without exposing a port on the node.
-These nodes could be in different data centers or CSPs. This example uses the `router --child-prefix` option to advertise the private
+These nodes could be in different data centers or CSPs. This example uses the `router --advertise-cidr` option to advertise the private
 container networks to the mesh and enable connectivity.
 
 **Node1 setup:**
 
 Join node1 to the user's default assigned organization
 
 ```shell
-sudo nexd router --child-prefix=172.24.0.0/24 <SERVICE_URL>
+sudo nexd router --advertise-cidr=172.24.0.0/24 <SERVICE_URL>
 ```
 
 Create the container network:
@@ -39,7 +39,7 @@ docker run -it --rm --network=net1 busybox bash
 Join node2 to the user's default assigned organization
 
 ```shell
-sudo nexd router --child-prefix=172.28.0.0/24 <SERVICE_URL>
+sudo nexd router --advertise-cidr=172.28.0.0/24 <SERVICE_URL>
 ```
 
 Setup a docker network and start a node on it: