SOFTFLOWD(8)

📦
version 1.1.1 · 3 versions
, in debian trixie, nixos 26.05, nixpkgs unstable, ubuntu questing, ubuntu resolute, ubuntu stonking

🌸 SOFTFLOWD(8) — the softflowd manual, bestie edition 🌸

System Manager's Manual ✨ softflowd ✨ Traffic flow monitoring

okay so listen. this is softflowd(8), and she is that girl when it comes to watching your network traffic. let's get into it 💅

✨ NAME ✨

softflowd — Traffic flow monitoring 🦋

✨ SYNOPSIS ✨

softflowd [-6dDhbalN] [-L hoplimit] [-T track_level] [-c ctl_sock] [-i
          [if_ndx:]interface] [-m max_flows] [-n host:port] [-p pidfile]
          [-r pcap_file] [-t timeout_name=seconds] [-v netflow_version]
          [-P transport_protocol] [-A time_format] [-s sampling_rate]
          [-C capture_length] [-R receive_port] [-S send_interface_name]
          [-x number_of_mpls_labels] [-e exporter_ip_address]
          [bpf_expression]

like… that's a lot of flags bestie but every single one of them eats, i promise 🫶

✨ DESCRIPTION ✨

softflowd is a software implementation of a flow-based network traffic monitor. she reads network traffic and gathers info about the active traffic flows running through it. and a "traffic flow"? that's communication between two IP addresses — or, if the protocol sitting on top is TCP or UDP, address/port tuples. periodt. 💖

the intended use of softflowd is as a software implementation of Cisco's NetFlow(tm) traffic account system. she supports data export using versions 1, 5, 9 or 10 (a.k.a. IPFIX) of the NetFlow protocol. softflowd can also run in statistics-only mode, where it just collects summary information. but ngl? too few statistics get collected there to make that mode really useful for anything other than debugging. 🙈

network traffic can be obtained two ways:

  • by listening on a promiscuous network interface (unless the -N option is given), or
  • by reading stored pcap(3) files — like the ones written by tcpdump(8).

traffic may be filtered with an optional bpf(4) program, specified on the command-line as bpf_expression. softflowd is IPv6 capable and will track IPv6 flows if the NetFlow export protocol supports it (currently only NetFlow v.9 possesses an IPv6 export capability). 👑

softflowd tries to track only active traffic flows. when a flow has been quiescent for a period of time it gets expired automatically. flows may also be expired early if they approach their traffic counts exceed 2 Gib, or if the number of flows being tracked exceeds max_flows (default: 8192). in that last case, flows are expired oldest-first. 💀

upon expiry, the flow information is accumulated into statistics which may be viewed using softflowctl(8). if the -n option has been specified, the flow information is formatted in a UDP datagram which is compatible with versions 1, 5 or 9 of Cisco's NetFlow(tm) accounting export format. these records are sent to the specified host and port. the host may represent a unicast host or a multicast group. 🌈

the command-line options are as follows:

  • -n host:port — Specify the host and port that the accounting datagrams are to be sent to. The host may be specified using a hostname or using a numeric IPv4 or IPv6 address. Numeric IPv6 addresses should be enclosed in square brackets to avoid ambiguity between the address and the port. The destination port may be a portname listed in services(5) or a numeric port. Comma can be used for specifying multiple destinations. 🎀
  • -N — Do not put the interface into promiscuous mode. Note that the interface might be in promiscuous mode for some other reason.
  • -i [if_ndx:]interface — Specify a network interface on which to listen for traffic. Either the -i or the -r options must be specified.
  • -r pcap_file — Specify that softflowd should read from a pcap(3) packet capture file (such as one created with the -w option of tcpdump(8)) file rather than a network interface. softflowd processes the whole capture file and only expires flows when max_flows is exceeded. In this mode, softflowd will not fork and will automatically print summary statistics before exiting.
  • -p pidfile — Specify an alternate location to store the process ID when in daemon mode. Default is /var/run/softflowd.pid
  • -c ctlsock — Specify an alternate location for the remote control socket in daemon mode. Default is /var/run/softflowd.ctl
  • -m max_flows — Specify the maximum number of flows to concurrently track. If this limit is exceeded, the flows which have least recently seen traffic are forcibly expired. In practice, the actual maximum may briefly exceed this limit by a small amount as expiry processing happens less frequently than traffic collection. The default is 8192 flows, which corresponds to slightly less than 800k of working data.
  • -t timeout_name=time — Set the timeout names timeout_name to time. Refer to the "Timeouts" section for the valid timeout names and their meanings. The time parameter may be specified using one of the formats explained in the "Time Formats" section below.
  • -d — Specify that softflowd should not fork and daemonise itself.
  • -6 — Force softflowd to track IPv6 flows even if the NetFlow export protocol does not support reporting them. This is useful for debugging and statistics gathering only.
  • -D — Places softflowd in a debugging mode. This implies the -d and -6 flags and turns on additional debugging output. 🔍
  • -B size_bytes — Libpcap buffer size in bytes
  • -b — Bidirectional mode in IPFIX (-b work with -v 10)
  • -a — Adjusting time for reading pcap file (-a work with -r)
  • -l — Load balancing mode for multiple destinations which are specified with -n
  • -x number_of_mpls_labels — specify number of mpls labels for export
  • -h — Display command-line usage information.
  • -L hoplimit — Set the IPv4 TTL or the IPv6 hop limit to hoplimit. softflowd will use the default system TTL when exporting flows to a unicast host. When exporting to a multicast group, the default TTL will be 1 (i.e. link-local).
  • -T track_level — Specify which flow elements softflowd should be used to define a flow. track_level may be one of:
    • “ether” — track everything including source and destination addresses, source and destination port, source and destination ethernet address, vlanid and protocol
    • “vlan” — track source and destination addresses, source and destination port, vlanid and protocol
    • “full” — track source and destination addresses, source and destination port and protocol in the flow, the default
    • “proto” — track source and destination addresses and protocol
    • “ip” — only track source and destination addresses

Selecting either of the latter options will produce flows with less information in them (e.g. TCP/UDP ports will not be recorded). This will cause flows to be consolidated, reducing the quantity of output and CPU load that softflowd will place on the system at the cost of some detail being lost. 🎀

  • -v netflow_version — Specify which version of the NetFlow(tm) protocol softflowd should use for export of the flow data. Supported versions are 1, 5, 9, 10(IPFIX), and psamp. Default is version 5.
  • -P transport_protocol — Specify transport layer protocol for exporting packets. Supported transport layer protocols are udp, tcp, and sctp.
  • -A time_format — Specify absolute time format form exporting records. Supported time formats are sec, milli, micro, and nano.
  • -s sampling_rate — Specify periodical sampling rate (denominator).
  • -C capture_length — Specify length for packet capture (snaplen).
  • -R receive_port — Specify port number for PSAMP receive mode.
  • -S send_interface_name — Specify send interface name. (This option works on Linux only because of use of SO_BINDTODEVICE for setsockopt.) 🐧
  • -e exporter_ip_address — Specify exporter IPv4 or IPv6 address.

any further command-line arguments will be concatenated together and applied as a bpf(4) packet filter. this filter will cause softflowd to ignore the specified traffic. 🙅‍♀️

⏰ Timeouts ⏰

softflowd will expire quiescent flows after user-configurable periods. the exact timeout used depends on the nature of the flow. the various timeouts that may be set from the command-line (using the -t option) and their meanings are:

  • general — This is the general timeout applied to all traffic unless overridden by one of the other timeouts.
  • tcp — This is the general TCP timeout, applied to open TCP connections.
  • tcp.rst — This timeout is applied to a TCP connection when a RST packet has been sent by one or both endpoints.
  • tcp.fin — This timeout is applied to a TCP connection when a FIN packet has been sent by both endpoints.
  • udp — This is the general UDP timeout, applied to all UDP connections.
  • maxlife — This is the maximum lifetime that a flow may exist for. All flows are forcibly expired when they pass maxlife seconds. To disable this feature, specify a maxlife of 0.
  • expint — Specify the interval between expiry checks. Increase this to group more flows into a NetFlow packet. To disable this feature, specify a expint of 0.

flows may also be expired if there are not enough flow entries to hold them, or if their traffic exceeds 2 Gib in either direction. softflowctl(8) may be used to print information on the average lifetimes of flows and the reasons for their expiry. 👑

🕰️ Time Formats 🕰️

softflowd command-line arguments that specify time may be expressed using a sequence of the form: time[qualifier], where time is a positive integer value and qualifier is one of the following:

  • <none> — seconds
  • s | S — seconds
  • m | M — minutes
  • h | H — hours
  • d | D — days
  • w | W — weeks

each member of the sequence is added together to calculate the total time value. ✨

time format examples:

600     600 seconds (10 minutes)
10m     10 minutes
1h30m   1 hour 30 minutes (90 minutes)

🎛️ Run-time Control 🎛️

a daemonised softflowd instance may be controlled using the softflowctl(8) command. this interface allows one to shut down the daemon, force expiry of all tracked flows and extract debugging and summary data. also, receipt of a SIGTERM or SIGINT will cause softflowd to exit, after expiring all flows (and thus sending flow export packets if -n was specified on the command-line). 🫶

⚠️ bestie, listen: if you do not want to export flows upon shutdown, clear them first with softflowctl(8) or use softflowctl(8)'s “exit” command. otherwise she's gonna send everything on her way out the door 💅

to be continued… 👀

✨ EXAMPLES ✨

Okay bestie, this is the part where it all clicks. Real commands, real vibes 💅

  • softflowd -i fxp0
softflowd -i fxp0

This one tells softflowd to listen on the interface fxp0 and just… vibe. It runs in statistics gathering mode only — meaning no NetFlow data export at all. It's watching, it's counting, it's minding its business. No packets leave. 🫶

  • softflowd -i fxp0 -n 10.1.0.2:4432
softflowd -i fxp0 -n 10.1.0.2:4432

Now we're talking. Listens on fxp0 and exports NetFlow v.5 datagrams on flow expiry to a flow collector hanging out at 10.1.0.2 port 4432. ✨

  • softflowd -i fxp0 -n 10.1.0.2:4432,10.1.0.3:4432
softflowd -i fxp0 -n 10.1.0.2:4432,10.1.0.3:4432

Same deal, but the flows get exported to two collectors: 10.1.0.2 port 4432 and 10.1.0.3 port 4432. Double the collectors, double the slay. 🎀

  • softflowd -i fxp0 -l -n 10.1.0.2:4432,10.1.0.3:4432
softflowd -i fxp0 -l -n 10.1.0.2:4432,10.1.0.3:4432

Okay so this is the same two-collector setup but with load balancing mode turned on via -l. The way it splits: odd netflow packets go to 10.1.0.2 port 4432, and even netflow packets go to 10.1.0.3 port 4432. Perfectly balanced, as all things should be. ⚖️🔥

  • softflowd -v 5 -i fxp0 -n 10.1.0.2:4432 -m 65536 -t udp=1m30s
softflowd -v 5 -i fxp0 -n 10.1.0.2:4432 -m 65536 -t udp=1m30s

This glow-up does two things: it bumps the number of concurrent flows softflowd tracks up to 65536, and it stretches the timeout for UDP flows out to 90 seconds. More flows, longer patience. Iconic. 👑

  • softflowd -v 9 -i fxp0 -n 224.0.1.20:4432 -L 64
softflowd -v 9 -i fxp0 -n 224.0.1.20:4432 -L 64

NetFlow v.9 flows going out to the multicast group 224.0.1.20. And -L 64 sets the TTL on those export datagrams to 64, so multicast receivers can be many hops away and still catch them. Long-distance relationship, but make it networking. 🌈

  • softflowd -i fxp0 -p /var/run/sfd.pid.fxp0 -c /var/run/sfd.ctl.fxp0
softflowd -i fxp0 -p /var/run/sfd.pid.fxp0 -c /var/run/sfd.ctl.fxp0

Here we're picking alternate locations for the control socket and the pid file. This kind of command line is super useful when you're running multiple instances of softflowd on one machine — no fighting over the same files, everyone gets their own lil corner. 🦋

🌸 FILES 🌸

  • /var/run/softflowd.pid

This file stores the process ID when softflowd is in daemon mode. You can override this location with the -p command-line option. 📌

  • /var/run/softflowd.ctl

This is the remote control socket. softflowd listens right here for commands coming in from softflowctl(8). And yep, you can override this location too, with the -c command-line option. 🎛️

💀 BUGS 💀

Not everything is perfect, bestie, and we gotta be honest about it.

Right now, softflowd does not handle maliciously fragmented packets properly. Like — packets fragmented such that the UDP or TCP header doesn't fit into the first fragment. 🙈

What happens? It will produce correct traffic counts when it's handed those maliciously fragmented packets, but it will not record TCP or UDP port information. So the bytes are right, the ports are just… missing. 😭

Please report bugs in softflowd to https://github.com/irino/softflowd/issues 🫶

👑 AUTHORS 👑

  • Damien Miller <djm@mindrot.org>
  • Hitoshi Irino (current maintainer) <irino@sfc.wide.ad.jp>

Legends, both of them. 💜

🔗 SEE ALSO 🔗

And for the lore girlies who love a primary source:

And that's a wrap on SOFTFLOWD(8)! This one's the Debian build, dated November 17, 2019. Go forth and export those flows, babe. No cap. 💖✨🎀

📦 where this page comes from