1SC_ANALYSIS_DUMP(1) BSD General Commands Manual SC_ANALYSIS_DUMP(1)
2
4 sc_analysis_dump — dump of traceroute data in a format that is easily
5 parsed.
6
8 sc_analysis_dump [-cCdeghHilMopQrstT] [-D debug-count] [-G geo-server]
9 [-S skip-count] [file ...]
10
12 The sc_analysis_dump utility provides a dump of traceroute data in a for‐
13 mat that is easily parsed by scripts. Each line output contains a sum‐
14 mary of a single trace, and includes the interfaces visited and the delay
15 of each response. The output format is identical to that of sk_analy‐
16 sis_dump from CAIDA, except that it uses the scamper file API to read
17 both arts++ files produced by skitter and warts files produced by scam‐
18 per. The sc_analysis_dump utility only outputs traceroute data; for
19 parsing other types of measurement, use sc_warts2json(1) instead. The
20 options are as follows:
21 -c disables printing the cycle number in each line of output.
23 -C disables printing the comments about the output at the top of the
25 output.
26 -d disables printing the destination address in each line of output.
28 -D debug-count
30 for each input file stop reading after the specified number of
31 traces.
32 -e adds the response from the destination to each line of output.
34 Please read the bugs section below.
35 -g use geographical data from netacuity. Not all builds of
37 sc_analysis_dump support this option.
38 -G geo-server
40 specifies the name of the netacuity server to use.
41 -h prints a help message and then exits.
43 -H disables printing the halt fields: why traceroute halted and data
45 for that reason.
46 -i disables printing the RTT to each hop, and how many tries were
48 required.
49 -l disables printing the list id in each line of output.
51 -M prints any MPLS label stack objects embedded in ICMP responses.
53 -o prints each line of output using the old format from sk_analy‐
55 sis_dump 1.0.
56 -p disables print path data in each line of output.
58 -Q prints the IP-TTL from inside the ICMP quotation.
60 -r disables printing the data associated the response from a desti‐
62 nation: the RTT, the TTL of the probe, and the TTL of the
63 response.
64 -s disables printing the source IP address in each line of output.
66 -S skip-count
68 skips the defined number of traces from each input file.
69 -t disables printing the timestamp of when the traceroute began.
71 -T prints the IP-TTL of the response packet.
73
75 There is one trace per line. Fields are separated by a tab character.
76 The output is structured into header fields (2 to 6), reply fields (7 to
77 10) corresponding to the response received from the destination, halt
78 fields (11 and 12), and hop fields (beginning at index 13).
79 1. Key
81 Indicates the type of line and determines the meaning of the
83 remaining fields. This will always be 'T' for an IP trace.
84 2. Source
86 Source IP of skitter/scamper monitor performing the trace.
88 3. Destination
90 Destination IP being traced.
92 4. ListId
94 ID of the destination list containing this destination address.
96 This value will be zero if no list ID was provided. A ListId
97 is a 32 bit unsigned integer.
98 5. CycleId
100 ID of current probing cycle. A cycle is a single run through a
102 given list. A CycleId is a 32 bit unsigned integer. For skit‐
103 ter traces, cycle IDs will be equal to or slightly earlier than
104 the timestamp of the first trace in each cycle. There is no
105 standard interpretation for scamper cycle IDs. This value will
106 be zero if no cycle ID was provided.
107 6. Timestamp
109 Timestamp when trace began to this destination.
111 7. DestReplied
113 Whether a response from the destination was received. The
115 character R is printed if a reply was received. The character
116 N is printed if no reply was received. Since skitter sends a
117 packet with a TTL of 255 when it halts probing, it is still
118 possible for the final destination to send a reply and for the
119 HaltReasonData (see below) to not equal no_halt. Note: scamper
120 does not perform this last-ditch probing at TTL 255 by default.
121 8. DestRTT
123 The RTT (ms) of first response packet from destination. This
125 value is zero if DestReplied is N.
126 9. RequestTTL
128 TTL set in request packet which elicited a response (echo
130 reply) from the destination. This value is zero if DestReplied
131 is N.
132 10. ReplyTTL
134 TTL found in reply packet from destination. This value is zero
136 if DestReplied is N.
137 11. HaltReason
139 A single character corresponding to the reason, if any, why
141 incremental probing stopped. S is printed if the destination
142 was reached or there is no halt data. U is printed if an ICMP
143 unreachable message was received. L is printed if a loop was
144 detected. G is printed if the gaplimit was reached.
145 12. HaltReasonData
147 Extra data about why probing halted. If HaltReason is S, the
149 zero is output. If HaltReason is U, the ICMP code of the
150 unreachable message is printed. If HaltReason is L, the length
151 of the loop is printed. If HaltReason is G, the length of the
152 gap is printed.
153 13. PathComplete
155 Whether all hops to destination were found. C is printed if
157 the trace is complete, all hops are found. I is printed if the
158 trace is incomplete, at least one hop is missing (i.e., did not
159 respond).
160 14. PerHopData
162 Response data for each hop. If multiple IP addresses respond
164 at the same hop, response data for each IP address are sepa‐
165 rated by semicolons:
166 IP,RTT,numTries (for only one responding IP)
168 IP,RTT,numTries;IP,RTT,numTries;... (for multiple responding
169 IPs)
170 where IP is the IP address which sent a TTL expired packet, RTT
172 is the RTT of the TTL expired packet, and numTries is the num‐
173 ber of tries before a response was received from the TTL.
174 This field has the value 'q' if there was no response at a hop.
176 If the -M option is specified, any MPLS label stack objects
178 embedded in the ICMP response will be included in the following
179 format, and the four fields correspond to each of the fields in
180 a MPLS header.
181 M|ttl|label|exp|s
183 If the ICMP response embeds more than one MPLS header, they are
185 given one at a time, each starting with an M.
186 If the -Q option is specified, the TTL value found in a quoted
188 IP packet is included with the following format:
189 Q|ttl
191 If the -T option is specified, the TTL value of the response
193 packet is included with the following format:
194 T|ttl
196
198 The command:
199 sc_analysis_dump file1.warts file2.warts
201 will decode and print the traceroute objects in file1.warts, followed by
203 the traceroute objects in file2.warts.
204 The command:
206 gzcat file1.warts.gz | sc_analysis_dump
208 will decode and print the traceroute objects in the uncompressed file
210 supplied on stdin.
211
213 When the -e option is used, any unresponsive hops between the last
214 responding router and the destination are not printed, which could imply
215 an IP link where none exists. The author recommends using
216 sc_warts2json(1) instead.
217
219 scamper(1), sc_wartsdump(1,) sc_warts2json(1)
220
222 sc_analysis_dump is written by Matthew Luckie <mjl@luckie.org.nz>. It is
223 derived from CAIDA's sk_analysis_dump program and should behave in an
224 identical manner.
225BSD July 8, 2013 BSD