SCAMPER(1)

📦
this version · 3 versions
, in debian bookworm, debian trixie, ubuntu noble, ubuntu questing, ubuntu resolute, ubuntu stonking

🎀 SCAMPER 🎀 — the manual page, bestie edition

okay so you've stumbled into the scamper(1) page, and honestly? it's giving parallel Internet measurement utility, which is exactly what it is. this lives in the General Commands Manual, and it's a big one, so grab a snack 🍓

✨ 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] [-n nameserver] [-d debugfile] [-e pidfile]
        [-O options]
        [-i IPs | -I cmds | -f file | -P [ip:]port | -R name:port | -U unix-dom]

✨ DESCRIPTION ✨

so like, what is scamper? bestie. it's a utility that runs Internet measurement techniques against IPv4 and IPv6 addresses, in parallel, filling a packets-per-second rate that you specify. it's the main character of network measurement tools, no cap 👑

right now scamper supports the well-known traceroute and ping techniques, DNS, and also MDA traceroute, alias resolution, some parts of tbit, sting, and neighbour discovery. it ate and left no crumbs 💅

scamper has five modes of operation, and this is the part where you pay attention:

  1. you hand it a list of one or more addresses on the command line with the -i option. scamper then executes a command with each of the supplied addresses, in parallel, and outputs the results as each task completes.
  2. you hand it a list of one or more addresses in a listfile, one address per line, using the -f option.
  3. you hand it a list of one or more complete commands on the command line with the -I option.
  4. you tell scamper to listen on an IP address and port given with the -P option, or on a unix domain socket given with the -U option, where it can take commands dynamically.
  5. you tell scamper to connect to a remote host and port given with the -R option, where it will be supplied with commands dynamically.
⚠️ heads up: for most modules, scamper must be run as root. like, it's not being dramatic, it literally needs the permissions.

the options are as follows 🫶

✨ OPTIONS ✨

  • -? — prints a list of command line options and a synopsis of each. your little help menu bestie 🥺
  • -v — causes scamper to output version information and exit. bye! 👋
  • -D — with this option set, scamper will detach and become a daemon. use with the -P or -U options. (main character energy: it leaves the room and keeps working behind the scenes)
  • -c command — specifies the command for scamper to use by default. the current choices for this option are:
    • dealias: use Ally, Mercator, or Radargun-style probing to infer which IP addresses belong to the same system.
    • host: issue simple DNS queries to a domain name server.
    • neighbourdisc: issue an IPv4 ARP or IPv6 Neighbour discovery query to determine the layer-2 address of an IP address on the same network.
    • ping: conduct simple delay measurements with various probe types.
    • trace: conduct classic and Paris-style traceroute probing, which infers a single path towards a destination.
    • tracelb: use the multipath discovery algorithm (MDA) to infer the presence of load-balanced paths towards a destination.
    • sniff: capture a subset of packets arriving at the host using a subset of tcpdump-style filter expressions.
    • sting: use the sting method to infer one-way packet loss with a TCP receiver.
    • tbit: use techniques from the TCP behavior inference tool (TBIT) to infer properties of a TCP receiver.

scamper uses trace by default. the options for each of these commands are documented in their own sections of this manual page — so yes, there's more, keep scrolling 🌈

  • -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. (unhinged? maybe. iconic? absolutely.)
  • -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 (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.
  • -n nameserver — specifies the nameserver for scamper to use. by default, scamper uses the first nameserver specified in /etc/resolv.conf
  • -d debugfile — specifies a filename to write 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 options are case insensitive. the current choices for this option are:
    • text: output results in plain text. suitable for interactive use.
    • warts: output results in warts format. suitable for archiving measurement results and for use by researchers as it records details that cannot be easily represented with the text option.
    • json: output results in json format. suitable for processing measurement results with a scripting language. a better approach is to output results in warts format, and to use sc_warts2json(1).
    • 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.
    • ICMP-rxerr: tell scamper to use IP_RECVERR or IPV6_RECVERR to receive ICMP responses, rather than raw sockets. this is useful on Linux systems that have these sockets, and scamper does not have the permissions to obtain a raw socket. this option currently only works with the trace command.
    • 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.
    • noinitndc: do not initialise the neighbour discovery cache.
    • outcopy: write a copy of all data written by scamper with the default output method.
    • debugfileappend: append to the debugfile specified with the -d option. the default is to truncate the debugfile.
    • notls-remote: do not use TLS when establishing a connection with the remove controller specified with the -R option.
    • notls: do not use TLS anywhere in scamper, including tbit.
  • -i IP 1..N — specifies a list of one or more 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 a list of one or more complete commands, including target addresses, for scamper to execute.
  • -P [ip:]port — specifies that scamper 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:port — specifies that scamper connects to a specified remote host and port to receive commands.
  • -U unix domain socket — specifies that scamper provide a control socket listening on the specified socket in the unix domain.

✨ TRACE OPTIONS ✨

okay so the trace command is your classic glow-up moment for traceroute-style probing — both the classic kind and the Paris-style kind, which together infer a single path towards a destination 🛤️✨. here are all the lil variations of the traceroute(8) options you get to play with:

trace [-MQT] [-c confidence] [-d dport] [-f firsthop] [-g gaplimit]
[-G gapaction] [-l loops] [-m maxttl] [-N squeries] [-o offset]
[-O option] [-p payload] [-P method] [-q attempts] [-r rtraddr]
[-s sport] [-S srcaddr] [-t tos] [-U userid] [-w wait] [-W wait-probe]
[-z gss-entry] [-Z lss-name]
  • -c confidence — says a hop should be probed up to a specified confidence level (95% or 99%) so you can be sure the trace has seen every interface that'll reply for that hop. no guessing, bestie 💅
  • -d dport — the base destination port value for UDP-based and TCP-based traceroute methods. and plot twist: for ICMP-Paris, this option sets the ICMP checksum value instead 🫶
  • -f firsthop — the TTL or HLIM value to start probing with. by default, a first hop of one is used. starting at the top, as you should ✨
  • -g gaplimit — how many unresponsive hops are allowed before a check happens to see if the destination will respond. default is a gap limit of 5 hops. setting it to 0 disables the gap limit entirely…
⚠️ …but doing that is not recommended, bestie. scamper said what it said.
  • -G gapaction — what happens when the gaplimit condition gets met. a value of 1 (default) means halt probing; a value of 2 means send last-ditch probes 🚨
  • -l loops — max number of loops allowed before probing stops. default is one, and a value of zero disables loop checking. zero chill, literally 🔁
  • -m maxttl — the max TTL or HLIM value that'll be probed. by default there's no restriction, other than the 255 hops the Internet protocols allow 🌈
  • -M — asks for path MTU discovery (PMTUD) to be attempted for the path once the initial traceroute completes. heads up tho: scamper will not do PMTUD unless it's probing a responsive destination, because otherwise there's no way to tell "all packets are lost" apart from "just the big packets (larger than MTU) are lost" 😭
  • -N squeries — the number of consecutive hops that may have an outstanding probe. by default, only one hop may have an outstanding probe. bumping this number makes traceroutes finish faster, but at the cost of sending unnecessary probes. also the number of outstanding probes must be less than the gaplimit 👑
  • -o offset — the fragmentation offset to use in probes. by default, no offset is used.
  • -O option — optional arguments to use. the current choices are:
    • dl: says the datalink socket should be used to timestamp packets, and to receive certain packets.
    • dtree-noback: says the traceroute should not do backwards probing when using doubletree.
    • ptr: lookup hostnames for intermediate traceroute hops. so you get names instead of just numbers 🎀
  • -p payload — the payload of the probe to use as a base, specified in hexadecimal. note that the payload you hand over is merely a base; the first 2 bytes may get modified to accomplish ICMP-Paris and UDP-Paris traceroute 👀
  • -P method — the traceroute method to use. scamper currently supports five different probe methods: UDP, ICMP, UDP-Paris, ICMP-Paris, TCP, and TCP-ACK. (yes we know that's six names, we're just reading the page, bestie 😭) also note: scamper uses UDP-Paris by default, and these options are case insensitive.
  • -q attempts — max number of attempts to get a response per hop. default is two.
  • -Q — send all allocated probes, no matter how many responses came back. all of them. every single one 🔥
  • -r rtraddr — the IP address of the router to use.
  • -s sport — the source port value to use. for ICMP-based methods, this option specifies the ICMP identifier instead.
  • -S srcaddr — the source address to use in probes. and no, you cannot spoof this address, don't even try 💀
  • -t tos — the value to set in the IP ToS/DSCP + ECN byte. by default this byte is set to zero.
  • -T — says that time exceeded messages coming from the destination do not cause the trace to be defined as reaching the destination. rude, honestly.
  • -U userid — an unsigned integer to include with the data collected. the meaning of the user-id is entirely up to you and has zero effect on how traceroute behaves 🫶
  • -w wait — how long to wait, in seconds, for a reply. default is 5.
  • -W wait-probe — the minimum time to wait, in 10s of milliseconds, between sending consecutive probes. by default the next probe goes out as soon as possible ⚡
  • -z gss-entry — an IP address to halt probing when encountered; used with the double-tree algorithm.
  • -Z lss-name — the name of the local stop set to use when deciding when to halt probing backwards; used with the double-tree algorithm.

🌸 PING OPTIONS 🌸

and now for the ping command!! it's for simple delay measurements with a whole menu of probe types. here are the variations of the ping(8) options available to you:

ping [-R] [-A TCP-ack] [-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] [-r rtraddr] [-s size]
[-S srcaddr] [-T timestamp] [-U userid] [-W timeout] [-z tos]
  • -A TCP-ack — the number to use in the acknowledgement field of the TCP header, or the sequence number field of the TCP header when sending reset probes.
  • -B payload — the payload to include in each probe, as a hexadecimal string.
  • -c probecount — how many probes to send before exiting. default is 4.
  • -C ICMP-sum — the ICMP checksum to use when sending a probe. the payload of each probe gets manipulated so that the checksum is valid. sneaky but legal ✨
  • -d dport — the destination port to use in each TCP/UDP probe, and the first ICMP sequence number to use in ICMP probes.
  • -F sport — the source port to use in each TCP/UDP probe, and the ICMP ID to use in ICMP probes.
  • -i wait — how long to wait, in seconds, between probes. default is 1.
  • -m ttl — the TTL value to use for outgoing packets. default is 64.
  • -M MTU — a pseudo MTU value. if the response packet is larger than the pseudo MTU, an ICMP packet too big (PTB) message is sent 📦
  • -o replycount — the number of replies required before probing may cease. by default, all probes are sent.
  • -O options — the current choices for this option are:
    • dl: says the ping should use datalink sockets rather than raw sockets.
    • nosrc: says the real address of the host should not be embedded in the payload of the packet when the spoof option is used.
    • spoof: says the source address is to be spoofed according to the address given with the -S option. the address scamper would otherwise use as the source address gets embedded in the payload of the probe — unless nosrc is used.
    • tbt: says the goal of the ping is to get fragmented responses, so the -c option specifies how many packets to send, and the -o option specifies how many fragmented responses are wanted 🧩
  • -p pattern — 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 — the type of ping packets to send. by default, ICMP echo requests are sent. choices are: ICMP-echo, ICMP-time, TCP-syn, TCP-ack, TCP-ack-sport, TCP-synack, TCP-rst, UDP, and UDP-dport, and these options are case insensitive 👑
  • -r rtraddr — the IP address of the router to use.
  • -R — says the record route IP option should be used.
  • -s size — 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 — the source address to use in probes. this address can be spoofed if -O spoof is included 👀
  • -T timestamp — says an IP timestamp option should be included. the timestamp option can be either: 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 info 🕰️
  • -U userid — an unsigned integer to include with the data collected. the meaning of the user-id is entirely up to you and has no effect on how ping behaves.
  • -W timeout — how long to wait for responses after the last ping is sent. by default this is one second.
  • -z tos — the value to use in the IPv4 ToS/DSCP + ECN byte. by default this byte is set to zero.

💅 DEALIAS OPTIONS 💅

Okay bestie, the dealias command is the one where we go hunting for aliases — like, when one router is out here living a double life with multiple IP addresses and we gotta prove it's the same icon. 🕵️‍♀️✨

Here's the tea on the five techniques:

  • mercator — aliases get inferred when a router uses a different address while sending an ICMP response. Sneaky little shapeshifter.
  • ally — you send a sequence of probes to alternating IP addresses, and if the responses come back with IP-ID values that are incrementing and interleaved? Yeah. Same router. Caught. 💀
  • radargun — you fire probes at a whole set of IP addresses over multiple rounds, then post-process the results to figure out the aliases.
  • prefixscan — you go searching inside a prefix for one specific IP address.
  • bump — you take two addresses you believe are aliases and probe them to try and force their IP-ID values out of sequence. Aggressive. Iconic.

Here's every option 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 — picks the destination port to use when sending probes. Only valid for the mercator technique btw — for the other alias resolution methods you specify destination ports in probedefs defined with -p.
  • -f fudge — sets a fudge factor for alias matching. Defaults to 200. Only valid for ally and bump.
  • -m method — tells scamper which method to use for alias resolution. The valid options are: ally, bump, mercator, prefixscan, and radargun. And yes, these are case insensitive, so live your truth. 🌈
  • -o replyc — how many replies to wait for. Only valid for prefixscan.
  • -O option — lets you tailor alias resolution behaviour even further. Current choices:
    • inseq — IP-ID values are required to be strictly in sequence, with zero tolerance for packet reordering. No chill whatsoever.
    • shuffle — randomises 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 — sets a definition for a probe. Possible options inside it are:
    • -c sum — specifies what ICMP checksum to use for ICMP probes. The payload of the probe gets altered appropriately to make that happen.
    • -d dst-port — the destination port of the probe. Defaults to 33435.
    • -F src-port — the source port of the probe. Defaults to (pid & 0x7fff) + 0x8000.
    • -i IP — the destination IP address of the probe.
    • -M mtu — the pseudo MTU to use when soliciting fragmented responses.
    • -P method — which method to use for the probe. Valid options are: UDP, UDP-dport, TCP-ack, TCP-ack-sport, TCP-syn-sport, and ICMP-echo. Case insensitive, as always. 💅
    • -s size — the size of the probes to send.
    • -t ttl — the IP time to live of the probe.

Now, how many probedefs does each method want? Bestie, it varies:

  • ally accepts up to two probe definitions
  • prefixscan expects one probe definition
  • radargun expects at least one probe definition
  • bump expects two probe definitions
  • -q attempts — how many times a probe should be retried if it doesn't get a useful response. Persistence, queen. 🫶
  • -r wait-round — how many milliseconds to wait between probing rounds with radargun.
  • -s sport — the source port to use when sending probes. Only valid for mercator.
  • -t ttl — the time-to-live of probes sent. Only valid for mercator.
  • -U userid — an unsigned integer to include with the data collected. The meaning of the user-id is entirely up to you and has zero effect on the behaviour of dealias.
  • -w wait-timeout — how long to wait, in seconds, for a reply from the remote host.
  • -W wait-probe — how long to wait, in milliseconds, between probes.
  • -x exclude — an IP address to exclude when using the prefixscan method. You can specify this multiple times to exclude multiple addresses. ✨

🎀 HOST OPTIONS 🎀

The host command can issue requests to a domain name server. Here's what's available for the scamper host command:

host [-r] [-R retry-count] [-s server-ip] [-t type] [-U userid]
[-W wait]
  • -r — says this query is a non-recursive query. The default is to issue a recursive query.
  • -R retry-count — the number of retries. Default is to send one retry.
  • -s server-ip — the IP address of the name server to query instead of the default nameserver. 👑
  • -t type — the DNS query type. The type argument can be one of: A, AAAA, PTR, and MX. The default is A if a name is queried, or a PTR if an IP address is queried.
  • -U userid — an unsigned integer to include with the data collected. The meaning of the user-id is entirely up to you and has no effect on the behaviour of host.
  • -W wait — the number of seconds to wait for a response. Default is to wait for five seconds.

🦋 NEIGHBOUR DISCOVERY OPTIONS 🦋

The neighbourdisc command tries to find the layer-2 address of a given IP address, using IPv4 ARP or IPv6 Neighbour Discovery. Like, who is this at the MAC address level? 👀

Here's what's available for the scamper neighbourdisc command:

neighbourdisc [-FQ] [-i interface] [-o reply-count] [-q attempts]
[-w wait]
  • -F — says we only want the first response. One and done, no waiting around.
  • -Q — says we want to send all attempts. All of them. Every last one. 😤
  • -i interface — the name of the interface to use for neighbour discovery.
  • -o reply-count — how many replies we wait for.
  • -q attempts — how many probes we send out.
  • -w wait — how long to wait between probes, in milliseconds. Defaults to 1000.

💅 TBIT OPTIONS 💅

The tbit command is here to spill all the tea on how a host does TCP — like, we're literally inferring TCP behaviour of a specified host. Right now it runs tests to check: can the host respond to ICMP Packet Too Big messages, can it respond to Explicit Congestion Notification, how does it do with Selective Acknowledgement behaviour, what's its Initial Congestion Window, and how resilient is it to Blind Attacks. Obsessed, honestly. 💖

Here's what you can throw at 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 — picks which type of testing we're doing. Valid options are: pmtud, ecn, null, sack-rcvr, icw, abc, blind-rst, blind-syn, blind-data. Pick your fighter bestie ✨
  • -p app — says what kind of traffic to generate for testing. The destination port defaults to the application standard port. Valid applications are: http, bgp.
  • -d dport — the destination port for the packets being sent. Defaults are application-specific.
  • -s sport — the source port for the packets being sent. Default is based of the scamper process id.
  • -a acks — the sequence of packets that should be acknowledged as part of the ABC test.
  • -b ASN — the autonomous system number (ASN) that should be used when establishing a BGP session.
  • -i ICW — the initial congestion window (ICW) that we expect from the peer when conducting the ABC test.
  • -f cookie — the TCP fast open cookie that should be used when establishing a TCP connection.
  • -L limit — test the response to a theoretical limit (L) value with ABC.
  • -m mss — the maximum segment size to advertise to the remote host.
  • -M mtu — the MTU to use in a Packet Too Big message.
  • -o offset — the sequence number offset to use when conducting blind-syn and blind-rst tests, and the acknowledgement number offset to use when conducting a blind-data test.
  • -O option — lets tbit behaviour be further tailored. The current choices for this option are:
    • 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.
    • tcpts: advertise support for TCP timestamps when establishing a TCP connection. If the peer supports TCP timestamps, embed timestamps in data packets.
    • ipts-syn: use the timestamp IP option in a SYN packet when attempting to establish a TCP connection.
    • iprr-syn: use the record-route IP option in a SYN packet when attempting to establish a TCP connection.
    • ipqs-syn: use the quick-start IP option in a SYN packet when attempting to establish a TCP connection.
    • sack: advertise support for TCP selective acknowledgements (SACK) when establishing a TCP connection.
    • fo: advertise support for TCP fast open using the official IANA number assigned for fast open.
    • fo-exp: advertise support for TCP fast open using the testing number assigned by IANA for fast open.
  • -P ptbsrc — the source address that should be used to send Packet Too Big messages in the pmtud test.
  • -q attempts — the number of attempts to make with each packet to reduce false inferences caused by packet loss.
  • -S srcaddr — the source address that should be used in TCP packets sent by the tbit test.
  • -T ttl — the IP time-to-live value that should be used in TCP packets sent by the tbit test.
  • -u url — a url to use when using the http application method. If the url starts with https, the tbit test begins with a TLS handshake. 🔒
  • -U userid — 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 tbit.
  • -w wscale — the window scale option to use when establishing the TCP connection.

🌈 TRACELB OPTIONS 🌈

The tracelb command is the one that infers all per-flow load-balanced paths between a source and destination, using the multipath discovery algorithm (MDA). It's giving main character energy fr fr. Here's what you can use with scamper tracelb:

tracelb [-c confidence] [-d dport] [-f firsthop] [-g gaplimit]
[-O option] [-P method] [-q attempts] [-r rtraddr] [-Q maxprobec]
[-s sport] [-t tos] [-U userid] [-w wait-timeout] [-W wait-probe]
  • -c confidence — 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 — the base destination port to use. Defaults to 33435, the default used by traceroute(8).
  • -f firsthop — how many hops away we should start probing.
  • -g gaplimit — how many consecutive unresponsive hops are permitted before probing down a branch halts. Defaults to three.
  • -O option — lets tracelb behaviour be further tailored. The current choices for this option are:
    • ptr: do Domain Name System pointer (PTR) record lookups for IP addresses.
  • -P method — which method we should use to do the probing. Valid options are: UDP-dport, ICMP-echo, UDP-sport, TCP-sport, and TCP-ack-sport. Note: scamper uses UDP-dport by default, and these options are case insensitive.
  • -q attempts — how many probes we should send in an attempt to receive a reply. Defaults to 2.
  • -Q maxprobec — the maximum number of probes we ever want to send. Defaults to 3000.
  • -r rtraddr — the IP address of the router to use.
  • -s sport — the source port to use when sending probes. Default based on process ID.
  • -t tos — the value for the IP Type-of-service field for outgoing probes. Defaults to 0.
  • -U userid — 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 — in seconds, how long to wait for a reply to a probe. Defaults to 5.
  • -W wait-probe — in 1/100ths of seconds, how long to wait between probes. Defaults to 25 (i.e. 250ms).

🦋 STING OPTIONS 🦋

The sting command infers one-way loss using an algorithm with TCP probes. Heads up: it requires the firewall be enabled in scamper using the -F option. Don't skip that bestie. Here's what scamper sting gives you:

sting [-c count] [-d dport] [-f distribution] [-h request] [-H hole]
[-i inter] [-m mean] [-s sport]
  • -c count — 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 — the base destination port to use. Defaults to 80, the default port used by the HTTP protocol.
  • -f distribution — 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 — the default request to make. Currently not implemented.
  • -H hole — the size of the initial hole left in the request. The default is 3 bytes, the same as sting-0.7.
  • -i inter — the inter-phase delay between data seeding and hole filling, in milliseconds. By default, sting waits 2000ms between phases.
  • -m mean — the mean rate to send packets in the data phase, in milliseconds. By default, sting waits 100ms between probes.
  • -s sport — the source port to use when sending probes. Default is based on the process ID.

🎀 SNIFF OPTIONS 🎀

The sniff command captures 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. Here's what scamper sniff is working with:

sting [-c limit-pktc] [-G limit-time] [-S ipaddr] [-U userid]
<expression>
Okay so yes, the synopsis up there says sting and not sniff — that's literally what the original page says, so we're keeping it exactly as-is. Not me fixing it. 💀
  • -c limit-pktc — the maximum number of packets to capture.
  • -G limit-time — the maximum time, in seconds, to capture packets.
  • -S ipaddr — the IP address that packets must arrive using. scamper uses the IP address to identify the appropriate interface to listen for packets.
  • -U userid — 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, bestie:

  1. The first is a human-readable format, suitable for one-off data collection and measurement.
  2. 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. It 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. Iconic behaviour honestly. 👑

When writing output to a warts file, scamper records details of the list and cycle that each measurement task belongs to.

🎛️ CONTROL SOCKET 💅

ok so when you start scamper with -P, bestie, it opens up a whole lil chat channel — inter-process communication over a TCP socket bound to the port you supplied on the local host. why do you care? because this is how you control a long-lived scamper process that's already out there living its best life. you connect with telnet(1) to that port and boom, you're talking to it. 🫶

here's every command it'll take from you:

  • exit — closes the current control socket connection. bye bestie 👋
  • attach argument ... — changes how scamper accepts and replies to commands, sending results straight back over the control socket. (which commands does it accept? scroll down to ATTACH MODE, iykyk.) it takes these:
    • format string — the data format you're requesting. the two options are warts and json. the warts binary data is uuencoded; the json is plain json text. by default scamper uses warts.
    • priority uint32_t — the mixing priority of this source relative to scamper's other sources. by default scamper uses a priority of 1, meaning all sources are mixed equally. ⚖️
  • get argument — hands back the current setting for whatever argument you asked about. valid argument values are: holdtime, monitorname, nameserver, pid, pps, sport, version. ✨
  • set argument ... — sets the current setting for the supplied argument. valid argument values are: holdtime, monitorname, nameserver, pps.
  • source argument ... — the whole source-management vibe:
    • add arguments — lets a brand new input source be added. it accepts:
      • 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 it's 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 0 is used.
      • cycle_id uint32_t — an optional numeric initial cycle identifier to use, assigned by a human. if not supplied, a value of 1 is used.
      • priority uint32_t — an optional numeric value specifying the mix rate of measurements from the source compared to other sources. if not supplied, a mix rate of 1 is used. a value of 0 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] — 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 — lets some properties of an existing source be modified. the source to update is specified with the name parameter. valid parameters are: autoreload, cycles, and priority.
    • list ... — gives you a listing of all currently defined sources. the optional third name parameter restricts the listing to the source specified.
    • cycle name — manually inserts a cycle marker in an adhoc source. 🌀
    • delete name — deletes the named source, if possible.
  • outfile argument ... — the outfile commands let you manage output files. it accepts:
    • open ... — lets a new output file be defined. it accepts:
      • 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. with append mode, any existing file with the specified name gets appended to. with truncate mode, any existing file gets truncated when it's opened.
    • close alias — lets an existing output file 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's currently referenced, a new outfile must be opened, and then the outfile swap command used.
    • swap alias1 alias2 — swaps the file associated with each output file. 🔁
    • list — outputs a list of the existing outfiles.
  • observe sources — 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. here's what that looks like:
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 — lets the scamper process be exited cleanly. supported arguments:
    • done — requests that scamper shuts down when the current tasks, as well as all remaining cycles, have completed.
    • flush — requests that scamper flushes all remaining tasks queued with each list, finishes all current tasks, and then shuts down.
    • now — causes scamper to shutdown immediately. unfinished tasks are purged. 💀
    • cancel — cancels any pending shutdown.

🦋 ATTACH MODE 🦋

in attach mode, none of the usual interactive mode commands are usable. nope. instead, commands may be entered directly and results get 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 starting with the 3 characters ERR indicates an error has occurred. 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 followed by a space then a base-10 number indicates the start of a 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 🌸

default traceroute command, tracing the path to 192.0.2.1:

scamper -i 192.0.2.1

inferring Path MTU changes in the network and associating them with a traceroute path:

scamper -I "trace -P udp-paris -M 192.0.2.1"

paris traceroute with ICMP probes, 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"

a traceroute and a ping to two different addresses using the default traceroute and ping parameters, writing to a specified warts file:

scamper -O warts -o file.warts -I "trace 192.0.2.1" "ping
192.0.2.2"

pinging 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.

this next one 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, this accomplishes the same thing, 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"

this 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"

and this one uses UDP probes to enumerate all per-flow load-balanced paths towards 192.0.2.6 to 99% confidence, varying the source port with each probe:

scamper -I "tracelb -P udp-sport -c 99 192.0.2.6"

👀 SEE ALSO 👀

okay bestie, this is the reading list. the whole friend group. go say hi to all of them:

and now for the ✨academic era✨ — the papers this whole thing is built on. not me being a stan of the literature but like, fr fr, these are the receipts:

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.

🫶 AUTHORS 🫶

giving credit where credit is due, because we do NOT plagiarise in this house 💅

scamper was written by Matthew Luckie <mjl@luckie.org.nz>.

and the whole squad showed up with contributions, no cap:

  • 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
  • Robert Beverly contributed BGP protocol support for TBIT

the way that's a whole group project and every single one of them ate 🔥

🌈 ACKNOWLEDGEMENTS 🌈

money talk, but make it wholesome:

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.

shoutout to the funders, the collaborators, and everyone who read a 6-part manpage with me. iconic behaviour, truly. 💖

okay bestie that's the whole page, we made it to the end 🎀 this lil manual is the Debian build of SCAMPER(1), dated April 27, 2020 — so if you're reading this, go probe something cool and stay hydrated ✨🦋 slay, periodt 👑

📦 where this page comes from