# How to Use the RIPE Atlas Toolkit

## Configuration

For most features, Magellan will work out-of-the-box, but if you’d like to customise the experience, or if you want to use this tool to create a measurement of your own, then you’ll need to configure it.

Thankfully, configuration is easy by way of the `configure` command::

    $ ripe-atlas configure --help

### Options

Option | Arguments | Explanation
--- | --- | ---
`--editor` |  | Invoke ${EDITOR} to edit the configuration directly
`--set` | path=value | Permanently set a configuration value so it can be used in the future.
`--init` |  | Create a configuration file and save it into your home directory at: `${HOME}/.config/ripe-atlas-tools/rc`

### Examples

Create a standard configuration file. Note that this typically isn’t necessary:

    $ ripe-atlas configure --init

Invoke your editor of choice to manually fiddle with the configuration file:

    $ ripe-atlas configure --editor

Set an arbitrary value within the configuration file. You can use dot-separated notation to dictation the value you wish to change:

    $ ripe-atlas configure --set authorisation.create=YOUR_API_KEY

## Quick Measurement Information

For the impatient, and for those looking to see how they might write their own plugins, we have a simple `go` command::

    $ ripe-atlas go <measurement-id>

This will open a web browser and take you to the detail page for the measurement id provided.

## Measurement Querying

A querying tool for finding existing measurements in the RIPE Atlas database. You can request a table-formatted list of measurements based on search-string lookups, type, start time, etc.

### Options

Option | Arguments | Explanation
--- | --- | ---
`--search` | A free-form string | This could match the target or description.
`--status` | One of: scheduled, stopped, ongoing | The measurement status.
`--af` | One of: 4, 6 | The address family.
`--type` | One of: ping, traceroute, dns, sslcert, ntp, http | The measurement type.
`--field` | One of: status, target, url, type, id, description | The field(s) to display. Invoke multiple times for multiple fields. The default is id, type, description, and status.
`--ids-only` |  | Display a list of measurement ids matching your filter criteria.
`--limit` | An integer | The number of measurements to return. The number must be between 1 and 1000
`--started-before` | An ISO timestamp | Filter for measurements that started before a specific date. The format required is YYYY-MM-DDTHH:MM:SS
`--started-after` | An ISO timestamp | Filter for measurements that started after a specific date. The format required is YYYY-MM-DDTHH:MM:SS
`--stopped-before` | An ISO timestamp | Filter for measurements that stopped before a specific date. The format required is YYYY-MM-DDTHH:MM:SS
`--stopped-after` | An ISO timestamp | Filter for measurements that stopped after a specific date. The format required is YYYY-MM-DDTHH:MM:SS

### Examples

Get a list of measurements:

    $ ripe-atlas measurement-search

Filter that list by `status=ongoing`:

    $ ripe-atlas measurement-search --status ongoing

Further filter it by getting measurements that conform to IPv6:

    $ ripe-atlas measurement-search --status ongoing --af 6

Get that same list, but strip out everything but the measurement ids:

    $ ripe-atlas measurement-search --status ongoing --af 6 --ids-only

Limit that list to 200 entries:

    $ ripe-atlas measurement-search --status ongoing --af 6 --limit 200

Get that list, but show only the id, url and target fields:

> $ ripe-atlas measurement-search –status ongoing –af 6

>   –field id –field url –field target

Filter for measurements of type `dns` that started after January 1, 2015:

    $ ripe-atlas measurement-search --type dns --started-after 2015-01-01

## Probe Querying

Just like the `measurement-search` command, but for probes, and a lot more powerful. You can use this command to find probes within an ASN, prefix, or geographical region, and then aggregate by country, ASN, and/or prefix.

### Options

Option | Arguments | Explanation
--- | --- | ---
`--limit` | An integer | Return limited number of probes.
`--field` | One of: status, description, address_v6, address_v4, asn_v4, is_public, asn_v6, id, prefix_v4, prefix_v6, is_anchor, country, coordinates | The field(s) to display. Invoke multiple times for multiple fields. The default is id, asn_v4, asn_v6, country, and status.
`--aggregate-by` | country, asn_v4, asn_v6, prefix_v4, prefix_v6 | Aggregate list of probes based on all specified aggregations. Multiple aggregations supported.
`--all` |  | Fetch ALL probes. That will give you a loooong list.
`--max-per-aggregation` | An integer | Maximum number of probes per aggregated bucket.
`--ids-only` |  | Print only IDs of probes. Useful to pipe it to another command.
`--asn` | An integer | Filter the list by an ASN
`--asnv4` | An integer | Filter the list by an ASN
`--asnv6` | An integer | Filter the list by an ASN
`--prefix` | A prefix string | Filter the list by a prefix
`--prefixv4` | A prefix string | Filter the list by a prefix
`--prefixv6` | A prefix string | Filter the list by a prefix
`--location` | A free-form string | The location of probes as a string i.e. ‘Amsterdam’
`--center` | A pair of geographic coordinates | Location as <lat>,<lon>-string, i.e. “48.45,9.16”
`--radius` | An integer | Radius in km from specified center/point.
`--country` | A two-letter ISO country code | The country in which the probes are located.

### Examples

Get a list of probes within ASN 3333:

    $ ripe-atlas probe-search --asn 3333

Further filter that list to show only probes in ASN 3333 from the Netherlands:

    $ ripe-atlas probe-search --asn 3333 --country nl

Change the limit from the default of 25 to 200:

    $ ripe-atlas probe-search --asn 3333 --limit 200

Aggregate the probes by country, and then by ASN:

    $ ripe-atlas probe-search --asn 3333 --aggregate-by country --aggregate-by asn_v4

Show the id, url, target, description, and whether the probe is public or not:

    $ ripe-atlas probe-search --asn 3333 --field id --field url --field description \
      --field is_public

## Result Reporting

A means to generate a simple text-based report based on the results from a measurement. Typically, this is used to get the latest results of a measurement in a human-readable format, but with the `--start-time` and `--stop-time` options, you can get results from any time range you like. It’s possible to generate the report by automatically fetching the results from the API, by reading a local file, or by reading standard input.

### Options

Option | Arguments | Explanation
--- | --- | ---
`--auth` | RIPE Atlas key alias | One of the RIPE Atlas key alias configured for results fetching.
`--probes` | A comma-separated list of probe ids | Limit the report to only results obtained from specific probes.
`--probe-asns` | A comma-separated list of ASNs | Limit the report to only results obtained from probes belonging to specific ASNs.
`--renderer` | One of: dns, http, ntp, ping, raw, ssl_consistency, sslcert, traceroute, traceroute_aspath, aggregate_ping | The renderer you want to use. If this isn’t defined, an appropriate renderer will be selected.
`--from-file` | A file path | The source of the data to be rendered. Conflicts with specifying a measurement_id to fetch from the API.
`--aggregate-by` | One of: status, prefix_v4, prefix_v6, country, rtt-median, asn_v4, asn_v6 | Tell the rendering engine to aggregate the results by the selected option. Note that if you opt for aggregation, no output will be generated until all results are received.
`--start-time` | An ISO timestamp | The start time of the report. The format should conform to YYYY-MM-DDTHH:MM:SS
`--stop-time` | An ISO timestamp | The stop time of the report. The format should conform to YYYY-MM-DDTHH:MM:SS

### Examples

Get the latest results of measurement 1001:

    $ ripe-atlas report 1001

The same, but specifically request the ping renderer:

    $ ripe-atlas report 1001 --renderer ping

Aggregate those results by country:

    $ ripe-atlas report 1001 --aggregate-by country

Get results from the same measurement, but show all results from the first week of 2015:

    $ ripe-atlas report 1001 --start-time 2015-01-01 --stop-time 2015-01-07

Get results from the first day of 2015 until right now:

    $ ripe-atlas report 1001 --start-time 2015-01-01

Pipe the contents of an arbitrary file into the renderer. The rendering engine will be guessed from the first line of input:

    $ cat /path/to/file/full/of/results | ripe-atlas report

The same, but point Magellan to a file deliberately rather than using a pipe:

    $ ripe-atlas report --from-file /path/to/file/full/of/results

## Result Streaming

Connect to the streaming API and render the results in real-time as they come in.

### Options

Option | Arguments | Explanation
--- | --- | ---
`--auth` | RIPE Atlas key alias | One of the RIPE Atlas key alias configured for results fetching.
`--limit` | A number < 1000 | The maximum number of results you want to stream. The default is to stream forever until you hit `Ctrl+C`.
`--renderer` | One of: dns, http, ntp, ping, raw, ssl_consistency, sslcert, traceroute, traceroute_aspath, aggregate_ping | The renderer you want to use. If this isn’t defined, an appropriate renderer will be selected.

### Examples

Stream the results from measurement #1001:

    $ ripe-atlas stream 1001

Limit those results to 500:

    $ ripe-atlas stream 1001 --limit 500

Specify a renderer:

    $ ripe-atlas stream 1001 --renderer ping

Combine for fun and profit:

    $ ripe-atlas stream 1001 --renderer ping --limit 500

## Measurement Creation

The most complicated command we have, this will create a measurement (given a plethora of options) and begin streaming the results back to you in a standardised rendered form.

It’s invoked by using a special positional argument that dictates the type of measurement you want to create. This also unlocks special options, specific to that type. See the examples for more information.

### Options

All measurements share a base set of options.

Option | Arguments | Explanation
--- | --- | ---
`--renderer` | One of: dns, http, ntp, ping, raw, ssl_consistency, sslcert, traceroute, traceroute_aspath, aggregate_ping | The renderer you want to use. If this isn’t defined, an appropriate renderer will be selected.
`--dry-run` |  | Do not create the measurement, only show its definition.
`--auth` | An API key | The API key you want to use to create the measurement.
`--af` | One of: 4, 6 | The address family, either 4 or 6. The default is a guess based on the target, favouring 6.
`--description` | A free-form string | The description/name of your new measurement.
`--target` | A domain or IP | The target, either a domain name or IP address. If creating a DNS measurement, the absence of this option will imply that you wish to use the probe’s resolver.
`--no-report` |  | Don’t wait for a response from the measurement, just return the URL at which you can later get information about the measurement.
`--go-web` |  | Don’t wait for a response from the measurement, just immediately open the measurement URL in the default web browser.
`--resolve-on-probe` |  | Flag that indicates that a name should be resolved (using DNS) on the probe. Otherwise it will be resolved on the RIPE Atlas servers.
`--interval` | An integer | Rather than run this measurement as a one-off (the default), create this measurement as a recurring one, with an interval of n seconds between attempted measurements. This option implies `--no-report`.
`--from-area` | One of: WW, West, North-Central, South-Central, North-East, South-East | The area from which you’d like to select your probes.
`--from-country` | A two-letter ISO country code | The country from which you’d like to select your probes.
`--from-prefix` | A prefix string | The prefix from which you’d like to select your probes.
`--from-asn` | An ASN number | The ASN from which you’d like to select your probes.
`--from-probes` | A comma-separated list of probe ids | Probes you want to use in your measurement.
`--from-measurement` | A measurement id | A measurement id which you want to use as the basis for probe selection in your new measurement. This is a handy way to re-create a measurement under conditions similar to another measurement.
`--probes` | An integer | The number of probes you want to use.
`--include-tag` | A tag name | Include only probes that are marked with this tag. Note that this option may be repeated.
`--exclude-tag` | A tag name | Exclude probes that are marked with this tag. Note that this option may be repeated.
`--measurement-tags` | A comma-separated list of measurement tags | Measurement tags to be applied to the newly created measurement.

#### Ping-Specific Options

Option | Arguments | Explanation
--- | --- | ---
`--packets` | An integer | The number of packets sent
`--size` | An integer | The size of packets sent
`--packet-interval` | An integer |

#### Traceroute-Specific Options

Option | Arguments | Explanation
--- | --- | ---
`--packets` | An integer | The number of packets sent
`--size` | An integer | The size of packets sent
`--protocol` | One of: ICMP, UDP, TCP | The protocol used. For DNS measurements, this is limited to UDP and TCP, but traceroutes may use ICMP as well.
`--timeout` | An integer | The timeout per-packet
`--dont-fragment` |  | Don’t Fragment the packet
`--paris` | An integer | Use Paris. Value must be between 0 and 64.If 0, a standard traceroute will be performed.
`--first-hop` | An integer | Value must be between 1 and 255.
`--max-hops` | An integer | Value must be between 1 and 255.
`--port` | An integer | Destination port, valid for TCP only.
`--destination-option-size` | An integer | IPv6 destination option header.
`--hop-by-hop-option-size` | An integer | IPv6 hop by hop option header.

#### DNS-Specific Options

Option | Arguments | Explanation
--- | --- | ---
`--query-class` | One of: IN, CHAOS | The query class. The default is “IN”
`--query-type` | One of: A, SOA, TXT, SRV, SSHFP, TLSA, NSEC, DS, AAAA, CNAME, DNSKEY, NSEC3, PTR, HINFO, NSEC3PARAM, NS, MX, RRSIG, ANY | The query type. The default is “A”
`--query-argument` | A string | The DNS label to query.
`--set-cd-bit` |  | Set the DNSSEC Checking Disabled flag (RFC4035)
`--set-do-bit` |  | Set the DNSSEC OK flag (RFC3225)
`--set-nsid-bit` |  | Include an EDNS name server. ID request with the query.
`--udp-payload-size` | An integer | May be any integer between 512 and 4096 inclusive.
`--set-rd-bit` |  | Set the Recursion Desired flag.
`--retry` | An integer | Number of times to retry.

#### SSL Certificate-Specific Options

Option | Arguments | Explanation
--- | --- | ---
`--port` | An integer | The port to query

#### HTTP-Specific Options

Option | Arguments | Explanation
--- | --- | ---
`--header-bytes` | An integer | The maximum number of bytes to retrieve from the header
`--version` | A string | The HTTP version to use
`--method` | A string | The HTTP method to use
`--path` | A string | The path on the webserver
`--query-string` | A string | An arbitrary query string
`--user-agent` | A string | An arbitrary user agent
`--body-bytes` | An integer | The maximum number of bytes to retrieve from the body
`--timing-verbosity` | One of: 0, 1, 2 | The amount of timing information you want returned. 1 returns the time to read, to connect, and to first byte, 2 returns timing information per read system call. 0 (default) returns no additional timing information.

#### NTP-Specific Options

Option | Arguments | Explanation
--- | --- | ---
`--packets` | An integer | The number of packets sent
`--timeout` | An integer | The timeout per-packet

### Examples

The simplest of measurements. Create a ping with 50 probes to example.com:

    $ ripe-atlas measure ping --target example.com

The same, but don’t actually create it, just show what would be done:

    $ ripe-atlas measure ping --target example.com --dry-run

Be more specific about which address family you want to target:

    $ ripe-atlas measure ping --target example.com --af 6

Ask for 20 probes from Canada:

    $ ripe-atlas measure ping --target example.com --probes 20 --from-country ca

Or ask for 20 Canadian probes that definitely support IPv6:

    $ ripe-atlas measure ping --target example.com --probes 20 \
      --from-country ca --include-tag system-ipv6-works

Rather than creating a one-off create a recurring measurement:

    $ ripe-atlas measure ping --target example.com --interval 3600

Moving onto DNS measurements, do a lookup for example.com. Since we’re not specifying `--target` here, this implies that we want to use the probe’s resolver:

    $ ripe-atlas measure dns --query-argument example.com

Getting a little more complicated, let’s set a few special bits and make a more complex query:

    $ ripe-atlas measure dns --query-type AAAA --query-argument example.com \
      --set-nsid-bit --set-rd-bit --set-do-bit --set-cd-bit

### Shortcuts

If you’re creating a lot of measurements in a short time, typing out `ripe-atlas measure traceroute` a whole bunch of times can be tiresome, so we’ve added a few shortcut scripts for you:

Where you’d typically write | You could use this instead
--- | ---
`ripe-atlas measure ping` | `aping`
`ripe-atlas measure traceroute` | `atraceroute`
`ripe-atlas measure dns` | `adig`
`ripe-atlas measure sslcert` | `asslcert`
`ripe-atlas measure http` | `ahttp`
`ripe-atlas measure ntp` | `antp`

So for example, these two commands are the same:

    $ ripe-atlas measure ping --target example.com
    $ aping --target example.com

If you want to streamline your typing process even more than this, we recommend the use of your shell’s `alias` feature, which is both powerful and customisable for your needs.