github.com/hairyhenderson/templater@v3.5.0+incompatible/docs-src/content/functions/sockaddr.yml (about) 1 ns: sockaddr 2 preamble: | 3 This namespace wraps the [`github.com/hashicorp/go-sockaddr`](https://github.com/hashicorp/go-sockaddr) 4 package, which makes it easy to discover information about a system's network 5 interfaces. 6 7 These functions are _partly_ documented here for convenience, but the canonical 8 documentation is at https://godoc.org/github.com/hashicorp/go-sockaddr. 9 10 Aside from some convenience functions, the general method of working with these 11 functions is through a _pipeline_. There are _source_ functions, which select 12 interfaces ([`IfAddr`](https://godoc.org/github.com/hashicorp/go-sockaddr#IfAddr)), 13 and there are functions to further filter, refine, and finally to select 14 the specific attributes you're interested in. 15 16 To demonstrate how this can be used, here's an example that lists all of the IPv4 addresses available on the system: 17 18 ```console 19 $ gomplate -i '{{ range (sockaddr.GetAllInterfaces | sockaddr.Include "type" "ipv4") -}} 20 {{ . | sockaddr.Attr "address" }} 21 {{end}}' 22 127.0.0.1 23 10.0.0.8 24 132.79.79.79 25 ``` 26 27 [RFC 1918]: http://tools.ietf.org/html/rfc1918 28 [RFC 6890]: http://tools.ietf.org/html/rfc6890 29 funcs: 30 - name: sockaddr.GetAllInterfaces 31 description: | 32 Iterates over all available network interfaces and finds all available IP 33 addresses on each interface and converts them to `sockaddr.IPAddrs`, and returning 34 the result as an array of `IfAddr`. 35 36 Should be piped through a further function to refine and extract attributes. 37 - name: sockaddr.GetDefaultInterfaces 38 description: | 39 Returns `IfAddrs` of the addresses attached to the default route. 40 41 Should be piped through a further function to refine and extract attributes. 42 - name: sockaddr.GetPrivateInterfaces 43 description: | 44 Returns an array of `IfAddr`s containing every IP that matches 45 [RFC 6890][], is attached to the interface with 46 the default route, and is a forwardable IP address. 47 48 **Note:** [RFC 6890][] is a more exhaustive version of [RFC 1918][] 49 because it spans IPv4 and IPv6, however it does permit the inclusion of likely 50 undesired addresses such as multicast, therefore our definition of a "private" 51 address also excludes non-forwardable IP addresses (as defined by the IETF). 52 53 Should be piped through a further function to refine and extract attributes. 54 - name: sockaddr.GetPublicInterfaces 55 description: | 56 Returns an array of `IfAddr`s that do not match [RFC 6890][], 57 are attached to the default route, and are forwardable. 58 59 Should be piped through a further function to refine and extract attributes. 60 - name: sockaddr.Sort 61 description: | 62 Returns an array of `IfAddr`s sorted based on the given selector. Multiple sort 63 clauses can be passed in as a comma-delimited list without whitespace. 64 65 ### Selectors 66 67 The valid selectors are: 68 69 | selector | sorts by... | 70 |----------|-------------| 71 | `address` | the network address | 72 | `default` | whether or not the `IfAddr` has a default route | 73 | `name` | the interface name | 74 | `port` | the port, if included in the `IfAddr` | 75 | `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) | 76 | `type` | the type of the `IfAddr`. Order is Unix, IPv4, then IPv6 | 77 78 Each of these selectors sort _ascending_, but a _descending_ sort may be chosen 79 by prefixing the selector with a `-` (e.g. `-address`). You may prefix with a `+` 80 to make explicit that the sort is ascending. 81 82 `IfAddr`s that are not comparable will be at the end of the list and in a 83 non-deterministic order. 84 pipeline: true 85 arguments: 86 - name: selector 87 required: true 88 description: which selector to use (see above for values) 89 - name: <array-of-IfAddrs> 90 required: true 91 description: the array of `IfAddr`s to sort 92 rawExamples: 93 - | 94 To sort first by interface name, then by address (descending): 95 ```console 96 $ gomplate -i '{{ sockaddr.GetAllInterfaces | sockaddr.Sort "name,-address" }}' 97 ``` 98 - name: sockaddr.Exclude 99 description: | 100 Returns an array of `IfAddr`s filtered by interfaces that do not match the given 101 selector's value. 102 103 ### Selectors 104 105 The valid selectors are: 106 107 | selector | excludes by... | 108 |----------|-------------| 109 | `address` | the network address | 110 | `flag` | the specified flags (see below) | 111 | `name` | the interface name | 112 | `network` | being part of the given IP network (in net/mask format) | 113 | `port` | the port, if included in the `IfAddr` | 114 | `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 | 115 | `size` | the size of the network mask, as number of bits (e.g. `"24"` for a /24) | 116 | `type` | the type of the `IfAddr`. `unix`, `ipv4`, or `ipv6` | 117 118 #### supported flags 119 120 These flags are supported by the `flag` selector: 121 `broadcast`, `down`, `forwardable`, `global unicast`, `interface-local multicast`, 122 `link-local multicast`, `link-local unicast`, `loopback`, `multicast`, `point-to-point`, 123 `unspecified`, `up` 124 pipeline: true 125 arguments: 126 - name: selector 127 required: true 128 description: which selector to use (see above for values) 129 - name: value 130 required: true 131 description: the selector value to exclude 132 - name: <array-of-IfAddrs> 133 required: true 134 description: the array of `IfAddr`s to consider 135 rawExamples: 136 - | 137 To exclude all IPv6 interfaces: 138 ```console 139 $ gomplate -i '{{ sockaddr.GetAllInterfaces | sockaddr.Exclude "type" "ipv6" }}' 140 ``` 141 - name: sockaddr.Include 142 description: | 143 Returns an array of `IfAddr`s filtered by interfaces that match the given 144 selector's value. 145 146 This is the inverse of `sockaddr.Exclude`. See [`sockaddr.Exclude`](#sockaddr.Exclude) for details. 147 pipeline: true 148 arguments: 149 - name: selector 150 required: true 151 description: which selector to use (see above for values) 152 - name: value 153 required: true 154 description: the selector value to include 155 - name: <array-of-IfAddrs> 156 required: true 157 description: the array of `IfAddr`s to consider 158 - name: sockaddr.Attr 159 description: | 160 Returns the named attribute as a string. 161 pipeline: true 162 arguments: 163 - name: selector 164 required: true 165 description: the attribute to return 166 - name: <array-of-IfAddrs> 167 required: true 168 description: the array of `IfAddr`s to inspect 169 examples: 170 - | 171 $ gomplate -i '{{ range (sockaddr.GetAllInterfaces | sockaddr.Include "type" "ipv4") }}{{ . | sockaddr.Attr "name" }} {{end}}' 172 lo0 en0 173 - name: sockaddr.Join 174 description: | 175 Selects the given attribute from each `IfAddr` in the source array, and joins 176 the results with the given separator. 177 pipeline: true 178 arguments: 179 - name: selector 180 required: true 181 description: the attribute to select 182 - name: separator 183 required: true 184 description: the separator 185 - name: <array-of-IfAddrs> 186 required: true 187 description: the array of `IfAddr`s to join 188 examples: 189 - | 190 $ gomplate -i '{{ sockaddr.GetAllInterfaces | sockaddr.Join "name" "," }}' 191 lo0,lo0,lo0,en0,en0 192 - name: sockaddr.Limit 193 description: | 194 Returns a slice of `IfAddr`s based on the specified limit. 195 pipeline: true 196 arguments: 197 - name: limit 198 required: true 199 description: the maximum number of `IfAddrs` 200 - name: <array-of-IfAddrs> 201 required: true 202 description: the array of `IfAddr`s 203 examples: 204 - | 205 $ gomplate -i '{{ sockaddr.GetAllInterfaces | sockaddr.Limit 2 | sockaddr.Join "name" "|" }}' 206 lo0|lo0 207 - name: sockaddr.Offset 208 description: | 209 Returns a slice of `IfAddr`s based on the specified offset. 210 pipeline: true 211 arguments: 212 - name: offset 213 required: true 214 description: the offset 215 - name: <array-of-IfAddrs> 216 required: true 217 description: the array of `IfAddr`s 218 examples: 219 - | 220 $ gomplate -i '{{ sockaddr.GetAllInterfaces | sockaddr.Limit 2 | sockaddr.Offset 1 | sockaddr.Attr "address" }}' 221 ::1 222 - name: sockaddr.Unique 223 description: | 224 Creates a unique array of `IfAddr`s based on the matching selector. Assumes the input has 225 already been sorted. 226 pipeline: true 227 arguments: 228 - name: selector 229 required: true 230 description: the attribute to select 231 - name: <array-of-IfAddrs> 232 required: true 233 description: the array of `IfAddr`s 234 examples: 235 - | 236 $ gomplate -i '{{ sockaddr.GetAllInterfaces | sockaddr.Unique "name" | sockaddr.Join "name" ", " }}' 237 lo0, en0 238 - name: sockaddr.Math 239 description: | 240 Applies a math operation to each `IfAddr` in the input. Any failure will result in zero results. 241 242 See [the source code](https://github.com/hashicorp/go-sockaddr/blob/master/ifaddrs.go#L725) 243 for details. 244 pipeline: true 245 arguments: 246 - name: selector 247 required: true 248 description: the attribute to operate on 249 - name: operation 250 required: true 251 description: the operation 252 - name: <array-of-IfAddrs> 253 required: true 254 description: the array of `IfAddr`s 255 examples: 256 - | 257 $ gomplate -i '{{ sockaddr.GetAllInterfaces | sockaddr.Math "address" "+5" | sockaddr.Attr "address" }}' 258 127.0.0.6 259 - name: sockaddr.GetPrivateIP 260 description: | 261 Returns a string with a single IP address that is part of [RFC 6890][] and has a 262 default route. If the system can't determine its IP address or find an [RFC 6890][] 263 IP address, an empty string will be returned instead. 264 pipeline: false 265 examples: 266 - | 267 $ gomplate -i '{{ sockaddr.GetPrivateIP }}' 268 10.0.0.28 269 - name: sockaddr.GetPrivateIPs 270 description: | 271 Returns a space-separated string with all IP addresses that are part of [RFC 6890][] 272 (regardless of whether or not there is a default route, unlike `GetPublicIP`). 273 If the system can't find any [RFC 6890][] IP addresses, an empty string will be 274 returned instead. 275 pipeline: false 276 examples: 277 - | 278 $ gomplate -i '{{ sockaddr.GetPrivateIPs }}' 279 10.0.0.28 192.168.0.1 280 - name: sockaddr.GetPublicIP 281 description: | 282 Returns a string with a single IP address that is NOT part of [RFC 6890][] and 283 has a default route. If the system can't determine its IP address or find a 284 non-[RFC 6890][] IP address, an empty string will be returned instead. 285 pipeline: false 286 examples: 287 - | 288 $ gomplate -i '{{ sockaddr.GetPublicIP }}' 289 8.1.2.3 290 - name: sockaddr.GetPublicIPs 291 description: | 292 Returns a space-separated string with all IP addresses that are NOT part of 293 [RFC 6890][] (regardless of whether or not there is a default route, unlike 294 `GetPublicIP`). If the system can't find any non-[RFC 6890][] IP addresses, an 295 empty string will be returned instead. 296 pipeline: false 297 examples: 298 - | 299 $ gomplate -i '{{ sockaddr.GetPublicIPs }}' 300 8.1.2.3 8.2.3.4 301 - name: sockaddr.GetInterfaceIP 302 description: | 303 Returns a string with a single IP address sorted by the size of the network 304 (i.e. IP addresses with a smaller netmask, larger network size, are sorted first). 305 pipeline: false 306 arguments: 307 - name: name 308 required: true 309 description: the interface name 310 examples: 311 - | 312 $ gomplate -i '{{ sockaddr.GetInterfaceIP "en0" }}' 313 10.0.0.28 314 - name: sockaddr.GetInterfaceIPs 315 description: | 316 Returns a string with all IPs, sorted by the size of the network (i.e. IP 317 addresses with a smaller netmask, larger network size, are sorted first), on a 318 named interface. 319 pipeline: false 320 arguments: 321 - name: name 322 required: true 323 description: the interface name 324 examples: 325 - | 326 $ gomplate -i '{{ sockaddr.GetInterfaceIPs "en0" }}' 327 10.0.0.28 fe80::1f9a:5582:4b41:bd18