package template

import "github.com/hashicorp/go-sockaddr/template"

Package sockaddr/template provides a text/template interface the SockAddr helper functions. The primary entry point into the sockaddr/template package is through its Parse() call. For example: 

import (
  "fmt"

  template "github.com/hashicorp/go-sockaddr/template"
)

results, err := template.Parse(`{{ GetPrivateIP }}`)
if err != nil {
  fmt.Errorf("Unable to find a private IP address: %v", err)
}
fmt.Printf("My Private IP address is: %s\n", results)

Below is a list of builtin template functions and details re: their usage. It is possible to add additional functions by calling ParseIfAddrsTemplate directly.

In general, the calling convention for this template library is to seed a list of initial interfaces via one of the Get*Interfaces() calls, then filter, sort, and extract the necessary attributes for use as string input. This template interface is primarily geared toward resolving specific values that are only available at runtime, but can be defined as a heuristic for execution when a config file is parsed.

All functions, unless noted otherwise, return an array of IfAddr structs making it possible to `sort`, `filter`, `limit`, seek (via the `offset` function), or `unique` the list. To extract useful string information, the `attr` and `join` functions return a single string value. See below for details.

Important note: see the https://github.com/hashicorp/go-sockaddr/tree/master/cmd/sockaddr utility for more examples and for a CLI utility to experiment with the template syntax.

`GetAllInterfaces` - Returns an exhaustive set of IfAddr structs available on the host. `GetAllInterfaces` is the initial input and accessible as the initial "dot" in the pipeline.

Example: 

{{ GetAllInterfaces }}

`GetDefaultInterfaces` - Returns one IfAddr for every IP that is on the interface containing the default route for the host.

Example: 

{{ GetDefaultInterfaces }}

`GetPrivateInterfaces` - Returns one IfAddr for every forwardable IP address that is included in RFC 6890 and whose interface is marked as up. NOTE: RFC 6890 is a more exhaustive version of RFC1918 because it spans IPv4 and IPv6, however, RFC6890 does permit the inclusion of likely undesired addresses such as multicast, therefore our version of "private" also filters out non-forwardable addresses.

Example: 

{{ GetPrivateInterfaces | sort "default" | join "address" " " }}

`GetPublicInterfaces` - Returns a list of IfAddr structs whos IPs are forwardable, do not match RFC 6890, and whose interface is marked up.

Example: 

{{ GetPublicInterfaces | sort "default" | join "name" " " }}

`GetPrivateIP` - Helper function that returns a string of the first IP address from GetPrivateInterfaces.

Example: 

{{ GetPrivateIP }}

`GetPrivateIPs` - Helper function that returns a string of the all private IP addresses on the host.

Example: 

{{ GetPrivateIPs }}

`GetPublicIP` - Helper function that returns a string of the first IP from GetPublicInterfaces.

Example: 

{{ GetPublicIP }}

`GetPublicIPs` - Helper function that returns a space-delimited string of the all public IP addresses on the host.

Example: 

{{ GetPrivateIPs }}

`GetInterfaceIP` - Helper function that returns a string of the first IP from the named interface.

Example: 

{{ GetInterfaceIP "en0" }}

`GetInterfaceIPs` - Helper function that returns a space-delimited list of all IPs on a given interface.

Example: 

{{ GetInterfaceIPs "en0" }}

`sort` - Sorts the IfAddrs result based on its arguments. `sort` takes one argument, a list of ways to sort its IfAddrs argument. The list of sort criteria is comma separated (`,`):

Example: 

{{ GetPrivateInterfaces | sort "default,-type,size,+address" }}

`exclude` and `include`: Filters IfAddrs based on the selector criteria and its arguments. Both `exclude` and `include` take two arguments. The list of available filtering criteria is:

Example: 

{{ GetPrivateInterfaces | exclude "type" "IPv6" }}

`unique`: Removes duplicate entries from the IfAddrs list, assuming the list has already been sorted. `unique` only takes one argument:

Example: 

{{ GetAllInterfaces | sort "default,-type,address" | unique "name" }}

`limit`: Reduces the size of the list to the specified value.

Example: 

{{ GetPrivateInterfaces | limit 1 }}

`offset`: Seeks into the list by the specified value. A negative value can be used to seek from the end of the list.

Example: 

{{ GetPrivateInterfaces | offset "-2" | limit 1 }}

`math`: Perform a "math" operation on each member of the list and return new values. `math` takes two arguments, the attribute to operate on and the operation's value.

Supported operations include:

Example: 

{{ GetPrivateInterfaces | include "type" "IP" | math "address" "+256" | attr "address" }}
{{ GetPrivateInterfaces | include "type" "IP" | math "address" "-256" | attr "address" }}
{{ GetPrivateInterfaces | include "type" "IP" | math "network" "+2" | attr "address" }}
{{ GetPrivateInterfaces | include "type" "IP" | math "network" "-2" | attr "address" }}
{{ GetPrivateInterfaces | include "type" "IP" | math "mask" "24" | attr "address" }}
{{ GetPrivateInterfaces | include "flags" "forwardable|up" | include "type" "IPv4" | math "network" "+2" | attr "address" }}

`attr`: Extracts a single attribute of the first member of the list and returns it as a string. `attr` takes a single attribute name. The list of available attributes is type-specific and shared between `join`. See below for a list of supported attributes.

Example: 

{{ GetAllInterfaces | exclude "flags" "up" | attr "address" }}

`Attr`: Extracts a single attribute from an `IfAttr` and in every other way performs the same as the `attr`.

Example: 

{{ with $ifAddrs := GetAllInterfaces | include "type" "IP" | sort "+type,+address" -}}
  {{- range $ifAddrs -}}
    {{- Attr "address" . }} -- {{ Attr "network" . }}/{{ Attr "size" . -}}
  {{- end -}}
{{- end }}

`join`: Similar to `attr`, `join` extracts all matching attributes of the list and returns them as a string joined by the separator, the second argument to `join`. The list of available attributes is type-specific and shared between `join`.

Example: 

{{ GetAllInterfaces | include "flags" "forwardable" | join "address" " " }}

`exclude` and `include` flags:

Attributes for `attr`, `Attr`, and `join`:

SockAddr Type:

IPAddr Type:

IPv4Addr Type:

IPv6Addr Type:

UnixSock Type:

Index

Variables 

var (
	// SourceFuncs is a map of all top-level functions that generate
	// sockaddr data types.
	SourceFuncs template.FuncMap

	// SortFuncs is a map of all functions used in sorting
	SortFuncs template.FuncMap

	// FilterFuncs is a map of all functions used in sorting
	FilterFuncs template.FuncMap

	// HelperFuncs is a map of all functions used in sorting
	HelperFuncs template.FuncMap
)

Functions

func Attr 

func Attr(selectorName string, ifAddrsRaw interface{}) (string, error)

Attr returns the attribute from the ifAddrRaw argument. If the argument is an IfAddrs, only the first element will be evaluated for resolution.

func Parse 

func Parse(input string) (string, error)

Parse parses input as template input using the addresses available on the host, then returns the string output if there are no errors.

func ParseIfAddrs 

func ParseIfAddrs(input string, ifAddrs sockaddr.IfAddrs) (string, error)

ParseIfAddrs parses input as template input using the IfAddrs inputs, then returns the string output if there are no errors.

func ParseIfAddrsTemplate 

func ParseIfAddrsTemplate(input string, ifAddrs sockaddr.IfAddrs, tmplIn *template.Template) (string, error)

ParseIfAddrsTemplate parses input as template input using the IfAddrs inputs, then returns the string output if there are no errors.

Source Files

doc.go template.go

Version
v1.0.7 (latest)
Published
Sep 19, 2024
Platform
linux/amd64
Imports
5 packages
Last checked
2 months ago –

Tools for package owners.