NAME¶
scamper —
parallel Internet measurement
utility
SYNOPSIS¶
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 port | -U unix-dom] |
DESCRIPTION¶
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 four 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. Finally,
scamper can be instructed to listen on a
port specified with the
-P option only accessible on the
local host, or on a unix domain socket specified with the
-U
option, where it can take commands dynamically.
The options are as follows:
- -?
- prints a list of command line options and a synopsis of
each.
- -v
- causes scamper to output version
information and exit.
- -D
- With this option set, scamper will detach
and become a daemon. Use with the -P or
-U options.
- -c
command
- specifies the command for scamper to use
by default. The current choices for this option are:
- dealias
- neighbourdisc
- ping
- trace
- tracelb
- sniff
- sting
- tbit
scamper uses trace by default. The available commands and
their options are documented below.
- -p
pps
- specifies the target packets-per-second rate for
scamper to reach. By default, this value is 20.
- -w
window
- specifies the maximum number of tasks that may be probed in
parallel. A value of zero places no upper limit. By default, zero is
used.
- -M
monitorname
- specifies the canonical name of machine where
scamper is run. This value is used when recording the
output in a warts output file.
- -l
listname
- specifies the name of the list when run from the command
line. This value is used when recording the output in a warts output
file.
- -L
listid
- specifies the numerical id of the list when run from the
command line. This value is used when recording the output in a warts
output file.
- -C
cycleid
- specifies the numerical cycle id to begin with when run
from the command line. This value is used when recording the output in a
warts output file.
- -o
outfile
- specifies the default output file to write measurement
results to. By default, stdout is used.
- -F
firewall
- specifies that scamper may use the firewall in measurements
that require it. To use the firewall on FreeBSD and MacOS X systems, pass
ipfw here.
- -d
debugfile
- specifies a filename to append debugging messages to. By
default, no debugfile is used, though debugging output is sent to stderr
if scamper is built for debugging.
- -e
pidfile
- specifies a file to write scamper's process ID to. If
scamper is built with privilege separation, the ID of the unprivileged
process is written.
- -O
options
- allows scamper's behaviour to be further tailored. The
current choices for this option are:
- text
output results using plain text. Suitable for interactive use.
- warts
output results to a warts binary file. Suitable for archiving
measurement results and for use by researchers as it records details
that cannot be easily represented with the text option.
- planetlab
tell scamper it is running on a planetlab system. Necessary to use
planetlab's safe raw sockets.
- rawtcp
tell scamper to use IPPROTO_RAW socket to send IPv4 TCP probes, rather
than a datalink socket.
- select
tell scamper to use select(2) rather than
poll(2)
- kqueue
tell scamper to use kqueue(2) rather than
poll(2) on systems where kqueue(2)
is available.
- epoll
tell scamper to use epoll(7) rather than
poll(2) on systems where epoll(7)
is available.
- tsps the
input file consists of a sequence of IP addresses for pre-specified IP
timestamps.
- cmdfile
the input file consists of complete commands.
- dlts use
timestamps from the datalink layer, if possible.
- copyout
write a copy of all data written by scamper with the default output
method.
- -i
IP 1..N
- specifies the addresses to probe, on the command line,
using the command specified with the -c option.
- -f
listfile
- specifies the input file to read for target addresses, one
per line, and uses the command specified with the -c
option on each.
- -I
cmds.
- specifies complete commands, including target addresses,
for scamper to execute.
- -P
port
- specifies that scamper provide a control
socket listening on the specified port on the local host.
- -U
unix domain socket
- specifies that scamper provide a control
socket listening on the specified socket in the unix domain.
TRACE OPTIONS¶
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]
[
-L loopaction]
[
-m maxttl]
[
-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
- specifies that a hop should be probed to a specified
confidence level (95% or 99%) to be sure the trace has seen all interfaces
that will reply for that hop.
- -d
dport
- specifies the base destination port value to use for
UDP-based and TCP-based traceroute methods. For ICMP-paris, this option
sets the ICMP checksum value.
- -f
firsthop
- specifies the TTL or HLIM value to begin probing with. By
default, a first hop of one is used.
- -g
gaplimit
- specifies the number of unresponsive hops permitted until a
check is made to see if the destination will respond. By default, a gap
limit of 5 hops is used. Setting the gap limit to 0 disables the gap
limit, but doing this is not recommended.
- -G
gapaction
- specifies what should happen if the gaplimit condition is
met. A value of 1 (default) means halt probing, while a value of 2 means
send last-ditch probes.
- -m
maxttl
- specifies the maximum TTL or HLIM value that will be
probed. By default, there is no restriction, apart from the 255 hops that
the Internet protocols allow.
- -M
- specifies that path MTU discovery (PMTUD) should be
attempted for the path when the initial traceroute completes.
scamper 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
- specifies the maximum number of loops permitted until
probing stops. By default, a value of one is used. A value of zero
disables loop checking.
- -L
loopaction
- specifies the action to take when a loop is encountered. A
value of 1 tells scamper to probe beyond the first loop in the trace.
- -p
payload
- specifies the payload of the probe to use as a base. The
payload is specified in hexadecimal. Note that the payload supplied is
merely a base; the first 2 bytes may be modified to accomplish ICMP-Paris
and UDP-Paris traceroute.
- -P
method
- specifies the traceroute method to use.
scamper currently supports five different probe methods:
UDP, ICMP, UDP-paris, ICMP-paris, TCP, and TCP-ACK. By default, UDP-paris
is used.
- -q
attempts
- specifies the maximum number of attempts to obtain a
response per hop. By default, a value of two is used.
- -Q
- specifies that all allocated probes are sent, regardless of
how many responses have been received.
- -s
sport
- specifies the source port value to use. For ICMP-based
methods, this option specifies the ICMP identifier to use.
- -S
srcaddr
- specifies the source address to use in probes. The address
cannot be spoofed.
- -t
tos
- specifies the value to set in the IP ToS/DSCP + ECN byte.
By default, this byte is set to zero.
- -T
- specifies that time exceeded messages from the destination
do not cause the trace to be defined as reaching the destination.
- -U
userid
- specifies an unsigned integer to include with the data
collected; the meaning of the user-id is entirely up to the user and has
no effect on the behaviour of traceroute.
- -w
wait
- specifies how long to wait, in seconds, for a reply. By
default, a value of 5 is used.
- -W
wait-probe
- specifies the minimum time to wait, in 10s of milliseconds,
between sending consecutive probes. By default the next probe is sent as
soon as possible.
- -z
gss-entry
- specifies an IP address to halt probing when encountered;
used with the double-tree algorithm.
- -Z
lss-name
- specifies the name of the local stop set to use when
determining when to halt probing backwards; used with the double-tree
algorithm.
PING OPTIONS¶
The 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]
[
-o replycount]
[
-O options]
[
-p pattern]
[
-P method]
[
-U userid]
[
-s size]
[
-S srcaddr]
[
-T timestamp]
[
-z tos]
- -B
payload
- specifies, in a hexadecimal string, the payload to include
in each probe.
- -c
probecount
- specifies the number of probes to send before exiting. By
default, a value of 4 is used.
- -C
icmp-sum
- specifies the ICMP checksum to use when sending a probe.
The payload of each probe will be manipulated so that the checksum is
valid.
- -d
dport
- specifies the destination port to use in each TCP/UDP
probe.
- -F
sport
- specifies the source port to use in each TCP/UDP probe, and
the ICMP ID to use in ICMP echo probes.
- -i
wait
- specifies the length of time to wait, in seconds, between
probes. By default, a value of 1 is used.
- -m
ttl
- specifies the TTL value to use for outgoing packets. By
default, a value of 64 is used.
- -o
replycount
- specifies the number of replies required at which time
probing may cease. By default, all probes are sent.
- -O
options
- The current choices for this option are:
- spoof
specifies that the source address is to be spoofed according to the
address specified with the -S option. The address
scamper would otherwise use as the source address is embedded in the
payload of the probe.
- -p
pattern
- specifies the pattern, in hex, to use in probes. Up to 16
bytes may be specified. By default, each probe's bytes are zeroed.
- -P
method
- specifies the type of ping packets to send. By default,
ICMP echo requests are sent. Choices are: icmp-echo, tcp-ack,
tcp-ack-sport, udp, and udp-dport.
- -U
userid
- specifies an unsigned integer to include with the data
collected; the meaning of the user-id is entirely up to the user and has
no effect on the behaviour of ping.
- -R
- specifies that the record route IP option should be
used.
- -s
size
- specifies the size of the probes to send. The probe size
includes the length of the IP and ICMP headers. By default, a probe size
of 84 bytes is used for IPv4 pings, and 56 bytes for IPv6 pings.
- -S
srcaddr
- specifies the source address to use in probes. The address
can be spoofed if -O spoof is included.
- -T
timestamp
- specifies that an IP timestamp option be included. The
timestamp option can either be: tsprespec where IP addresses of devices of
interest can be specified; tsonly, where timestamps are embedded by
devices but no IP addresses are included; and tsandaddr, where timestamps
and IP addresses are included by devices in the path. See the examples
section for more information.
- -z
tos
- specifies the value to use in the IPv4 ToS/DSCP + ECN byte.
By default, this byte is set to zero.
DEALIAS OPTIONS¶
The 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
- specifies the destination port to use when sending probes.
Only valid for the mercator technique; destination ports can be specified
in probedefs defined with -p for other alias resolution
methods.
- -f
fudge
- specifies a fudge factor for alias matching. Defaults to
200. Only valid for ally and bump.
- -m
method
- specifies which method to use for alias resolution. Valid
options are: ally, bump, mercator, prefixscan, and radargun.
- -o
replyc
- specifies how many replies to wait for. Only valid for
prefixscan.
- -O
option
- allows alias resolution behaviour to be further tailored.
The current choices for this option are:
- inseq
where IP-ID values are required to be strictly in sequence (with no
tolerance for packet reordering)
- shuffle
randomise the order of probes sent each round; only valid for radargun
probing.
- nobs do
not allow for byte swapped IP-ID values in responses. Valid for ally
and prefixscan.
- -p
probedef
- specifies a definition for a probe. Possible options are:
- -c
sum
- specifies what ICMP checksum to use for ICMP probes.
The payload of the probe will be altered appropriately.
- -d
dst-port
- specifies the destination port of the probe. Defaults
to 33435.
- -i
IP
- specifies the destination IP address of the probe.
- -P
method
- specifies which method to use for the probe. Valid
options are: udp, udp-dport, tcp-ack, tcp-ack-sport, tcp-syn-sport,
and icmp-echo.
- -s
src-port
- specifies the source port of the probe. Defaults to
(pid & 0x7fff) + 0x8000.
- -t
ttl
- specifies the IP time to live of the probe.
The ally method accepts up to two probe definitions; the prefixscan method
expects one probe definition; radargun expects at least one probe
definition; bump expects two probe definitions.
- -q
attempts
- specifies how many times a probe should be retried if it
does not obtain a useful response.
- -r
wait-round
- specifies how many milliseconds to wait between probing
rounds with radargun.
- -s
sport
- specifies the source port to use when sending probes. Only
valid for mercator.
- -t
ttl
- specifies the time-to-live of probes sent. Only valid for
mercator.
- -U
userid
- specifies an unsigned integer to include with the data
collected; the meaning of the user-id is entirely up to the user and has
no effect on the behaviour of dealias.
- -w
wait-timeout
- specifies how long to wait in milliseconds for a reply from
the remote host.
- -W
wait-probe
- specifies how long to wait in milliseconds between
probes.
- -x
exclude
- specifies an IP address to exclude when using the
prefixscan method. May be specified multiple times to exclude multiple
addresses.
NEIGHBOUR DISCOVERY OPTIONS¶
The 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
availible for the
scamper neighbourdisc command:
neighbourdisc [
-FQ]
[
-i interface]
[
-o reply-count]
[
-q attempts]
[
-w wait]
- -F
- specifies that we only want the first response.
- -Q
- specifies that we want to send all attempts.
- -i
interface
- specifies the name of the interface to use for neighbour
discovery.
- -o
reply-count
- specifies how many replies we wait for.
- -q
attempts
- specifies how many probes we send out.
- -w
wait
- specifies how long to wait between probes in milliseconds.
Defaults to 1000.
TBIT OPTIONS¶
The 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, and respond to Explicit Congestion Notification.
The following options are available for the
scamper tbit
command:
tbit
[
-t type]
[
-p app]
[
-d dport]
[
-s sport]
[
-m mss]
[
-M mtu]
[
-O option]
[
-P ptbsrc]
[
-S srcaddr]
[
-u url]
- -t
type
- specifies which type of testing to use. Valid options are:
pmtud, ecn, null, sack-rcvr.
- -p
app
- specifies what kind of traffic to generate for testing.
Destination port defaults the application standard port. Valid
applications are: smtp, http, dns, ftp.
- -d
dport
- specifies the destination port for the packets being sent.
Defaults are application-specific.
- -s
sport
- specifies the source port for the packets being sent.
Default is based of the scamper process id.
- -m
mss
- specifies the maximum segment size to advertise to the
remote host.
- -M
mtu
- specifies the MTU to use in a Packet Too Big message.
- -O
option
- allows tbit behaviour to be further tailored. The current
choice for this option is:
- blackhole
for PMTUD testing, do not send Packet Too Big messages; this tests to
ability of a host to infer a PMTUD blackhole and work around it.
- -P
ptbsrc
- specifies the source address that should be used to send
Packet Too Big messages in the pmtud test.
- -S
srcaddr
- specifies the source address that should be used in TCP
packets sent by the tbit test.
- -u
url
- specifies a url for the http application.
TRACELB OPTIONS¶
The 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
- specifies the level of confidence we want to attain that
there are no more parallel load balanced paths at a given hop. Valid
values are 95 (default) and 99, for 95% confidence and 99% confidence
respectively.
- -d
dport
- specifies the base destination port to use. Defaults to
33435, the default used by traceroute(8).
- -f
firsthop
- specifies how many hops away we should start probing.
- -g
gaplimit
- specifies how many consecutive unresponsive hops are
permitted before probing down a branch halts. Defaults to three.
- -P
method
- specifies which method we should use to do the probing.
Valid options are: "udp-dport", "icmp-echo",
"udp-sport", "tcp-sport", and
"tcp-ack-sport". Defaults to "udp-dport".
- -q
attempts
- specifies how many probes we should send in an attempt to
receive a reply. Defaults to 2.
- -Q
maxprobec
- specifies the maximum number of probes we ever want to
send. Defaults to 3000.
- -s
sport
- specfies to the source port to use when sending probes.
Default based on process ID.
- -t
tos
- specifies the value for the IP Type-of-service field for
outgoing probes. Defaults to 0.
- -U
userid
- specifies an unsigned integer to include with the data
collected; the meaning of the user-id is entirely up to the user and has
no effect on the behaviour of tracelb.
- -w
wait-timeout
- specifies in seconds how long to wait for a reply to a
probe. Defaults to 5.
- -W
wait-probe
- specifies in 1/100ths of seconds how long to wait between
probes. Defaults to 25 (i.e. 250ms).
STING OPTIONS¶
The 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
- specifies the number of samples to make. By default 48
samples are sent, as this value is the current default of the FreeBSD TCP
reassembly queue length. Sting 0.7 uses 100 samples.
- -d
dport
- specifies the base destination port to use. Defaults to 80,
the default port used by the HTTP protocol.
- -f
distribution
- specifies the delay distribution of samples. By default a
uniform distribution is constructed. Other distributions are currently not
implemented in scamper's implementation of sting.
- -h
request
- specifies the default request to make. Currently not
implemented.
- -H
hole
- specifies the size of the initial hole left in the request.
The default is 3 bytes, the same as sting-0.7.
- -i
inter
- specifies the inter-phase delay between data seeding and
hole filling, in milliseconds. By default, sting waits 2000ms between
phases.
- -m
mean
- specifies the mean rate to send packets in the data phase,
in milliseconds. By default, sting waits 100ms between probes.
- -s
sport
- specfies to the source port to use when sending probes.
Default is based on the process ID.
SNIFF OPTIONS¶
The 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
- specifies the maximum number of packets to capture.
- -G
limit-time
- specifies the maximum time, in seconds, to capture
packets.
- -S
ipaddr
- specifies the IP address that packets must arrive using.
scamper uses the IP address to identify the appropriate interface to
listen for packets.
- -U
userid
- specifies an unsigned integer to include with the data
collected; the meaning of the user-id is entirely up to the user and has
no effect on the behaviour of sniff.
The sole supported expression is icmp[icmpid] == X, where X is the ICMP-ID to
select.
DATA COLLECTION FEATURES¶
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.
CONTROL SOCKET¶
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.
- exit
- The exit command closes the current control socket
connection.
- attach
- The attach command changes how scamper
accepts and replies to commands, returning results straight over the
control socket. See ATTACH section below for details on
which commands are accepted.
- get
argument
- The get command returns the current setting for the
supplied argument. Valid argument values are: holdtime, monitorname, pid,
pps, sport, version.
- set
argument ...
- The set command sets the current setting for the supplied
argument. Valid argument values are: holdtime, monitorname, pps.
- source
argument ...
-
- add
arguments
- The source add command allows a new
input source to be added. It accepts the following arguments:
- name
string
- The name of the source. This parameter is
mandatory.
- descr
string
- An optional string describing the source.
- command
string
- The command to execute for each address supplied.
If not supplied, the default command is used.
- list_id
uint32_t
- An optional numeric list identifier, assigned by a
human. If not supplied, a value of zero is used.
- cycle_id
uint32_t
- An optional numeric initial cycle identifier to
use, assigned by a human. If not supplied, a value of one is
used.
- priority
uint32_t
- An optional numeric value that specifies the mix
rate of measurements from the source compared to other sources. If
not supplied, a mix rate of one is used. A value of zero causes
the source to be created, but not actively used.
- outfile
string
- The name of the output file to write results to,
previously defined with outfile open. If not
supplied, the default output file is used.
- file
string
- The name of the input file to read target addresses
from. This parameter is mandatory if the source is a managed
source.
- cycles
integer
- The number of cycles to make over the target
address file. If zero, scamper will loop
indefinitely over the file. This parameter is ignored unless a
managed source is defined.
- autoreload
[on |
off]
- This parameter specifies if the target address file
should be re-read whenever a cycle is completed, or if the same
set of target addresses as the previous cycle should be used. If
not specified, the file is not automatically reloaded at cycle
time.
- update
name arguments
- The source 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
...
- The source list command provides a
listing of all currently defined sources. The optional third
name parameter restricts the listing to the
source specified.
- cycle
name
- The source cycle command manually
inserts a cycle marker in an adhoc source.
- delete
name
- The source delete command deletes the
named source, if possible.
- outfile
argument ...
- The outfile commands provide the ability to manage output
files. It accepts the following arguments:
- open
...
- The outfile open command allows a new
output file to be defined. It accepts the following parameters:
- name
alias
- The alias of the output file. This parameter is
mandatory.
- file
string
- The filename of the output file. This parameter is
mandatory.
- mode
[truncate |
append]
- How the file will be opened. If the append mode is
used, any existing file with the specified name will be appended
to. If the truncate mode is used, any existing file will be
truncated when it is opened.
- close
alias
- The outfile 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 alias2
- The outfile swap command swaps the
file associated with each output file.
- list
- The outfile list command outputs a
list of the existing outfiles.
- observe
sources
- This command allows for monitoring of source events. When
executed, the control socket will then supply event notices whenever a
source is added, updated, deleted, finished, or cycled. Each event is
prefixed with a count of the number of seconds elapsed since the Unix
epoch. The following examples illustrate the event monitoring
capabilities:
EVENT 1169065640 source add name 'foo'
list_id 5 priority 1
EVENT 1169065641 source update 'foo'
priority 15
EVENT 1169065642 source cycle 'bar' id
2
EVENT 1169065650 source finish
'bar'
EVENT 1169065661 source delete
'foo'
- shutdown
argument
- The shutdown argument allows the scamper
process to be exited cleanly. The following arguments are supported
- done
- The shutdown done command requests
that scamper shuts down when the current tasks, as
well as all remaining cycles, have completed.
- flush
- The shutdown flush command requests
that scamper flushes all remaining tasks queued with
each list, finishes all current tasks, and then shuts down.
- now
- The shutdown now command causes
scamper to shutdown immediately. Unfinished tasks
are purged.
- cancel
- The shutdown cancel command cancels
any pending shutdown.
ATTACH MODE¶
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
...
- A line staring with the 3 characters "ERR"
indicate an error has occured. The rest of the line will contain an error
message.
- OK
id-num
- A line with the 2 characters "OK" indicates that
scamper has accepted the command. scamper versions after
20110623 return an id number associated with the command, which allow the
task to be halted by subsequently issuing a "halt"
instruction.
- MORE
- A line with just the 4 characters "MORE"
indicates that scamper has the capacity to accept more probing commands to
run in parallel.
- DATA
length
- A line starting with the 4 characters "DATA"
follow by a space then a base-10 number indicates the start of result.
length specifies the number of characters of the
data, including newlines. The data is in binary warts format and uuencoded
before transmission.
To 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.
EXAMPLES¶
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"
SEE ALSO¶
ping(8),
traceroute(8),
libscamperfile(3),
sc_ally(1),
sc_analysis_dump(1),
sc_attach(1),
sc_tracediff(1),
sc_wartscat(1),
sc_wartsdump(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, Proc. ACM/SIGCOMM Internet Measurement
Conference 2004.
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.
AUTHORS¶
scamper is 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.
ACKNOWLEDGEMENTS¶
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.