.. _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 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 ,-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 ` 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.