nettrigger

README

nettrigger

A swiss army knife of triggerable network actions. Intended to capture callbacks from other programs. Originally written as a DNS registration handler for ISC DHCP.

The nettrigger library provides a rudimentary rules engine. The included nettrigger program performs one-time evaluation of a set of rules upon its execution.

This package is experimental and subject to breaking changes.

Rules

Each rule defines zero or more triggers and one or more actions.

Triggers and actions can contain environment variables in their arguments.

Rule Syntax (Text)

Triggers

pattern subject glob
regex   subject expression

Actions

dns.a      host zone ip [ttl]
dns.cname  host zone target [ttl]
https.post url
http.post  url

Rules

[trigger [,trigger ...] :] action [,action ...]

Example Rule

pattern $HOST *-server : dns.a $HOST.example.com $IP

This example relies upon the definition of HOST and IP environment variables. It matches host names ending in -server and attempts to register A records for them.

Environment

Rules can be defined via environment variables:

RULE1='[rule syntax]'
RULE2='[rule syntax]'

Arguments can be mapped to environment variables, using environment variables:

ARG1='Host'
ARG2='IP'
ARG2='MAC'

Functions

When expanding environment variables, a small set of built-in functions are provided:

concat(value[, value ...])

sha2_256(value)
sha2_64(value)

Providers

Some actions rely on providers to perform their work. For example, DNS actions require configuration of a DNS provider that has control of the zone.

Currently supported:

• DNS: Digital Ocean

ISC DHCP

The nettrigger program was originally written to register DNS records on lease commits. The dhcpd daemon can be configured to call nettrigger on commit like so:

on commit {
    set clip = binary-to-ascii(10, 8, ".", leased-address);
    set clhw = binary-to-ascii(16, 8, "", substring(hardware, 1, 6));
    execute("/nettrigger", host-decl-name, clip, clhw);
}

Note that this assumes the existence of nettrigger in the / root driectory.

Such an invocation of nettrigger would also require its arguments to be mapped:

ARG1='HOST'
ARG2='IP'
ARG3='MAC'

See this helpful blog post by Jan-Piet Mens for additional information about the on commit handler.

Documentation

Index

• Variables
• func Concat(s string, next Mapper) (value string, ok bool)
• func Hasher(s string, next Mapper) (value string, ok bool)
• func Literal(s string, next Mapper) (value string, ok bool)
• func Lower(s string, next Mapper) (value string, ok bool)
• func ParseFunction(name, s string) (params string, ok bool)
• func Upper(s string, next Mapper) (value string, ok bool)
• type Action
  • func BuildAction(spec ActionSpec, builders ...ActionBuilder) (Action, error)
  • func BuildActions(specs []ActionSpec, builders ...ActionBuilder) ([]Action, error)
  • func DomainRecordActionBuilder(spec ActionSpec) (Action, error)
• type ActionBuilder
• type ActionSpec
  • func ParseAction(v string) (ActionSpec, error)
  • func ParseActions(v string) ([]ActionSpec, error)
  • func (spec ActionSpec) Arg(n int) string
• type ArgMap
  • func (m ArgMap) Map(args ...string) Mapper
  • func (m ArgMap) Value(name string, args ...string) (value string, ok bool)
• type Config
  • func (c *Config) ParseEnv() error
• type DNS
  • func NewDigitalOceanDNS(token string) DNS
  • func NewGoogleDNS(project string) (DNS, error)
• type DomainRecord
• type DomainRecordAction
  • func (action DomainRecordAction) Apply(ctx context.Context, env Environment, prov Providers) error
• type DomainRecordTemplate
• type Environment
• type Filter
  • func BuildFilter(spec FilterSpec, builders ...FilterBuilder) (Filter, error)
  • func BuildFilters(specs []FilterSpec, builders ...FilterBuilder) ([]Filter, error)
  • func PatternBuilder(spec FilterSpec) (Filter, error)
  • func RegexpBuilder(spec FilterSpec) (Filter, error)
• type FilterBuilder
• type FilterSpec
  • func ParseFilter(v string) (FilterSpec, error)
  • func ParseFilters(v string) ([]FilterSpec, error)
  • func (spec FilterSpec) Arg(n int) string
• type Mapper
  • func (m Mapper) Expand(s string) string
• type MapperSet
  • func (ms MapperSet) Expand(s string) string
  • func (ms MapperSet) Resolve(s string) string
• type Providers
• type Rule
  • func BuildRule(spec RuleSpec, fb []FilterBuilder, ab []ActionBuilder) (Rule, error)
  • func BuildRules(specs []RuleSpec, fb []FilterBuilder, ab []ActionBuilder) ([]Rule, error)
  • func (r Rule) Match(env Environment) bool
• type RuleSpec
  • func ParseRule(v string) (RuleSpec, error)
  • func ParseRules(v string) ([]RuleSpec, error)
• type SimpleMapper
  • func (simple SimpleMapper) Mapper(s string, next Mapper) (string, bool)

Variables

var DefaultConfig = Config{}

DefaultConfig holds the default configuration values.

Functions

func Concat

func Concat(s string, next Mapper) (value string, ok bool)

Concat concatenates variable values taken from next.

func Hasher

func Hasher(s string, next Mapper) (value string, ok bool)

Hasher performs hashing of variable values taken from next.

func Literal

func Literal(s string, next Mapper) (value string, ok bool)

Literal returns the value of quoted literals.

func Lower

func Lower(s string, next Mapper) (value string, ok bool)

Lower returns the lower case of variable values taken from next.

func ParseFunction

func ParseFunction(name, s string) (params string, ok bool)

ParseFunction attemps to parse s as a function. If successful it returns the function's parameters and true.

func Upper

func Upper(s string, next Mapper) (value string, ok bool)

Upper returns the upper case of variable values taken from next.

Types

type Action

type Action func(context.Context, Environment, Providers) error

Action performs some action based on the environment and providers.

func BuildAction

func BuildAction(spec ActionSpec, builders ...ActionBuilder) (Action, error)

BuildAction uses builders to construct an action from the specification.

func BuildActions

func BuildActions(specs []ActionSpec, builders ...ActionBuilder) ([]Action, error)

BuildActions converts the given specifications into an action list.

func DomainRecordActionBuilder

func DomainRecordActionBuilder(spec ActionSpec) (Action, error)

DomainRecordActionBuilder constructs DNS actions from action specifications in the following forms:

dns.a     name zone ip    [ttl]
dns.cname name zone alias

type ActionBuilder

type ActionBuilder func(ActionSpec) (Action, error)

ActionBuilder builds actions from specifications.

type ActionSpec

type ActionSpec struct {
	Type string
	Args []string
}

ActionSpec is a parsed action specification.

func ParseAction

func ParseAction(v string) (ActionSpec, error)

ParseAction parses v as a string representation of an action.

func ParseActions

func ParseActions(v string) ([]ActionSpec, error)

ParseActions parses v as a string representation of an action list.

func (ActionSpec) Arg

func (spec ActionSpec) Arg(n int) string

Arg returns the argument with the nth index.

An empty string is returned if the argument doesn't exist.

type ArgMap

type ArgMap map[string]int

ArgMap maps variable names to argument indices.

func (ArgMap) Map

func (m ArgMap) Map(args ...string) Mapper

Map returns a mapper that maps variable names in m to indices in args.

func (ArgMap) Value

func (m ArgMap) Value(name string, args ...string) (value string, ok bool)

Value returns the named argument from the given argument list.

type Config

type Config struct {
	Params            ArgMap
	Rules             []RuleSpec
	Timeout           time.Duration
	GoogleProject     string
	DigitalOceanToken string
	Concurrent        bool
}

Config holds configuration values.

func (*Config) ParseEnv

func (c *Config) ParseEnv() error

ParseEnv will parse environment variables and apply them to the configuration.

type DNS

type DNS interface {
	Register(ctx context.Context, domain string, record DomainRecord) error
}

DNS is a DNS provider interface.

func NewDigitalOceanDNS

func NewDigitalOceanDNS(token string) DNS

NewDigitalOceanDNS returns a DigitalOcean DNS provider.

func NewGoogleDNS

func NewGoogleDNS(project string) (DNS, error)

NewGoogleDNS returns a Google DNS provider.

type DomainRecord

type DomainRecord struct {
	Type     string
	Name     string
	Data     string
	TTL      int
	Priority int
	Port     int
	Weight   int
}

DomainRecord is a domain record used by DNS providers.

type DomainRecordAction

type DomainRecordAction struct {
	Domain   string
	Template DomainRecordTemplate
}

DomainRecordAction performs an action on a DNS record.

func (DomainRecordAction) Apply

func (action DomainRecordAction) Apply(ctx context.Context, env Environment, prov Providers) error

Apply runs the domain record action.

type DomainRecordTemplate

type DomainRecordTemplate struct {
	Type     string
	Name     string
	Data     string
	TTL      string
	Priority string
	Port     string
	Weight   string
}

DomainRecordTemplate is a template used by DNS actions. Its fields may contain environment variable expressions.

type Environment

type Environment interface {
	// Expand replaces ${var} or $var in the string according to the
	// state of the current environment.
	Expand(s string) string
}

Environment provides the ability to expand environment variables.

type Filter

type Filter func(Environment) bool

A Filter matches some particular condition of its environment.

func BuildFilter

func BuildFilter(spec FilterSpec, builders ...FilterBuilder) (Filter, error)

BuildFilter uses builders to construct a filter from the specification.

func BuildFilters

func BuildFilters(specs []FilterSpec, builders ...FilterBuilder) ([]Filter, error)

BuildFilters converts the given specifications into a filter list.

func PatternBuilder

func PatternBuilder(spec FilterSpec) (Filter, error)

PatternBuilder constructs pattern filters from filter specifications.

func RegexpBuilder

func RegexpBuilder(spec FilterSpec) (Filter, error)

RegexpBuilder constructs regular expression filters from filter specifications.

type FilterBuilder

type FilterBuilder func(FilterSpec) (Filter, error)

FilterBuilder builds filters from specifications.

type FilterSpec

type FilterSpec struct {
	Type string
	Args []string
}

FilterSpec is a parsed filter specification.

func ParseFilter

func ParseFilter(v string) (FilterSpec, error)

ParseFilter parses v as a string representation of a filter.

func ParseFilters

func ParseFilters(v string) ([]FilterSpec, error)

ParseFilters parses v as a string representation of a filter list.

func (FilterSpec) Arg

func (spec FilterSpec) Arg(n int) string

Arg returns the argument with the nth index.

An empty string is returned if the argument doesn't exist.

type Mapper

type Mapper func(s string, next Mapper) (value string, ok bool)

Mapper converts variables and functions into values.

func (Mapper) Expand

func (m Mapper) Expand(s string) string

Expand replaces ${var} or $var in the string with its value.

type MapperSet

type MapperSet []Mapper

MapperSet maps variables to values by iterating through a set of mappers.

func (MapperSet) Expand

func (ms MapperSet) Expand(s string) string

Expand replaces ${var} or $var in the string based on the mapper set.

func (MapperSet) Resolve

func (ms MapperSet) Resolve(s string) string

Resolve returns the value for the variable s. It returns an empty string if the s can't be resolved.

type Providers

type Providers struct {
	DNS
}

Providers holds the set of providers.

type Rule

type Rule struct {
	Filters []Filter
	Actions []Action
}

A Rule defines zero or more triggers and one or more actions.

func BuildRule

func BuildRule(spec RuleSpec, fb []FilterBuilder, ab []ActionBuilder) (Rule, error)

BuildRule uses fb and ab to construct a rule from the specification.

func BuildRules

func BuildRules(specs []RuleSpec, fb []FilterBuilder, ab []ActionBuilder) ([]Rule, error)

BuildRules converts the given specifications into a rule list.

func (Rule) Match

func (r Rule) Match(env Environment) bool

Match returns true if the rule's filters match the environment.

type RuleSpec

type RuleSpec struct {
	Filters []FilterSpec
	Actions []ActionSpec
}

RuleSpec is a parsed rule specification.

func ParseRule

func ParseRule(v string) (RuleSpec, error)

ParseRule parses v as a string representation of a rule.

func ParseRules

func ParseRules(v string) ([]RuleSpec, error)

ParseRules parses v as a string representation of a rule list.

type SimpleMapper

type SimpleMapper func(string) (string, bool)

A SimpleMapper maps variables to values without recursion.

func (SimpleMapper) Mapper

func (simple SimpleMapper) Mapper(s string, next Mapper) (string, bool)

Mapper performs a simple mapping of s.