github.com/hairyhenderson/gomplate/v4@v4.0.0-pre-2.0.20240520121557-362f058f0c93/docs-src/content/functions/net.yml (about) 1 ns: net 2 preamble: | 3 The `net` namespace contains functions that can help deal with network-related 4 lookups and calculations. Some of these functions return specifically-typed 5 values that contain additional methods useful for formatting or further 6 calculations. 7 8 [RFC 4632]: http://tools.ietf.org/html/rfc4632 9 [RFC 4291]: http://tools.ietf.org/html/rfc4291 10 [`inet.af/netaddr`]: https://pkg.go.dev/inet.af/netaddr 11 [`net`]: https://pkg.go.dev/net 12 funcs: 13 - name: net.LookupIP 14 released: v1.9.0 15 description: | 16 Resolve an IPv4 address for a given host name. When multiple IP addresses 17 are resolved, the first one is returned. 18 pipeline: true 19 arguments: 20 - name: name 21 required: true 22 description: The hostname to look up. This can be a simple hostname, or a fully-qualified domain name. 23 examples: 24 - | 25 $ gomplate -i '{{ net.LookupIP "example.com" }}' 26 93.184.216.34 27 - name: net.LookupIPs 28 released: v1.9.0 29 description: | 30 Resolve all IPv4 addresses for a given host name. Returns an array of strings. 31 pipeline: true 32 arguments: 33 - name: name 34 required: true 35 description: The hostname to look up. This can be a simple hostname, or a fully-qualified domain name. 36 examples: 37 - | 38 $ gomplate -i '{{ join (net.LookupIPs "twitter.com") "," }}' 39 104.244.42.65,104.244.42.193 40 - name: net.LookupCNAME 41 released: v1.9.0 42 description: | 43 Resolve the canonical name for a given host name. This does a DNS lookup for the 44 `CNAME` record type. If no `CNAME` is present, a canonical form of the given name 45 is returned -- e.g. `net.LookupCNAME "localhost"` will return `"localhost."`. 46 pipeline: true 47 arguments: 48 - name: name 49 required: true 50 description: The hostname to look up. This can be a simple hostname, or a fully-qualified domain name. 51 examples: 52 - | 53 $ gomplate -i '{{ net.LookupCNAME "www.amazon.com" }}' 54 d3ag4hukkh62yn.cloudfront.net. 55 - name: net.LookupSRV 56 released: v1.9.0 57 description: | 58 Resolve a DNS [`SRV` service record](https://en.wikipedia.org/wiki/SRV_record). 59 This implementation supports the canonical [RFC2782](https://tools.ietf.org/html/rfc2782) 60 form (i.e. `_Service._Proto.Name`), but other forms are also supported, such as 61 those served by [Consul's DNS interface](https://www.consul.io/docs/agent/dns.html#standard-lookup). 62 63 When multiple records are returned, this function returns the first. 64 65 A [`net.SRV`](https://golang.org/pkg/net/#SRV) data structure is returned. The 66 following properties are available: 67 - `Target` - _(string)_ the hostname where the service can be reached 68 - `Port` - _(uint16)_ the service's port 69 - `Priority`, `Weight` - see [RFC2782](https://tools.ietf.org/html/rfc2782) for details 70 pipeline: true 71 arguments: 72 - name: name 73 required: true 74 description: The service name to look up 75 examples: 76 - | 77 $ gomplate -i '{{ net.LookupSRV "_sip._udp.sip.voice.google.com" | toJSONPretty " " }}' 78 { 79 "Port": 5060, 80 "Priority": 10, 81 "Target": "sip-anycast-1.voice.google.com.", 82 "Weight": 1 83 } 84 - name: net.LookupSRVs 85 released: v1.9.0 86 description: | 87 Resolve a DNS [`SRV` service record](https://en.wikipedia.org/wiki/SRV_record). 88 This implementation supports the canonical [RFC2782](https://tools.ietf.org/html/rfc2782) 89 form (i.e. `_Service._Proto.Name`), but other forms are also supported, such as 90 those served by [Consul's DNS interface](https://www.consul.io/docs/agent/dns.html#standard-lookup). 91 92 This function returns all available SRV records. 93 94 An array of [`net.SRV`](https://golang.org/pkg/net/#SRV) data structures is 95 returned. For each element, the following properties are available: 96 - `Target` - _(string)_ the hostname where the service can be reached 97 - `Port` - _(uint16)_ the service's port 98 - `Priority`, `Weight` - see [RFC2782](https://tools.ietf.org/html/rfc2782) for details 99 pipeline: true 100 arguments: 101 - name: name 102 required: true 103 description: The hostname to look up. This can be a simple hostname, or a fully-qualified domain name. 104 rawExamples: 105 - | 106 _input.tmpl:_ 107 ``` 108 {{ range (net.LookupSRVs "_sip._udp.sip.voice.google.com") -}} 109 priority={{.Priority}}/port={{.Port}} 110 {{- end }} 111 ``` 112 113 ```console 114 $ gomplate -f input.tmpl 115 priority=10/port=5060 116 priority=20/port=5060 117 ``` 118 - name: net.LookupTXT 119 released: v1.9.0 120 description: | 121 Resolve a DNS [`TXT` record](https://en.wikipedia.org/wiki/SRV_record). 122 123 This function returns all available TXT records as an array of strings. 124 pipeline: true 125 arguments: 126 - name: name 127 required: true 128 description: The host name to look up 129 examples: 130 - | 131 $ gomplate -i '{{net.LookupTXT "example.com" | data.ToJSONPretty " " }}' 132 [ 133 "v=spf1 -all" 134 ] 135 - name: net.ParseAddr 136 # released: v4.0.0 137 description: | 138 Parse the given string as an IP address (a 139 [`netip.Addr`](https://pkg.go.dev/net/netip#Addr)). 140 141 Any of `netip.Addr`'s methods may be called on the resulting value. See 142 [the docs](https://pkg.go.dev/net/netip#Addr) for details. 143 pipeline: true 144 arguments: 145 - name: addr 146 required: true 147 description: The IP string to parse. It must be either an IPv4 or IPv6 address. 148 examples: 149 - | 150 $ gomplate -i '{{ (net.ParseAddr "192.168.0.1").IsPrivate }}' 151 true 152 $ gomplate -i '{{ $ip := net.ParseAddr (net.LookupIP "example.com") -}} 153 {{ $ip.Prefix 12 }}' 154 93.176.0.0/12 155 - name: net.ParseIP 156 released: v3.10.0 157 deprecated: Use [`net.ParseAddr`](#net-parseaddr) instead. 158 description: | 159 Parse the given string as an IP address (a `netaddr.IP` from the 160 [`inet.af/netaddr`](https://pkg.go.dev/inet.af/netaddr) package). 161 162 Any of `netaddr.IP`'s methods may be called on the resulting value. See 163 [the docs](https://pkg.go.dev/inet.af/netaddr) for details. 164 pipeline: true 165 arguments: 166 - name: ip 167 required: true 168 description: The IP string to parse. It must be either an IPv4 or IPv6 address. 169 examples: 170 - | 171 $ gomplate -i '{{ (net.ParseIP "192.168.0.1").IsPrivate }}' 172 true 173 $ gomplate -i '{{ $ip := net.ParseIP (net.LookupIP "example.com") -}} 174 {{ $ip.Prefix 12 }}' 175 93.176.0.0/12 176 - name: net.ParsePrefix 177 # released: v4.0.0 178 description: | 179 Parse the given string as an IP address prefix (CIDR) representing an IP 180 network (a [`netip.Prefix`](https://pkg.go.dev/net/netip#Prefix)). 181 182 The string can be in the form `"192.168.1.0/24"` or `"2001::db8::/32"`, 183 the CIDR notations defined in [RFC 4632][] and [RFC 4291][]. 184 185 Any of `netip.Prefix`'s methods may be called on the resulting value. See 186 [the docs](https://pkg.go.dev/net/netip#Prefix) for details. 187 pipeline: true 188 arguments: 189 - name: prefix 190 required: true 191 description: The IP address prefix to parse. It must represent either an IPv4 or IPv6 prefix, containing a `/`. 192 examples: 193 - | 194 $ gomplate -i '{{ (net.ParsePrefix "192.168.0.0/24").Range }}' 195 192.168.0.0-192.168.0.255 196 $ gomplate -i '{{ $ip := net.ParseAddr (net.LookupIP "example.com") -}} 197 {{ $net := net.ParsePrefix "93.184.0.0/16" -}} 198 {{ $net.Contains $ip }}' 199 true 200 - name: net.ParseIPPrefix 201 released: v3.10.0 202 deprecated: Use [`net.ParsePrefix`](#net-parseprefix) instead. 203 description: | 204 Parse the given string as an IP address prefix (CIDR) representing an IP 205 network (a `netaddr.IPPrefix` from the 206 [`inet.af/netaddr`][] package). 207 208 The string can be in the form `"192.168.1.0/24"` or `"2001::db8::/32"`, 209 the CIDR notations defined in [RFC 4632][] and [RFC 4291][]. 210 211 Any of `netaddr.IPPrefix`'s methods may be called on the resulting value. 212 See [the docs][`inet.af/netaddr`] for details. 213 pipeline: true 214 arguments: 215 - name: ipprefix 216 required: true 217 description: The IP address prefix to parse. It must represent either an IPv4 or IPv6 prefix, containing a `/`. 218 examples: 219 - | 220 $ gomplate -i '{{ (net.ParseIPPrefix "192.168.0.0/24").Range }}' 221 192.168.0.0-192.168.0.255 222 $ gomplate -i '{{ $ip := net.ParseIP (net.LookupIP "example.com") -}} 223 {{ $net := net.ParseIPPrefix "93.184.0.0/16" -}} 224 {{ $net.Contains $ip }}' 225 true 226 $ gomplate -i '{{ $net := net.ParseIPPrefix "93.184.0.0/12" -}} 227 {{ $net.Range }}' 228 93.176.0.0-93.191.255.255 229 - name: net.ParseRange 230 experimental: true 231 # released: v4.0.0 232 description: | 233 Parse the given string as an inclusive range of IP addresses from the same 234 address family (a [`netipx.IPRange`](https://pkg.go.dev/go4.org/netipx#IPRange) 235 from the [`go4.org/netipx`](https://pkg.go.dev/go4.org/netipx) module). 236 237 The string must contain a hyphen (`-`). 238 239 Any of `netipx.IPRange`'s methods may be called on the resulting value. 240 See [the docs](https://pkg.go.dev/go4.org/netipx#IPRange) for details. 241 242 Note that this function is experimental for now, because it uses a 243 [third-party module](https://pkg.go.dev/go4.org/netipx) which may be 244 brought into the standard library in the future, which may require 245 breaking changes to this function. 246 pipeline: true 247 arguments: 248 - name: iprange 249 required: true 250 description: The IP address range to parse. It must represent either an IPv4 or IPv6 range, containing a `-`. 251 examples: 252 - | 253 $ gomplate -i '{{ (net.ParseRange "192.168.0.0-192.168.0.255").To }}' 254 192.168.0.255 255 $ gomplate -i '{{ $range := net.ParseRange "1.2.3.0-1.2.3.233" -}} 256 {{ $range.Prefixes }}' 257 [1.2.3.0/25 1.2.3.128/26 1.2.3.192/27 1.2.3.224/29 1.2.3.232/31] 258 - name: net.ParseIPRange 259 released: v3.10.0 260 deprecated: Use [`net.ParseRange`](#net-parserange) instead. 261 description: | 262 Parse the given string as an inclusive range of IP addresses from the same 263 address family (a `netaddr.IPRange` from the [`inet.af/netaddr`][] package). 264 265 The string must contain a hyphen (`-`). 266 267 Any of `netaddr.IPRange`'s methods may be called on the resulting value. 268 See [the docs][`inet.af/netaddr`] for details. 269 pipeline: true 270 arguments: 271 - name: iprange 272 required: true 273 description: The IP address range to parse. It must represent either an IPv4 or IPv6 range, containing a `-`. 274 examples: 275 - | 276 $ gomplate -i '{{ (net.ParseIPRange "192.168.0.0-192.168.0.255").To }}' 277 192.168.0.255 278 $ gomplate -i '{{ $range := net.ParseIPRange "1.2.3.0-1.2.3.233" -}} 279 {{ $range.Prefixes }}' 280 [1.2.3.0/25 1.2.3.128/26 1.2.3.192/27] 281 - name: net.CIDRHost 282 experimental: true 283 released: v3.11.0 284 description: | 285 Calculates a full host IP address for a given host number within a given IP network address prefix. 286 287 The IP network can be in the form `"192.168.1.0/24"` or `"2001::db8::/32"`, 288 the CIDR notations defined in [RFC 4632][] and [RFC 4291][]. 289 290 Any of `netip.Addr`'s methods may be called on the resulting value. See 291 [the docs](https://pkg.go.dev/net/netip#Addr) for details. 292 pipeline: true 293 arguments: 294 - name: hostnum 295 required: true 296 description: Is a whole number that can be represented as a binary integer with no more than the number of digits remaining in the address after the given prefix. 297 - name: prefix 298 required: true 299 description: Must be given in CIDR notation. It must represent either an IPv4 or IPv6 prefix, containing a `/`. String or [`net.IPNet`](https://pkg.go.dev/net#IPNet) object returned from `net.ParseIPPrefix` can by used. 300 examples: 301 - | 302 $ gomplate -i '{{ "10.12.127.0/20" | net.CIDRHost 268 }}' 303 10.12.113.12 304 - name: net.CIDRNetmask 305 experimental: true 306 released: v3.11.0 307 description: | 308 The result is a subnet address formatted in the conventional dotted-decimal IPv4 address syntax or hexadecimal IPv6 address syntax, as expected by some software. 309 310 Any of `netip.Addr`'s methods may be called on the resulting value. See 311 [the docs](https://pkg.go.dev/net/netip#Addr) for details. 312 pipeline: true 313 arguments: 314 - name: prefix 315 required: true 316 description: Must be given in CIDR notation. It must represent either an IPv4 or IPv6 prefix, containing a `/`. String or [`net.IPNet`](https://pkg.go.dev/net#IPNet) object returned from `net.ParseIPPrefix` can by used. 317 examples: 318 - | 319 $ gomplate -i '{{ net.CIDRNetmask "10.12.127.0/20" }}' 320 255.255.240.0 321 $ gomplate -i '{{ net.CIDRNetmask "fd00:fd12:3456:7890:00a2::/72" }}' 322 ffff:ffff:ffff:ffff:ff00:: 323 - name: net.CIDRSubnets 324 experimental: true 325 released: v3.11.0 326 description: | 327 Calculates a subnet address within given IP network address prefix. 328 329 Any of `netip.Prefix`'s methods may be called on the resulting values. See 330 [the docs](https://pkg.go.dev/net/netip#Prefix) for details. 331 pipeline: true 332 arguments: 333 - name: newbits 334 required: true 335 description: Is the number of additional bits with which to extend the prefix. For example, if given a prefix ending in `/16` and a `newbits` value of `4`, the resulting subnet address will have length `/20`. 336 - name: prefix 337 required: true 338 description: Must be given in CIDR notation. It must represent either an IPv4 or IPv6 prefix, containing a `/`. String or [`net.IPNet`](https://pkg.go.dev/net#IPNet) object returned from `net.ParseIPPrefix` can by used. 339 examples: 340 - | 341 $ gomplate -i '{{ index ("10.0.0.0/16" | net.CIDRSubnets 2) 1 }}' 342 10.0.64.0/18 343 $ gomplate -i '{{ net.CIDRSubnets 2 "10.0.0.0/16" -}}' 344 [10.0.0.0/18 10.0.64.0/18 10.0.128.0/18 10.0.192.0/18] 345 - name: net.CIDRSubnetSizes 346 experimental: true 347 released: v3.11.0 348 description: | 349 Calculates a sequence of consecutive IP address ranges within a particular CIDR prefix. 350 351 Any of `netip.Prefix`'s methods may be called on the resulting values. See 352 [the docs](https://pkg.go.dev/net/netip#Prefix) for details. 353 pipeline: true 354 arguments: 355 - name: newbits... 356 required: true 357 description: Numbers of additional network prefix bits for returned address range. 358 - name: prefix 359 required: true 360 description: Must be given in CIDR notation. It must represent either an IPv4 or IPv6 prefix, containing a `/`. String or [`net.IPNet`](https://pkg.go.dev/net#IPNet) object returned from `net.ParseIPPrefix` can by used. 361 examples: 362 - | 363 $ gomplate -i '{{ net.CIDRSubnetSizes 4 4 8 4 "10.1.0.0/16" -}}' 364 [10.1.0.0/20 10.1.16.0/20 10.1.32.0/24 10.1.48.0/20]