github.com/anth0d/nomad@v0.0.0-20221214183521-ae3a0a2cad06/website/content/docs/job-specification/hcl2/functions/ipnet/cidrsubnet.mdx (about) 1 --- 2 layout: docs 3 page_title: cidrsubnet - Functions - Configuration Language 4 description: |- 5 The cidrsubnet function calculates a subnet address within a given IP network 6 address prefix. 7 --- 8 9 # `cidrsubnet` Function 10 11 `cidrsubnet` calculates a subnet address within given IP network address prefix. 12 13 ```hcl 14 cidrsubnet(prefix, newbits, netnum) 15 ``` 16 17 `prefix` must be given in CIDR notation, as defined in 18 [RFC 4632 section 3.1](https://tools.ietf.org/html/rfc4632#section-3.1). 19 20 `newbits` is the number of additional bits with which to extend the prefix. 21 For example, if given a prefix ending in `/16` and a `newbits` value of 22 `4`, the resulting subnet address will have length `/20`. 23 24 `netnum` is a whole number that can be represented as a binary integer with 25 no more than `newbits` binary digits, which will be used to populate the 26 additional bits added to the prefix. 27 28 This function accepts both IPv6 and IPv4 prefixes, and the result always uses 29 the same addressing scheme as the given prefix. 30 31 Unlike the related function [`cidrsubnets`](/docs/job-specification/hcl2/functions/ipnet/cidrsubnets), `cidrsubnet` 32 allows you to give a specific network number to use. `cidrsubnets` can allocate 33 multiple network addresses at once, but numbers them automatically starting 34 with zero. 35 36 ## Examples 37 38 ```shell-session 39 > cidrsubnet("172.16.0.0/12", 4, 2) 40 172.18.0.0/16 41 > cidrsubnet("10.1.2.0/24", 4, 15) 42 10.1.2.240/28 43 > cidrsubnet("fd00:fd12:3456:7890::/56", 16, 162) 44 fd00:fd12:3456:7800:a200::/72 45 ``` 46 47 ## Netmasks and Subnets 48 49 Using `cidrsubnet` requires familiarity with some network addressing concepts. 50 51 The most important idea is that an IP address (whether IPv4 or IPv6) is 52 fundamentally constructed from binary digits, even though we conventionally 53 represent it as either four decimal octets (for IPv4) or a sequence of 16-bit 54 hexadecimal numbers (for IPv6). 55 56 Taking our example above of `cidrsubnet("10.1.2.0/24", 4, 15)`, the function 57 will first convert the given IP address string into an equivalent binary 58 representation: 59 60 ```text 61 10 . 1 . 2 . 0 62 00001010 00000001 00000010 | 00000000 63 network | host 64 ``` 65 66 The `/24` at the end of the prefix string specifies that the first 24 67 bits -- or, the first three octets -- of the address identify the network 68 while the remaining bits (32 - 24 = 8 bits in this case) identify hosts 69 within the network. 70 71 The CLI tool [`ipcalc`](https://gitlab.com/ipcalc/ipcalc) is useful for 72 visualizing CIDR prefixes as binary numbers. We can confirm the conversion 73 above by providing the same prefix string to `ipcalc`: 74 75 ```shell-session 76 $ ipcalc 10.1.2.0/24 77 Address: 10.1.2.0 00001010.00000001.00000010. 00000000 78 Netmask: 255.255.255.0 = 24 11111111.11111111.11111111. 00000000 79 Wildcard: 0.0.0.255 00000000.00000000.00000000. 11111111 80 => 81 Network: 10.1.2.0/24 00001010.00000001.00000010. 00000000 82 HostMin: 10.1.2.1 00001010.00000001.00000010. 00000001 83 HostMax: 10.1.2.254 00001010.00000001.00000010. 11111110 84 Broadcast: 10.1.2.255 00001010.00000001.00000010. 11111111 85 Hosts/Net: 254 Class A, Private Internet 86 ``` 87 88 This gives us some additional information but also confirms (using a slightly 89 different notation) the conversion from decimal to binary and shows the range 90 of possible host addresses in this network. 91 92 While [`cidrhost`](/docs/job-specification/hcl2/functions/ipnet/cidrhost) allows calculating single host IP addresses, 93 `cidrsubnet` on the other hand creates a new network prefix _within_ the given 94 network prefix. In other words, it creates a subnet. 95 96 When we call `cidrsubnet` we also pass two additional arguments: `newbits` and 97 `netnum`. `newbits` decides how much longer the resulting prefix will be in 98 bits; in our example here we specified `4`, which means that the resulting 99 subnet will have a prefix length of 24 + 4 = 28 bits. We can imagine these 100 bits breaking down as follows: 101 102 ```text 103 10 . 1 . 2 . ? 0 104 00001010 00000001 00000010 | XXXX | 0000 105 parent network | netnum | host 106 ``` 107 108 Four of the eight bits that were originally the "host number" are now being 109 repurposed as the subnet number. The network prefix no longer falls on an 110 exact octet boundary, so in effect we are now splitting the last decimal number 111 in the IP address into two parts, using half of it to represent the subnet 112 number and the other half to represent the host number. 113 114 The `netnum` argument then decides what number value to encode into those 115 four new subnet bits. In our current example we passed `15`, which is 116 represented in binary as `1111`, allowing us to fill in the `XXXX` segment 117 in the above: 118 119 ```text 120 10 . 1 . 2 . 15 0 121 00001010 00000001 00000010 | 1111 | 0000 122 parent network | netnum | host 123 ``` 124 125 To convert this back into normal decimal notation we need to recombine the 126 two portions of the final octet. Converting `11110000` from binary to decimal 127 gives 240, which can then be combined with our new prefix length of 28 to 128 produce the result `10.1.2.240/28`. Again we can pass this prefix string to 129 `ipcalc` to visualize it: 130 131 ```shell-session 132 $ ipcalc 10.1.2.240/28 133 Address: 10.1.2.240 00001010.00000001.00000010.1111 0000 134 Netmask: 255.255.255.240 = 28 11111111.11111111.11111111.1111 0000 135 Wildcard: 0.0.0.15 00000000.00000000.00000000.0000 1111 136 => 137 Network: 10.1.2.240/28 00001010.00000001.00000010.1111 0000 138 HostMin: 10.1.2.241 00001010.00000001.00000010.1111 0001 139 HostMax: 10.1.2.254 00001010.00000001.00000010.1111 1110 140 Broadcast: 10.1.2.255 00001010.00000001.00000010.1111 1111 141 Hosts/Net: 14 Class A, Private Internet 142 ``` 143 144 The new subnet has four bits available for host numbering, which means 145 that there are 14 host addresses available for assignment once we subtract 146 the network's own address and the broadcast address. You can thus use 147 [`cidrhost`](/docs/job-specification/hcl2/functions/ipnet/cidrhost) function to calculate those host addresses by 148 providing it a value between 1 and 14: 149 150 ```shell-session 151 > cidrhost("10.1.2.240/28", 1) 152 10.1.2.241 153 > cidrhost("10.1.2.240/28", 14) 154 10.1.2.254 155 ``` 156 157 For more information on CIDR notation and subnetting, see 158 [Classless Inter-domain Routing](https://en.wikipedia.org/wiki/Classless_Inter-Domain_Routing). 159 160 ## Related Functions 161 162 - [`cidrhost`](/docs/job-specification/hcl2/functions/ipnet/cidrhost) calculates the IP address for a single host 163 within a given network address prefix. 164 - [`cidrnetmask`](/docs/job-specification/hcl2/functions/ipnet/cidrnetmask) converts an IPv4 network prefix in CIDR 165 notation into netmask notation. 166 - [`cidrsubnets`](/docs/job-specification/hcl2/functions/ipnet/cidrsubnets) can allocate multiple consecutive 167 addresses under a prefix at once, numbering them automatically.