v0.2.0

ADDED:
* num-nets subcommand' this is MUCH much faster than actually splitting
  if you're trying to figure out how many times a given subnet fits into
  a network.

README.adoc

@@ -50,7 +50,7 @@ A tool to assist in design of segregate/segment/split/subnet networks.
 **** If the `XDG_CACHE_HOME` environment variable is not present...
 ***** On macOS, an explicit fallback of `~/Library/Caches/subnetter/` will be used. (To my knowledge/understanding, this is the standard user cache directory and cannot be changed.) This usually evaluates to `/Users/<username>/Library/Caches/subnetter/`.
 ***** On all others, an explicit fallback of `~/.cache/subnetter` will be used.
-****** On most non-macOS \*NIX-like systems , this is usually `/home/<username>/.cache/subetter/`, provided normal user homes. On http://p9f.org/[Plan9^] platforms (e.g. https://9p.io/plan9/index.html[Plan 9 4th Ed.^], https://9front.org/[9front^], http://9legacy.org/[9legacy^]), the `/env/home` environment variable (`$home`) will be used, the `./lib/` subdirectory under there (which typically/should already exist) will be appended to it, and that appended with `./cache/subnetter/` (this usually evaluates to `/usr/<username>/lib/cache/subnetter/`).
+****** On most non-macOS/*NIX-like systems , this is usually `/home/<username>/.cache/subetter/`, provided normal user homes. On http://p9f.org/[Plan9^] platforms (e.g. https://9p.io/plan9/index.html[Plan 9 4th Ed.^], https://9front.org/[9front^], http://9legacy.org/[9legacy^]), the `/env/home` environment variable (`$home`) will be used, the `./lib/` subdirectory under there (which typically/should already exist) will be appended to it, and that appended with `./cache/subnetter/` (this usually evaluates to `/usr/<username>/lib/cache/subnetter/`).
 *** For Windows systems...
 **** If https://learn.microsoft.com/en-us/windows/win32/shell/knownfolderid#constants[the `LOCALAPPDATA` environment variable^] is present, it will be `%LOCALAPPDATA%\Cache\subnetter\` (or `${env:LOCALAPPDATA}\Cache\subnetter\` in Powershell syntax). This usually evaluates to `C:\Users\<username>\AppData\Local\Cache\subnetter\`.
 
@@ -61,3 +61,5 @@ This program in general draws inspiration from `ipcalc` (http://jodies.de/ipcalc
 The `table` subcommand is inspired by `iptab` from https://metacpan.org/pod/Net::IP[Perl Net-IP^].
 
 Additional notes for certain contexts are primarily taken from https://en.wikipedia.org/wiki/Classless_Inter-Domain_Routing[the Wikipedia article on _Classless Inter-Domain Routing_^] (as of _Jan 28, 2025_).
+
+Reservations are pulled/cached directly from the IANA registries (https://www.iana.org/assignments/iana-ipv4-special-registry/iana-ipv4-special-registry.xhtml[IPv4^], https://www.iana.org/assignments/iana-ipv6-special-registry/iana-ipv6-special-registry.xhtml[IPv6^]).

TODO

@@ -1 +1,7 @@
-- add table rendering for reserved networks?
+- add table rendering for reserved networks?
+
+- when checking/rendering reserved networks, currently the footnotes aren't returned.
+-- netsplit.IANARegistryFootnote
+-- encapsulated in the IANARegistry.Footnotes
+
+- split-hosts returns the entire original subnet as an unallocated subnet if hosts exceed the number of assignable addrs.

cmd/subnetter/args.go

@@ -5,8 +5,9 @@ type Args struct {
 	SplitCIDR       SplitCIDRArgs   `command:"split-cidr" alias:"se" description:"Split a network into as many equal subnets of prefix size N as possible." validate:"omitempty"`
 	SplitHost       SplitHostArgs   `command:"split-hosts" alias:"sh" description:"Split a network into N total number of hosts *per subnet* as cleanly/evenly as possible. (VERY easy to run out of memory for IPv6 prefixes; be sure to specify very small network!)" validate:"omitempty"`
 	SplitSubnets    SplitSubnetArgs `command:"split-nets" alias:"sn" description:"Split a network into N number of subnets as cleanly as possible." validate:"omitempty"`
-	VLSM            VLSMArgs        `command:"vlsm" alias:"sv" description:"Use VLSM (Variable-Length Subnet Masks) to split a network into differently sized subnets." validate:"omitempty"`
-	ExplicitNetwork XNetArgs        `command:"net" alias:"xn" description:"Print information about an explicit network address." validate:"omitempty"`
+	VLSM            VLSMArgs        `command:"split-vlsm" alias:"sv" alias:"vlsm" description:"Use VLSM (Variable-Length Subnet Masks) to split a network into differently sized subnets." validate:"omitempty"`
+	ExplicitNetwork XNetArgs        `command:"net" alias:"xn" alias:"net" description:"Print information about an explicit network address." validate:"omitempty"`
+	NumNets         NNetArgs        `command:"num-nets" alias:"nn" alias:"nets" description:"Return the number of subnets of a given size that can fit into a given network size. This is MUCH, MUCH FASTER than splitting (if you do not need addressing)." validate:"omitempty"`
 	Parse           ParseArgs       `command:"parse" alias:"p" alias:"read" alias:"convert" description:"Parse/convert output from a previous subnetter run." validate:"omitempty"`
 	Table           TableArgs       `command:"table" alias:"t" alias:"tab" alias:"tbl" description:"Show prefix summaries (by default both IPv4 and IPv6)." validate:"omitempty"`
 	Check           CheckArgs       `command:"reserved" alias:"r" description:"Check if a subnet is reserved per IANA/RFC." validate:"omitempty"`
@@ -16,7 +17,7 @@ type verArgs struct {
 	DetailVersion bool `short:"V" long:"detail" description:"Print detailed version info and exit."`
 }
 
-type common struct {
+type commonBase struct {
 	cacheArgs
 	SuppressRemaining bool   `short:"r" long:"no-remaining" description:"Don't show leftover/unallocated/remaining space."`
 	Plain             bool   `short:"p" long:"plain" description:"Show plain output instead of unicode (only used if -f/--format=pretty)."`
@@ -26,7 +27,11 @@ type common struct {
 	AllowReserved     bool   `short:"R" long:"allow-reserved" description:"If specified, do not warn about reserved IP addresses/networks."`
 	reservedArgs
 	AllowHostNet bool `short:"H" long:"allow-host" description:"If specified, do not warn about host bits. Host bits are always removed for subnetting (as otherwise there would be errors); this is only used only for output."`
-	Network      Net  `positional-args:"yes" required:"true" description:"The network/parent prefix to operate on." validate:"required"`
+}
+
+type common struct {
+	commonBase
+	Network Net `positional-args:"yes" required:"true" description:"The network/parent prefix to operate on." validate:"required"`
 }
 
 type reservedArgs struct {
@@ -44,8 +49,17 @@ type cacheArgs struct {
 	DoResCache bool   `short:"c" long:"cache-reservations" env:"SBNTR_RSVCACHE" description:"Enable caching/cache lookup for reservation data."`
 }
 
+type NNetArgs struct {
+	Verbose   bool `short:"v" long:"verbose" description:"Be verbose (more ideal for logging)."`
+	NoV6Check bool `short:"6" long:"no-v6" description:"If specified, do not indicate if the subnetting is IPv6 only (true) or not (false; dual-stack/IPv4 supported)."`
+	Sizes     struct {
+		SubnetSize  uint8 `required:"1" validate:"required,le=128,gtefield=NetworkSize"`
+		NetworkSize uint8 `required:"1" validate:"required,le=128,ltefield=SubnetSize"`
+	} `positional-args:"yes" required:"2" validate:"required"`
+}
+
 type ParseArgs struct {
-	splitArgs
+	commonBase
 	InFile string `short:"i" long:"input" default:"-" description:"Input file to parse. Default is '-' (for STDIN)." required:"true" validate:"required,filepath|eq=-"`
 }
 

cmd/subnetter/errs.go

@@ -5,5 +5,6 @@ import (
 )
 
 var (
+	ErrBadFmt error = errors.New("unknown output format")
 	errBadNet error = errors.New("bad inet/addr family/version")
 )

cmd/subnetter/funcs.go

@@ -236,7 +236,9 @@ func printNets(orig *netip.Prefix, origNet *net.IPNet, nets []*netip.Prefix, rem
 
 	if args == nil {
 		args = &common{
-			Separator: "\n",
+			commonBase: commonBase{
+				Separator: "\n",
+			},
 		}
 	}
 	fmts = sectFmts[args.Plain]
@@ -471,7 +473,180 @@ func printNets(orig *netip.Prefix, origNet *net.IPNet, nets []*netip.Prefix, rem
 	return
 }
 
-func printReserved(nets []*netip.Prefix, remaining *netipx.IPSet, args *common) (err error) {
+func printReserved(records map[netip.Prefix]*netsplit.IANAAddrNetResRecord, origNet netip.Prefix, plain bool, fmtType string) (err error) {
+
+	var b []byte
+	var idx int
+	var pfx netip.Prefix
+	var rec *netsplit.IANAAddrNetResRecord
+	var sortedKeys []netip.Prefix
+	var sb = new(strings.Builder)
+
+	switch fmtType {
+	case "json":
+		if b, err = json.MarshalIndent(records, "", "  "); err != nil {
+			return
+		}
+		fmt.Println(string(b))
+		return
+	case "xml":
+		if b, err = xml.MarshalIndent(records, "", "  "); err != nil {
+			return
+		}
+		fmt.Println(string(b))
+		return
+	case "yml", "yaml":
+		if b, err = yaml.Marshal(records); err != nil {
+			return
+		}
+		fmt.Println(string(b))
+		return
+	}
+
+	if fmtType != "pretty" {
+		err = ErrBadFmt
+		return
+	}
+
+	if records == nil || len(records) == 0 {
+		fmt.Println("No IANA/IETF/RFC-reserved subnet(s) found.")
+		return
+	}
+
+	sortedKeys = make([]netip.Prefix, len(records))
+	idx = 0
+	for pfx, _ = range records {
+		sortedKeys[idx] = pfx
+		idx++
+	}
+	sort.SliceStable(
+		sortedKeys,
+		func(i, j int) (isBefore bool) {
+			isBefore = (netipx.ComparePrefix(sortedKeys[i], sortedKeys[j])) <= 0
+			return
+		},
+	)
+
+	fmt.Fprintf(sb, "= %s =\n", origNet.String())
+	for _, pfx = range sortedKeys {
+		rec = records[pfx]
+		fmt.Fprint(sb, sectFmts[plain][0]+"\n")
+		// Name
+		fmt.Fprintf(sb, "Reservation Name:\t%s\n", rec.Name)
+		fmt.Fprint(sb, "\t"+sectFmts[plain][1]+"\n")
+		// Networks
+		fmt.Fprint(sb, "\tCanonical Reserved Networks:")
+		if rec.Networks != nil {
+			fmt.Fprint(sb, "\n")
+			for _, recPfx := range rec.Networks.Prefixes {
+				fmt.Fprint(sb, "\t\t"+sectFmts[plain][2]+"\n")
+				fmt.Fprintf(sb, "\t\t%s\n", recPfx.String())
+				// TODO: Print footnotes/refs!
+			}
+		} else {
+			fmt.Fprint(sb, "\t(N/A)\n")
+		}
+		fmt.Fprint(sb, "\t"+sectFmts[plain][1]+"\n")
+		// Reference/Specification
+		fmt.Fprint(sb, "\tSpecification:")
+		if rec.Spec != nil {
+			fmt.Fprint(sb, "\n")
+			for _, line := range strings.Split(rec.Spec.Text, "\n") {
+				fmt.Fprint(sb, "\t\t"+line+"\n")
+			}
+			if rec.Spec.References != nil {
+				fmt.Fprintf(sb, "\t\t%s\n", sectFmts[plain][2])
+				for rIdx, recref := range rec.Spec.References {
+					if recref != nil {
+						fmt.Fprintf(sb, "\t\t[%d] (%s) %s\n", rIdx, recref.Type, recref.Reference)
+					}
+				}
+			}
+		} else {
+			fmt.Fprint(sb, "\t(None)\n")
+		}
+		fmt.Fprint(sb, "\t"+sectFmts[plain][1]+"\n")
+		// Allocated (always present)
+		fmt.Fprintf(sb, "\tAllocated:\t%s\n", time.Time(rec.Allocation).String())
+		// fmt.Fprint(sb, "\t"+sectFmts[plain][1]+"\n")
+		// Updated
+		fmt.Fprint(sb, "\tUpdated:\t")
+		if rec.Updated != nil {
+			fmt.Fprintf(sb, "%s\n", time.Time(*rec.Updated).String())
+		} else {
+			fmt.Fprint(sb, "(N/A)\n")
+		}
+		// fmt.Fprint(sb, "\t"+sectFmts[plain][1]+"\n")
+		// Termination
+		fmt.Fprint(sb, "\tTerminated:\t")
+		if rec.Termination != nil {
+			fmt.Fprintf(sb, "%s\n", time.Time(*rec.Termination).String())
+		} else {
+			fmt.Fprint(sb, "(N/A)\n")
+		}
+		fmt.Fprint(sb, "\t"+sectFmts[plain][1]+"\n")
+		// Source
+		fmt.Fprint(sb, "\tValid Source:\t\t\t")
+		if rec.Source != nil {
+			if rec.Source.Applicable != nil && !bool(*rec.Source.Applicable) {
+				fmt.Fprint(sb, "(N/A)\n")
+			} else {
+				fmt.Fprintf(sb, "%v\n", bool(*rec.Source.Evaluated))
+			}
+		} else {
+			fmt.Fprint(sb, "(N/A)\n")
+		}
+		// fmt.Fprint(sb, "\t"+sectFmts[plain][1]+"\n")
+		// Destination
+		fmt.Fprint(sb, "\tValid Destination:\t\t")
+		if rec.Dest != nil {
+			if rec.Dest.Applicable != nil && !bool(*rec.Dest.Applicable) {
+				fmt.Fprint(sb, "(N/A)\n")
+			} else {
+				fmt.Fprintf(sb, "%v\n", bool(*rec.Dest.Evaluated))
+			}
+		} else {
+			fmt.Fprint(sb, "(N/A)\n")
+		}
+		// fmt.Fprint(sb, "\t"+sectFmts[plain][1]+"\n")
+		// Forwardable
+		fmt.Fprint(sb, "\tForwardable:\t\t\t")
+		if rec.Forwardable != nil {
+			if rec.Forwardable.Applicable != nil && !bool(*rec.Forwardable.Applicable) {
+				fmt.Fprint(sb, "(N/A)\n")
+			} else {
+				fmt.Fprintf(sb, "%v\n", bool(*rec.Forwardable.Evaluated))
+			}
+		} else {
+			fmt.Fprint(sb, "(N/A)\n")
+		}
+		// fmt.Fprint(sb, "\t"+sectFmts[plain][1]+"\n")
+		// Globally reachable
+		fmt.Fprint(sb, "\tGlobally Routable/Reachable:\t")
+		if rec.GlobalReach != nil {
+			if rec.GlobalReach.Applicable != nil && !bool(*rec.GlobalReach.Applicable) {
+				fmt.Fprint(sb, "(N/A)\n")
+			} else {
+				fmt.Fprintf(sb, "%v\n", bool(*rec.GlobalReach.Evaluated))
+			}
+		} else {
+			fmt.Fprint(sb, "(N/A)\n")
+		}
+		// fmt.Fprint(sb, "\t"+sectFmts[plain][1]+"\n")
+		// Reserved by Protocol
+		fmt.Fprint(sb, "\tReserved by Protocol:\t\t")
+		if rec.ProtoReserved != nil {
+			if rec.ProtoReserved.Applicable != nil && !bool(*rec.ProtoReserved.Applicable) {
+				fmt.Fprint(sb, "(N/A)\n")
+			} else {
+				fmt.Fprintf(sb, "%v\n", bool(*rec.ProtoReserved.Evaluated))
+			}
+		} else {
+			fmt.Fprint(sb, "(N/A)\n")
+		}
+	}
+
+	fmt.Print(sb.String())
 
 	return
 }

cmd/subnetter/main.go

@@ -33,8 +33,11 @@ func main() {
 	var remaining *netipx.IPSet
 	var buf *bytes.Buffer
 	var res *netsplit.StructuredResults
+	var numNets uint
+	var v6Only bool
 	var noStrict bool
 	var strictErr error
+	var reservations map[netip.Prefix]*netsplit.IANAAddrNetResRecord
 	var splitErr *netsplit.SplitErr = new(netsplit.SplitErr)
 	var parser *flags.Parser = flags.NewParser(args, flags.Default)
 
@@ -78,8 +81,47 @@ func main() {
 			log.Panicln(err)
 		}
 		return
+	case "num-nets":
+		if numNets, v6Only, err = netsplit.NumNets(
+			args.NumNets.Sizes.SubnetSize,
+			args.NumNets.Sizes.NetworkSize,
+		); err != nil {
+			log.Panicln(err)
+		}
+		if !args.NumNets.Verbose {
+			fmt.Printf("%d\n", numNets)
+			if !args.NumNets.NoV6Check {
+				fmt.Println(v6Only)
+			}
+		} else {
+			fmt.Printf("Network Size:\t\t\t%d\n", args.NumNets.Sizes.NetworkSize)
+			fmt.Printf("Subnet Size:\t\t\t%d\n", args.NumNets.Sizes.SubnetSize)
+			fmt.Printf("Number of Subnets:\t\t%d\n", numNets)
+			if !args.NumNets.NoV6Check {
+				fmt.Printf("Subnetting is IPv6-Only:\t%v\n", v6Only)
+			}
+		}
+		return
 	case "reserved":
-		// TODO
+		if origPfx, err = netip.ParsePrefix(args.Check.Network.Network); err != nil {
+			log.Panicln(err)
+		}
+		nets = make([]*netip.Prefix, 1)
+		nets[0] = new(netip.Prefix)
+		*nets[0] = origPfx
+		if err = netsplit.SetCachePath(args.Check.CacheDir); err != nil {
+			log.Panicln(err)
+		}
+		if err = netsplit.EnableCache(args.Check.DoResCache); err != nil {
+			log.Panicln(err)
+		}
+		if reservations, err = netsplit.CheckReserved(nets, !args.Check.NoRevRecursive, !args.Check.NoRecursive, !args.Check.NoPrivate); err != nil {
+			log.Panicln(err)
+		}
+		if err = printReserved(reservations, origPfx, args.Check.Plain, args.Check.Fmt); err != nil {
+			log.Panicln(err)
+		}
+		return
 	case "table":
 		// Account for a weird redundant CLI condition.
 		if args.Table.NoIpv4 && args.Table.NoIpv6 {
@@ -117,7 +159,12 @@ func main() {
 			origPfx = *resPfx
 		}
 		pfx = netipx.PrefixIPNet(origPfx.Masked())
-		cmnArgs = args.Parse.common
+		cmnArgs = common{
+			commonBase: args.Parse.commonBase,
+			Network: Net{
+				Network: res.Original.String(),
+			},
+		}
 		if err = printNets(&origPfx, pfx, nets, remaining, &cmnArgs, res.GetSplitter()); err != nil {
 			log.Panicln(err)
 		}
@@ -166,7 +213,7 @@ func main() {
 				PrefixLength: args.SplitCIDR.Prefix,
 				BaseSplitter: new(netsplit.BaseSplitter),
 			}
-		case "vlsm":
+		case "split-vlsm":
 			if err = validate.Struct(args.VLSM); err != nil {
 				log.Panicln(err)
 			}

netsplit/conts.go

@@ -8,6 +8,12 @@ import (
 	`github.com/go-resty/resty/v2`
 )
 
+const (
+	maxBitsv4 uint8 = 32
+	maxBitsv6 uint8 = 128
+	maxBits   uint8 = maxBitsv6
+)
+
 const (
 	cachedirEnvName string = "SBNTR_RSVCACHE_DIR"
 	// https://www.iana.org/assignments/iana-ipv4-special-registry/iana-ipv4-special-registry.xhtml

netsplit/funcs.go

@@ -4,6 +4,7 @@ import (
 	"encoding/json"
 	"encoding/xml"
 	"fmt"
+	`math`
 	"net"
 	"net/netip"
 	"strings"
@@ -375,6 +376,38 @@ func MaskInvert(mask net.IPMask) (inverted net.IPMask) {
 	return
 }
 
+/*
+	NumNets returns the number of times prefix size subnet fits into prefix size network.
+
+	It will error if network is larger than 128 or if subnet is smaller than network.
+
+	This is MUCH more performant than splitting out an actual network into explicit subnets,
+	and does not require an actual network.
+*/
+func NumNets(subnet, network uint8) (numNets uint, ipv6Only bool, err error) {
+
+	var x float64
+
+	// network cannot be higher than 128, as that's the maximum for IPv6.
+	if network > maxBits {
+		err = ErrBadPrefixLen
+		return
+	}
+	if subnet < network {
+		err = ErrBigPrefix
+		return
+	}
+	if network > maxBitsv4 {
+		ipv6Only = true
+	}
+
+	x = float64(subnet - network)
+
+	numNets = uint(math.Pow(2, x))
+
+	return
+}
+
 // Parse parses b for JSON/XML/YAML and tries to return a StructuredResults from it.
 func Parse(b []byte) (s *StructuredResults, err error) {
 

netsplit/funcs_cache.go

@@ -195,6 +195,7 @@ func SetCachePath(cacheDirPath string) (err error) {
 	}
 
 	if cacheDirPath != oldPath {
+		cacheDir = cacheDirPath
 		if err = os.MkdirAll(cacheDir, cacheDirPerms); err != nil {
 			return
 		}

netsplit/funcs_cidrsplitter.go

@@ -31,7 +31,7 @@ func (c *CIDRSplitter) Split() (nets []*netip.Prefix, remaining *netipx.IPSet, e
 		return
 	}
 
-	if c.PrefixLength > uint8(base.Bits()) {
+	if c.PrefixLength < uint8(base.Bits()) {
 		err = ErrBigPrefix
 		return
 	}
@@ -48,10 +48,10 @@ func (c *CIDRSplitter) Split() (nets []*netip.Prefix, remaining *netipx.IPSet, e
 				// We just hit the end of the prefix.
 				break
 			}
-			subPtr = new(netip.Prefix)
-			*subPtr = sub
-			nets = append(nets, subPtr)
 		}
+		subPtr = new(netip.Prefix)
+		*subPtr = sub
+		nets = append(nets, subPtr)
 	}
 
 	return