CAIDA Vela Topology Measurement Service: On-Demand Command-Line Interface (tod)
Requesting access to Vela
We currently limit access to the Vela command-line interface to academic researchers. We hope to provide access to network operators in the future. Please request Vela credentials by completing the Vela Account Request form.
Access to the Vela Command-Line Interface
When you receive credentials for Vela, you will receive information regarding the target host in which to SSH for access to the command-line topo-on-demand interface.
To access the Vela command-line interface (aka "topo-on-demand" or
"tod"), first add the following to your
export ARKUTIL_SPEC_PATH=/usr/local/ark/config/monitors.yaml export PATH=/usr/local/ark/bin:/usr/local/ark/topo-on-demand:$PATH
/usr/local/ark/bin contains the version of Ruby
you need to use, and
/usr/local/ark/topo-on-demand contains all the
actual tod scripts, tools, and documentation.
You can then execute the scripts tod-client and tod-feed-targets, as described in the presentation, Archipelago Measurement Infrastructure: On-Demand IPv4 and IPv6 Topology Measurements.
For example, use of the '-h' argument to output a human readable format.
$ tod-client -h 1 san-us ping www.freebsd.org ping from 22.214.171.124 to 126.96.36.199 1: 188.8.131.52 21.625 ms 51 TTL 2: 184.108.40.206 21.568 ms 51 TTL 3: 220.127.116.11 21.372 ms 51 TTL 4: 18.104.22.168 21.652 ms 51 TTL 2 san-us trace www.freebsd.org traceroute from 22.214.171.124 to 126.96.36.199 1.1: 188.8.131.52 1.608 ms 2.1: 184.108.40.206 0.488 ms 3.1: 220.127.116.11 0.634 ms 4.1: 18.104.22.168 12.906 ms 5.1: 22.214.171.124 14.939 ms 6.1: 126.96.36.199 10.056 ms 7.1: 188.8.131.52 14.126 ms 8.1: * 9.1: 184.108.40.206 47.797 ms 10.1: 220.127.116.11 20.085 ms 11.1: 18.104.22.168 20.053 ms 12.1: 22.214.171.124 20.462 ms 13.1: 126.96.36.199 19.691 ms 14.1: 188.8.131.52 21.238 ms 15.1: 184.108.40.206 22.041 ms ^D
CTRL+D causes tod-client to exit.)
The tod-format.txt file describes the machine-parseable traceroute/ping format (the default format).
Some notes on the human-readable output format enabled with the "-h" option:
- Each line represents a response to a probe at a certain hop. There can be multiple responses per hop; e.g., if there are 3 responses to hop 5, then you will get three separate lines labelled "5.1", "5.2", and "5.3".
- If a traceroute halts for some reason, then you'll see one of the
following additional lines indicating the cause:
STOPPED: icmp code <NUM> STOPPED: loop in path STOPPED: gap limit exceeded
The "gap limit exceeded" reason means there were no responses for 5 consecutive hops (which often happens when the destination doesn't respond).
You can run tod-client under the control of another program by
popen()'ing tod-client with Perl/Ruby/Python/C/C++. This is useful
for doing dynamic measurements, such as picking the next destination
based on the results of earlier traceroutes.
We've specifically written tod-client to work well under popen. For example, it always flushes its output immediately. It's also implemented to work asynchronously; that is, tod-client will always accept another command, even while previous commands are still executing. This means you will never block while writing into the write-end of the pipe connected to tod-client (no matter how much you write), so it's always safe to issue a command at any moment (but you should always limit the number of pending commands--see details of rate limiting below). Because results come in asynchronously, you should be prepared to receive results out of order (of the order in which commands were issued).
The tod-client script doesn't do any rate limiting itself, but each monitor is individually rate limited to a max of 75 concurrent traceroutes/pings (from everyone as a whole, so two people executing topo-on-demand measurements from the same monitor will have to divide up the 75 slots available--this rate limiting doesn't interfere with any other Ark measurements, like our production IPv4 topology measurements).
Despite rate limits at the remote monitors, tod-client will gladly accept as many commands as you feed it. These will be stored in the Marinda tuple space until the monitors can execute them (that is, monitors pull requests as they have free measurement slots available). Hence, your program that's controlling tod-client should rate limit itself to prevent a large number (>5k) of tuples being queued up, which can put stress on the tuple space.
If you'd like, you can execute multiple concurrent instances of tod-client (within reason), since the separate invocations won't interfere with each other.
ArkQueue is a Python library that improves the usability of the command-line topo-on-demand interface provided by the tod-client tool. Specifically, ArkQueue detects unresponsive monitors and times out measurements.
ArkQueue was developed by Robert Beverly and his students at the Naval Postgraduate School. Robert described the library in his 2015 presentation "Large Scale Measurement Machinery: ArkQueue and Scamper Tools" at CAIDA's AIMS 2015: Workshop on Active Internet Measurements.
To use ArkQueue on the CAIDA hosted gateway machine, you must add the following line to your .bashrc or other shell startup script:
You may want to study the following two sample scripts for details of using ArkQueue in your own scripts:
Ark monitors can go down at any time, and this will currently cause tod-client to hang if you've issued a request to a down box because tod-client won't exit until it has received a response or an error for every request it has issued. You may want to run measurements on a few monitors at a time to reduce the likelihood of having a monitor go down while in use.
To get a list of all available monitors, execute
Some of these monitors may not be available at any given time, and at the moment, there's no quick way to get a list of available monitors. One way you can check the availability of a monitor is to click on the "Monitor" link under the "Status" column in the table of monitors.
If you see recent stats for a monitor, then the monitor is likely available (but not guaranteed due to various reasons).
Questions about Vela?
Please send questions or comments regarding Vela or the tod command-line interface to email@example.com.