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