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