slinkwatch

README

🔃 slinkwatch

slinkwatch is the Suricata Link Watcher, a tool to dynamically maintain interface entries in Suricata's configuration file, depending on what network interfaces are connected. It is meant to ease deployment of identical sensor installations at many heterogenous sites, allowing to make full use of the sensor resources in the light of varying monitoring volume.

Interaction with Suricata

In order to propagate changed interface configuration to Suricata, one would need to configure Suricata in such a way that the section of the configuration YAML created by the slinkwatch template is included from a separate file, e.g. via

...

include: interfaces.yaml

...

in, for example, /etc/suricata/suricata.yaml and then specifying /etc/suricata/interfaces.yaml as the --target-file in the slinkwatch call. Note that it must be writable by the slinkwatch process!

After modifying this file whenever a status change occurs, slinkwatch will attempt to restart Suricata. For systems that run systemd, slinkwatch will always try to restart the service given by the --service-name option (default is suricata.service). On non-systemd systems, it will run a simple command to restart Suricata (default is /etc/init.d/suricata restart). Whether systemd is available will be checked at runtime.

Resource assignment

Support for interfaces going online and offline at runtime obviously raises the question of how to assign computing resources (i.e. detection threads) to the individual interfaces. Unless all interfaces on a sensor are completely identical in terms of supported bandwidth and traffic, it is not sufficient to simply assign equal amounts of threads to all interfaces that are connected at a given point in time. For example, one might have a 10Gbit interface eth1 and a 1Gbit interface eth2 on such a machine, and most certainly one would want more threads assigned to the former than to the latter. Even more importantly, how would an existing assignment be changed to be most efficient when another 10Gbit interface, say eth3 gets a link?

We address this issue using thread weights. That is, each interface i is assigned a integer value w_i to denote its resource allocation importance. For example, in the case above we could assign w_eth1 = w_eth3 = 10 and w_eth2 = 2. We also consider the active set of interfaces A as the set of all interfaces that have an active link. On a machine with n threads available for detection, we can then assign to each interface i the value

as the number of threads allocated to detection for traffic on interface i. For example, for n = 40 we would then set

and

We aim for slight overcommitment of CPU hyperthreads to avoid idling CPUs as much as possible.

Installing dependencies via dep

The component of slinkwatch talking to systemd requires a specific godbus version. Please make sure to run

$ dep ensure

before building to make sure the correct version constraints apply.

Usage

Define the interfaces that are available to assign in a YAML file, together with their weights:

# Interfaces available for Suricata
--- 
ifaces:
  eth1: 
    clusterid: 98
    threadweight: 10
  eth2: 
    clusterid: 97
    threadweight: 2
  eth3: 
    clusterid: 96
    threadweight: 10

Adjust the template to fit the desired configuration format:

%YAML 1.1
---
af-packet:{{ range $iface, $vals := . }}
  - interface: {{ $iface }}
    threads: {{ $vals.Threads }}
    cluster-id: {{ $vals.ClusterID }}
    cluster-type: cluster_flow
    defrag: yes
    rollover: yes
    use-mmap: yes
    tpacket-v3: yes
    use-emergency-flush: yes
    buffer-size: 128000
{{ else }}
  - interface: default
    threads: auto
    use-mmap: yes
    rollover: yes
    tpacket-v3: yes
{{ end }}

Finally, run slinkwatch, preferably in the background (there's also a systemd service unit file in the repo).

$ slinkwatch run 

It is possible to specify the locations of the template and config file using the command line parameters:

$ slinkwatch run --help
Run the slinkwatch service

Usage:
  slinkwatch run [flags]

Flags:
  -c, --config string            Configuration file (default "config.yaml")
  -d, --delta-bytes uint         threshold of bytes to be exceeded on interface to be marked as up (default 100)
  -h, --help                     help for run
  -i, --interfaces string        Template file for interfaces (default "interfaces.tmpl")
  -p, --poll-interval duration   poll time for interface changes (default 5s)
  -r, --restart-command string   Suricata restart command (default "/etc/init.d/suricata restart")
  -s, --service-name string      systemd service name for Suricata service (default "suricata.service")
  -t, --target-file string       Target YAML file with interface information (default "/etc/suricata/interfaces.yaml")

Other commands

• slinkwatch make-config creates an initial YAML file with skeleton config entries for local interfaces (or a subset defined by a regular expression)
• slinkwatch makeman creates a set of man pages for the tool
• slinkwatch show-active lists the currently active set of interfaces (useful for debugging)

Dependencies/requirements

Needs ifplugo for network change notifications. This introduces a runtime dependency on libdaemon. It is also highly recommended to use systemd.

Authors

Sascha Steinbiss

License

GPL2 (due to ifplugo being GPL2).

Documentation

Index

• type ActiveSet
  • func MakeActiveSet(config *Config) *ActiveSet
  • func (a *ActiveSet) Add(iface string)
  • func (a *ActiveSet) Len() int
  • func (a *ActiveSet) Reset()
  • func (a *ActiveSet) String() string
  • func (a *ActiveSet) ToYAML(tmpl *template.Template, config *Config) (string, error)
• type ConfIface
• type Config
  • func (c *Config) GetWatchedInterfaces() []string
  • func (c *Config) LoadConfig(path string) error
• type InterfaceInfo
• type RestartManager
  • func MakeRestartManager(restartCommand string, serviceName string) (*RestartManager, error)
  • func (rm *RestartManager) RestartSuricata() error

Types

type ActiveSet

type ActiveSet struct {
	Config *Config
	Ifaces map[string]InterfaceInfo
}

ActiveSet contains descriptions of the currently connected interfaces.

func MakeActiveSet

func MakeActiveSet(config *Config) *ActiveSet

MakeActiveSet returns a new empty ActiveSet.

func (*ActiveSet) Add

func (a *ActiveSet) Add(iface string)

Add adds an interface to a given ActiveSet.

func (*ActiveSet) Len

func (a *ActiveSet) Len() int

Len returns the number of interfaces in the active set.

func (*ActiveSet) Reset

func (a *ActiveSet) Reset()

Reset clears the interfaces associated with an ActiveSet.

func (*ActiveSet) String

func (a *ActiveSet) String() string

String returns a string representation of an ActiveSet, listing its interfaces.

func (*ActiveSet) ToYAML

func (a *ActiveSet) ToYAML(tmpl *template.Template, config *Config) (string, error)

ToYAML returns the YAML representation of an ActiveSet, given a template and a configuration with thread weights.

type ConfIface

type ConfIface struct {
	ThreadWeight int
	ClusterID    int
	ExtraOptions map[string]string `yaml:"extraopts,omitempty"`
}

ConfIface represents the configured options associated with a single interface.

type Config

type Config struct {
	Ifaces map[string]ConfIface
}

Config represents basic configuration parsed from a file, such as interfaces to be watched.

func (*Config) GetWatchedInterfaces

func (c *Config) GetWatchedInterfaces() []string

GetWatchedInterfaces returns a slice of strings, listing all interfaces mentioned in the configuration file.

func (*Config) LoadConfig

func (c *Config) LoadConfig(path string) error

LoadConfig populates a Config from a file.

type InterfaceInfo

type InterfaceInfo struct {
	Threads      int
	ClusterID    int
	ExtraOptions map[string]string
}

InterfaceInfo contains basic information about a specific interface entry.

type RestartManager

type RestartManager struct {
	IsSystemd      bool
	RestartCommand string
	ServiceName    string
}

RestartManager encapsulates interaction with the init system to restart the Suricata process on request.

func MakeRestartManager

func MakeRestartManager(restartCommand string, serviceName string) (*RestartManager, error)

MakeRestartManager returns a new RestartManager with restart command and service name preconfigured.

func (*RestartManager) RestartSuricata

func (rm *RestartManager) RestartSuricata() error

RestartSuricata triggers a Suricata restart, using the most appropriate method.