sockaddr functions
This namespace wraps the 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),
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}}
$ gomplate -f in.tmpl
127.0.0.1
10.0.0.8
132.79.79.79
sockaddr.GetAllInterfaces
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.
Added in gomplate v2.4.0
Usage
sockaddr.GetAllInterfaces
sockaddr.GetDefaultInterfaces
Returns IfAddrs of the addresses attached to the default route.
Should be piped through a further function to refine and extract attributes.
Added in gomplate v2.4.0
Usage
sockaddr.GetDefaultInterfaces
sockaddr.GetPrivateInterfaces
Returns an array of IfAddrs 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.
Added in gomplate v2.4.0
Usage
sockaddr.GetPrivateInterfaces
sockaddr.GetPublicInterfaces
Returns an array of IfAddrs 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.
Added in gomplate v2.4.0
Usage
sockaddr.GetPublicInterfaces
sockaddr.Sort
Returns an array of IfAddrs 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.
IfAddrs that are not comparable will be at the end of the list and in a
non-deterministic order.
Added in gomplate v2.4.0
Usage
sockaddr.Sort selector <array-of-IfAddrs>
<array-of-IfAddrs> | sockaddr.Sort selector
Arguments
| name | description |
|---|---|
selector |
(required) which selector to use (see above for values) |
<array-of-IfAddrs> |
(required) the array of IfAddrs to sort |
Examples
To sort first by interface name, then by address (descending):
$ gomplate -i '{{ sockaddr.GetAllInterfaces | sockaddr.Sort "name,-address" }}'
sockaddr.Exclude
Returns an array of IfAddrs 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 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
Added in gomplate v2.4.0
Usage
sockaddr.Exclude selector value <array-of-IfAddrs>
<array-of-IfAddrs> | sockaddr.Exclude selector value
Arguments
| name | description |
|---|---|
selector |
(required) which selector to use (see above for values) |
value |
(required) the selector value to exclude |
<array-of-IfAddrs> |
(required) the array of IfAddrs to consider |
Examples
To exclude all IPv6 interfaces:
$ gomplate -i '{{ sockaddr.GetAllInterfaces | sockaddr.Exclude "type" "ipv6" }}'
sockaddr.Include
Returns an array of IfAddrs filtered by interfaces that match the given
selector’s value.
This is the inverse of sockaddr.Exclude. See sockaddr.Exclude for details.
Added in gomplate v2.4.0
Usage
sockaddr.Include selector value <array-of-IfAddrs>
<array-of-IfAddrs> | sockaddr.Include selector value
Arguments
| name | description |
|---|---|
selector |
(required) which selector to use (see above for values) |
value |
(required) the selector value to include |
<array-of-IfAddrs> |
(required) the array of IfAddrs to consider |
sockaddr.Attr
Returns the named attribute as a string.
Added in gomplate v2.4.0
Usage
sockaddr.Attr selector <array-of-IfAddrs>
<array-of-IfAddrs> | sockaddr.Attr selector
Arguments
| name | description |
|---|---|
selector |
(required) the attribute to return |
<array-of-IfAddrs> |
(required) the array of IfAddrs to inspect |
Examples
$ gomplate -i '{{ range (sockaddr.GetAllInterfaces | sockaddr.Include "type" "ipv4") }}{{ . | sockaddr.Attr "name" }} {{end}}'
lo0 en0
sockaddr.Join
Selects the given attribute from each IfAddr in the source array, and joins
the results with the given separator.
Added in gomplate v2.4.0
Usage
sockaddr.Join selector separator <array-of-IfAddrs>
<array-of-IfAddrs> | sockaddr.Join selector separator
Arguments
| name | description |
|---|---|
selector |
(required) the attribute to select |
separator |
(required) the separator |
<array-of-IfAddrs> |
(required) the array of IfAddrs to join |
Examples
$ gomplate -i '{{ sockaddr.GetAllInterfaces | sockaddr.Join "name" "," }}'
lo0,lo0,lo0,en0,en0
sockaddr.Limit
Returns a slice of IfAddrs based on the specified limit.
Added in gomplate v2.4.0
Usage
sockaddr.Limit limit <array-of-IfAddrs>
<array-of-IfAddrs> | sockaddr.Limit limit
Arguments
| name | description |
|---|---|
limit |
(required) the maximum number of IfAddrs |
<array-of-IfAddrs> |
(required) the array of IfAddrs |
Examples
$ gomplate -i '{{ sockaddr.GetAllInterfaces | sockaddr.Limit 2 | sockaddr.Join "name" "|" }}'
lo0|lo0
sockaddr.Offset
Returns a slice of IfAddrs based on the specified offset.
Added in gomplate v2.4.0
Usage
sockaddr.Offset offset <array-of-IfAddrs>
<array-of-IfAddrs> | sockaddr.Offset offset
Arguments
| name | description |
|---|---|
offset |
(required) the offset |
<array-of-IfAddrs> |
(required) the array of IfAddrs |
Examples
$ gomplate -i '{{ sockaddr.GetAllInterfaces | sockaddr.Limit 2 | sockaddr.Offset 1 | sockaddr.Attr "address" }}'
::1
sockaddr.Unique
Creates a unique array of IfAddrs based on the matching selector. Assumes the input has
already been sorted.
Added in gomplate v2.4.0
Usage
sockaddr.Unique selector <array-of-IfAddrs>
<array-of-IfAddrs> | sockaddr.Unique selector
Arguments
| name | description |
|---|---|
selector |
(required) the attribute to select |
<array-of-IfAddrs> |
(required) the array of IfAddrs |
Examples
$ gomplate -i '{{ sockaddr.GetAllInterfaces | sockaddr.Unique "name" | sockaddr.Join "name" ", " }}'
lo0, en0
sockaddr.Math
Applies a math operation to each IfAddr in the input. Any failure will result in zero results.
See the source code for details.
Added in gomplate v2.4.0
Usage
sockaddr.Math selector operation <array-of-IfAddrs>
<array-of-IfAddrs> | sockaddr.Math selector operation
Arguments
| name | description |
|---|---|
selector |
(required) the attribute to operate on |
operation |
(required) the operation |
<array-of-IfAddrs> |
(required) the array of IfAddrs |
Examples
$ gomplate -i '{{ sockaddr.GetAllInterfaces | sockaddr.Math "address" "+5" | sockaddr.Attr "address" }}'
127.0.0.6
sockaddr.GetPrivateIP
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.
Added in gomplate v2.4.0
Usage
sockaddr.GetPrivateIP
Examples
$ gomplate -i '{{ sockaddr.GetPrivateIP }}'
10.0.0.28
sockaddr.GetPrivateIPs
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.
Added in gomplate v2.4.0
Usage
sockaddr.GetPrivateIPs
Examples
$ gomplate -i '{{ sockaddr.GetPrivateIPs }}'
10.0.0.28 192.168.0.1
sockaddr.GetPublicIP
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.
Added in gomplate v2.4.0
Usage
sockaddr.GetPublicIP
Examples
$ gomplate -i '{{ sockaddr.GetPublicIP }}'
8.1.2.3
sockaddr.GetPublicIPs
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.
Added in gomplate v2.4.0
Usage
sockaddr.GetPublicIPs
Examples
$ gomplate -i '{{ sockaddr.GetPublicIPs }}'
8.1.2.3 8.2.3.4
sockaddr.GetInterfaceIP
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).
Added in gomplate v2.4.0
Usage
sockaddr.GetInterfaceIP name
Arguments
| name | description |
|---|---|
name |
(required) the interface name |
Examples
$ gomplate -i '{{ sockaddr.GetInterfaceIP "en0" }}'
10.0.0.28
sockaddr.GetInterfaceIPs
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.
Added in gomplate v2.4.0
Usage
sockaddr.GetInterfaceIPs name
Arguments
| name | description |
|---|---|
name |
(required) the interface name |
Examples
$ gomplate -i '{{ sockaddr.GetInterfaceIPs "en0" }}'
10.0.0.28 fe80::1f9a:5582:4b41:bd18