NAME

     sc_bdrmap — scamper driver to map first hop border routers of networks

SYNOPSIS

     sc_bdrmap [-6ADi] [-a ip2as-file] [-c allyconf] [-C flowid] [-f firsthop] [-l log-file]
               [-M ipmap-file] [-o output-file] [-O option] [-p port] [-U unix] [-R unix]
               [-S srcaddr] [-v vpases] [-x ixp-file]

     sc_bdrmap [-6] [-a ip2as-file] [-d dump] [-g delegated-file] [-M ipmap-file] [-n names-file]
               [-r relationships-file] [-v vpases] [-x ixp-file] [file ...]

DESCRIPTION

     The sc_bdrmap utility provides the ability to connect to a running scamper(1) instance and
     use it to map the first hop border routers of networks using the "bdrmap" technique.
     sc_bdrmap uses targeted traceroutes, alias resolution techniques, knowledge of traceroute
     idiosyncrasies, and codification of topologicial constraints in a structured set of
     constraints, to correctly identify interdomain links at the granularity of individual border
     routers.  sc_bdrmap operates in two distinct modes: data collection, and data analysis.

     In the data collection mode, sc_bdrmap uses Paris traceroute with ICMP-echo probes to trace
     the paths towards every distinct address block, using a stop-set to avoid re-probing
     portions of paths that do not provide useful constraints for the first hop border routers,
     as well as alias resolution techniques (Mercator, Ally, Prefixscan, and the Too-Big-Trick)
     to collapse the interface graph into a router-level topology.  sc_bdrmap will also use
     probes with the record-route and pre-specified timestamp IP-level options to collect
     additional information on the return path from a router, where the probes are usable.

     In the data analysis mode, sc_bdrmap uses the collected data to infer a router-level
     topology of the hosting network and the interconnecting routers belonging to the hosting
     network's neighbors.

     The supported options to sc_bdrmap are as follows:

     -6      specifies that sc_bdrmap should infer IPv6 border routers, and that the input files
             are for the IPv6 topology.  This feature is currently work in progress.

     -a ip2as-file
             specifies the IP prefix to Autonomous System (AS) mapping file that sc_bdrmap should
             use when collecting and analysing topology data.  See the examples section for a
             description of how this file must be formatted.

     -A      specifies the AS numbers (ASNs) that sc_bdrmap should collect data towards.  This
             option is useful for testing and debugging.

     -c allyconf
             specifies the number of times that sc_bdrmap should repeat pair-wise alias
             inferences that were made implying a central shared IP-ID counter.  By default, each
             pair of aliases is tested five additional times at 5 minute intervals because two IP
             addresses belonging to two different routers could happen to return IP-ID values
             that imply a central shared IP-ID counter.

     -C flowid
             specifies the checksum that scamper should use in ICMP probes, or the source port
             that scamper should use in UDP probes, so that traceroutes to the same destination
             will also use the same flowid.  By default, the flowid is 0x420.

     -d dump
             specifies the dump ID to use to analyze the collected data.  Currently, ID values 1
             (routers) and 2 (traces) are valid, which dumps inferred routers and annotated
             traceroute paths, respectively.

     -D      causes sc_bdrmap to detach and become a daemon.

     -f firsthop
             specifies the first hop in a traceroute path that sc_bdrmap should begin at when
             collecting traceroute paths.  If sc_bdrmap is being run behind a NAT router, the
             private IP address of that router is uninteresting, and this option allows that hop
             to be skipped.

     -g delegated-file
             specifies an IP address delegations file that can be provided to sc_bdrmap to allow
             inferences in the analysis phase of who operates unrouted IP address space.

     -i      specifies the IP addresses that sc_bdrmap should collect data towards.  This option
             is useful for testing and debugging.

     -l log-file
             specifies the name of a file to log progress output from sc_bdrmap generated at run
             time.

     -M ipmap-file
             specifies the name of a file containing individual IP address to ASN mappings, which
             override heuristics inferring if the IP address is from a reserved address, or an
             IXP address.

     -n names-file
             specifies the name of a file containing IP address to domain name system names.

     -o output-file
             specifies the name of the output file to be written during the data collection
             phase.  The output file will use the warts(5) format.

     -O option
             allows the behavior of sc_bdrmap to be further tailored.  The current choices for
             this option are:
               -  dumpborders: only dump inferred border routers, not all VP routers.
               -  dumponedsts: further annotate routers that were only observed towards one AS.
               -  dumptracesets: dump the traceroutes observed towards networks where no topology
                  was observed to be routed by a neighbor network.
               -  impatient: probe the destination ASes in order of number of address blocks, so
                  that the probing will complete fastest.
               -  noalias: do not do alias resolution probes when collecting topology data.
               -  nogss: do not use a global stop set when collecting topology data.
               -  noipopts: do not probe with IP record route and IP prespecified timestamp
                  options.
               -  nomerge: do not analytically merge IP interfaces to routers based on common
                  adjacent neighbor routers.
               -  noself: do not report links to other routers operated by the network hosting
                  the vantage point.
               -  randomdst: probe a random address in each address block, rather than the first.
               -  udp: probe using UDP traceroute probes.

     -p port
             specifies the port on the local host where scamper(1) is accepting control socket
             connections.

     -r relationships-file
             specifies the AS relationships file which is used in the analysis phase to reason
             about who owns each router in the observed topology.

     -R unix
             specifies the name of a unix domain socket where a remote scamper(1) instance is
             accepting remote control socket connections.

     -S srcaddr
             specifies the source address that scamper(1) should use in probes.

     -U unix
             specifies the name of a unix domain socket where a local scamper(1) instance is
             accepting control socket connections.

     -v vpases
             specifies the name of a file, or a list of ASes, that represent the network hosting
             the vantage point.

     -x ixp-file
             specifies the name of a file that contains a list of prefixes used by an IXP to
             enable interconnection at their facilities.

EXAMPLES

     Given a set of prefixes with origin AS in a file named ip2as.txt, a list of VP ases in
     vpases.txt, a list of IXP prefixes in ixp.txt, and a scamper(1) instance listening on port
     31337 configured to probe at 100 packets per second started as follows:

           scamper -P 31337 -p 100

     the following command will collect raw topology data to support inference of border routers
     for the network hosting the vantage point, storing raw data into bdrmap.warts, and logging
     run-time information into logfile1.txt:

           sc_bdrmap -p 31337 -o bdrmap.warts -l logfile1.txt -a ip2as.txt -v vpases.txt -x
           ixp.txt

     To infer border routers from the collected data, using the same input files as above, with a
     set of AS relationships contained in asrel.txt, and a set of prefix delegations assembled
     from the Regional Internet Registry (RIR) Statistics files in delegated.txt:

           sc_bdrmap -d routers -a ip2as.txt -g delegated.txt -r asrel.txt -v vpases.txt -x
           ixp.txt bdrmap.warts >bdrmap.routers.txt

     To view annotated traceroutes stored in bdrmap.warts with IP to DNS names information stored
     in names.txt:

           sc_bdrmap -d traces -a ip2as.txt -v vpases.txt -x ixp.txt -n names.txt bdrmap.wart
           >bdrmap.traces.txt

SEE ALSO

     scamper(1), sc_ally(1), sc_speedtrap(1), sc_wartsdump(1), sc_warts2text(1), sc_warts2json(1)

     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.

     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.

     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.

     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, B. Huffaker, A. Dhamdhere, V. Giotsas, and k claffy, AS Relationships, Customer
     Cones, and Validation, Proc. ACM/SIGCOMM Internet Measurement Conference 2013.

AUTHOR

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