1# sflowtool
2Print binary sFlow feed to ASCII,  or forward it to other collectors.
3
4This tool receives sFlow data, and generates either a simple-to-parse tagged-ASCII output,
5or binary output in tcpdump(1) format. It can also generate Cisco NetFlow version 5 datagrams
6and send them to a destination UDP host:port,  or forward the original sFlow feed to a number
7of additional collectors.
8
9Please read the licence terms in ./COPYING.
10
11For more details on the sFlow data format, see http://www.sflow.org.
12
13# Build from sources
14
15	./boot.sh
16	./configure
17	make
18	sudo make install
19
20(Start from ./configure if you downloaded a released version.)
21
22# Usage examples
23
24If sFlow is arriving on port 6343, you can pretty-print the data like this:
25
26% ./sflowtool -p 6343
27
28or get a line-by-line output like this:
29
30% ./sflowtool -p 6343 -l
31
32or a custom line-by-line output by listing fields like this:
33
34% ./sflowtool -p 6343 -L localtime,srcIP,dstIP
35
36or a JSON representation like this:
37
38% ./sflowtool -p 6343 -J
39
40In a typical application, this output would be parsed by an awk or perl script, perhaps to
41extract MAC->IP address-mappings or to extract a particular counter for trending. The
42usage might then look more like this:
43
44% ./sflowtool -p 6343 | my_perl_script.pl > output
45
46Alternatively, you can show packet decodes like this:
47
48% ./sflowtool -p 6343 -t | tcpdump -r -
49
50To forward Cisco NetFlow v5 records to UDP port 9991 on host collector.mysite.com, the
51options would be:
52
53% ./sflowtool -p 6343 -c collector.mysite.com -d 9991
54
55If you compiled with -DSPOOFSOURCE, then you have the option of "spoofing" the IP source
56address of the netflow packets to match the IP address(es) of the original sflow agent(s)...
57
58% ./sflowtool -p 6343 -c collector.mysite.com -d 9991 -S
59
60To replicate the input sflow stream to several collectors, use the "-f host/port" option
61like this:
62
63% ./sflowtool -p 6343 -f localhost/7777 -f localhost/7778 -f collector.mysite.com/6343
64
65
66# Example Output
67
68An example of the pretty-printed output is shown below. Note that every field can be
69parsed as two space-separated tokens (tag and value). Newlines separate one field from
70the next. The first field in a datagram is always the "unixSecondsUTC" field, and the
71first field in a flow or counters sample is always the "sampleSequenceNo" field. In
72this example, the datagram held two flow-samples and two counters-samples. Comments
73have been added in <<>> brackets.  These are not found in the output.
74
75     unixSecondsUTC 991362247      <<this is always the first field of a new datagram>>
76     datagramVersion 2
77     agent 10.0.0.254              <<the sFlow agent>>
78     sysUpTime 10391000
79     packetSequenceNo 5219         <<the sequence number for datagrams from this agent>>
80     samplesInPacket 4
81     sampleSequenceNo 9466         <<the sequence number for the first sample - a flow sample from 0:0>>
82     sourceId 0:0
83     sampleType FLOWSAMPLE
84     meanSkipCount 10
85     samplePool 94660
86     dropEvents 0
87     inputPort 14
88     outputPort 16
89     packetDataTag INMPACKETTYPE_HEADER
90     headerProtocol 1
91     sampledPacketSize 1014
92     headerLen 128
93     headerBytes 00-50-04-29-1B-D9-00-D0-B7-23-B7-D8-08-00-45-00-03-E8-37-44-40-00-40-06-EB-C6-0A-00-00-01-0A-00-00-05-0D-F1-17-70-A2-4C-D2-AF-B1-F0-BF-01-80-18-7C-70-82-E0-00-00-01-01-08-0A-23-BC-42-93-01-A9-
94     dstMAC 005004291bd9               <<a rudimentary decode, which assumes an ethernet packet format>>
95     srcMAC 00d0b723b7d8
96     srcIP 10.0.0.1
97     dstIP 10.0.0.5
98     IPProtocol 6
99     TCPSrcPort 3569
100     TCPDstPort 6000
101     TCPFlags 24
102     extendedType ROUTER               <<we have some layer3 forwarding information here too>>
103     nextHop 129.250.28.33
104     srcSubnetMask 24
105     dstSubnetMask 24
106     sampleSequenceNo 346              <<the next sample is a counters sample from 0:92>>
107     sourceId 0:92
108     sampleType COUNTERSSAMPLE
109     statsSamplingInterval 20
110     counterBlockVersion 1
111     ifIndex 92
112     networkType 53
113     ifSpeed 0
114     ifDirection 0
115     ifStatus 0
116     ifInOctets 18176791
117     ifInUcastPkts 92270
118     ifInMulticastPkts 0
119     ifInBroadcastPkts 100
120     ifInDiscards 0
121     ifInErrors 0
122     ifInUnknownProtos 0
123     ifOutOctets 40077590
124     ifOutUcastPkts 191170
125     ifOutMulticastPkts 1684
126     ifOutBroadcastPkts 674
127     ifOutDiscards 0
128     ifOutErrors 0
129     ifPromiscuousMode 0
130     sampleSequenceNo 9467             <<another flow sample from 0:0>>
131     sourceId 0:0
132     sampleType FLOWSAMPLE
133     meanSkipCount 10
134     samplePool 94670
135     dropEvents 0
136     inputPort 16
137     outputPort 14
138     packetDataTag INMPACKETTYPE_HEADER
139     headerProtocol 1
140     sampledPacketSize 66
141     headerLen 66
142     headerBytes 00-D0-B7-23-B7-D8-00-50-04-29-1B-D9-08-00-45-00-00-34-1E-D7-40-00-40-06-07-E8-0A-00-00-05-0A-00-00-01-17-70-0D-F1-B1-F0-BF-01-A2-4C-E3-A3-80-10-7C-70-E2-62-00-00-01-01-08-0A-01-A9-7F-A0-23-BC-
143     dstMAC 00d0b723b7d8
144     srcMAC 005004291bd9
145     srcIP 10.0.0.5
146     dstIP 10.0.0.1
147     IPProtocol 6
148     TCPSrcPort 6000
149     TCPDstPort 3569
150     TCPFlags 16
151     extendedType ROUTER
152     nextHop 129.250.28.33
153     srcSubnetMask 24
154     dstSubnetMask 24
155     sampleSequenceNo 346             <<and another counters sample, this time from 0:93>>
156     sourceId 0:93
157     sampleType COUNTERSSAMPLE
158     statsSamplingInterval 30
159     counterBlockVersion 1
160     ifIndex 93
161     networkType 53
162     ifSpeed 0
163     ifDirection 0
164     ifStatus 0
165     ifInOctets 103959
166     ifInUcastPkts 448
167     ifInMulticastPkts 81
168     ifInBroadcastPkts 93
169     ifInDiscards 0
170     ifInErrors 0
171     ifInUnknownProtos 0
172     ifOutOctets 196980
173     ifOutUcastPkts 460
174     ifOutMulticastPkts 599
175     ifOutBroadcastPkts 153
176     ifOutDiscards 0
177     ifOutErrors 0
178     ifPromiscuousMode 0
179
180
181# Other ExtendedTypes
182
183If your sFlow agent is running BGP, you may also see GATEWAY extendedType sections like this:
184
185   extendedType GATEWAY
186   my_as 65001
187   src_as 0
188   src_peer_as 0
189   dst_as_path_len 3
190   dst_as_path 65000-2828-4908
191
192
193The SWITCH, USER and URL extendedTypes may also appear. The SWITCH extendedType provides
194information on input and output VLANs and priorities. The USER extendedType provides
195information on the user-id that was allocated this IP address via a remote access session
196(e.g. RADIUS or TACAS). The URL field indicates for an HTTP flow what the original requested
197URL was for the flow.  For more information, see the published sFlow documentation at
198http://www.sflow.org.
199
200
201# line-by-line csv output
202
203If you run sflowtool using the "-l" option then only one row of output will be generated
204for each flow or counter sample. It will look something like this:
205
206    [root@server src]# ./sflowtool -l
207    CNTR,10.0.0.254,17,6,100000000,0,2147483648,175283006,136405187,2578019,297011,0,3,0,0,0,0,0,0,0,1
208    FLOW,10.0.0.254,0,0,00902773db08,001083265e00,0x0800,0,0,10.0.0.1,10.0.0.254,17,0x00,64,35690,161,0x00,143,125,80
209
210The counter samples are indicated with the "CNTR" entry in the first column.
211The second column is the agent address.  The remaining columns are the
212fields from the generic counters structure (see SFLIf_counters in sflow.h).
213
214The flow samples are indicated with the "FLOW" entry in the first column.
215The second column is the agent address. The remaining columns are:
216
217    inputPort
218    outputPort
219    src_MAC
220    dst_MAC
221    ethernet_type
222    in_vlan
223    out_vlan
224    src_IP
225    dst_IP
226    IP_protocol
227    ip_tos
228    ip_ttl
229    udp_src_port OR tcp_src_port OR icmp_type
230    udp_dst_port OR tcp_dst_port OR icmp_code
231    tcp_flags
232    packet_size
233    IP_size
234    sampling_rate
235
236To request a custom line output, use the -L <fields> option, like this:
237
238% sflowtool -L localtime,srcIP,dstIP
239
240# grep-friendly output
241
242The "-g" option causes sflowtool to include contextual information on every
243line of output.  The fields are:
244
245     agentIP
246     agentSubId
247     datasource_sequenceNo
248     datasource_class
249     datasource_index
250     sampletype_tag
251     elementtype_tag
252
253For example,  this makes it much easier to extract a particular counter for each agent,
254accumulate the deltas, and stream it to a time-series database.
255
256# JSON output
257
258The -J option prints human-readable JSON with a blank line between datagrams.  To
259print more compact JSON with each datagram on one line, use -j instead.
260
261---
262----------------------------------------
263Neil McKee (neil.mckee@inmon.com)
264InMon Corp. http://www.inmon.com
265
266