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