NAME

flowd.conf —

NetFlow Collector daemon configuration file

DESCRIPTION

This is the configuration file for the flowd(8) NetFlow collector daemon. All runtime configuration is performed through this file. By default, flowd(8) will use the configuration located at /usr/local/etc/flowd.conf, though an alterate file may be specified on the command line.

The flowd.conf config file is divided into four main sections.

Macros: User-defined variables may be defined and used later, simplifying the configuration file.
Global configuration: Global settings for the flowd daemon.
Storage field selection: This selection specifies which fields from the flow packets are stored in the on-disk log file. By eliminating unnecessary fields, the log files may be made quite compact.
Filter: The filter section allows filtering and tagging of flows using a matching language similar to a packet filter.

MACROS

Much like cpp(1) or m4(1), macros can be defined that will later be expanded in context. Macro names must start with a letter, and may contain letters, digits and underscores. Macro names may not be reserved words (for example listen, accept, store). Macros are not expanded inside quotes.

For example,

internal_network="192.0.2.0/24"
inbound_tag="0x100"
outbound_tag="0x200"
discard quick src $internal_network dst $internal_network
accept tag $inbound_tag src dst $internal_network
accept tag $outbound_tag src $internal_network dst any

GLOBAL CONFIGURATION

There are several settings that affect the operation of the flowd(8) daemon globally.

flow source

Specify an address (or network) that flowd(8) should accept flows from. The default is to accept flow packets from anywhere, but if one or more flow source options has been specified then flowd(8) will disregard flow packets from other hosts. This is separate from the flow filtering language (mentioned below in the Filter section) - packets disregarded at this stage are not subject to any further processing.

For example,

flow source 127.0.0.1
flow source 192.168.0.0/16
flow source [4000:1::]/32

This option is optional, if it is not specified then flowd(8) will accept flow records from any address. The use of this option is strongly recommended when flow export protocols are used that require the collector to retain state information (e.g. NetFlow v.9 flow templates) in order to avoid flooding attacks.

join group

Specify multicast groups to join. This allows flowd(8) to receive multicast NetFlow datagrams. Both IPv6 and IPv6 groups are supported, IPv6 groups may specify an interface scope.

For example,

join group 224.0.1.20
join group ff02::114%em0
join group ff05::114

listen on

Specifies an address and port on which flowd(8) should listen. IPv6 addresses must be surrounded by square brackets to distinguish them from the port number. This option may be specified more than once to listen on mutiple addresses and ports.

For example,

listen on 0.0.0.0:12345
listen on [::]:12345

This option accepts the modifier bufsize to allow the specification (in bytes) of the receive buffer for this socket. If not specified, flowd.conf will attempt to set a large buffer size automatically.

For example,

listen on 0.0.0.0:12345 bufsize 65536

The listen on directive is mandatory. There is no default value.

logfile

Specifies the file in which the received flow records are stored. The full path to the file must be specified in quotes.

For example,

logfile "/var/log/flowd.bin"

There is no default value for this option and it it mandatory to specify at least one of the logfile and logsock options.

logsock

Specifies a path to an AF_UNIX datagram socket that will be relayed flows in realtime as they are received by flowd. Please note that this option is experimental.

For example,

logsock "/var/log/flowd.sock"

This option accepts the modifier bufsize to allow the specification (in bytes) of the send buffer for this socket. If not specified, flowd.conf will use the system's default buffer size.

For example,

logsock "/var/log/flowd.sock" bufsize 65536

There is no default value for logfile and it is mandatory to specify at least one of the logfile and logsock options.

pidfile

Specify a file in which flowd(8) will store its process id once it has started up. For example,

pidfile "/var/run/flowd.pid"

The default is to create a PID file in /var/run/flowd.pid

STORAGE FIELD SELECTION

After filtering, flowd(8) stores the flows that it receives in a flexible binary format, which permits the selection of which fields will be stored on disk. This enables the flow logs to be made very compact, by selecting only the fields of interest (this is particularly relevant for high-traffic collectors)

The selection of which fields are recorded is made through the store configuration directive. Each store directive adds the specified field to the store log. For example:

store SRCDST_ADDR
store CRC32

This would store just the source/destination addresses and a checksum per flow received.

The field names supported in the store directive are:

ALL: Store all available fields.
TAG: Stores the tag set by the flow filter. This field must be present for the tags to be recorded.
RECV_TIME: Stores the time that the flow was received by flowd(8).
PROTO_FLAGS_TOS: Store the protocol, TCP flags and type-of-service (ToS) fields from the NetFlow packet.
Like several other storage fields, PROTO_FLAGS_TOS actually contains several small NetFlow fields together for convenience.
AGENT_ADDR: Store the address of the agent that sent the flow to the collector.
SRC_ADDR: Store the source address from the NetFlow packet.
DST_ADDR: Store the destination address from the NetFlow packet.
GATEWAY_ADDR: Store the gateway address from the NetFlow packet.
SRCDST_PORT: Store the source and destination ports from the NetFlow packet.
PACKETS_OCTETS: Store the packet and octet counters from the NetFlow packet.
IF_INDICES: Store the in and out interface indices from the NetFlow packet.
AGENT_INFO: Store several fields from the NetFlow packet's header, including the agent uptime and "wall clock" time and the version of NetFlow in use.
AS_INFO: Store the source and destination network Autonomous System (AS) numbers and network prefix lengths from the NetFlow packet.
FLOW_ENGINE_INFO: Store the flow engine type and ID fields from the NetFlow packet.
CRC32: Store a per-flow checksum along with each flow record to detect corruption of the flow log file. This checksum is automatically checked by flowd-reader(8). Its use is highly recommended.

Regardless of the options specified by the store directive, flowd(8) will always store the time that the flow was received and an integer "tag" that may be set by the filter system (see below).

FILTER

flowd(8) has the ability to accept and discard flow records based on the address of the agent that sent them or several parameters in the flow itself.

Flows that are accepted may also be "tagged" with a 32-bit unsigned integer. This is intended to allow basic classification of flows. For example, this may be used to tag traffic that remains internal to the local network so that it may be treated specially by a traffic accounting system.

For each flow received and processed by the filter, the filter rules are evaluated in sequential order, from first to last. The last matching accept or discard rule decides what action is taken.

The following actions can be used in the filter:

discard: The flow record is ignored and is not written to disk.
accept: The flow record is recorded to disk.

PARAMETERS

The rule parameters specify the NetFlow records to which a rule applies. Most parameters are optional. If a parameter is specified, the rule only applies to packets with matching attributes. The matching sense of some clauses in a filter rule may be negated by placing a ! operator between a filter keyword and its parameter.

tag <number>: Tag flows matched by this rule with the number. This option only makes sense for accept rules.
quick: If an flow record matches a rule which has the quick option set, this rule is considered the last matching rule, and evaluation of subsequent rules is skipped.
agent [!] <address>/<len>: This rule applies to incoming flow packets that are received from an agent with an address in the specified network range. NB. this applies to the device sending the NetFlow packet, not the addresses within the packet itself.
[!] <inet|inet6>: This rule applies to flows whose source or destination address family matches that specified.
in_ifndx [!] <index>: Match traffic whose input interface number matches index.
out_ifndx [!] <index>: Match traffic whose output interface number matches index.
src [!] <address>/<len> [port [!] <port>]: This rule applies only to flows whose source address (as recorded in the NetFlow packet) is in the specified address range.
If the port option is specified, then the rule is further restricted to flows whose source port number matches that specified. NB. the port checks are only valid for rules matching TCP or UDP flows.
dst [!] <address>/<len> [port [!] <port>]: This rule applies only to flows whose destination address (as recorded in the NetFlow packet) is in the specified address range.
If the port option is specified, then the rule is further restricted to flows whose destination port number matches that specified. NB. the port checks are only valid for rules matching TCP or UDP flows.
proto [!] <protocol>: This rule only applies for flows whose protocol matches that specified. Protocols may be specified by name (tcp, udp, icmp, etc) or by number.
tos [!] <tos>: This rule only applies for flows whose type-of-service (ToS) matches that specified. The
tos [!] <tos>: may be specified as a decimal or hexidecimal number.
tcp_flags [mask <mask>] [!] equals <flags>: This rule only applies for TCP flows where the accumulated TCP flags seen over the lifetime of the flow match the flags specified. If a mask is specified, the flags checked are the logical AND of the accumulated TCP flags and the mask. The mask and flags may be specified as decimal or hexidecimal numbers. NB. This clause may only be applied to rules matching TCP flows.
days <day> | <day>-<day> | <day> [,<day>[,...]]: This rule only applies for flows received on the specified days of the week. Days may be selected as a comma separated list of names (e.g. monday,tuesday,wednesday) or as a hyphen separated range. Abbreviations are allowed, e.g. mon-fri.
after <HH:MM[:SS]>: This rule only applies for flows received after the specified time of day.
before <HH:MM[:SS]>: This rule only applies for flows received before the specified time of day.
after date <YYYY[MMDD[HHMM[SS]]]>: This rule only applies for flows received after the specified date / time.
before date <YYYY[MMDD[HHMM[SS]]]>: This rule only applies for flows received before the specified date / time.

This is an example of the filtering language in action:

# Immediately discard all flowd from unknown agents
discard quick agent ! 192.2.0.254
# Perform classification of local traffic
accept tag 1 src 192.0.2.0/24 dst 192.0.2.0/24
# Classification of inbound traffic
accept tag 2 dst 192.0.2.0/24
# Classification of outbound traffic
accept tag 3 src 192.0.2.0/24
# Classification of web traffic
accept tag 0x100 dst any port 80 proto tcp
accept tag 0x100 src any port 80 proto tcp
# Ignore all but one hosts' traffic to a specific port
discard src ! 192.2.0.33 dst any port 12345 proto tcp
# Ignore unestablished TCP flows (ACK = 0x10, SYN = 0x02)
discard proto tcp tcp_flags mask 0x12 !equals 0x12
# Tag flows received during business hours
accept days Monday-Friday after 08:30:00 before 17:30:00
# Ignore flows sent on weekends
discard days Sat,Sun
# Ignore flows sent outside a certain date/time range
discard after date 20051123 before date 20051124084459
# Ignore flows coming in interface 10
discard in_ifndx 10

AUTHORS

Damien Miller <djm@mindrot.org>