config

Documentation

Overview

Package config implements a parser for L2TP configuration represented in the TOML format: https://github.com/toml-lang/toml.

Please refer to the TOML repos for an in-depth description of the syntax.

Tunnel and session instances are called out in the configuration file using named TOML tables. Each tunnel or session instance table contains configuration parameters for that instance as key:value pairs.

# This is a tunnel instance named "t1"
[tunnel.t1]

# local specifies the local address that the tunnel should
# bind its socket to
local = "127.0.0.1:5000"

# peer specifies the address of the peer that the tunnel should
# connect its socket to
peer = "127.0.0.1:5001"

# version specifies the version of the L2TP specification the
# tunnel should use.
# Currently supported values are "l2tpv2" and "l2tpv3"
version = "l2tpv3"

# encap specifies the encapsulation to be used for the tunnel.
# Currently supported values are "udp" and "ip".
# L2TPv2 tunnels are UDP only.
encap = "udp"

# tid specifies the local tunnel ID of the tunnel.
# Tunnel IDs must be unique for the host.
# L2TPv2 tunnel IDs are 16 bit, and may be in the range 1 - 65535.
# L2TPv3 tunnel IDs are 32 bit, and may be in the range 1 - 4294967295.
tid = 62719

# ptid specifies the peer's tunnel ID for the tunnel.
# The peer's tunnel ID must be unique for the peer, and are unrelated
# to the local tunnel ID.
# The rules for tunnel ID range apply to the peer tunnel ID too.
ptid = 72819

# window_size specifies the initial window size to use for the L2TP
# reliable transport algorithm which is used for control protocol
# messages.  The window size dictates how many control messages the
# tunnel may have "in flight" (i.e. pending an ACK from the peer) at
# any one time.  Tuning the window size can allow high-volume L2TP servers
# to improve performance.  Generally it won't be necessary to change
# this from the default value of 4.
window_size = 10 # control messages

# hello_timeout if set enables L2TP keep-alive (HELLO) messages.
# A hello message is sent N milliseconds after the last control
# message was sent or received.  It allows for early detection of
# tunnel failure on quiet connections.
# By default no keep-alive messages are sent.
hello_timeout = 7500 # milliseconds

# retry_timeout if set tweaks the starting retry timeout for the
# reliable transport algorithm used for L2TP control messages.
# The algorithm uses an exponential backoff when retrying messages.
# By default a starting retry timeout of 1000ms is used.
retry_timeout = 1500 # milliseconds

# max_retries sets how many times a given control message may be
# retried before the transport considers the message transmission to
# have failed.
# It may be useful to tune this value on unreliable network connections
# to avoid suprious tunnel failure, or conversely to allow for quicker
# tunnel failure detection on reliable links.
# The default is 3 retries.
max_retries 5

# host_name sets the host name the tunnel will advertise in the
# Host Name AVP per RFC2661.
# If unset the host's name will be queried and the returned value used.
host_name "basilbrush.local"

# framing_caps sets the framing capabilities the tunnel will advertise
# in the Framing Capabilities AVP per RFC2661.
# The default is to advertise both sync and async framing.
framing_caps = ["sync","async"]

# This is a session instance called "s1" within parent tunnel "t1".
# Session instances are always created inside a parent tunnel.
[tunnel.t1.session.s1]

# sid specifies the local session ID of the session.
# Session IDs must be unique to the tunnel for L2TPv2, or unique to
# the peer for L2TPv3.
# L2TPv2 session IDs are 16 bit, and may be in the range 1 - 65535.
# L2TPv3 session IDs are 32 bit, and may be in the range 1 - 4294967295.
sid = 12389

# psid specifies the peer's session ID for the session.
# The peer's session ID is unrelated to the local session ID.
# The rules for the session ID range apply to the peer session ID too.
psid = 1234

# pseudowire specifies the type of layer 2 frames carried by the session.
# Currently supported values are "ppp", "eth", and "pppac".
# L2TPv2 tunnels support PPP and PPPAC pseudowires only.
pseudowire = "eth"

# seqnum, if set, enables the transmission of sequence numbers with
# L2TP data messages.  Use of sequence numbers enables the data plane
# to reorder data packets to ensure they are delivered in sequence.
# By default sequence numbers are not used.
seqnum = false

# cookie, if set, specifies the local L2TPv3 cookie for the session.
# Cookies are a data verification mechanism intended to allow misdirected
# data packets to be detected and rejected.
# Transmitted data packets will include the local cookie in their header.
# Cookies may be either 4 or 8 bytes long, and contain aribrary data.
# By default no local cookie is set.
cookie = [ 0x12, 0xe9, 0x54, 0x0f, 0xe2, 0x68, 0x72, 0xbc ]

# peer_cookie, if set, specifies the L2TPv3 cookie the peer will send in
# the header of its data messages.
# Messages received without the peer's cookie (or with the wrong cookie)
# will be rejected.
# By default no peer cookie is set.
peer_cookie = [ 0x74, 0x2e, 0x28, 0xa8 ]

# interface_name, if set, specifies the network interface name to be
# used for the session instance.
# By default the Linux kernel autogenerates an interface name specific to
# the pseudowire type, e.g. "l2tpeth0", "ppp0".
# Setting the interface name can be useful when you need to be certain
# of the interface name a given session will use.
# By default the kernel autogenerates an interface name.
interface_name = "l2tpeth42"

# l2spec_type specifies the L2TPv3 Layer 2 specific sublayer field to
# be used in data packet headers as per RFC3931 section 3.2.2.
# Currently supported values are "none" and "default".
# By default no Layer 2 specific sublayer is used.
l2spec_type = "default"

# pppoe_session_id specifies the assigned PPPoE session ID for the session.
# Per RFC2516, the PPPoE session ID is in the range 1 - 65535
# This parameter only applies to pppac pseudowires.
pppoe_session_id = 1234

# pppoe_peer_mac specifies the MAC address of the PPPoE peer for the session.
# This parameter only applies to pppac pseudowires.
pppoe_peer_mac = [ 0x02, 0x42, 0x94, 0xd1, 0x4e, 0x9a ]

Index

• type Config
  • func LoadFile(path string) (*Config, error)
  • func LoadFileWithCustomParser(path string, customParser ConfigParser) (*Config, error)
  • func LoadString(content string) (*Config, error)
  • func LoadStringWithCustomParser(content string, customParser ConfigParser) (*Config, error)
• type ConfigParser
• type NamedSession
• type NamedTunnel

Types

type Config

type Config struct {
	// The entire tree as a map as parsed from the TOML representation.
	// Apps may access this tree to handle their own config tables.
	Map map[string]interface{}
	// All the tunnels defined in the configuration.
	Tunnels []NamedTunnel
	// contains filtered or unexported fields
}

Config contains L2TP configuration for tunnel and session instances.

func LoadFile

func LoadFile(path string) (*Config, error)

LoadFile loads configuration from the specified file.

func LoadFileWithCustomParser

func LoadFileWithCustomParser(path string, customParser ConfigParser) (*Config, error)

LoadFileWithCustomParser loads configuration from the specified file, calling the ConfigParser interface for unrecognised key/value pairs.

func LoadString

func LoadString(content string) (*Config, error)

LoadString loads configuration from the specified string.

func LoadStringWithCustomParser

func LoadStringWithCustomParser(content string, customParser ConfigParser) (*Config, error)

LoadStringWithCustomParser loads configuration from the specified file, calling the ConfigParser interface for unrecognised key/value pairs.

type ConfigParser

type ConfigParser interface {
	// ParseParameter is called for any unrecognised key/value pair not
	// within either a tunnel or session block.
	ParseParameter(key string, value interface{}) error
	// ParseTunnelParameter is called for an unrecognised key/value pair
	// within a tunnel block.
	ParseTunnelParameter(tunnel *NamedTunnel, key string, value interface{}) error
	// ParseSessionParameter is called for an unrecognised key/value pair
	// within a session block.
	ParseSessionParameter(tunnel *NamedTunnel, session *NamedSession, key string, value interface{}) error
}

ConfigParser allows for parsing of custom config file fields which are not directly implemented by package config.

This is useful to allow an application to embed custom configuration into the configuration file.

type NamedSession

type NamedSession struct {
	// The session's name as specified in the config file.
	Name string
	// The session L2TP configuration.
	Config *l2tp.SessionConfig
}

NamedSession contains L2TP configuration for a session instance.

type NamedTunnel

type NamedTunnel struct {
	// The tunnel's name as specified in the config file.
	Name string
	// The tunnel L2TP configuration.
	Config *l2tp.TunnelConfig
	// The sessions defined within this tunnel in the config file.
	Sessions []NamedSession
}

NamedTunnel contains L2TP configuration for a tunnel instance, and the sessions that tunnel contains.