path: root/docs-src/content/functions/net.yml

ns: net
preamble: |
  The `net` namespace contains functions that can help deal with network-related
  lookups and calculations. Some of these functions return specifically-typed
  values that contain additional methods useful for formatting or further
  calculations.

  [RFC 4632]: http://tools.ietf.org/html/rfc4632
  [RFC 4291]: http://tools.ietf.org/html/rfc4291
  [`inet.af/netaddr`]: https://pkg.go.dev/inet.af/netaddr
  [`net`]: https://pkg.go.dev/net
funcs:
  - name: net.LookupIP
    released: v1.9.0
    description: |
      Resolve an IPv4 address for a given host name. When multiple IP addresses
      are resolved, the first one is returned.
    pipeline: true
    arguments:
      - name: name
        required: true
        description: The hostname to look up. This can be a simple hostname, or a fully-qualified domain name.
    examples:
      - |
        $ gomplate -i '{{ net.LookupIP "example.com" }}'
        93.184.216.34
  - name: net.LookupIPs
    released: v1.9.0
    description: |
      Resolve all IPv4 addresses for a given host name. Returns an array of strings.
    pipeline: true
    arguments:
      - name: name
        required: true
        description: The hostname to look up. This can be a simple hostname, or a fully-qualified domain name.
    examples:
      - |
        $ gomplate -i '{{ join (net.LookupIPs "twitter.com") "," }}'
        104.244.42.65,104.244.42.193
  - name: net.LookupCNAME
    released: v1.9.0
    description: |
      Resolve the canonical name for a given host name. This does a DNS lookup for the
      `CNAME` record type. If no `CNAME` is present, a canonical form of the given name
      is returned -- e.g. `net.LookupCNAME "localhost"` will return `"localhost."`.
    pipeline: true
    arguments:
      - name: name
        required: true
        description: The hostname to look up. This can be a simple hostname, or a fully-qualified domain name.
    examples:
      - |
        $ gomplate -i '{{ net.LookupCNAME "www.amazon.com" }}'
        d3ag4hukkh62yn.cloudfront.net.
  - name: net.LookupSRV
    released: v1.9.0
    description: |
      Resolve a DNS [`SRV` service record](https://en.wikipedia.org/wiki/SRV_record).
      This implementation supports the canonical [RFC2782](https://tools.ietf.org/html/rfc2782)
      form (i.e. `_Service._Proto.Name`), but other forms are also supported, such as
      those served by [Consul's DNS interface](https://www.consul.io/docs/agent/dns.html#standard-lookup).

      When multiple records are returned, this function returns the first.

      A [`net.SRV`](https://golang.org/pkg/net/#SRV) data structure is returned. The
      following properties are available:
      - `Target` - _(string)_ the hostname where the service can be reached
      - `Port` - _(uint16)_ the service's port
      - `Priority`, `Weight` - see [RFC2782](https://tools.ietf.org/html/rfc2782) for details
    pipeline: true
    arguments:
      - name: name
        required: true
        description: The service name to look up
    examples:
      - |
        $ gomplate -i '{{ net.LookupSRV "_sip._udp.sip.voice.google.com" | toJSONPretty "  " }}'
        {
          "Port": 5060,
          "Priority": 10,
          "Target": "sip-anycast-1.voice.google.com.",
          "Weight": 1
        }
  - name: net.LookupSRVs
    released: v1.9.0
    description: |
      Resolve a DNS [`SRV` service record](https://en.wikipedia.org/wiki/SRV_record).
      This implementation supports the canonical [RFC2782](https://tools.ietf.org/html/rfc2782)
      form (i.e. `_Service._Proto.Name`), but other forms are also supported, such as
      those served by [Consul's DNS interface](https://www.consul.io/docs/agent/dns.html#standard-lookup).

      This function returns all available SRV records.

      An array of [`net.SRV`](https://golang.org/pkg/net/#SRV) data structures is
      returned. For each element, the following properties are available:
      - `Target` - _(string)_ the hostname where the service can be reached
      - `Port` - _(uint16)_ the service's port
      - `Priority`, `Weight` - see [RFC2782](https://tools.ietf.org/html/rfc2782) for details
    pipeline: true
    arguments:
      - name: name
        required: true
        description: The hostname to look up. This can be a simple hostname, or a fully-qualified domain name.
    rawExamples:
      - |
        _input.tmpl:_
        ```
        {{ range (net.LookupSRVs "_sip._udp.sip.voice.google.com") -}}
        priority={{.Priority}}/port={{.Port}}
        {{- end }}
        ```

        ```console
        $ gomplate -f input.tmpl
        priority=10/port=5060
        priority=20/port=5060
        ```
  - name: net.LookupTXT
    released: v1.9.0
    description: |
      Resolve a DNS [`TXT` record](https://en.wikipedia.org/wiki/SRV_record).

      This function returns all available TXT records as an array of strings.
    pipeline: true
    arguments:
      - name: name
        required: true
        description: The host name to look up
    examples:
      - |
        $ gomplate -i '{{net.LookupTXT "example.com" | data.ToJSONPretty "  " }}'
        [
          "v=spf1 -all"
        ]
  - name: net.ParseAddr
    released: v4.0.0
    description: |
      Parse the given string as an IP address (a
      [`netip.Addr`](https://pkg.go.dev/net/netip#Addr)).

      Any of `netip.Addr`'s methods may be called on the resulting value. See
      [the docs](https://pkg.go.dev/net/netip#Addr) for details.
    pipeline: true
    arguments:
      - name: addr
        required: true
        description: The IP string to parse. It must be either an IPv4 or IPv6 address.
    examples:
      - |
        $ gomplate -i '{{ (net.ParseAddr "192.168.0.1").IsPrivate }}'
        true
        $ gomplate -i '{{ $ip := net.ParseAddr (net.LookupIP "example.com") -}}
          {{ $ip.Prefix 12 }}'
        93.176.0.0/12
  - name: net.ParseIP
    released: v3.10.0
    deprecated: Use [`net.ParseAddr`](#net-parseaddr) instead.
    description: |
      Parse the given string as an IP address (a `netaddr.IP` from the
      [`inet.af/netaddr`](https://pkg.go.dev/inet.af/netaddr) package).

      Any of `netaddr.IP`'s methods may be called on the resulting value. See
      [the docs](https://pkg.go.dev/inet.af/netaddr) for details.
    pipeline: true
    arguments:
      - name: ip
        required: true
        description: The IP string to parse. It must be either an IPv4 or IPv6 address.
    examples:
      - |
        $ gomplate -i '{{ (net.ParseIP "192.168.0.1").IsPrivate }}'
        true
        $ gomplate -i '{{ $ip := net.ParseIP (net.LookupIP "example.com") -}}
          {{ $ip.Prefix 12 }}'
        93.176.0.0/12
  - name: net.ParsePrefix
    released: v4.0.0
    description: |
      Parse the given string as an IP address prefix (CIDR) representing an IP
      network (a [`netip.Prefix`](https://pkg.go.dev/net/netip#Prefix)).

      The string can be in the form `"192.168.1.0/24"` or `"2001::db8::/32"`,
      the CIDR notations defined in [RFC 4632][] and [RFC 4291][].

      Any of `netip.Prefix`'s methods may be called on the resulting value. See
      [the docs](https://pkg.go.dev/net/netip#Prefix) for details.
    pipeline: true
    arguments:
      - name: prefix
        required: true
        description: The IP address prefix to parse. It must represent either an IPv4 or IPv6 prefix, containing a `/`.
    examples:
      - |
        $ gomplate -i '{{ (net.ParsePrefix "192.168.0.0/24").Range }}'
        192.168.0.0-192.168.0.255
        $ gomplate -i '{{ $ip := net.ParseAddr (net.LookupIP "example.com") -}}
          {{ $net := net.ParsePrefix "93.184.0.0/16" -}}
          {{ $net.Contains $ip }}'
        true
  - name: net.ParseIPPrefix
    released: v3.10.0
    deprecated: Use [`net.ParsePrefix`](#net-parseprefix) instead.
    description: |
      Parse the given string as an IP address prefix (CIDR) representing an IP
      network (a `netaddr.IPPrefix` from the
      [`inet.af/netaddr`][] package).

      The string can be in the form `"192.168.1.0/24"` or `"2001::db8::/32"`,
      the CIDR notations defined in [RFC 4632][] and [RFC 4291][].

      Any of `netaddr.IPPrefix`'s methods may be called on the resulting value.
      See [the docs][`inet.af/netaddr`] for details.
    pipeline: true
    arguments:
      - name: ipprefix
        required: true
        description: The IP address prefix to parse. It must represent either an IPv4 or IPv6 prefix, containing a `/`.
    examples:
      - |
        $ gomplate -i '{{ (net.ParseIPPrefix "192.168.0.0/24").Range }}'
        192.168.0.0-192.168.0.255
        $ gomplate -i '{{ $ip := net.ParseIP (net.LookupIP "example.com") -}}
          {{ $net := net.ParseIPPrefix "93.184.0.0/16" -}}
          {{ $net.Contains $ip }}'
        true
        $ gomplate -i '{{ $net := net.ParseIPPrefix "93.184.0.0/12" -}}
          {{ $net.Range }}'
        93.176.0.0-93.191.255.255
  - name: net.ParseRange
    experimental: true
    released: v4.0.0
    description: |
      Parse the given string as an inclusive range of IP addresses from the same
      address family (a [`netipx.IPRange`](https://pkg.go.dev/go4.org/netipx#IPRange)
      from the [`go4.org/netipx`](https://pkg.go.dev/go4.org/netipx) module).

      The string must contain a hyphen (`-`).

      Any of `netipx.IPRange`'s methods may be called on the resulting value.
      See [the docs](https://pkg.go.dev/go4.org/netipx#IPRange) for details.

      Note that this function is experimental for now, because it uses a
      [third-party module](https://pkg.go.dev/go4.org/netipx) which may be
      brought into the standard library in the future, which may require
      breaking changes to this function.
    pipeline: true
    arguments:
      - name: iprange
        required: true
        description: The IP address range to parse. It must represent either an IPv4 or IPv6 range, containing a `-`.
    examples:
      - |
        $ gomplate -i '{{ (net.ParseRange "192.168.0.0-192.168.0.255").To }}'
        192.168.0.255
        $ gomplate -i '{{ $range := net.ParseRange "1.2.3.0-1.2.3.233" -}}
          {{ $range.Prefixes }}'
        [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]
  - name: net.ParseIPRange
    released: v3.10.0
    deprecated: Use [`net.ParseRange`](#net-parserange) instead.
    description: |
      Parse the given string as an inclusive range of IP addresses from the same
      address family (a `netaddr.IPRange` from the [`inet.af/netaddr`][] package).

      The string must contain a hyphen (`-`).

      Any of `netaddr.IPRange`'s methods may be called on the resulting value.
      See [the docs][`inet.af/netaddr`] for details.
    pipeline: true
    arguments:
      - name: iprange
        required: true
        description: The IP address range to parse. It must represent either an IPv4 or IPv6 range, containing a `-`.
    examples:
      - |
        $ gomplate -i '{{ (net.ParseIPRange "192.168.0.0-192.168.0.255").To }}'
        192.168.0.255
        $ gomplate -i '{{ $range := net.ParseIPRange "1.2.3.0-1.2.3.233" -}}
          {{ $range.Prefixes }}'
        [1.2.3.0/25 1.2.3.128/26 1.2.3.192/27]
  - name: net.CIDRHost
    experimental: true
    released: v3.11.0
    description: |
      Calculates a full host IP address for a given host number within a given IP network address prefix.

      The IP network can be in the form `"192.168.1.0/24"` or `"2001::db8::/32"`,
      the CIDR notations defined in [RFC 4632][] and [RFC 4291][].

      Any of `netip.Addr`'s methods may be called on the resulting value. See
      [the docs](https://pkg.go.dev/net/netip#Addr) for details.
    pipeline: true
    arguments:
      - name: hostnum
        required: true
        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.
      - name: prefix
        required: true
        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.
    examples:
      - |
        $ gomplate -i '{{ "10.12.127.0/20" | net.CIDRHost 268 }}'
        10.12.113.12
  - name: net.CIDRNetmask
    experimental: true
    released: v3.11.0
    description: |
      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.

      Any of `netip.Addr`'s methods may be called on the resulting value. See
      [the docs](https://pkg.go.dev/net/netip#Addr) for details.
    pipeline: true
    arguments:
      - name: prefix
        required: true
        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.
    examples:
      - |
        $ gomplate -i '{{ net.CIDRNetmask "10.12.127.0/20" }}'
        255.255.240.0
        $ gomplate -i '{{ net.CIDRNetmask "fd00:fd12:3456:7890:00a2::/72" }}'
        ffff:ffff:ffff:ffff:ff00::
  - name: net.CIDRSubnets
    experimental: true
    released: v3.11.0
    description: |
      Calculates a subnet address within given IP network address prefix.

      Any of `netip.Prefix`'s methods may be called on the resulting values. See
      [the docs](https://pkg.go.dev/net/netip#Prefix) for details.
    pipeline: true
    arguments:
      - name: newbits
        required: true
        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`.
      - name: prefix
        required: true
        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.
    examples:
      - |
        $ gomplate -i '{{ index ("10.0.0.0/16" | net.CIDRSubnets 2) 1 }}'
        10.0.64.0/18
        $ gomplate -i '{{ net.CIDRSubnets 2 "10.0.0.0/16" -}}'
        [10.0.0.0/18 10.0.64.0/18 10.0.128.0/18 10.0.192.0/18]
  - name: net.CIDRSubnetSizes
    experimental: true
    released: v3.11.0
    description: |
      Calculates a sequence of consecutive IP address ranges within a particular CIDR prefix.

      Any of `netip.Prefix`'s methods may be called on the resulting values. See
      [the docs](https://pkg.go.dev/net/netip#Prefix) for details.
    pipeline: true
    arguments:
      - name: newbits...
        required: true
        description: Numbers of additional network prefix bits for returned address range.
      - name: prefix
        required: true
        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.
    examples:
      - |
        $ gomplate -i '{{ net.CIDRSubnetSizes 4 4 8 4 "10.1.0.0/16" -}}'
        [10.1.0.0/20 10.1.16.0/20 10.1.32.0/24 10.1.48.0/20]