ns: sockaddr preamble: | This namespace wraps the [`github.com/hashicorp/go-sockaddr`](https://github.com/hashicorp/go-sockaddr) package, which makes it easy to discover information about a system's network interfaces. These functions are _partly_ documented here for convenience, but the canonical documentation is at https://godoc.org/github.com/hashicorp/go-sockaddr. Aside from some convenience functions, the general method of working with these functions is through a _pipeline_. There are _source_ functions, which select interfaces ([`IfAddr`](https://godoc.org/github.com/hashicorp/go-sockaddr#IfAddr)), and there are functions to further filter, refine, and finally to select the specific attributes you're interested in. To demonstrate how this can be used, here's an example that lists all of the IPv4 addresses available on the system: _in.tmpl:_ ``` {{ range (sockaddr.GetAllInterfaces | sockaddr.Include "type" "ipv4") -}} {{ . | sockaddr.Attr "address" }} {{end}} ``` ```console $ gomplate -f in.tmpl 127.0.0.1 10.0.0.8 132.79.79.79 ``` [RFC 1918]: http://tools.ietf.org/html/rfc1918 [RFC 6890]: http://tools.ietf.org/html/rfc6890 funcs: - name: sockaddr.GetAllInterfaces released: v2.4.0 description: | Iterates over all available network interfaces and finds all available IP addresses on each interface and converts them to `sockaddr.IPAddrs`, and returning the result as an array of `IfAddr`. Should be piped through a further function to refine and extract attributes. - name: sockaddr.GetDefaultInterfaces released: v2.4.0 description: | Returns `IfAddrs` of the addresses attached to the default route. Should be piped through a further function to refine and extract attributes. - name: sockaddr.GetPrivateInterfaces released: v2.4.0 description: | Returns an array of `IfAddr`s containing every IP that matches [RFC 6890][], is attached to the interface with the default route, and is a forwardable IP address. **Note:** [RFC 6890][] is a more exhaustive version of [RFC 1918][] because it spans IPv4 and IPv6, however it does permit the inclusion of likely undesired addresses such as multicast, therefore our definition of a "private" address also excludes non-forwardable IP addresses (as defined by the IETF). Should be piped through a further function to refine and extract attributes. - name: sockaddr.GetPublicInterfaces released: v2.4.0 description: | Returns an array of `IfAddr`s that do not match [RFC 6890][], are attached to the default route, and are forwardable. Should be piped through a further function to refine and extract attributes. - name: sockaddr.Sort released: v2.4.0 description: | Returns an array of `IfAddr`s sorted based on the given selector. Multiple sort clauses can be passed in as a comma-delimited list without whitespace. ### Selectors The valid selectors are: | selector | sorts by... | |----------|-------------| | `address` | the network address | | `default` | whether or not the `IfAddr` has a default route | | `name` | the interface name | | `port` | the port, if included in the `IfAddr` | | `size` | the size of the network mask, smaller mask (larger number of hosts per network) to largest (e.g. a /24 sorts before a /32) | | `type` | the type of the `IfAddr`. Order is Unix, IPv4, then IPv6 | Each of these selectors sort _ascending_, but a _descending_ sort may be chosen by prefixing the selector with a `-` (e.g. `-address`). You may prefix with a `+` to make explicit that the sort is ascending. `IfAddr`s that are not comparable will be at the end of the list and in a non-deterministic order. pipeline: true arguments: - name: selector required: true description: which selector to use (see above for values) - name: required: true description: the array of `IfAddr`s to sort rawExamples: - | To sort first by interface name, then by address (descending): ```console $ gomplate -i '{{ sockaddr.GetAllInterfaces | sockaddr.Sort "name,-address" }}' ``` - name: sockaddr.Exclude released: v2.4.0 description: | Returns an array of `IfAddr`s filtered by interfaces that do not match the given selector's value. ### Selectors The valid selectors are: | selector | excludes by... | |----------|-------------| | `address` | the network address | | `flag` | the specified flags (see below) | | `name` | the interface name | | `network` | being part of the given IP network (in net/mask format) | | `port` | the port, if included in the `IfAddr` | | `rfc` | being included in networks defined by the given RFC. See [the source code](https://github.com/hashicorp/go-sockaddr/blob/master/rfc.go#L38) for a list of valid RFCs | | `size` | the size of the network mask, as number of bits (e.g. `"24"` for a /24) | | `type` | the type of the `IfAddr`. `unix`, `ipv4`, or `ipv6` | #### supported flags These flags are supported by the `flag` selector: `broadcast`, `down`, `forwardable`, `global unicast`, `interface-local multicast`, `link-local multicast`, `link-local unicast`, `loopback`, `multicast`, `point-to-point`, `unspecified`, `up` pipeline: true arguments: - name: selector required: true description: which selector to use (see above for values) - name: value required: true description: the selector value to exclude - name: required: true description: the array of `IfAddr`s to consider rawExamples: - | To exclude all IPv6 interfaces: ```console $ gomplate -i '{{ sockaddr.GetAllInterfaces | sockaddr.Exclude "type" "ipv6" }}' ``` - name: sockaddr.Include released: v2.4.0 description: | Returns an array of `IfAddr`s filtered by interfaces that match the given selector's value. This is the inverse of `sockaddr.Exclude`. See [`sockaddr.Exclude`](#sockaddrexclude) for details. pipeline: true arguments: - name: selector required: true description: which selector to use (see above for values) - name: value required: true description: the selector value to include - name: required: true description: the array of `IfAddr`s to consider - name: sockaddr.Attr released: v2.4.0 description: | Returns the named attribute as a string. pipeline: true arguments: - name: selector required: true description: the attribute to return - name: required: true description: the array of `IfAddr`s to inspect examples: - | $ gomplate -i '{{ range (sockaddr.GetAllInterfaces | sockaddr.Include "type" "ipv4") }}{{ . | sockaddr.Attr "name" }} {{end}}' lo0 en0 - name: sockaddr.Join released: v2.4.0 description: | Selects the given attribute from each `IfAddr` in the source array, and joins the results with the given separator. pipeline: true arguments: - name: selector required: true description: the attribute to select - name: separator required: true description: the separator - name: required: true description: the array of `IfAddr`s to join examples: - | $ gomplate -i '{{ sockaddr.GetAllInterfaces | sockaddr.Join "name" "," }}' lo0,lo0,lo0,en0,en0 - name: sockaddr.Limit released: v2.4.0 description: | Returns a slice of `IfAddr`s based on the specified limit. pipeline: true arguments: - name: limit required: true description: the maximum number of `IfAddrs` - name: required: true description: the array of `IfAddr`s examples: - | $ gomplate -i '{{ sockaddr.GetAllInterfaces | sockaddr.Limit 2 | sockaddr.Join "name" "|" }}' lo0|lo0 - name: sockaddr.Offset released: v2.4.0 description: | Returns a slice of `IfAddr`s based on the specified offset. pipeline: true arguments: - name: offset required: true description: the offset - name: required: true description: the array of `IfAddr`s examples: - | $ gomplate -i '{{ sockaddr.GetAllInterfaces | sockaddr.Limit 2 | sockaddr.Offset 1 | sockaddr.Attr "address" }}' ::1 - name: sockaddr.Unique released: v2.4.0 description: | Creates a unique array of `IfAddr`s based on the matching selector. Assumes the input has already been sorted. pipeline: true arguments: - name: selector required: true description: the attribute to select - name: required: true description: the array of `IfAddr`s examples: - | $ gomplate -i '{{ sockaddr.GetAllInterfaces | sockaddr.Unique "name" | sockaddr.Join "name" ", " }}' lo0, en0 - name: sockaddr.Math released: v2.4.0 description: | Applies a math operation to each `IfAddr` in the input. Any failure will result in zero results. See [the source code](https://github.com/hashicorp/go-sockaddr/blob/master/ifaddrs.go#L725) for details. pipeline: true arguments: - name: selector required: true description: the attribute to operate on - name: operation required: true description: the operation - name: required: true description: the array of `IfAddr`s examples: - | $ gomplate -i '{{ sockaddr.GetAllInterfaces | sockaddr.Math "address" "+5" | sockaddr.Attr "address" }}' 127.0.0.6 - name: sockaddr.GetPrivateIP released: v2.4.0 description: | Returns a string with a single IP address that is part of [RFC 6890][] and has a default route. If the system can't determine its IP address or find an [RFC 6890][] IP address, an empty string will be returned instead. pipeline: false examples: - | $ gomplate -i '{{ sockaddr.GetPrivateIP }}' 10.0.0.28 - name: sockaddr.GetPrivateIPs released: v2.4.0 description: | Returns a space-separated string with all IP addresses that are part of [RFC 6890][] (regardless of whether or not there is a default route, unlike `GetPublicIP`). If the system can't find any [RFC 6890][] IP addresses, an empty string will be returned instead. pipeline: false examples: - | $ gomplate -i '{{ sockaddr.GetPrivateIPs }}' 10.0.0.28 192.168.0.1 - name: sockaddr.GetPublicIP released: v2.4.0 description: | Returns a string with a single IP address that is NOT part of [RFC 6890][] and has a default route. If the system can't determine its IP address or find a non-[RFC 6890][] IP address, an empty string will be returned instead. pipeline: false examples: - | $ gomplate -i '{{ sockaddr.GetPublicIP }}' 8.1.2.3 - name: sockaddr.GetPublicIPs released: v2.4.0 description: | Returns a space-separated string with all IP addresses that are NOT part of [RFC 6890][] (regardless of whether or not there is a default route, unlike `GetPublicIP`). If the system can't find any non-[RFC 6890][] IP addresses, an empty string will be returned instead. pipeline: false examples: - | $ gomplate -i '{{ sockaddr.GetPublicIPs }}' 8.1.2.3 8.2.3.4 - name: sockaddr.GetInterfaceIP released: v2.4.0 description: | Returns a string with a single IP address sorted by the size of the network (i.e. IP addresses with a smaller netmask, larger network size, are sorted first). pipeline: false arguments: - name: name required: true description: the interface name examples: - | $ gomplate -i '{{ sockaddr.GetInterfaceIP "en0" }}' 10.0.0.28 - name: sockaddr.GetInterfaceIPs released: v2.4.0 description: | Returns a string with all IPs, sorted by the size of the network (i.e. IP addresses with a smaller netmask, larger network size, are sorted first), on a named interface. pipeline: false arguments: - name: name required: true description: the interface name examples: - | $ gomplate -i '{{ sockaddr.GetInterfaceIPs "en0" }}' 10.0.0.28 fe80::1f9a:5582:4b41:bd18