SFCAPD(1)

🎀 SFCAPD(1) 🎀

okay so real talk — this is the General Commands Manual page for sfcapd, section 1 of your man pages, and she's a whole icon. bestie, grab a snack, because this synopsis is a long one and we're getting into all of it. 💅

---

✨ NAME ✨

sfcapd — an sflow collector for sflow version v2/v4 and v5. that's it, that's the vibe. she collects, she listens, she does not miss. 🦋

---

🌸 SYNOPSIS 🌸

sfcapd -w flowdir [-C config] [-z=<compress>] [-j] [-y] [-l flowdir]
       [-T] [-E] [-Z] [-D] [-u userid] [-g groupid] [-S num]
       [-t interval] [-P pidfile] [-p port] [-d device] [-I ident]
       [-b bindhost] [-f pcapfile] [-4] [-6] [-J mcastgroup]
       [-R repeater] [-A] [-B buffsize] [-n sourceparam]
       [-M multiflowdir] [-i metricrate] [-m metricpath] [-o optionlist]
       [-e] [-x command] [-X extensionList] [-W workers] [-v level] [-V]
       [-h]

ngl that's a lot of brackets, but don't panic — every single one of those flags gets its own little moment later on, iykyk. 👑

✨ DESCRIPTION ✨

Okay so picture this: sfcapd is out here reading sflow data straight off the network and stashing all those records into binary formatted files. The sflow implementation? It's based off sflowtool, bestie. And the packet samples get converted into netflow compatible records. It's giving translator energy and honestly it ate. 💅

🫶 Quick heads-up from the group chat: if what you actually wanna collect is netflow data, go look at nfcapd, which is also part of the nfdump tools. Different vibe, different job.

So sflow is an industry standard developed by InMon Corporation — literally iconic of them. For more info see http://sflow.org. 🦋

sfcapd is the twin of nfcapd and supports the exact same feature set, no cap. See also nfcapd(1) for more details if you want the full lore.

✨ One thing to know though: sFlow sampling information is supplied by the exporter in each sample, so sfcapd does not provide nfcapd's -s default-sampling option. It's just built different. Not me leaving features out — it literally doesn't need it. 💀

Here come the options:

• -w flowdir — Sets the flow directory where the output files get stored. If you also specify a sub hierarchy with -S, the final directory is concatenated to flowdir/subdir. So like, they team up. 🎀
• -C config — Reads additional configuration parameters from the config file config. sfcapd tries to read the config file from the install default path $prefix/etc/ — which may be overwritten by the environment variable NFCONF, which again is overwritten by this option -C. Yeah, it's a whole precedence chain, iykyk. And if you specify -C none, then no config file is read, even if one is found in the search path. Bye config. 🙈
• -p portnum — Set the port number to listen on. Default port is 9995. 👑
• -d interface — Reads sflow data from an erspan encoded datalink. All traffic sent to this interface is interpreted as sflow data stream. Yes, all of it. Main character energy, it assumes everything is sflow. 🔥
• -b bindhost — Specifies the hostname/IPv4/IPv6 address to bind for listening. This can be an IP address or a hostname, resolving to a local IP address. 🧚
• -f pcapfile — Offline mode, bestie: read sflow data from a pcap file instead of the network. Needs --enable-readpcap for configure, so uh, check that first. 💀
• -4 — Forces sfcapd to listen on IPv4 addresses only. Can be used together with -b if a hostname has IPv4 and IPv6 addresses. Pick a side. 💅
• -6 — Forces sfcapd to listen on IPv6 addresses only. Can be used together with -b if a hostname has IPv4 and IPv6 addresses. Also picking a side, but the other one. 🌈
• -J mcastgroup — Join the specified IPv4 or IPv6 multicast group for listening. Come hang out with the multicast girlies. 🫶
• -R host[/port] — Enables the packet repeater. All incoming packets are sent additionally to another host and port. So host is either a valid IPv4/IPv6 address, or a symbolic hostname, which resolves to a valid IP address. port may be omitted and defaults to 9995. 📌 Note: as IPv4/IPv6 are both accepted, the host/port separator is /. Up to 8 additional repeaters may be defined. Use this method to daisy chain collectors, fr fr. 🌸
• -A — Sets source address spoofing mode for the repeater. The source address of the repeated packages is set to the original IP address. This needs sfcapd to be started with root privileges. 🙈 And please note: source spoofing may be blocked by firewalls or routers in your network. So like, don't be shocked if it doesn't work through somebody's firewall, that's not on us.
• -I ident — Sets ident as the identification string for the current source. This string is written into the output file to identify the source. Default is 'none'. If you have multiple sources, see option -n below. 👀
• -n 'ident,IPList,flowdir' — Configures a NetFlow/IPFIX source identified by the string ident,IPList,flowdir. The IPList is a semicolon-separated list of one or more IP addresses or CIDR blocks, and may include both IPv4 and IPv6 addresses. For example:

-n 'router1,192.0.2.1;2001:db8::1/64,in'

Note that the entire argument must be enclosed in single quotes to prevent the shell from interpreting the semicolon as a command separator. Shell said "new command?" and we said no bestie. 😭

This option also acts as a filter: only packets originating from IP addresses listed in IPList will be accepted. Packets from sources not matching any entry in the list are silently discarded. Not even a goodbye. 💀

If you have multiple sources per collector, specify multiple -n options. All exporters send their flows to the same port specified with -p. And ⚠️ do not mix single-source configuration using -I with multiple -n options. Pick a lane, queen.

• -M flowdir — Set the flow directory for dynamically allocated exporters. New exporters are dynamically added when sending data. All exporters send netflow data to the same port and IP. For each dynamically added source, a new sub directory is created under flowdir with the name of the IP address of the exporter. All . and : in IP addresses are replaced by -. Glow-up for filenames honestly. ✨
• -D — Set daemon mode: fork to background and detach from terminal. sfcapd terminates on signal TERM, INT or HUP. It's independent now, it doesn't need you. 🦋
• -P pidfile — Writes the running process ID into pidfile. Use this option to integrate sfcapd in start/stop files. Very practical, very demure. 🎀
• -u userid — Drop privileges of running process to user userid. sfcapd needs to be started as user root. 👑 (Yes, it starts as root just to give up the power. Growth.)
• -g groupid — Drop privileges of running process to group groupid. sfcapd needs to be started as user root. Same energy, group flavoured. 💜
• -B bufflen — Sets the network socket input buffer to bufflen bytes. For high volume traffic it is recommended to raise this value to typically > 100k, otherwise you risk to lose packets. 😭 The default is OS (and kernel) dependent, so it's giving "it depends."
• -S num — Adds an additional directory sub hierarchy to store the data files. The default is 0, no sub hierarchy, which means all files go directly into flowdir. The flowdir is concatenated with the specified sub hierarchy format to create the final data directory. Here's the whole menu of hierarchies, and yes, I'm listing every single one because we don't skip:
  • 0 default — no hierarchy levels
  • 1 %Y/%m/%d — year/month/day
  • 2 %Y/%m/%d/%H — year/month/day/hour
  • 3 %Y/%W/%u — year/week_of_year/day_of_week
  • 4 %Y/%W/%u/%H — year/week_of_year/day_of_week/hour
  • 5 %Y/%j — year/day-of-year
  • 6 %Y/%j/%H — year/day-of-year/hour
  • 7 %Y-%m-%d — year-month-day
  • 8 %Y-%m-%d/%H — year-month-day/hour
• -t interval — Sets the time interval in seconds to rotate files. The default value is 300s (5min). The smallest available interval is 2s. Rotate rotate rotate. 🔄
• -z=lzo — Compress flow files with LZO1X-1 compression. Fastest compression. Speed queen. ⭐
• -z — Legacy shorthand for -z=lzo. Old but still cute. 🎀
• -z=bz2 — Compress flow files with bz2 compression. Slow but most efficient. It is not recommended to use bz2 in a real time capturing. Like, do not do that to yourself in production. 💀
• -z=lz4[:level] — Compress flow files with LZ4 compression. Fast and efficient. Optional level should be between 1..10. Changing the level results in smaller files but uses up more time to compress. Levels > 5 may need more workers — see -W. 🔥
• -z=zstd[:level] — Compress flow files with ZSTD compression. Fast and efficient. Optional level should be between 1..10. Changing the level results in smaller files but uses up more time to compress. Levels > 5 may need more workers — see -W. Same deal, different algorithm, both slay. 🌸
• -j — Legacy shorthand for -z=bz2. 🎀
• -y — Legacy shorthand for -z=lz4. 🎀
• -l flowdir — Legacy alias for -w flowdir. Same thing, older name. 🤝
• -T — Legacy option accepted and ignored. It's just there. Vibing. Doing nothing. Honestly iconic. 💀
• -E — Deprecated debugging shorthand for -v -3. Deprecated, bestie, so like, use the real flags. 🫶
• -Z — Append the local time-zone offset to generated filenames. Timezone girlies rise. 🌍
• -W num — Set the number of worker threads. The default depends on the number of cores online. The value must not exceed the number of online CPU cores. ⚠️ Periodt.

Worker threads are used to compress data blocks when writing flow files to disc. Using multiple workers can significantly improve throughput, especially when using higher compression levels for lz4 or zstd. More workers = more slay, basically. 🔥

• -e — Sets auto-expire mode. At the end of every rotate interval -t, sfcapd runs an expire cycle to delete files according to max lifetime and max filesize as defined by nfexpire(1). It's giving spring cleaning, on a schedule. 🧹
• -x command — At the end of every -t interval and after the file rotate has completed, sfcapd runs the command command. The string for command may contain the following place holders, which are expanded before running:
  • %f — File name of new data file including any sub hierarchy.
  • %d — Top flowdir. The full path of the new file is: %d/%f
  • %t — Time slot string in ISO format e.g. 201107110845.
  • %u — Time slot string in UNIX time format.
  • %i — Identification string ident string supplied by -I
• -X extensionList — extensionList is a ',' separated list of extensions to be stored by sfcapd. The numbers correspond to the extension list in nfxV3.h. By default extensions are added dynamically to store all data sent by the exporter. If extensionList is given, only those elements matching the extension are processed and stored. Usually this option is not needed, unless for specific requirements. So like, only touch this if you know why you're touching it. 💅
• -o options — Set sfcapd options. This is a ',' separated list of options. Available options:
  • tun — Decode GRE and 6in4 tunneled traffic and use the inner IP addresses and protocol for the flow record. Peeling back the layers, love that for us. 🧅

These options may also be defined in the nfdump.conf config file. Options specified on the command line overwrite the value in the config file. Command line stays winning. 👑

• -m metricpath — Enables the flow metric exporter. Flow metric information is sent to the UNIX socket metricpath at the rate specified by -i. This option may be used to export flow metric information to other systems such as InfluxDB or Prometheus. 🫶 Please note: the flow metric does not include the full record. Only the flow statistics is sent. So it's the highlights reel, not the whole movie. 🎬
• -i metricrate — Sets the interval for the flow metric exporter. This interval may be different from the file rotation interval t and is therefore independent from file rotation. Free agent. 🦋
• -v level — Set verbose level. Accepted 0 to 4. The default level is 1 with moderate information. Use -v 3 to printf netflow records in raw format while collecting. Please note that not all elements are printed. This option is for debugging purpose only, to verify if incoming netflow data is processed correctly. So don't come for it about missing fields, it said what it said. 😭
• -V — Print sfcapd version and exit. Quick little flex then dip. 💅
• -h — Print help text on stdout with all options and exit. The "help me help you" option. 🫶

---

🌈 EXIT STATUS 🌈

sfcapd returns 0 on success and 255 if initialization failed. That's it, that's the whole story. Zero for "we ate", 255 for "something went wrong before we even started." 😭

🌸 SEE ALSO 🌸

okay bestie, here's where to go when you wanna fall down the rabbit hole 💅

• http://sflow.org — the main sFlow HQ, the mothership, the whole vibe 🦋
• https://sflow.org/developers/licensing.php — the licensing page, aka where you go to check what you're actually allowed to do (iykyk, read it fr fr) 🎀
• https://github.com/sflow/sflowtool — the sflowtool repo on GitHub, iconic behavior honestly 👑
• nfdump(1) nfcapd(1) nfpcapd(1) — the netflow-adjacent besties, all manual pages, all here for you 🫶

---

💀 BUGS 💀

"No software without bugs!" — and honestly that's the most real thing anyone's ever said 😭 no cap, everything has bugs, this included.

Please report any bugs back to me. that's it, that's the ask — just tell the author when something breaks 🙈💖

---

okay that's the whole page bestie, you made it to the very end, I'm so proud 🥹✨

before you go: this one's the Debian build, and its date field is just the placeholder $Mdocdate$ (the packaging system swaps in the real date when it renders), tagged SFCAPD(1) in the corner like a little name badge 🎀

now go capture some sFlow data and slay 💅🌈