trunk/src/fprobe-ulog.8

   1 .TH fprobe-ulog 8 "2005-01-29" "fprobe-ulog 1.1"
   2
   3 .SH NAME
   4 fprobe-ulog \- a NetFlow probe
   5
   6 .SH SYNOPSIS
   7 .BI fprobe-ulog
   8 [\fIoptions\fR] \fIremote:port[/[local][/type]] ...\fR
   9
  10 .SH DESCRIPTION
  11 .B fprobe-ulog
  12 \- libipulog-based tool that collect network traffic data and emit it as
  13 NetFlow flows towards the specified collector.
  14
  15 .SH OPTIONS
  16 .TP
  17 .B -h
  18 Display short help
  19 .TP
  20 .B -U \fI<mask>\fR
  21 ULOG group bitwise mask. [default=1]
  22 .TP
  23 .B -s \fI<seconds>\fR
  24 How often scan for expired flows. [default=5]
  25 .TP
  26 .B -g \fI<seconds>\fR
  27 Fragmented flow lifetime. [default=30]
  28 .TP
  29 .B -d \fI<seconds>\fR
  30 Idle flow lifetime (inactive timer). [default=60]
  31 .TP
  32 .B -e \fI<seconds>\fR
  33 Active flow lifetime (active timer). [default=300]
  34 .TP
  35 .B -n \fI<version>\fR
  36 NetFlow version for use (1, 5, 7). [default=5]
  37 .TP
  38 .B -a \fI<address>\fR
  39 Use \fIaddress\fR as source for NetFlow flow.
  40 .TP
  41 .B -X \fI<rule[,...]>\fR
  42 Comma separated list of interface name to SNMP-index conversion rules.
  43 Each \fIrule\fR consists of \fIinterface base name\fR and \fISNMP-index
  44 base\fR separated by colon (e.g. ppp:200). Final SNMP-index is sum of
  45 corresponding \fISNMP-index base\fR and \fIinterface number\fR.
  46 .br
  47 In the above example SNMP-index of interface ppp11 is 211.
  48 .br
  49
  50 If interface name did not fit to any of conversion rules then SNMP-index
  51 will be taken from kernel.
  52 .TP
  53 .B -M
  54 Use the netfilter mark as Type Of Service value.
  55 .TP
  56 .B -b \fI<flows>\fR
  57 Memory bulk size. [default=200 or 10000]
  58 .br
  59 Note that maximum and default values depends on compiling options
  60 (\fI--with-membulk\fR parameter).
  61 .TP
  62 .B -m \fI<kilobytes>\fR
  63 Memory limit for flows cache (0=no limit). [default=0]
  64 .TP
  65 .B -q \fI<flows>\fR
  66 Pending queue length. [default=100]
  67 .br
  68 Each captured packet at first puts into special buffer called `pending
  69 queue'. Purpose of this buffer is to separate most time-critical packet
  70 capture thread from other.
  71 .TP
  72 .B -B \fI<kilobytes>\fR
  73 Kernel capture buffer size (0=don't change). [default=0]
  74 .br
  75 Increase kernel capture buffer size is most adequate way to prevent
  76 packets loss.
  77 .br
  78 Note that maximum allowed size of the buffer in Linux limited and
  79 generally relatively small, so it should need to change the maximum:
  80 sysctl -w net/core/rmem_max=4194304
  81 .TP
  82 .B -r \fI<priority>\fR
  83 Real-time priority (0=disabled). [default=0]
  84 .br
  85 If parameter greater then zero \fBfprobe-ulog\fR will use real-time scheduling
  86 policy to prevent packets loss. Note that possible values for this
  87 option depends on operating system.
  88 .TP
  89 .B -t \fI<B:N>\fR
  90 Emitting rate limit (0:0=no limit). [default=0:0]
  91 .br
  92 Produce \fIN\fR nanosecond delay after each \fIB\fR bytes sent. This
  93 option may be useful with slow interfaces and slow collectors. Note that
  94 the suspension time may be longer than requested because the argument
  95 value is rounded up to an integer multiple of the sleep resolution (it
  96 depends on operating system and hardware) or because of the scheduling
  97 of other activity by the system.
  98 .br
  99 See BUGS section.
 100 .TP
 101 .B -c \fI<directory>\fR
 102 Directory to chroot to.
 103 .TP
 104 .B -u \fI<user>\fR
 105 User to run as.
 106 .TP
 107 .B -v \fI<level>\fR
 108 Maximum displayed log level. (0=EMERG, 1=ALERT, 2=CRIT, 3=ERR, 4=WARNING,
 109 5=NOTICE, 6=INFO, 7=DEBUG) [default=6]
 110 .TP
 111 .B -l \fI<[dst][:id]>\fR
 112 Log destination (0=none, 1=syslog, 2=stdout, 3=both) and log/pidfile
 113 identifier. [default=1]
 114 .br
 115 This option allows to select opportune log destination and process
 116 identifier. The identifier helps to distinguish pidfile and logs of one
 117 \fBfprobe-ulog\fR process from other.
 118 .br
 119 Note that if log destination contains `\fIstdout\fR' (equal 2 or 3)
 120 \fBfprobe-ulog\fR will run in foreground.
 121 .TP
 122 .B remote:port/local/type
 123 Parameters \fIremote\fR and \fIport\fR are respectively define address
 124 and port of the NetFlow collector.
 125 .br
 126 The \fIlocal\fR parameter allows binding certain local IP address with
 127 specified collector. If the parameter is omitted the value (if any) of
 128 \fI-a\fR option will be used.
 129 .br
 130 The \fItype\fR parameter determines emitting behavior. It may be `m' for
 131 mirroring (by default) and `r' for collectors round-robin rotating.
 132 .br
 133 You may specify multiple collectors.
 134
 135 .SH EXAMPLES
 136 \fBfprobe-ulog -Xeth:100,ppp:200 localhost:2055\fR
 137
 138 Reasonable configuration to run under heavy load:
 139 .br
 140 \fBfprobe-ulog -B4096 -r2 -q10000 -t10000:10000000 localhost:2055\fR
 141
 142 Send packets to collector at 10.1.1.1:2055 and distribute them between
 143 collectors at 10.1.1.2:2055 and at 10.1.1.3:2055 on a round-robin basis:
 144 .br
 145 \fBfprobe-ulog 10.1.1.1:2055 10.1.1.2:2055//r 10.1.1.3:2055//r\fR
 146
 147 .SH BUGS
 148 .B Slow interfaces and slow collectors.
 149 .br
 150 There are may be problems with slow interfaces and slow collectors. It
 151 effects as emitted packets loss. On the one hand silent non-blocking
 152 sendto() implementation can't guarantee that packet was really sent to
 153 collector - it may be dropped by kernel due to outgoing buffer shortage
 154 (slow interface's problem) and on the other hand packet may be dropped
 155 on collector's machine due the similar reason - incoming buffer shortage
 156 (slow collector's problem).
 157 .br
 158 Use \fI-t\fR option as workaround for this issue.
 159
 160 .B Locally originated packets and their timestamps.
 161 .br
 162 Locally originated packets does not contains valid timestamps. Therefore
 163 \fBfprobe-ulog\fR fill timestamp by itself on act of receive such
 164 packet. Unfortunately, between capturing packet by netfilter code and
 165 receiving it by \fBfprobe-ulog\fR may occur certain lags, thus
 166 timestamps of locally originated packets generally inexact.
 167 .br
 168 It is possible to fix this problem entirely by trivial kernel patch (see
 169 contrib/ipt_ULOG.patch).
 170
 171 .SH SEE ALSO
 172 .BR iptables(8)
 173 .br
 174 .BR http://freshmeat.net/projects/ulogd
 175 .br
 176 .BR http://www.cisco.com/go/netflow