1nfcapd(1)                                                            nfcapd(1)
2
3
4

NAME

6       nfcapd - netflow capture daemon
7

SYNOPSIS

9       nfcapd [options]
10

DESCRIPTION

12       nfcapd is the netflow capture daemon of the nfdump tools. It reads net‐
13       flow data from the network and stores it into files. The output file is
14       automatically  rotated  and renamed every n minutes - typically 5 min -
15       according  the  timestamp  YYYYMMddhhmm  of  the  interval  e.g.    nf‐
16       capd.201907110845  contains  the data from July 11th 2019 08:45 onward.
17       If the time interval is smaller then 60s, the naming extends to seconds
18       e.g. nfcapd.20190711084510.
19
20
21       Netflow  version  v1,  v5,  v7  and v9 and IPFIX are transparently sup‐
22       ported.
23
24       Extensions: nfcapd supports a large number of v9 tags. In order to  op‐
25       timise disk space and performance, v9 tags are grouped into a number of
26       extensions which may or may not be stored into the data file. Therefore
27       the  v9 templates configured on the exporter may be tuned according the
28       collector. Only those tags common to both  are  stored  into  the  data
29       files.
30
31       Sampling:  By  default, the sampling rate is set to 1 (unsampled) or to
32       any given value specified by the -s cmd line option. If sampling infor‐
33       mation is found in the netflow stream, it overwrites the default value.
34       Sampling is automatically recognised when announced in v9  option  tem‐
35       plates (tags #34, #35 or #48, #49, #50 ) or in the unofficial v5 header
36       hack.  Note: Not all platforms (or IOS/JunOS versions) support  export‐
37       ing  sampling  information in netflow data, even if sampling is config‐
38       ured. The number of bytes/packets in each netflow record  is  automati‐
39       cally  multiplied  by  the sampling rate.  The total number of flows is
40       not changed as this is not accurate enough. (Small flows  versus  large
41       flows)  If the default sampling rate given by -s is negative, this will
42       hard overwrite any device specific announced sampling rates.
43
44       NSEL/ASA Support: nfcapd can be  compiled  with  NSEL/ASA  support  in‐
45       cluded. See notes on NSEL/ASA
46
47       NEL  (NAT Event logging): nfcapd can be compiled with CISCO NEL support
48       included.  See notes on NEL.
49

OPTIONS

51       -p portnum
52          Specifies the port number to listen. Default port is 9995
53
54       -b bindhost
55          Specifies the hostname/IPv4/IPv6 address to bind for listening. This
56          can  be  an IP address or a hostname, resolving to an IP address at‐
57          tached to an interface.  Defaults to any available  IPv4  interface,
58          if not specified.
59
60       -4 Forces nfcapd to listen on IPv4 addresses only. Can be used together
61          with -b if a hostname has an IPv4 and IPv6 address record.
62
63       -6 Forces nfcapd to listen on IPv6 addresses only. Can be used together
64          with -b if a hostname has an IPv4 and IPv6 address record. Depending
65          on the socket implementation -6 also accepts IPv4 data.
66
67       -J MulticastGroup
68          Join the specified IPv4 or IPv6 multicast group for listening.
69
70       -R host[/port}
71          Enable packet repeater. Send all incoming packets  to  another  host
72          and port.  host is either a valid IPv4/IPv6 address, or a valid sym‐
73          bolic hostname, which resolves to a IPv6 or IPv4 address.  port  may
74          be  omitted  and  defaults  to port 9995. Note: Due to IPv4/IPv6 ac‐
75          cepted addresses the port separator is '/'. Up to 8 repeaters my  be
76          defined.
77
78       -I IdentString ( capital letter i )
79          Specifies  an ident string, which describes the source e.g. the name
80          of the router. This string is put into the stat record  to  identify
81          the source. Default is 'none'. This is for compatibility with nfdump
82          1.5.x and used to specify a single netflow source. See -n
83
84       -l base_directory ( letter ell )
85          Specifies the base directory to store the output files.   If  a  sub
86          hierarchy  is  specified with -S the final directory is concatenated
87          to base_directory/sub_hierarchy. This is for compatibility with  nf‐
88          dump 1.5.x and used to specify a single netflow source. See -n
89
90       -n <Ident,IP,base_directory>
91          Configures  a netflow source named Ident and identified by source IP
92          address IP.  The base directory for the flow  files  is  base_direc‐
93          tory. If a sub hierarchy is specified with -S the final directory is
94          concatenated  to  base_directory/sub_hierarchy.   Multiple   netflow
95          sources  can  be specified. All data is sent to the same port speci‐
96          fied by -p.  Note: You must not mix -n option with -I  and  -l.  Use
97          either syntax.
98
99       -N <file>
100          Specifies the file to read to add multiple netflow sources. The file
101          is expected to contain one netflow source per line based on the same
102          syntax than the -n option. Comments are not interpreted.  Ident col‐
103          lision are not handled if -N is specified multiple times.
104
105       -M <dynbase_directory>
106          Specifies the base directory to store the output files. In  contrast
107          to  -l -M allows to add dynamically new flow sources (exporters), as
108          they appear. All exporters send netflow data to the  same  port  and
109          IP.   For  each dynamically added source, a new directory is created
110          with the name of the IPv4/IPv6 address of the exporter. All '.'  and
111          ':"  in  IP  addresses are replaced be '-' e.g.  10.11.12.13 is con‐
112          verted to the directory name 10-11-12-13.  Note: Please make sure to
113          restrict at host level the potential range of IP addresses which are
114          allowed to connect to nfcapd. Otherwise you risk a potential DoS at‐
115          tack on nfcapd, as nfcapd has no built in restrictions.
116
117       -f <pcap_file>
118          Read  netflow  packets from a give pcap_file instead of the network.
119          This requires nfcapd to be compiled with the pcap option and is  in‐
120          tended for debugging only.
121
122       -s <rate>
123          Apply  default sampling rate rate to all netflow records, unless the
124          sampling rate is announced by the exporting device. In that case the
125          announced sampling rate is applied. If <rate> is negative, this will
126          hard overwrite any device specific announced sampling rates.
127
128       -S <num>
129          Allows to specify an additional directory sub hierarchy to store the
130          data  files.  The  default  is  0, no sub hierarchy, which means the
131          files go directly in the base directory  (-l).  The  base  directory
132          (-l) is concatenated with the specified sub hierarchy format to form
133          the final data directory.  The following hierarchies are defined:
134            0 default     no hierarchy levels
135            1 %Y/%m/%d    year/month/day
136            2 %Y/%m/%d/%H year/month/day/hour
137            3 %Y/%W/%u    year/week_of_year/day_of_week
138            4 %Y/%W/%u/%H year/week_of_year/day_of_week/hour
139            5 %Y/%j       year/day-of-year
140            6 %Y/%j/%H    year/day-of-year/hour
141            7 %Y-%m-%d    year-month-day
142            8 %Y-%m-%d/%H year-month-day/hour
143
144       -T <extension list>
145          The argument is considered legacy. By default all matching extension
146          sent  by  the  exporter are stored. You still may overwrite this, if
147          you want to skip certain extansions.  Regardless  of  the  extension
148          list,  the following netflow data is stored per record: first, last,
149          fwd status, tcp flags, proto, (src)tos,  src  port,  dst  port,  src
150          ipaddr,  dst  ipaddr,  in(packets),  in(bytes).  In  addition nfcapd
151          recognises the extensions as described below.  Some  are  valid  for
152          v5/v7/v9, but most of them make only sense for v9. Any specified ex‐
153          tensions which do not exist in the input  netflow  records  are  ig‐
154          nored.
155
156          Extensions:
157           v5/v7/v9/IPFIX extensions:
158            1 input/output interface SNMP numbers.
159            2 src/dst AS numbers.
160            3 src/dst mask, (dst)TOS, direction.
161            4 line Next hop IP addr line
162            5 line BGP next hop IP addr line
163            6 src/dst vlan id labels
164            7 counter output packets
165            8 counter output bytes
166            9 counter aggregated flows
167           10 in_src/out_dst MAC address
168           11 in_dst/out_src MAC address
169           12 MPLS labels 1-10
170           13 Exporting router IPv4/IPv6 address
171           14 Exporting router ID
172           15 BGP adjacent prev/next AS
173           16 time stamp flow received by the collector
174           NSEL/ASA/NAT extensions
175           26 NSEL     ASA event, xtended event, ICMP type/code
176           27 NSEL/NAT xlate ports
177           28 NSEL/NAT xlate IPv4/IPv6 addr
178           29 NSEL     ASA ACL ingress/egress acl ID
179           30 NSEL     ASA username
180           NEL/NAT extensions
181           31 NAT event, ingress egress vrfid
182           32 NAT Block port allocation - block start, end step and size
183           latency extension
184           64 nfpcapd/nprobe client/server/application latency"},
185
186           IMPORTANT:  By default all extension are selected Extensions can be
187           added/deleted by specifying a ',' separated list of extension  ids.
188           Each id may be prepended by an optional sign +/- to add or remove a
189           given id from the extension  list.   Shortcuts:  The  string  'all'
190           means all extensions. The strings
191            'nsel' and 'nel' enable all NSEL or NEL extensions respectively.
192
193           Examples:
194           -T all       Enables all possible extensions.
195           -T +3,+4     Adds extensions 3 and 4 to the defaults 1 and 2.
196           -T all,-8,-9 Set all extensions but 8 and 9
197           -T -1,4      Removes default extension 1 and adds extension 4
198           -T nsel      Enables all required ASA?NSEL extensions
199           -T nel       Enables all required nell extensions
200           Note:  Only  those tags in common with the exporting device and en‐
201           abled extensions at the collector side are  stored  into  the  data
202           files.  A  detailed list which v9 tags are mapped into which exten‐
203           sions is given in the section NOTES
204
205       -t interval
206          Specifies the time interval in seconds to rotate files. The  default
207          value is 300s ( 5min ). The smallest interval is 2s.
208
209       -w Align file rotation with next n minute ( specified by -t ) interval.
210          Example: If interval is 5 min, sync at 0,5,10... wall clock  minutes
211          Default: no alignment.
212
213       -x cmd
214          Run  command  cmd  at the end of every interval, when a new file be‐
215          comes available. The following command expansion is available:
216           %f   Replaced by the file name e.g nfcapd.200907110845 inluding any
217                sub hierarchy. ( 2009/07/11/nfcapd.200907110845 )
218           %d   Replaced by the directory where the file is located.
219           %t   Replaced by the time ISO format e.g. 200907110845.
220           %u   Replaced by the UNIX time format.
221           %i   Replaced ident string given by -I
222
223       -X Collect and embed extended statistics. Currently a port and bpp his‐
224          togram is embedded. Mostly experimental for now
225
226       -e Auto  expire files at every cycle. max lifetime and max filesize are
227          defined using nfexpire(1)
228
229       -P pidfile
230          Specify name of pidfile. Default is no pidfile.
231
232       -D Daemon mode: fork to background and detach  from  terminal.   Nfcapd
233          terminates on signal TERM, INT and HUP.
234
235       -u userid
236          Change  to the user userid as soon as possible. Only root is allowed
237          to use this option.
238
239       -g groupid
240          Change to the group groupid as soon as possible. Only  root  is  al‐
241          lowed use this option.
242
243       -B bufflen
244          Specifies  the  socket input buffer length in bytes. For high volume
245          traffic ( near GB traffic ) it is recommended to set this  value  as
246          high  as  possible  ( typically > 100k ), otherwise you risk to lose
247          packets. The default is OS ( and kernel )  dependent.
248
249       -E Print netflow records in nfdump raw format to stdout. This option is
250          for debugging purpose only, to see how incoming netflow data is pro‐
251          cessed and stored.
252
253       -j Compress flows. Use bz2 compression in output file. Note: not recom‐
254          mended while collecting
255
256       -y Compress flows. Use LZ4 compression in output file.
257
258       -z Compress flows. Use fast LZO1X-1 compression in output file.
259
260       -V Print nfcapd version and exit.
261
262       -h Print help text to stdout with all options and exit.
263

RETURN VALUE

265       Returns 0 on success, or 255 if initialization failed.
266

LOGGING

268       nfcapd logs to syslog with SYSLOG_FACILITY LOG_DAEMON For normal opera‐
269       tion level 'warning' should be fine.  More information is  reported  at
270       level 'info' and 'debug'.
271
272       A  small statistic about the collected flows, as well as errors are re‐
273       ported at the end of every interval to syslog with level 'info'.
274

EXAMPLES

276       All flows are sent to port 9995 from all exporters and  stored  into  a
277       single file. All known v9 tags are taken.
278              nfcapd -z -w -D -T all -l /netflow/spool/allflows -I any -S 2 -P
279              /var/run/nfcapd.allflows.pid
280
281       All flows from 2 different exporters are sent to port 8877  and  stored
282       in  separate directory trees. All known v9 tags are taken. Input buffer
283       size is set to 128000 bytes
284              nfcapd -z -w -D -T all  -p  8877  -n  upstream,192.168.1.1,/net‐
285              flow/spool/upstream -n peer,192.168.2.1,/netflow/spool/peer -S 2
286              -B 128000
287
288       Only accept from from a single exporter and only extension  3,4  and  5
289       are  accepted. Run a given command when files are rotated and automati‐
290       cally expire flows:
291              nfcapd -w -D -T 3,4,5 -n upstream,192.168.1.1,/netflow/spool/up‐
292              stream -p 23456 -B 128000 -s 100 -x '/path/command -r %d/%f'  -P
293              /var/run/nfcapd/nfcapd.pid -e
294

NOTES

296       Multiple netflow sources:
297
298       Netflow data may be sent from different exporters to  a  single  nfcapd
299       process.   Use  the -n option to separate each netflow source to a dif‐
300       ferent data directory.  For compatibility with nfdump 1.5.x, old  style
301       -l/-I options are still valid.  In that case all flows from all sources
302       are stored in a single file. For high volume  netflow  streams,  it  is
303       still recommended to have a single nfcapd process per netflow source.
304
305       Nfdump supports a large number of v9 and ipfix elements. For a detailed
306       list chek the netflow_v9 and ipfix header files.  32  and  64  bit  are
307       supported for all counters. 32it AS numbers are supported.
308
309       The format of the data files is netflow version independent.
310
311       Socket  buffer:  Setting  the  socket  buffer size is system dependent.
312       When starting up, nfcapd returns the number of bytes the buffer was ac‐
313       tually set. This is done by reading back the buffer size and may differ
314       from what you requested.
315

SEE ALSO

317       nfdump(1), nfprofile(1), nfreplay(1)
318

BUGS

320       No software without bugs! Please report any bugs back to me.
321
322
323
324                                  2009-09-09                         nfcapd(1)
Impressum