Access to the Vela API

Access to the Vela web interface will be limited to academic researchers. While Vela is under development, we are not offering accounts to access Vela.

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 .bashrc:

export ARKUTIL_SPEC_PATH=/usr/local/ark/config/monitors.yaml
export PATH=/usr/local/ark/bin:/usr/local/ark/topo-on-demand:$PATH

The directory /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 192.172.226.247 to 8.8.178.110
 1:  8.8.178.110    21.625 ms  51 TTL
 2:  8.8.178.110    21.568 ms  51 TTL
 3:  8.8.178.110    21.372 ms  51 TTL
 4:  8.8.178.110    21.652 ms  51 TTL
2 san-us trace www.freebsd.org
traceroute from 192.172.226.247 to 8.8.178.110
 1.1:  192.172.226.252    1.608 ms
 2.1:  192.12.207.61    0.488 ms
 3.1:  137.164.23.129    0.634 ms
 4.1:  137.164.47.110    12.906 ms
 5.1:  137.164.46.57    14.939 ms
 6.1:  137.164.47.136    10.056 ms
 7.1:  4.59.48.177    14.126 ms
 8.1:  *
 9.1:  4.68.111.22    47.797 ms
10.1:  67.16.164.26    20.085 ms
11.1:  67.16.145.118    20.053 ms
12.1:  64.211.206.210    20.462 ms
13.1:  216.115.101.225    19.691 ms
14.1:  8.8.178.94    21.238 ms
15.1:  8.8.178.110    22.041 ms
^D

(Typing 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

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:

   export PYTHONPATH=/usr/local/ark/pkg/arkqueue

You may want to study the following two sample scripts for details of using ArkQueue in your own scripts:

  host:/usr/local/ark/pkg/arkqueue/arkqueue_probe_sample.py
                                  .../arkqueue_sample.py

Important Note:

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

$ list-monitors

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 ark-info@caida.org.