| SCAMPER(1) | General Commands Manual | SCAMPER(1) |
scamper — parallel
Internet measurement utility
scamper |
[-?Dv]
[-c command]
[-p pps]
[-w window]
[-M monitorname]
[-l listname]
[-L listid]
[-C cycleid]
[-o outfile]
[-F firewall]
[-d debugfile]
[-e pidfile]
[-O options]
[-i IPs | -I cmds | -f file | -P [ip:]port | -R name:port | -U unix-dom] |
The scamper utility provides the ability
to execute Internet measurement techniques to IPv4 and IPv6 addresses, in
parallel, to fill a specified packets-per-second rate. Currently,
scamper supports the well-known traceroute and ping
techniques, as well as MDA traceroute, alias resolution, some parts of tbit,
sting, and neighbour discovery.
scamper has five modes of operation.
First, scamper can be supplied a list of addresses
on the command line with the -i option.
scamper will then execute a command with each of the
supplied addresses, in parallel, and output the results as each task
completes. Second, scamper can be supplied a list of
addresses in a listfile, one address per line, using the
-f option. Third, scamper
can be supplied a list of complete commands on the command line with the
-I option. Fourth, scamper
can be instructed to listen on an IP address and port specified with the
-P option, or on a unix domain socket specified with
the -U option, where it can take commands
dynamically. Finally, scamper can be instructed to
connect to a remote host and port specified with the
-R option, where it will be supplied with commands
dynamically.
The options are as follows:
-?-vscamper to output version information and
exit.-Dscamper will detach and
become a daemon. Use with the -P or
-U options.-c
commandscamper to use by
default. The current choices for this option are:
scamper uses trace by default. The available
commands and their options are documented below.-p
ppsscamper to reach. By default, this value is
20.-w
window-M
monitornamescamper is run. This value is used when recording
the output in a warts output file.-l
listname-L
listid-C
cycleid-o
outfile-F
firewallscamper may use the firewall in
measurements that require it (tbit and sting).
scamper supports two firewall types: IPFW, and PF.
To use the IPFW firewall, pass ipfw:<start>-<end>, where
<start> is the first rule scamper can use,
and <end> is the last. To use the PF firewall, pass
pf:<anchor>:<num>, where <anchor> is the anchor for
scamper to use, and <num> specifies the
number of rules scamper is allowed to use.-d
debugfile-e
pidfile-O
options-d
option. The default is to truncate the debugfile.-R option.-i
IP 1..N-c option.-f
listfile-c option on
each.-I
cmds.-P
[ip:]portscamper provide a control socket
listening on the specified IP address and port on the local host. If an IP
address is not specified, scamper will bind to the
port specified on the loopback address.-R
name:portscamper connects to a specified
remote host and port to receive commands.-U
unix domain socketscamper provide a control socket
listening on the specified socket in the unix domain.The trace command is used for conducting traceroute. The following variations of the traceroute(8) options are available:
trace [-MQT]
[-c confidence]
[-d dport]
[-f firsthop]
[-g gaplimit]
[-G gapaction]
[-l loops]
[-m maxttl]
[-o offset]
[-O option]
[-p payload]
[-P method]
[-q attempts]
[-s sport]
[-S srcaddr]
[-t tos]
[-U userid]
[-w wait]
[-W wait-probe]
[-z gss-entry]
[-Z lss-name]
-c
confidence-d
dport-f
firsthop-g
gaplimit-G
gapaction-m
maxttl-Mscamper
will not conduct PMTUD unless it is probing a responsive destination, as
otherwise there is no way to distinguish all packets being lost from just
big packets (larger than MTU) being lost.-l
loops-o
offset-O
option-p
payload-P
methodscamper
currently supports five different probe methods: UDP, ICMP, UDP-paris,
ICMP-paris, TCP, and TCP-ACK. By default, UDP-paris is used.-q
attempts-Q-s
sport-S
srcaddr-t
tos-T-U
userid-w
wait-W
wait-probe-z
gss-entry-Z
lss-nameThe ping command is used for conducting ping. The following variations of the ping(8) options are available:
ping [-R]
[-B payload]
[-c probecount]
[-C icmp-sum]
[-d dport]
[-F sport]
[-i wait]
[-m ttl]
[-M MTU]
[-o replycount]
[-O options]
[-p pattern]
[-P method]
[-s size]
[-S srcaddr]
[-T timestamp]
[-U userid]
[-W timeout]
[-z tos]
-B
payload-c
probecount-C
icmp-sum-d
dport-F
sport-i
wait-m
ttl-M
MTU-o
replycount-O
options-S option. The
address scamper would otherwise use as the source address is embedded
in the payload of the probe.-c option specifies how many
packets to send, and the -o option specifies
how many fragmented responses are desired.-p
pattern-P
method-R-s
size-S
srcaddr-T
timestamp-U
userid-W
timeout-z
tosThe dealias command is used to send probes for the purpose of
alias resolution. It supports the mercator technique, where aliases are
inferred if a router uses a different address when sending an ICMP response;
the ally technique, where aliases are inferred if a sequence of probes sent
to alternating IP addresses yields responses with incrementing, interleaved
IP-ID values; radargun, where probes are sent to a set of IP addresses in
multiple rounds and aliases are inferred by post-processing the results;
prefixscan, where an alias is searched in a prefix for a specified IP
address; and bump, where two addresses believed to be aliases are probed in
an effort to force their IP-ID values out of sequence. The following options
are available for the scamper dealias command:
dealias
[-d dport]
[-f fudge]
[-m method]
[-o replyc]
[-O option]
[-p probe-options]
[-q attempts]
[-r wait-round]
[-s sport]
[-t ttl]
[-U userid]
[-w wait-timeout]
[-W wait-probe]
[-x exclude]
-d
dport-p for other alias resolution
methods.-f
fudge-m
method-o
replyc-O
option-p
probedef-c
sum-d
dst-port-F
src-port-i
IP-M
mtu-P
method-s
size-t
ttl-q
attempts-r
wait-round-s
sport-t
ttl-U
userid-w
wait-timeout-W
wait-probe-x
excludeThe neighbourdisc command attempts to find the layer-2 address of
a given IP address using IPv4 ARP or IPv6 Neighbour Discovery. The following
options are available for the scamper neighbourdisc
command:
neighbourdisc [-FQ]
[-i interface]
[-o reply-count]
[-q attempts]
[-w wait]
-F-Q-i
interface-o
reply-count-q
attempts-w
waitThe tbit command can be used to infer TCP behaviour of a specified
host. At present, it implements tests to check the ability of the host to
respond to ICMP Packet Too Big messages, respond to Explicit Congestion
Notification, test Selective Acknowledgement behaviour, the Initial
Congestion Window, and resilience to Blind Attacks. The following options
are available for the scamper tbit command:
tbit
[-t type]
[-p app]
[-d dport]
[-s sport]
[-a acks]
[-b ASN]
[-i ICW]
[-f cookie]
[-L limit]
[-m mss]
[-M mtu]
[-o offset]
[-O option]
[-P ptbsrc]
[-q attempts]
[-S srcaddr]
[-T ttl]
[-u url]
[-U userid]
[-w wscale]
-t
type-p
app-d
dport-s
sportscamper process id.-a
acks-b
ASN-i
ICW-f
cookie-L
limit-m
mss-M
mtu-o
offset-O
option-P
ptbsrc-q
attempts-S
srcaddr-T
ttl-u
url-U
userid-w
wscaleThe tracelb command is used to infer all per-flow load-balanced
paths between a source and destination. The following options are available
for the scamper tracelb command:
tracelb
[-c confidence]
[-d dport]
[-f firsthop]
[-g gaplimit]
[-P method]
[-q attempts]
[-Q maxprobec]
[-s sport]
[-t tos]
[-U userid]
[-w wait-timeout]
[-W wait-probe]
-c
confidence-d
dport-f
firsthop-g
gaplimit-P
method-q
attempts-Q
maxprobec-s
sport-t
tos-U
userid-w
wait-timeout-W
wait-probeThe sting command is used to infer one-way loss using an algorithm
with TCP probes. It requires the firewall be enabled in scamper using the
-F option. The following options are available for
the scamper sting command:
sting
[-c count]
[-d dport]
[-f distribution]
[-h request]
[-H hole]
[-i inter]
[-m mean]
[-s sport]
-c
count-d
dport-f
distribution-h
request-H
hole-i
inter-m
mean-s
sportThe sniff command is used to capture packets matching a specific
signature. At present, the only supported signature is ICMP echo packets
with a specific ID value, or packets containing such a quote. The following
options are available for the scamper sniff
command:
sting
[-c limit-pktc]
[-G limit-time]
[-S ipaddr]
[-U userid]
<expression>
-c
limit-pktc-G
limit-time-S
ipaddr-U
useridThe sole supported expression is icmp[icmpid] == X, where X is the ICMP-ID to select.
scamper has two data output formats. The
first is a human-readable format suitable for one-off data collection and
measurement. The second, known as warts, is a binary
format that records much more meta-data and is more precise than the
human-readable format.
scamper is designed for Internet-scale
measurement, where large lists of targets are supplied for probing.
scamper has the ability to probe multiple lists
simultaneously, with each having a mix rate that specifies the priority of
the list. scamper can also make multiple cycles over
a list of addresses.
When writing output to a warts file,
scamper records details of the list and cycle that
each measurement task belongs to.
When started with the -P option,
scamper allows inter-process communication via a TCP
socket bound to the supplied port on the local host. This socket is useful
for controlling the operation of a long-lived
scamper process. A client may interact with scamper
by using telnet(1) to open a connection to the supplied
port.
The following control socket commands are available.
exitattachscamper accepts and
replies to commands, returning results straight over the control socket.
See
ATTACH
section below for details on which commands are accepted.get
argumentset
argument ...source
argument ...add
argumentssource add command allows a new input
source to be added. It accepts the following arguments:
name
stringdescr
stringcommand
stringlist_id
uint32_tcycle_id
uint32_tpriority
uint32_toutfile
stringoutfile open. If not
supplied, the default output file is used.file
stringcycles
integerscamper will loop indefinitely over
the file. This parameter is ignored unless a managed source is
defined.autoreload
[on | off]update
name argumentssource update command allows some
properties of an existing source to be modified. The source to update
is specified with the name parameter. Valid
parameters are: autoreload, cycles, and priority.list
...source list command provides a listing of
all currently defined sources. The optional third
name parameter restricts the listing to the
source specified.cycle
namesource cycle command manually inserts a
cycle marker in an adhoc source.delete
namesource delete command deletes the named
source, if possible.outfile
argument ...open
...outfile open command allows a new output
file to be defined. It accepts the following parameters:
name
aliasfile
stringmode
[truncate |
append]close
aliasoutfile close command allows an existing
output file to be closed. The mandatory alias
parameter specifies which output file to close. An output file that is
currently referenced is not able to be closed. To close a file that is
currently referenced, a new outfile must be opened, and then the
outfile swap command be used.swap
alias1 alias2outfile swap command swaps the file
associated with each output file.listoutfile list command outputs a list of the
existing outfiles.observe
sourcesEVENT 1169065640 source add name
'foo' list_id 5 priority 1EVENT 1169065641 source update
'foo' priority 15EVENT 1169065642 source cycle
'bar' id 2EVENT 1169065650 source finish
'bar'EVENT 1169065661 source delete
'foo'shutdown
argumentscamper process
to be exited cleanly. The following arguments are supported
doneshutdown done command requests that
scamper shuts down when the current tasks, as
well as all remaining cycles, have completed.flushshutdown flush command requests that
scamper flushes all remaining tasks queued
with each list, finishes all current tasks, and then shuts down.nowshutdown now command causes
scamper to shutdown immediately. Unfinished
tasks are purged.cancelshutdown cancel command cancels any
pending shutdown.In attach mode, none of the usual interactive mode commands are
usable. Instead, commands may be entered directly and results will be sent
back directly over the control socket. Commands are specified just as they
would be with the -I flag for a command-line invocation of
scamper. Replies are split into lines by single \n
characters and have one of the following formats:
ERR
...OK
id-numscamper versions after
20110623 return an id number associated with the command, which allow the
task to be halted by subsequently issuing a "halt"
instruction.MOREDATA
lengthTo exit attached mode the client must send a single line containing "done". To halt a command that has not yet completed, issue a "halt" instruction with the id number returned when the command was accepted as the sole parameter.
To use the default traceroute command to trace the path to 192.0.2.1:
scamper -i 192.0.2.1
To infer Path MTU changes in the network and associate them with a traceroute path:
scamper -I "trace -P udp-paris -M 192.0.2.1"
To use paris traceroute with ICMP probes, using 3 probes per hop, sending all probes, writing to a specified warts file:
scamper -O warts -o file.warts -I "trace -P icmp-paris -q 3 -Q 192.0.2.1"
To ping a series of addresses defined in filename, probing each address 10 times:
scamper -c "ping -c 10" filename
Care must be taken with shell quoting when using commands with multiple levels of quoting, such as when giving a probe description with a dealias command. The following sends UDP probes to alternating IP addresses, one second apart, and requires the IP-ID values returned to be strictly in sequence.
scamper -O warts -o ally.warts -I "dealias -O inseq -W 1000 -m ally -p '-P udp -i 192.0.2.1' -p '-P udp -i 192.0.2.4'"
Alternatively, the following accomplishes the same, but without specifying the UDP probe method twice.
scamper -O warts -o ally.warts -I "dealias -O inseq -W 1000 -m ally -p '-P udp' 192.0.2.1 192.0.2.4"
The following command scans 198.51.100.0/28 for a matching alias to 192.0.2.4, but skips 198.51.100.3.
scamper -O warts -o prefixscan.warts -I "dealias -O inseq -W 1000 -m prefixscan -p '-P udp' -x 198.51.100.3 192.0.2.4 198.51.100.0/28"
The following uses UDP probes to enumerate all per-flow load-balanced paths towards 192.0.2.6 to 99% confidence; it varies the source port with each probe.
scamper -I "tracelb -P udp-sport -c 99 192.0.2.6"
ping(8), traceroute(8), libscamperfile(3), sc_ally(1), sc_analysis_dump(1), sc_attach(1), sc_ipiddump(1), sc_filterpolicy(1), sc_remoted(1), sc_speedtrap(1), sc_tbitblind(1), sc_tracediff(1), sc_uptime(1), sc_wartscat(1), sc_wartsdump(1), sc_warts2json(1), sc_warts2pcap(1), sc_warts2text(1),
S. Savage, Sting: a TCP-based Network Measurement Tool, 1999 USENIX Symposium on Internet Technologies and Systems.
R. Govindan and H. Tangmunarunkit, Heuristics for Internet Map Discovery, Proc. IEEE INFOCOM 2000.
N. Spring, R. Mahajan, and D. Wetherall, Measuring ISP topologies with Rocketfuel, Proc. ACM SIGCOMM 2002.
A. Medina, M. Allman, and S. Floyd, Measuring the evolution of transport protocols in the Internet, ACM/SIGCOMM Computer Communication Review.
M. Luckie, K. Cho, and B. Owens, Inferring and Debugging Path MTU Discovery Failures, Proc. ACM/SIGCOMM Internet Measurement Conference 2005.
B. Donnet, P. Raoult, T. Friedman, and M. Crovella, Efficient algorithms for large-scale topology discovery, Proc. ACM SIGMETRICS 2005.
B. Augustin, X. Cuvellier, B. Orgogozo, F. Viger, T. Friedman, M. Latapy, C. Magnien, and R. Teixeira, Avoiding traceroute anomalies with Paris traceroute, Proc. ACM/SIGCOMM Internet Measurement Conference 2006.
B. Augustin, T. Friedman, and R. Teixeira, Measuring Load-balanced Paths in the Internet, Proc. ACM/SIGCOMM Internet Measurement Conference 2007.
A. Bender, R. Sherwood, and N. Spring, Fixing Ally's growing pains with velocity modeling, Proc. ACM/SIGCOMM Internet Measurement Conference 2008.
M. Luckie, Scamper: a Scalable and Extensible Packet Prober for Active Measurement of the Internet, Proc. ACM/SIGCOMM Internet Measurement Conference 2010.
R. Beverly, W. Brinkmeyer, M. Luckie, and J.P. Rohrer, IPv6 Alias Resolution via Induced Fragmentation, Proc. Passive and Active Measurement Conference 2013.
M. Luckie, R. Beverly, W. Brinkmeyer, and k claffy, Speedtrap: Internet-scale IPv6 Alias Resolution, Proc. ACM/SIGCOMM Internet Measurement Conference 2013.
M. Luckie, R. Beverly, T. Wu, M. Allman, and k. claffy, Resilience of Deployed TCP to Blind Attacks, Proc. ACM/SIGCOMM Internet Measurement Conference 2015.
J. Czyz, M. Luckie, M. Allman, and M. Bailey, Don't Forget to Lock the Back Door! A Characterization of IPv6 Network Security Policy, Proc. Network and Distributed Systems Security (NDSS) Conference 2016.
M. Luckie, A. Dhamdhere, B. Huffaker, D. Clark, and k. claffy, bdrmap: Inference of Borders Between IP Networks, Proc. ACM/SIGCOMM Internet Measurement Conference 2016.
M. Luckie and R. Beverly, The Impact of Router Outages on the AS-level Internet, Proc. ACM/SIGCOMM Conference 2017.
scamper was written by Matthew Luckie
<mjl@luckie.org.nz>. Alistair King contributed an initial
implementation of Doubletree; Ben Stasiewicz contributed an initial
implementation of TBIT's PMTUD test; Stephen Eichler contributed an initial
implementation of TBIT's ECN test; Boris Pfahringer adapted
scamper to use GNU autotools, modularised the tests,
and updated this man page. Brian Hammond of Internap Network Services
Corporation provided an initial implementation of scamper's json output
format. Tiange Wu contributed an initial implementation of the blind
in-window TBIT test, and Robert Beverly contributed BGP protocol support for
TBIT.
scamper development was initially funded
by the WIDE project in association with CAIDA. Boris' work was funded by the
University of Waikato's Centre for Open Source Innovation.
| July 2, 2017 | Debian |