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