NFCAPD(1)

🦋 nfcapd(1) — General Commands Manual 🦋

okay bestie, buckle up, we're reading a manpage together and honestly? it's a good one 💅

---

✨ NAME ✨

nfcapd — flow collector for netflow version v1, v5/v7 v9 and ipfix 🌸

---

🌈 SYNOPSIS 🌈

nfcapd -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] [-s rate] [-i metricrate] [-m metricpath] [-e]
       [-x command] [-X extensionList] [-W workers] [-Y yaf-file]
       [-v level] [-V] [-h]

---

💖 DESCRIPTION 💖

okay so nfcapd is a flow collector — it reads netflow data straight off the network and stores those records into binary formatted files. and the way it just accepts netflow v1, v5/v7, v9 and ipfix transparently?? iconic. it doesn't even make you pick. 👑

it's mostly compatible with a whole bunch of other flow implementations like cflow, jflow, pflow, and it accepts a wide range of exporters including CISCO Flexible Netflow (FNF), ASA firewalls and NAT devices for event logging. it also has support for a wide range of different vendors and their netflow implementations, such as Juniper, VMware, PaloAlto devices and yaf. highkey a glow-up for your whole rack ✨

Sflow is a different technology. not the same thing, bestie, don't come for me.

nfcapd supports a large number of netflow v9 and ipfix elements according to the IANA assignments. yes, all of them. she studied. 🎀

if you want to collect sflow data, please have a look at sfcapd — which is also part of the nfdump tools 🫶

---

nfcapd also accepts pre-processed records from its companion collector nfpcapd. so they're a duo, a collab, a joint slay 💜

nfcapd saves the flows in an output file, which is automatically rotated at a given interval — typically every 5min. these rotated output files are stored in the flowdir directory and are organized by timestamps 🌸

the output files are named according to the time interval in the following format:

nfcapd.YYYYMMddhhmm

e.g. nfcapd.202207110845 which contains flow data from July 11th 2022 08:45 onwards.

and if the rotation interval is set to a time smaller then 60s, the naming extends to seconds, e.g. nfcapd.20220711084510 ⏱️

---

nfcapd can run in auto-expire mode with -e, which automatically expires old flow files at the end of every rotation interval. nfexpire(1) explains in more details how to setup flow expiration 📚

nfcapd can run any given command -x or shell script at the end of each rotation interval 🔥

nfcapd can send universal flow metric information about the collected flow data (flow summary) to a UNIX socket. programs such as nfinflux or nfexporter may be used to send the metric information to an InfluxDB or to a Prometheus monitoring system. metrics bestie, we love to see it 💅

🎀 The options are as follows 🎀

• -w flowdir — set the flowdir directory to store the output files. if a sub hierarchy is specified with -S, the final directory is concatenated to flowdir/subdir 🌸
• -C config — reads additional configuration parameters from config file. nfcapd 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. and if -C none is specified, then no config file is read, even if found in the search path. respect the hierarchy bestie, it's giving chain of command 👑
• -p portnum — set the port number to listen. default port is 9995 🎀
• -d interface — reads flow data from an erspan encoded datalink. all traffic sent to this interface is interpreted as flow data stream.
• -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.
• -4 — forces nfcapd to listen on IPv4 addresses only. can be used together with -b if a hostname has IPv4 and IPv6 addresses.
• -6 — forces nfcapd to listen on IPv6 addresses only. can be used together with -b if a hostname has IPv4 and IPv6 addresses.
• -J mcastgroup — join the specified IPv4 or IPv6 multicast group for listening. group chat but make it packets 💬
• -Y yaffile — offline mode: read flows from yaf file, created by the yaf flow-collector. disables reading flows from network.
• -f pcapfile — offline mode: read flows from pcap file, instead of the network. need --enable-readpcap for configure ⚠️
• -R host[/port] — enables the packet repeater. all incoming packets are sent additionally to another host and port. 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 accepted, the host/port separator is /. up to 8 additional repeaters may be defined. use this method to daisy chain collectors 🌼

• -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 nfcapd to be started with root privileges.

heads up bestie: source spoofing may be blocked by firewalls or routers in your network. don't come crying to me 😭

• -I ident — sets ident as 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: the entire argument must be enclosed in single quotes to prevent the shell from interpreting the semicolon as a command separator. shell said "not today" and we said "no fr, quoted" 🫶

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 💀

if you have multiple sources per collector, specify multiple -n options. all exporters send their flows to the same port specified with -p. do not mix single-source configuration using -I with multiple -n options. pick a lane bestie 🎀

• -M flowdir — set the flowdir directory for dynamic 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 be '-' 🦋
• -D — set daemon mode: fork to background and detach from terminal. nfcapd terminates on signal TERM, INT or HUP. main character energy, she leaves the group chat but you can still reach her 👑
• -P pidfile — writes the running process ID into pidfile. use this option to integrate nfcapd in start/stop files.
• -u userid — drop privileges of running process to user userid. nfcapd needs to be started as user root ⚠️
• -g groupid — drop privileges of running process to group groupid. nfcapd needs to be started as user root ⚠️
• -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 😭
• -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. the following hierarchies are defined:

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 ⏱️
• -s rate — set the default sampling rate for flow records from exporters that do not announce a sampling rate. the default is 1 (unsampled). a positive rate from 1 through 10000000 is used only when the exporter does not provide sampling information. a negative value in the same range forces its absolute value for all records and overrides exporter-provided sampling information. sampling multiplies the packet and byte counters in a record; it may therefore differ from counters reported by SNMP or other sources. do the math bestie, don't blame the collector 🧮
• -z=lzo — compress flow files with LZO1X-1 compression. fastest compression ⚡
• -z — legacy shorthand for -z=lzo.
• -z=bz2 — compress flow files with bz2 compression. slow but most efficient. it is not recommended to use bz2 in a real time capturing. she's a slow queen but she delivers 💅
• -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 🎀
• -j — legacy shorthand for -z=bz2.
• -y — legacy shorthand for -z=lz4.
• -l flowdir — legacy alias for -w flowdir.
• -T — legacy option accepted and ignored. she's here, she's not doing anything, she's still invited 🌸
• -E — deprecated debugging shorthand for -v -3 ⚠️
• -Z — append the local time-zone offset to generated filenames 🌍
• -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. 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. teamwork makes the dream work 🫶
• -e — sets auto-expire mode. at the end of every rotate interval -t, nfcapd runs an expire cycle to delete files according to max lifetime and max filesize as defined by nfexpire(1) 🔥
• -x command — okay so every time a -t interval wraps up and the file rotate has finished doing its thing, nfcapd runs command. And the string you pass can have lil placeholders in it that get expanded before it runs, bestie:
  • %f — the file name of the new data file, including any sub hierarchy 💖
  • %d — the top flowdir. Full path of the new file is: %d/%f
  • %t — the time slot string in ISO format, e.g. 201107110845
  • %u — the time slot string in UNIX time format
  • %i — the identification string, i.e. the ident string you supplied with -I
• -X extensionList — extensionList is a ',' separated list of extensions that nfcapd should store. The numbers correspond to the extension list in nfxV3.h. By default extensions are added dynamically so it stores all the data the exporter sends. But if you give extensionList, only those elements matching the extension get processed and stored. Usually you don't need this option at all, unless you have specific requirements ✨
• -m metricpath — turns on the flow metric exporter 🎀 Flow metric info gets sent to the UNIX socket metricpath at the rate you set with -i. This option may be used to export flow metric info to other systems such as InfluxDB or Prometheus. But real talk: the flow metric does not include the full record, only the flow statistics get sent. 💅
• -i metricrate — sets the interval for the flow metric exporter. This interval can be different from the file rotation interval t, so it's independent from file rotation. Two separate clocks, no drama 🦋
• -v level — sets the verbose level. Accepted values are 0 to 4. Default level is 1 with moderate information. Use -v 3 to printf netflow records in raw format while collecting. Heads up though — not all elements get printed. This option is for debugging purposes only, to verify if incoming netflow data is processed correctly 👑
• -V — prints the nfcapd version and exits. Short and sweet, we love a quick exit ⭐
• -h — prints the help text on stdout with all the options and exits 🌸

---

✨ EXIT STATUS ✨

nfcapd returns 0 on success and 255 if initialization failed 😭

So like, if you see 255, something went wrong before it even got going. Vibe check failed. 💀

---

🦋 SEE ALSO 🦋

• https://www.iana.org/assignments/ipfix/ipfix.xhtml
• https://www.cisco.com/en/US/technologies/tk648/tk362/technologies_white_paper09186a00800a3db9.html
• nf:dump(1) — wait, no, keeping it exact: nfdump(1), nfpcapd(1), sfcapd(1)

---

🐛 BUGS 🐛

No software without bugs! Please report any bugs back to me 🙈🫶

---

And that's the whole page, bestie — it's giving source Debian, version $Mdocdate$, and it's dated NFCAPD(1). Go collect those flows, ily, bye 💜🌈✨