1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
|
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: <array-of-IfAddrs>
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: <array-of-IfAddrs>
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: <array-of-IfAddrs>
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: <array-of-IfAddrs>
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: <array-of-IfAddrs>
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: <array-of-IfAddrs>
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: <array-of-IfAddrs>
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: <array-of-IfAddrs>
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: <array-of-IfAddrs>
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
|
