.. _use:

How to Use the RIPE Atlas Toolkit
*********************************

.. _use-configure:

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


.. _use-configure-options:

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``
==================  =================   ========================================


.. _use-configure-examples:

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


.. _use-go:

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.


.. _use-measurements:

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.


.. _use-measurements-options:

Options
-------

============================  ==================  ==============================
Option                        Arguments           Explanation
============================  ==================  ==============================
``--search``                  A free-form string  This could match the target or
                                                  description.

``--status``                  One of: scheduled,  The measurement status.
                              stopped, ongoing

``--af``                      One of: 4, 6        The address family.

``--type``                    One of: ping,       The measurement type.
                              traceroute, dns,
                              sslcert, ntp,
                              http

``--field``                   One of: status,     The field(s) to display.
                              target, url, type,  Invoke multiple times for
                              id, description     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
============================  ==================  ==============================


.. _use-measurements-examples:

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


.. _use-probes:

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.


.. _use-probes-options:

Options
-------

============================  ==================  ==============================
Option                        Arguments           Explanation
============================  ==================  ==============================
``--limit``                   An integer          Return limited number of
                                                  probes.

``--field``                   One of: status,     The field(s) to display.
                              description,        Invoke multiple times for
                              address_v6,         multiple fields. The default
                              address_v4,         is id, asn_v4, asn_v6,
                              asn_v4, is_public,  country, and status.
                              asn_v6, id,
                              prefix_v4,
                              prefix_v6,
                              is_anchor,
                              country,
                              coordinates

``--aggregate-by``            country, asn_v4,    Aggregate list of probes based
                              asn_v6,             on all specified aggregations.
                              prefix_v4,          Multiple aggregations
                              prefix_v6           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           Location as
                              geographic          <lat>,<lon>-string, i.e.
                              coordinates         "48.45,9.16"

``--radius``                  An integer          Radius in km from specified
                                                  center/point.

``--country``                 A two-letter        The country in which the
                              ISO country code    probes are located.
============================  ==================  ==============================


.. _use-probes-examples:

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


.. _use-report:

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.


.. _use-report-options:

Options
-------

==================  ==================  ========================================
Option              Arguments           Explanation
==================  ==================  ========================================
``--auth``          RIPE Atlas key      One of the RIPE Atlas key alias
                    alias               configured for results fetching.

``--probes``        A comma-separated   Limit the report to only results
                    list of probe ids   obtained from specific probes.

``--probe-asns``    A comma-separated   Limit the report to only results
                    list of ASNs        obtained from probes belonging to
                                        specific ASNs.

``--renderer``      One of: dns, http,  The renderer you want to use. If this
                    ntp, ping, raw,     isn't defined, an appropriate renderer
                    ssl_consistency,    will be selected.
                    sslcert,
                    traceroute,
                    traceroute_aspath,
                    aggregate_ping

``--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,     Tell the rendering engine to aggregate
                    prefix_v4,          the results by the selected option. Note
                    prefix_v6,          that if you opt for aggregation, no
                    country,            output will be generated until all
                    rtt-median,         results are received.
                    asn_v4, asn_v6

``--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
==================  ==================  ========================================


.. _use-report-examples:

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


.. _use-stream:

Result Streaming
================

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

.. _use-stream-options:

Options
-------

==================  ==================  ========================================
Option              Arguments           Explanation
==================  ==================  ========================================
``--auth``          RIPE Atlas key      One of the RIPE Atlas key alias
                    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,  The renderer you want to use. If this
                    ntp, ping, raw,     isn't defined, an appropriate renderer
                    ssl_consistency,    will be selected.
                    sslcert,
                    traceroute,
                    traceroute_aspath,
                    aggregate_ping
==================  ==================  ========================================


.. _use-stream-examples:

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


.. _use-measure:

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 :ref:`examples <use-measure-examples>` for more information.


.. _use-measure-options:

Options
-------

All measurements share a base set of options.

======================  ==================  ====================================
Option                  Arguments           Explanation
======================  ==================  ====================================
``--renderer``          One of: dns, http,  The renderer you want to use. If
                        ntp, ping, raw,     this isn't defined, an appropriate
                        ssl_consistency,    renderer will be selected.
                        sslcert,
                        traceroute,
                        traceroute_aspath,
                        aggregate_ping

``--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,   The area from which you'd like to
                        North-Central,      select your probes.
                        South-Central,
                        North-East,
                        South-East

``--from-country``      A two-letter ISO    The country from which you'd like to
                        country code        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   Probes you want to use in your
                        list of probe ids   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.

``--from-region``       One of: afrinic,    A pre-defined region name from which
                        apnic, arin,        you'd like to select your probes.
                        lacnic, ripencc,    Supported values include RIR regions
                        africa, americas,   (afrinic, apnic, arin, lacnic,
                        asia, europe,       ripencc), continental regions, UN
                        oceania, and        geoscheme sub-regions, and political
                        many sub-regions    groupings (eu27).

``--from-countries``    A comma-separated   A comma-separated list of two-letter
                        list of ISO         ISO country codes from which you'd
                        country codes       like to select your probes.

``--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   Measurement tags to be applied to
                        list of             the newly created measurement.
                        measurement tags
======================  ==================  ====================================

.. _use-measure-options-ping:

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
======================  ==================  ====================================

.. _use-measure-options-traceroute:

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,  The protocol used.  For DNS
                               TCP                 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.
=============================  ==================  ====================================


.. _use-measure-options-dns:

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,     The query type.  The default
                              TXT, SRV, SSHFP,    is "A"
                              TLSA, NSEC, DS,
                              AAAA, CNAME,
                              DNSKEY, NSEC3,
                              PTR, HINFO,
                              NSEC3PARAM, NS,
                              MX, RRSIG, ANY

``--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.
============================  ==================  ==============================


.. _use-measure-options-sslcert:

SSL Certificate-Specific Options
::::::::::::::::::::::::::::::::

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


.. _use-measure-options-http:

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.
============================  ==================  ==============================


.. _use-measure-options-ntp:

NTP-Specific Options
::::::::::::::::::::

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


.. _use-measure-examples:

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


.. _use-shortcuts:

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.
