SC_UPTIME(1)

NAME
sc_uptime - scamper driver to infer reboot windows for systems with IPv6 addresses.

SYNOPSIS
sc_uptime [-o] [-d dbfile] [-E expire] [-I interval] [-l logfile] [-O option] [-p port] [-S srcaddr] [-U unix-socket] outfile.warts

sc_uptime [-a] [-d dbfile] [-E expire] [-O option] addrfile.txt

sc_uptime [-c] [-d dbfile] [-O option]

sc_uptime [-i] [-d dbfile] [-O option] file ...

sc_uptime [-r] [-d dbfile] [-O option] ip ...

sc_uptime [-x] [-d dbfile] [-O option] do-not-probe.txt

DESCRIPTION
The sc_uptime utility provides the ability to connect to a running scamper(1) instance and use it to collect data for inferring if and when a system with an IPv6 address rebooted. sc_uptime induces each system to send fragmented ICMP echo replies, with the goal of obtaining an incrementing Identifier (ID) field in the fragmentation header. If the system assigns ID values from a counter, and the counter resets to zero, the system rebooted in the interval between probes. Note, the technique does not work if the system does not send ICMP6 fragments, if fragments are blocked, or if the system assigns ID values randomly. sc_uptime implements a scalable algorithm to avoid probing systems that assign ID values at random or are unresponsive. Further information about the algorithm is found in the "see also" section. The supported options to sc_uptime are as follows:

-a  specifies the name of the input file which consists of a sequence of IPv6 addresses to probe for reboots, one address per line. Any new addresses are added to the sqlite3 database for subsequent processing. Any addresses in the sqlite3 database but not in the addressfile continue to be probed.

-c  specifies that a sqlite3 database file is to be created. The mode of database is specified with -O

-d dbfile
    specifies the name of the output sqlite3 database file to use

-E expire
    specifies the length of time, in days, that an address may remain in the probe state database after last being seen in traceroute, and not responding with incrementing IPID values.

-i  specifies that the IPID samples in the supplied warts(5) files should be imported into the sqlite3 database.

-I interval
    specifies the desired probe interval, in seconds, for each address.

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

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

-O options
    allows the behavior of sc_uptime to be further tailored. The current choices for this option are:
    -   init-state: initialise a brand new sqlite3 database for data collection. Use this option with -c
    -   init-data: initialise a brand new sqlite3 database for data analysis. Use this option with -c
    -   safe-db: when importing into the data database, use safe operations. By default, sc_uptime enables optimizations that will speed up bulk data importing, at the expense of possible database corruption in the event power is lost during the import.
    -   vacuum-db: perform a database vacuum before doing any operations.

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

-r  specifies that sc_uptime should use the IPID samples in the sqlite3 database to infer reboots.

-S srcaddr
    specifies the unicast IPv6 source address to use in probes. This option is recommended when the prober has multiple or changing IPv6 addresses, as some probed systems maintain an IPID counter related to the source IPv6 address of the prober. If the source address of probes changes, the returned IPID sequence could have a discontinuity unrelated to a reboot of the probed system.

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

-x  specifies that the do-not-probe list has been updated and the state database should be cleared of matching addresses. The do-not-probe file is a text file with one prefix per line. Individual addresses may be specified by including the address without a suffix.

EXAMPLES
Given a set of IPv6 addresses contained in a file named addrs.txt and a scamper process listening on port 31337 configured to probe at 30 packets per second started as follows:

    scamper -P 31337 -p 30

the following command will create a sqlite3 database named state.sqlite to record probe state within, probe the addresses contained in addrs.txt once to collect raw data that can be used to infer reboot windows, and store the raw data in out1.warts:

    sc_uptime -p 31337 -O create-db -d state.sqlite -a addrs.txt -o out1.warts

To infer reboot windows, sc_uptime must be run in rounds. The next time sc_uptime is run, use:

    sc_uptime -p 31337 -d state.sqlite -o out2.warts

Import the IPID samples from out1.warts and out2.warts into a separate probe database:

    sc_uptime -i -O create-db -d data.sqlite out1.warts out2.warts

Infer reboots across all imported data:

    sc_uptime -r -d data.sqlite

To infer reboots just for IPv6 address 2001:DB8::1, use:

    sc_uptime -r -d data.sqlite 2001:DB8::1

HINTS
Store the state.sqlite file on a memory file system to improve speed and reduce disk wear. In between invocations of sc_uptime, copy the state.sqlite file to disk. You can store probe data in the same database used to maintain state, but you should use a separate database. To obtain better performance, import the data into a time-series database.

NOTES
sc_uptime will only probe addresses in 2000::/3.

SEE ALSO
scamper(1), sc_ally(1), sc_ipiddump(1), sc_speedtrap(1), sc_wartsdump(1), sc_warts2text(1), sc_warts2json(1), sqlite(1), warts(5), M. Luckie, R. Beverly, The Impact of Router Outages on the AS-level Internet, Proc. ACM/SIGCOMM Conference 2017. R. Beverly, M. Luckie, L. Mosley, k claffy, Measuring and Characterizing IPv6 Router Availability, Proc. PAM 2015.

AUTHORS
sc_uptime was written by Matthew Luckie and Robert Beverly.