1SCAMPER(1) BSD General Commands Manual SCAMPER(1)
2
4 scamper — parallel Internet measurement utility
5
7 scamper [-?Dv] [-c command] [-p pps] [-w window] [-M monitorname]
8 [-l listname] [-L listid] [-C cycleid] [-o outfile] [-F firewall]
9 [-d debugfile] [-e pidfile] [-O options]
10 [-i IPs | -I cmds | -f file | -P [ip:]port | -U unix-dom]
11
13 The scamper utility provides the ability to execute Internet measurement
14 techniques to IPv4 and IPv6 addresses, in parallel, to fill a specified
15 packets-per-second rate. Currently, scamper supports the well-known
16 traceroute and ping techniques, as well as MDA traceroute, alias resolu‐
17 tion, some parts of tbit, sting, and neighbour discovery.
18 scamper has four modes of operation. First, scamper can be supplied a
20 list of addresses on the command line with the -i option. scamper will
21 then execute a command with each of the supplied addresses, in parallel,
22 and output the results as each task completes. Second, scamper can be
23 supplied a list of addresses in a listfile, one address per line, using
24 the -f option. Third, scamper can be supplied a list of complete com‐
25 mands on the command line with the -I option. Finally, scamper can be
26 instructed to listen on an IP address and port specified with the -P
27 option, or on a unix domain socket specified with the -U option, where it
28 can take commands dynamically.
29 The options are as follows:
31 -? prints a list of command line options and a synopsis of each.
33 -v causes scamper to output version information and exit.
35 -D With this option set, scamper will detach and become a daemon.
37 Use with the -P or -U options.
38 -c command
40 specifies the command for scamper to use by default. The current
41 choices for this option are:
42 - dealias
43 - neighbourdisc
44 - ping
45 - trace
46 - tracelb
47 - sniff
48 - sting
49 - tbit
50 scamper uses trace by default. The available commands and their
51 options are documented below.
52 -p pps specifies the target packets-per-second rate for scamper to
54 reach. By default, this value is 20.
55 -w window
57 specifies the maximum number of tasks that may be probed in par‐
58 allel. A value of zero places no upper limit. By default, zero
59 is used.
60 -M monitorname
62 specifies the canonical name of machine where scamper is run.
63 This value is used when recording the output in a warts output
64 file.
65 -l listname
67 specifies the name of the list when run from the command line.
68 This value is used when recording the output in a warts output
69 file.
70 -L listid
72 specifies the numerical id of the list when run from the command
73 line. This value is used when recording the output in a warts
74 output file.
75 -C cycleid
77 specifies the numerical cycle id to begin with when run from the
78 command line. This value is used when recording the output in a
79 warts output file.
80 -o outfile
82 specifies the default output file to write measurement results
83 to. By default, stdout is used.
84 -F firewall
86 specifies that scamper may use the firewall in measurements that
87 require it (tbit and sting). scamper supports two firewall
88 types: IPFW, and PF. To use the IPFW firewall, pass
89 ipfw:<start>-<end>, where <start> is the first rule scamper can
90 use, and <end> is the last. To use the PF firewall, pass
91 pf:<anchor>:<num>, where <anchor> is the anchor for scamper to
92 use, and <num> specifies the number of rules scamper is allowed
93 to use.
94 -d debugfile
96 specifies a filename to write debugging messages to. By default,
97 no debugfile is used, though debugging output is sent to stderr
98 if scamper is built for debugging.
99 -e pidfile
101 specifies a file to write scamper's process ID to. If scamper is
102 built with privilege separation, the ID of the unprivileged
103 process is written.
104 -O options
106 allows scamper's behaviour to be further tailored. The current
107 choices for this option are:
108 - text: output results in plain text. Suitable for interac‐
109 tive use.
110 - warts: output results in warts format. Suitable for archiv‐
111 ing measurement results and for use by researchers as it
112 records details that cannot be easily represented with the
113 text option.
114 - json: output results in json format. Suitable for process‐
115 ing measurement results with a scripting language. A better
116 approach is to output results in warts format, and to use
117 sc_warts2json(1).
118 - planetlab: tell scamper it is running on a planetlab system.
119 Necessary to use planetlab's safe raw sockets.
120 - rawtcp: tell scamper to use IPPROTO_RAW socket to send IPv4
121 TCP probes, rather than a datalink socket.
122 - select: tell scamper to use select(2) rather than poll(2)
123 - kqueue: tell scamper to use kqueue(2) rather than poll(2) on
124 systems where kqueue(2) is available.
125 - epoll: tell scamper to use epoll(7) rather than poll(2) on
126 systems where epoll(7) is available.
127 - tsps: the input file consists of a sequence of IP addresses
128 for pre-specified IP timestamps.
129 - cmdfile: the input file consists of complete commands.
130 - noinitndc: do not initialise the neighbour discovery cache.
131 - outcopy: write a copy of all data written by scamper with
132 the default output method.
133 - debugfileappend: append to the debugfile specified with the
134 -d option. The default is to truncate the debugfile.
135 - notls: do not use TLS anywhere in scamper, including tbit.
136 -i IP 1..N
138 specifies the addresses to probe, on the command line, using the
139 command specified with the -c option.
140 -f listfile
142 specifies the input file to read for target addresses, one per
143 line, and uses the command specified with the -c option on each.
144 -I cmds.
146 specifies complete commands, including target addresses, for
147 scamper to execute.
148 -P [ip:]port
150 specifies that scamper provide a control socket listening on the
151 specified IP address and port on the local host. If an IP
152 address is not specified, scamper will bind to the port specified
153 on the loopback address.
154 -U unix domain socket
156 specifies that scamper provide a control socket listening on the
157 specified socket in the unix domain.
158
160 The trace command is used for conducting traceroute. The following vari‐
161 ations of the traceroute(8) options are available:
162 trace [-MQT] [-c confidence] [-d dport] [-f firsthop] [-g gaplimit]
164 [-G gapaction] [-l loops] [-m maxttl] [-o offset] [-O option]
165 [-p payload] [-P method] [-q attempts] [-s sport] [-S srcaddr] [-t tos]
166 [-U userid] [-w wait] [-W wait-probe] [-z gss-entry] [-Z lss-name]
167 -c confidence
169 specifies that a hop should be probed to a specified confidence
170 level (95% or 99%) to be sure the trace has seen all interfaces
171 that will reply for that hop.
172 -d dport
174 specifies the base destination port value to use for UDP-based
175 and TCP-based traceroute methods. For ICMP-paris, this option
176 sets the ICMP checksum value.
177 -f firsthop
179 specifies the TTL or HLIM value to begin probing with. By
180 default, a first hop of one is used.
181 -g gaplimit
183 specifies the number of unresponsive hops permitted until a check
184 is made to see if the destination will respond. By default, a
185 gap limit of 5 hops is used. Setting the gap limit to 0 disables
186 the gap limit, but doing this is not recommended.
187 -G gapaction
189 specifies what should happen if the gaplimit condition is met. A
190 value of 1 (default) means halt probing, while a value of 2 means
191 send last-ditch probes.
192 -m maxttl
194 specifies the maximum TTL or HLIM value that will be probed. By
195 default, there is no restriction, apart from the 255 hops that
196 the Internet protocols allow.
197 -M specifies that path MTU discovery (PMTUD) should be attempted for
199 the path when the initial traceroute completes. scamper will not
200 conduct PMTUD unless it is probing a responsive destination, as
201 otherwise there is no way to distinguish all packets being lost
202 from just big packets (larger than MTU) being lost.
203 -l loops
205 specifies the maximum number of loops permitted until probing
206 stops. By default, a value of one is used. A value of zero dis‐
207 ables loop checking.
208 -o offset
210 specifies the fragmentation offset to use in probes. By default,
211 no offset is used.
212 -O option
214 specifies optional arguments to use. The current choices for
215 this option are:
216 - dl specifies that the datalink socket should be used to
217 timestamp packets, and to receive certain packets.
218 - dtree-noback specifies that the traceroute should not do
219 backwards probing when using doubletree.
220 -p payload
222 specifies the payload of the probe to use as a base. The payload
223 is specified in hexadecimal. Note that the payload supplied is
224 merely a base; the first 2 bytes may be modified to accomplish
225 ICMP-Paris and UDP-Paris traceroute.
226 -P method
228 specifies the traceroute method to use. scamper currently sup‐
229 ports five different probe methods: UDP, ICMP, UDP-paris, ICMP-
230 paris, TCP, and TCP-ACK. By default, UDP-paris is used.
231 -q attempts
233 specifies the maximum number of attempts to obtain a response per
234 hop. By default, a value of two is used.
235 -Q specifies that all allocated probes are sent, regardless of how
237 many responses have been received.
238 -s sport
240 specifies the source port value to use. For ICMP-based methods,
241 this option specifies the ICMP identifier to use.
242 -S srcaddr
244 specifies the source address to use in probes. The address can‐
245 not be spoofed.
246 -t tos specifies the value to set in the IP ToS/DSCP + ECN byte. By
248 default, this byte is set to zero.
249 -T specifies that time exceeded messages from the destination do not
251 cause the trace to be defined as reaching the destination.
252 -U userid
254 specifies an unsigned integer to include with the data collected;
255 the meaning of the user-id is entirely up to the user and has no
256 effect on the behaviour of traceroute.
257 -w wait
259 specifies how long to wait, in seconds, for a reply. By default,
260 a value of 5 is used.
261 -W wait-probe
263 specifies the minimum time to wait, in 10s of milliseconds,
264 between sending consecutive probes. By default the next probe is
265 sent as soon as possible.
266 -z gss-entry
268 specifies an IP address to halt probing when encountered; used
269 with the double-tree algorithm.
270 -Z lss-name
272 specifies the name of the local stop set to use when determining
273 when to halt probing backwards; used with the double-tree algo‐
274 rithm.
275
277 The ping command is used for conducting ping. The following variations
278 of the ping(8) options are available:
279 ping [-R] [-B payload] [-c probecount] [-C icmp-sum] [-d dport]
281 [-F sport] [-i wait] [-m ttl] [-M MTU] [-o replycount] [-O options]
282 [-p pattern] [-P method] [-s size] [-S srcaddr] [-T timestamp]
283 [-U userid] [-W timeout] [-z tos]
284 -B payload
286 specifies, in a hexadecimal string, the payload to include in
287 each probe.
288 -c probecount
290 specifies the number of probes to send before exiting. By
291 default, a value of 4 is used.
292 -C icmp-sum
294 specifies the ICMP checksum to use when sending a probe. The
295 payload of each probe will be manipulated so that the checksum is
296 valid.
297 -d dport
299 specifies the destination port to use in each TCP/UDP probe, and
300 the first ICMP sequence number to use in ICMP probes.
301 -F sport
303 specifies the source port to use in each TCP/UDP probe, and the
304 ICMP ID to use in ICMP probes.
305 -i wait
307 specifies the length of time to wait, in seconds, between probes.
308 By default, a value of 1 is used.
309 -m ttl specifies the TTL value to use for outgoing packets. By default,
311 a value of 64 is used.
312 -M MTU specifies a pseudo MTU value. If the response packet is larger
314 than the pseudo MTU, an ICMP packet too big (PTB) message is
315 sent.
316 -o replycount
318 specifies the number of replies required at which time probing
319 may cease. By default, all probes are sent.
320 -O options
322 The current choices for this option are:
323 - dl specifies that the ping should use datalink sockets,
324 rather than raw sockets.
325 - spoof specifies that the source address is to be spoofed
326 according to the address specified with the -S option. The
327 address scamper would otherwise use as the source address is
328 embedded in the payload of the probe.
329 - tbt specifies that the goal of the ping is to obtain frag‐
330 mented responses, so that the -c option specifies how many
331 packets to send, and the -o option specifies how many frag‐
332 mented responses are desired.
333 -p pattern
335 specifies the pattern, in hex, to use in probes. Up to 16 bytes
336 may be specified. By default, each probe's bytes are zeroed.
337 -P method
339 specifies the type of ping packets to send. By default, ICMP
340 echo requests are sent. Choices are: icmp-echo, icmp-time, tcp-
341 syn, tcp-ack, tcp-ack-sport, udp, and udp-dport.
342 -R specifies that the record route IP option should be used.
344 -s size
346 specifies the size of the probes to send. The probe size
347 includes the length of the IP and ICMP headers. By default, a
348 probe size of 84 bytes is used for IPv4 pings, and 56 bytes for
349 IPv6 pings.
350 -S srcaddr
352 specifies the source address to use in probes. The address can
353 be spoofed if -O spoof is included.
354 -T timestamp
356 specifies that an IP timestamp option be included. The timestamp
357 option can either be: tsprespec where IP addresses of devices of
358 interest can be specified; tsonly, where timestamps are embedded
359 by devices but no IP addresses are included; and tsandaddr, where
360 timestamps and IP addresses are included by devices in the path.
361 See the examples section for more information.
362 -U userid
364 specifies an unsigned integer to include with the data collected;
365 the meaning of the user-id is entirely up to the user and has no
366 effect on the behaviour of ping.
367 -W timeout
369 specifies how long to wait for responses after the last ping is
370 sent. By default this is one second.
371 -z tos specifies the value to use in the IPv4 ToS/DSCP + ECN byte. By
373 default, this byte is set to zero.
374
376 The dealias command is used to send probes for the purpose of alias reso‐
377 lution. It supports the mercator technique, where aliases are inferred
378 if a router uses a different address when sending an ICMP response; the
379 ally technique, where aliases are inferred if a sequence of probes sent
380 to alternating IP addresses yields responses with incrementing, inter‐
381 leaved IP-ID values; radargun, where probes are sent to a set of IP
382 addresses in multiple rounds and aliases are inferred by post-processing
383 the results; prefixscan, where an alias is searched in a prefix for a
384 specified IP address; and bump, where two addresses believed to be
385 aliases are probed in an effort to force their IP-ID values out of
386 sequence. The following options are available for the scamper dealias
387 command:
388 dealias [-d dport] [-f fudge] [-m method] [-o replyc] [-O option]
390 [-p probe-options] [-q attempts] [-r wait-round] [-s sport] [-t ttl]
391 [-U userid] [-w wait-timeout] [-W wait-probe] [-x exclude]
392 -d dport
394 specifies the destination port to use when sending probes. Only
395 valid for the mercator technique; destination ports can be speci‐
396 fied in probedefs defined with -p for other alias resolution
397 methods.
398 -f fudge
400 specifies a fudge factor for alias matching. Defaults to 200.
401 Only valid for ally and bump.
402 -m method
404 specifies which method to use for alias resolution. Valid
405 options are: ally, bump, mercator, prefixscan, and radargun.
406 -o replyc
408 specifies how many replies to wait for. Only valid for prefixs‐
409 can.
410 -O option
412 allows alias resolution behaviour to be further tailored. The
413 current choices for this option are:
414 - inseq where IP-ID values are required to be strictly in
415 sequence (with no tolerance for packet reordering)
416 - shuffle randomise the order of probes sent each round; only
417 valid for radargun probing.
418 - nobs do not allow for byte swapped IP-ID values in
419 responses. Valid for ally and prefixscan.
420 -p probedef
422 specifies a definition for a probe. Possible options are:
423 -c sum specifies what ICMP checksum to use for ICMP probes. The
425 payload of the probe will be altered appropriately.
426 -d dst-port
428 specifies the destination port of the probe. Defaults to
429 33435.
430 -F src-port
432 specifies the source port of the probe. Defaults to (pid
433 & 0x7fff) + 0x8000.
434 -i IP specifies the destination IP address of the probe.
436 -M mtu specifies the pseudo MTU to use when soliciting frag‐
438 mented responses.
439 -P method
441 specifies which method to use for the probe. Valid
442 options are: udp, udp-dport, tcp-ack, tcp-ack-sport, tcp-
443 syn-sport, and icmp-echo.
444 -s size
446 specifies the size of the probes to send.
447 -t ttl specifies the IP time to live of the probe.
449 The ally method accepts up to two probe definitions; the prefixs‐
450 can method expects one probe definition; radargun expects at
451 least one probe definition; bump expects two probe definitions.
452 -q attempts
454 specifies how many times a probe should be retried if it does not
455 obtain a useful response.
456 -r wait-round
458 specifies how many milliseconds to wait between probing rounds
459 with radargun.
460 -s sport
462 specifies the source port to use when sending probes. Only valid
463 for mercator.
464 -t ttl specifies the time-to-live of probes sent. Only valid for merca‐
466 tor.
467 -U userid
469 specifies an unsigned integer to include with the data collected;
470 the meaning of the user-id is entirely up to the user and has no
471 effect on the behaviour of dealias.
472 -w wait-timeout
474 specifies how long to wait in seconds for a reply from the remote
475 host.
476 -W wait-probe
478 specifies how long to wait in milliseconds between probes.
479 -x exclude
481 specifies an IP address to exclude when using the prefixscan
482 method. May be specified multiple times to exclude multiple
483 addresses.
484
486 The neighbourdisc command attempts to find the layer-2 address of a given
487 IP address using IPv4 ARP or IPv6 Neighbour Discovery. The following
488 options are available for the scamper neighbourdisc command:
489 neighbourdisc [-FQ] [-i interface] [-o reply-count] [-q attempts]
491 [-w wait]
492 -F specifies that we only want the first response.
494 -Q specifies that we want to send all attempts.
496 -i interface
498 specifies the name of the interface to use for neighbour discov‐
499 ery.
500 -o reply-count
502 specifies how many replies we wait for.
503 -q attempts
505 specifies how many probes we send out.
506 -w wait
508 specifies how long to wait between probes in milliseconds.
509 Defaults to 1000.
510
512 The tbit command can be used to infer TCP behaviour of a specified host.
513 At present, it implements tests to check the ability of the host to
514 respond to ICMP Packet Too Big messages, and respond to Explicit Conges‐
515 tion Notification. The following options are available for the scamper
516 tbit command:
517 tbit [-t type] [-p app] [-d dport] [-s sport] [-b ASN] [-f cookie]
519 [-m mss] [-M mtu] [-o offset] [-O option] [-P ptbsrc] [-q attempts]
520 [-S srcaddr] [-T ttl] [-u url] [-U userid] [-w wscale]
521 -t type specifies which type of testing to use. Valid options are:
523 pmtud, ecn, null, sack-rcvr, icw, blind-rst, blind-syn,
524 blind-data.
525 -p app specifies what kind of traffic to generate for testing.
527 Destination port defaults the application standard port.
528 Valid applications are: http, bgp.
529 -d dport specifies the destination port for the packets being sent.
531 Defaults are application-specific.
532 -s sport specifies the source port for the packets being sent.
534 Default is based of the scamper process id.
535 -b ASN specifies the autonomous system number (ASN) that should be
537 used when establishing a BGP session.
538 -f cookie specifies the TCP fast open cookie that should be used when
540 establishing a TCP connection.
541 -m mss specifies the maximum segment size to advertise to the
543 remote host.
544 -M mtu specifies the MTU to use in a Packet Too Big message.
546 -o offset specifies the sequence number offset to use when conducting
548 blind-syn and blind-rst tests, and the acknowledgement num‐
549 ber offset to use when conducting a blind-data test.
550 -O option allows tbit behaviour to be further tailored. The current
552 choices for this option are:
553 - blackhole: for PMTUD testing, do not send Packet Too
554 Big messages; this tests to ability of a host to infer
555 a PMTUD blackhole and work around it.
556 - tcpts: advertise support for TCP timestamps when
557 establishing a TCP connection. If the peer supports
558 TCP timestamps, embed timestamps in data packets.
559 - ipts-syn: use the timestamp IP option in a SYN packet
560 when attempting to establish a TCP connection.
561 - iprr-syn: use the record-route IP option in a SYN
562 packet when attempting to establish a TCP connection.
563 - ipqs-syn: use the quick-start IP option in a SYN
564 packet when attempting to establish a TCP connection.
565 - sack: advertise support for TCP selective acknowledge‐
566 ments (SACK) when establishing a TCP connection.
567 - fo: advertise support for TCP fast open using the
568 official IANA number assigned for fast open.
569 - fo-exp: advertise support for TCP fast open using the
570 testing number assigned by IANA for fast open.
571 -P ptbsrc specifies the source address that should be used to send
573 Packet Too Big messages in the pmtud test.
574 -q attempts specifies the number of attempts to make with each packet
576 to reduce false inferences caused by packet loss.
577 -S srcaddr specifies the source address that should be used in TCP
579 packets sent by the tbit test.
580 -T ttl specifies the IP time-to-live value that should be used in
582 TCP packets sent by the tbit test.
583 -u url specifies a url for the http application.
585 -U userid specifies an unsigned integer to include with the data col‐
587 lected; the meaning of the user-id is entirely up to the
588 user and has no effect on the behaviour of tbit.
589 -w wscale specifies the window scale option to use when establishing
591 the TCP connection.
592
594 The tracelb command is used to infer all per-flow load-balanced paths
595 between a source and destination. The following options are available
596 for the scamper tracelb command:
597 tracelb [-c confidence] [-d dport] [-f firsthop] [-g gaplimit]
599 [-P method] [-q attempts] [-Q maxprobec] [-s sport] [-t tos] [-U userid]
600 [-w wait-timeout] [-W wait-probe]
601 -c confidence
603 specifies the level of confidence we want to attain that
604 there are no more parallel load balanced paths at a given
605 hop. Valid values are 95 (default) and 99, for 95% confi‐
606 dence and 99% confidence respectively.
607 -d dport specifies the base destination port to use. Defaults to
609 33435, the default used by traceroute(8).
610 -f firsthop specifies how many hops away we should start probing.
612 -g gaplimit specifies how many consecutive unresponsive hops are per‐
614 mitted before probing down a branch halts. Defaults to
615 three.
616 -P method specifies which method we should use to do the probing.
618 Valid options are: "udp-dport", "icmp-echo", "udp-sport",
619 "tcp-sport", and "tcp-ack-sport". Defaults to "udp-dport".
620 -q attempts specifies how many probes we should send in an attempt to
622 receive a reply. Defaults to 2.
623 -Q maxprobec specifies the maximum number of probes we ever want to
625 send. Defaults to 3000.
626 -s sport specifies to the source port to use when sending probes.
628 Default based on process ID.
629 -t tos specifies the value for the IP Type-of-service field for
631 outgoing probes. Defaults to 0.
632 -U userid specifies an unsigned integer to include with the data col‐
634 lected; the meaning of the user-id is entirely up to the
635 user and has no effect on the behaviour of tracelb.
636 -w wait-timeout
638 specifies in seconds how long to wait for a reply to a
639 probe. Defaults to 5.
640 -W wait-probe
642 specifies in 1/100ths of seconds how long to wait between
643 probes. Defaults to 25 (i.e. 250ms).
644
646 The sting command is used to infer one-way loss using an algorithm with
647 TCP probes. It requires the firewall be enabled in scamper using the -F
648 option. The following options are available for the scamper sting com‐
649 mand:
650 sting [-c count] [-d dport] [-f distribution] [-h request] [-H hole]
652 [-i inter] [-m mean] [-s sport]
653 -c count specifies the number of samples to make. By default 48
655 samples are sent, as this value is the current default of
656 the FreeBSD TCP reassembly queue length. Sting 0.7 uses
657 100 samples.
658 -d dport specifies the base destination port to use. Defaults to
660 80, the default port used by the HTTP protocol.
661 -f distribution
663 specifies the delay distribution of samples. By default a
664 uniform distribution is constructed. Other distributions
665 are currently not implemented in scamper's implementation
666 of sting.
667 -h request specifies the default request to make. Currently not
669 implemented.
670 -H hole specifies the size of the initial hole left in the request.
672 The default is 3 bytes, the same as sting-0.7.
673 -i inter specifies the inter-phase delay between data seeding and
675 hole filling, in milliseconds. By default, sting waits
676 2000ms between phases.
677 -m mean specifies the mean rate to send packets in the data phase,
679 in milliseconds. By default, sting waits 100ms between
680 probes.
681 -s sport specifies to the source port to use when sending probes.
683 Default is based on the process ID.
684
686 The sniff command is used to capture packets matching a specific signa‐
687 ture. At present, the only supported signature is ICMP echo packets with
688 a specific ID value, or packets containing such a quote. The following
689 options are available for the scamper sniff command:
690 sting [-c limit-pktc] [-G limit-time] [-S ipaddr] [-U userid] <expres‐
692 sion>
693 -c limit-pktc
695 specifies the maximum number of packets to capture.
696 -G limit-time
698 specifies the maximum time, in seconds, to capture packets.
699 -S ipaddr specifies the IP address that packets must arrive using.
701 scamper uses the IP address to identify the appropriate
702 interface to listen for packets.
703 -U userid specifies an unsigned integer to include with the data col‐
705 lected; the meaning of the user-id is entirely up to the
706 user and has no effect on the behaviour of sniff.
707 The sole supported expression is icmp[icmpid] == X, where X is the ICMP-
709 ID to select.
710
712 scamper has two data output formats. The first is a human-readable for‐
713 mat suitable for one-off data collection and measurement. The second,
714 known as warts, is a binary format that records much more meta-data and
715 is more precise than the human-readable format.
716 scamper is designed for Internet-scale measurement, where large lists of
718 targets are supplied for probing. scamper has the ability to probe mul‐
719 tiple lists simultaneously, with each having a mix rate that specifies
720 the priority of the list. scamper can also make multiple cycles over a
721 list of addresses.
722 When writing output to a warts file, scamper records details of the list
724 and cycle that each measurement task belongs to.
725
727 When started with the -P option, scamper allows inter-process communica‐
728 tion via a TCP socket bound to the supplied port on the local host. This
729 socket is useful for controlling the operation of a long-lived scamper
730 process. A client may interact with scamper by using telnet(1) to open a
731 connection to the supplied port.
732 The following control socket commands are available.
734 exit
736 The exit command closes the current control socket connection.
737 attach
739 The attach command changes how scamper accepts and replies to com‐
740 mands, returning results straight over the control socket. See
741 ATTACH section below for details on which commands are accepted.
742 get argument
744 The get command returns the current setting for the supplied argu‐
745 ment. Valid argument values are: holdtime, monitorname, pid, pps,
746 sport, version.
747 set argument ...
749 The set command sets the current setting for the supplied argument.
750 Valid argument values are: holdtime, monitorname, pps.
751 source argument ...
753 add arguments
755 The source add command allows a new input source to be added.
756 It accepts the following arguments:
757 name string
759 The name of the source. This parameter is mandatory.
760 descr string
762 An optional string describing the source.
763 command string
765 The command to execute for each address supplied. If not
766 supplied, the default command is used.
767 list_id uint32_t
769 An optional numeric list identifier, assigned by a human.
770 If not supplied, a value of zero is used.
771 cycle_id uint32_t
773 An optional numeric initial cycle identifier to use,
774 assigned by a human. If not supplied, a value of one is
775 used.
776 priority uint32_t
778 An optional numeric value that specifies the mix rate of
779 measurements from the source compared to other sources.
780 If not supplied, a mix rate of one is used. A value of
781 zero causes the source to be created, but not actively
782 used.
783 outfile string
785 The name of the output file to write results to, previ‐
786 ously defined with outfile open. If not supplied, the
787 default output file is used.
788 file string
790 The name of the input file to read target addresses from.
791 This parameter is mandatory if the source is a managed
792 source.
793 cycles integer
795 The number of cycles to make over the target address file.
796 If zero, scamper will loop indefinitely over the file.
797 This parameter is ignored unless a managed source is
798 defined.
799 autoreload [on | off]
801 This parameter specifies if the target address file should
802 be re-read whenever a cycle is completed, or if the same
803 set of target addresses as the previous cycle should be
804 used. If not specified, the file is not automatically
805 reloaded at cycle time.
806 update name arguments
808 The source update command allows some properties of an existing
809 source to be modified. The source to update is specified with
810 the name parameter. Valid parameters are: autoreload, cycles,
811 and priority.
812 list ...
814 The source list command provides a listing of all currently
815 defined sources. The optional third name parameter restricts
816 the listing to the source specified.
817 cycle name
819 The source cycle command manually inserts a cycle marker in an
820 adhoc source.
821 delete name
823 The source delete command deletes the named source, if possi‐
824 ble.
825 outfile argument ...
827 The outfile commands provide the ability to manage output files. It
828 accepts the following arguments:
829 open ...
831 The outfile open command allows a new output file to be
832 defined. It accepts the following parameters:
833 name alias
835 The alias of the output file. This parameter is manda‐
836 tory.
837 file string
839 The filename of the output file. This parameter is manda‐
840 tory.
841 mode [truncate | append]
843 How the file will be opened. If the append mode is used,
844 any existing file with the specified name will be appended
845 to. If the truncate mode is used, any existing file will
846 be truncated when it is opened.
847 close alias
849 The outfile close command allows an existing output file to be
850 closed. The mandatory alias parameter specifies which output
851 file to close. An output file that is currently referenced is
852 not able to be closed. To close a file that is currently ref‐
853 erenced, a new outfile must be opened, and then the outfile
854 swap command be used.
855 swap alias1 alias2
857 The outfile swap command swaps the file associated with each
858 output file.
859 list
861 The outfile list command outputs a list of the existing out‐
862 files.
863 observe sources
865 This command allows for monitoring of source events. When executed,
866 the control socket will then supply event notices whenever a source
867 is added, updated, deleted, finished, or cycled. Each event is pre‐
868 fixed with a count of the number of seconds elapsed since the Unix
869 epoch. The following examples illustrate the event monitoring capa‐
870 bilities:
871 EVENT 1169065640 source add name 'foo' list_id 5 priority 1
873 EVENT 1169065641 source update 'foo' priority 15
874 EVENT 1169065642 source cycle 'bar' id 2
875 EVENT 1169065650 source finish 'bar'
876 EVENT 1169065661 source delete 'foo'
877 shutdown argument
879 The shutdown argument allows the scamper process to be exited
880 cleanly. The following arguments are supported
881 done
883 The shutdown done command requests that scamper shuts down when
884 the current tasks, as well as all remaining cycles, have com‐
885 pleted.
886 flush
888 The shutdown flush command requests that scamper flushes all
889 remaining tasks queued with each list, finishes all current
890 tasks, and then shuts down.
891 now The shutdown now command causes scamper to shutdown immedi‐
893 ately. Unfinished tasks are purged.
894 cancel
896 The shutdown cancel command cancels any pending shutdown.
897
899 In attach mode, none of the usual interactive mode commands are usable.
900 Instead, commands may be entered directly and results will be sent back
901 directly over the control socket. Commands are specified just as they
902 would be with the -I flag for a command-line invocation of scamper.
903 Replies are split into lines by single \n characters and have one of the
904 following formats:
905 ERR ...
907 A line starting with the 3 characters "ERR" indicates an error has
908 occurred. The rest of the line will contain an error message.
909 OK id-num
911 A line with the 2 characters "OK" indicates that scamper has
912 accepted the command. scamper versions after 20110623 return an id
913 number associated with the command, which allow the task to be
914 halted by subsequently issuing a "halt" instruction.
915 MORE
917 A line with just the 4 characters "MORE" indicates that scamper has
918 the capacity to accept more probing commands to run in parallel.
919 DATA length
921 A line starting with the 4 characters "DATA" follow by a space then
922 a base-10 number indicates the start of result. length specifies
923 the number of characters of the data, including newlines. The data
924 is in binary warts format and uuencoded before transmission.
925 To exit attached mode the client must send a single line containing
927 "done". To halt a command that has not yet completed, issue a "halt"
928 instruction with the id number returned when the command was accepted as
929 the sole parameter.
930
932 To use the default traceroute command to trace the path to 192.0.2.1:
933 scamper -i 192.0.2.1
935 To infer Path MTU changes in the network and associate them with a
937 traceroute path:
938 scamper -I "trace -P udp-paris -M 192.0.2.1"
940 To use paris traceroute with ICMP probes, using 3 probes per hop, sending
942 all probes, writing to a specified warts file:
943 scamper -O warts -o file.warts -I "trace -P icmp-paris -q 3 -Q
945 192.0.2.1"
946 To ping a series of addresses defined in filename, probing each address
948 10 times:
949 scamper -c "ping -c 10" filename
951 Care must be taken with shell quoting when using commands with multiple
953 levels of quoting, such as when giving a probe description with a dealias
954 command. The following sends UDP probes to alternating IP addresses, one
955 second apart, and requires the IP-ID values returned to be strictly in
956 sequence.
957 scamper -O warts -o ally.warts -I "dealias -O inseq -W 1000 -m ally
959 -p '-P udp -i 192.0.2.1' -p '-P udp -i 192.0.2.4'"
960 Alternatively, the following accomplishes the same, but without specify‐
962 ing the UDP probe method twice.
963 scamper -O warts -o ally.warts -I "dealias -O inseq -W 1000 -m ally
965 -p '-P udp' 192.0.2.1 192.0.2.4"
966 The following command scans 198.51.100.0/28 for a matching alias to
968 192.0.2.4, but skips 198.51.100.3.
969 scamper -O warts -o prefixscan.warts -I "dealias -O inseq -W 1000 -m
971 prefixscan -p '-P udp' -x 198.51.100.3 192.0.2.4 198.51.100.0/28"
972 The following uses UDP probes to enumerate all per-flow load-balanced
974 paths towards 192.0.2.6 to 99% confidence; it varies the source port with
975 each probe.
976 scamper -I "tracelb -P udp-sport -c 99 192.0.2.6"
978
980 ping(8), traceroute(8), libscamperfile(3), sc_ally(1),
981 sc_analysis_dump(1), sc_attach(1), sc_ipiddump(1), sc_filterpolicy(1),
982 sc_speedtrap(1), sc_tbitblind(1), sc_tracediff(1), sc_wartscat(1),
983 sc_wartsdump(1), sc_warts2json(1), sc_warts2pcap(1), sc_warts2text(1),
984 S. Savage, Sting: a TCP-based Network Measurement Tool, 1999 USENIX
986 Symposium on Internet Technologies and Systems.
987 R. Govindan and H. Tangmunarunkit, Heuristics for Internet Map Discovery,
989 Proc. IEEE INFOCOM 2000.
990 N. Spring, R. Mahajan, and D. Wetherall, Measuring ISP topologies with
992 Rocketfuel, Proc. ACM SIGCOMM 2002.
993 A. Medina, M. Allman, and S. Floyd, Measuring the evolution of transport
995 protocols in the Internet, Proc. ACM/SIGCOMM Internet Measurement
996 Conference 2004.
997 M. Luckie, K. Cho, and B. Owens, Inferring and Debugging Path MTU
999 Discovery Failures, Proc. ACM/SIGCOMM Internet Measurement Conference
1000 2005.
1001 B. Donnet, P. Raoult, T. Friedman, and M. Crovella, Efficient algorithms
1003 for large-scale topology discovery, Proc. ACM SIGMETRICS 2005.
1004 B. Augustin, X. Cuvellier, B. Orgogozo, F. Viger, T. Friedman, M. Latapy,
1006 C. Magnien, and R. Teixeira, Avoiding traceroute anomalies with Paris
1007 traceroute, Proc. ACM/SIGCOMM Internet Measurement Conference 2006.
1008 B. Augustin, T. Friedman, and R. Teixeira, Measuring Load-balanced Paths
1010 in the Internet, Proc. ACM/SIGCOMM Internet Measurement Conference 2007.
1011 A. Bender, R. Sherwood, and N. Spring, Fixing Ally's growing pains with
1013 velocity modeling, Proc. ACM/SIGCOMM Internet Measurement Conference
1014 2008.
1015 M. Luckie, Scamper: a Scalable and Extensible Packet Prober for Active
1017 Measurement of the Internet, Proc. ACM/SIGCOMM Internet Measurement
1018 Conference 2010.
1019 R. Beverly, W. Brinkmeyer, M. Luckie, and J.P. Rohrer, IPv6 Alias
1021 Resolution via Induced Fragmentation, Proc. Passive and Active
1022 Measurement Conference 2013.
1023 M. Luckie, R. Beverly, W. Brinkmeyer, and k claffy, Speedtrap: Internet-
1025 scale IPv6 Alias Resolution, Proc. ACM/SIGCOMM Internet Measurement
1026 Conference 2013.
1027 M. Luckie, R. Beverly, T. Wu, M. Allman, and k. claffy, Resilience of
1029 Deployed TCP to Blind Attacks, Proc. ACM/SIGCOMM Internet Measurement
1030 Conference 2015.
1031 J. Czyz, M. Luckie, M. Allman, and M. Bailey, Don't Forget to Lock the
1033 Back Door! A Characterization of IPv6 Network Security Policy, Proc.
1034 Network and Distributed Systems Security (NDSS) Conference 2016.
1035
1037 scamper was written by Matthew Luckie <mjl@luckie.org.nz>. Alistair King
1038 contributed an initial implementation of Doubletree; Ben Stasiewicz con‐
1039 tributed an initial implementation of TBIT's PMTUD test; Stephen Eichler
1040 contributed an initial implementation of TBIT's ECN test; Boris
1041 Pfahringer adapted scamper to use GNU autotools, modularised the tests,
1042 and updated this man page. Brian Hammond of Internap Network Services
1043 Corporation provided an initial implementation of scamper's json output
1044 format. Tiange Wu contributed an initial implementation of the blind in-
1045 window TBIT test, and Robert Beverly contributed BGP protocol support for
1046 TBIT.
1047
1049 scamper development was initially funded by the WIDE project in associa‐
1050 tion with CAIDA. Boris' work was funded by the University of Waikato's
1051 Centre for Open Source Innovation.
1052BSD August 8, 2016 BSD