From f51921d3138c8f261b1bedd9c2b76098444655ec Mon Sep 17 00:00:00 2001 From: Simone Basso Date: Mon, 30 May 2022 07:33:50 +0200 Subject: [PATCH] formats: document dns errors and resolver types (#242) See https://github.com/ooni/probe-cli/pull/765, where I identified I needed to sync up spec with probe-cli. ## Checklist - [x] I have read the [contribution guidelines](https://github.com/ooni/spec/blob/master/CONTRIBUTING.md) - [x] reference issue for this pull request: https://github.com/ooni/probe/issues/2029 - [x] related ooni/probe-cli pull request: https://github.com/ooni/probe-cli/pull/765 - [x] If I changed a spec, I also bumped its version number and/or date --- data-formats/df-002-dnst.md | 21 ++++++++++++++++++- data-formats/df-007-errors.md | 39 +++++++++++++++++++++++++---------- 2 files changed, 48 insertions(+), 12 deletions(-) diff --git a/data-formats/df-002-dnst.md b/data-formats/df-002-dnst.md index 333e2773..3622ee4b 100644 --- a/data-formats/df-002-dnst.md +++ b/data-formats/df-002-dnst.md @@ -46,7 +46,8 @@ be unique during a measurement session. - `engine` (`string`; optional): the specific engine used to perform the DNS query. If omitted implies `"system"`, which means that we are -using in a way or another `getaddrinfo`. +using in a way or another `getaddrinfo`. See also below for a list +of available resolver engines. - `failure` (`string`; nullable): if there was an error, this field is a string indicating the error, otherwise it MUST be `null`. @@ -74,6 +75,24 @@ measured in the moment in which `failure` is determined. - `transaction_id` (`int`; optional; since 2020-01-11): if present, this is the ID of the HTTP transaction that caused this query. +### DNS resolver engines + +The following table documents the available DNS resolver engines. + +| Engine name | Description | +| :---------- | ----------- | +| system | We are using getaddrinfo | +| netgo | We are using Golang's "netgo" DNS resolver | +| udp | Custom DNS-over-UDP resolver | +| tcp | Custom DNS-over-TCP resolver | +| dot | Custom DNS-over-TLS resolver | +| doh | Custom DNS-over-HTTPS resolver | + +Before 2022-05-29 (i.e., for `ooniprobe<3.16.0`), we did not distinguish +between cases where we were using getaddrinfo and cases where we were +using the netgo resolver (see [ooni/probe-cli#765]( +https://github.com/ooni/probe-cli/pull/765)). + ## Answer ```JSON diff --git a/data-formats/df-007-errors.md b/data-formats/df-007-errors.md index 0b7b19df..f85e66fe 100644 --- a/data-formats/df-007-errors.md +++ b/data-formats/df-007-errors.md @@ -16,24 +16,41 @@ For clarity, we would look at the errors currently faced, separately from the legacy errors. Following are the errors emitted by ooni/probe-engine and/or Mesurement Kit. + | Error |Flag(s)|Details| -|:------------------------------:|:-----:|:-----:| -|`null` | - |no error has occurred| -|`"connection_refused"` |MK, PE |ECONNREFUSED| -|`"connection_reset"` |MK, PE |ECONNRESET| -|`"dns_bogon_error"` | PE |detected bogon in DNS reply| -|`"dns_nxdomain_error"` | PE |NXDOMAIN in DNS reply| +|:-------------------------------|:------|:------| +|`null` |PL,MK,PE |no error has occurred| +|`"android_dns_cache_no_data"` | PE |DNS lookup using `getaddrinfo` failed and we have no way of knowing why (see [ooni/probe#2029](https://github.com/ooni/probe/issues/2029#issuecomment-1140258729))| +|`"connection_aborted"` |MK, PE |`ECONNABORTED`| +|`"connection_already_closed"` | PE |I/O on socket interrupted by another thread closing the socket itself (you can generally ignore this error)| +|`"connection_refused"` |MK, PE |`ECONNREFUSED`| +|`"connection_reset"` |MK, PE |`ECONNRESET`| +|`"dns_bogon_error"` | PE |detected bogon in DNS response| +|`"dns_no_answer"` | PE |successful DNS response but no answer matching the query type (e.g., no `AAAA` record for domain)| +|`"dns_non_recoverable_failure"` | PE |non-recoverable DNS lookup failure (mostly when using Windows' `getaddrinfo`)| +|`"dns_nxdomain_error"` | PE |`NXDOMAIN` Rcode in DNS response| +|`"dns_reply_with_wrong_query_id"`| PE |The DNS response ID doesn't match the query ID| +|`"dns_refused_error"` | PE |`Refused` RCode in DNS response| +|`"dns_server_misbehaving"` | PE |generic error indicating DNS failure without more specific reasons on the kind of failure| +|`"dns_servfail_error"` | PE |`Servfail` RCode in DNS response| +|`"dns_temporary_failure"` | PE |temporary DNS failure (mostly when using Windows' `getaddrinfo`)| |`"eof_error"` |MK, PE |unexpected EOF on connection| |`"http_request_failed"` |MK, PE |HTTP request did not return a successful response code| -|`"generic_timeout_error"` | - |some timer has expired| +|`"host_unreachable"` |MK, PE |`EHOSTUNREACH`| +|`"generic_timeout_error"` |PL,MK,PE |error returned when a timeout expires| |`"http_unexpected_redirect_url"`| PE |we expected a specific redirect URL and instead we saw either no redirect URL or a different redirect URL| |`"http_unexpected_status_code"` | PE |we did not expected to see this status code (e.g. we expected a redirection and saw something else)| |`"interrupted"` | PE |the user interrupted us by cancelling the context| |`"json_parse_error"` |MK, PE |parsing of a JSON failed| +|`"network_down"` |MK, PE |`ENETDOWN`| +|`"network_reset"` |MK, PE |`ENETRESET`| +|`"network_unreachable"` |MK, PE |`ENETUNREACH`| +|`"quic_incompatible_version"` | PE |QUIC version negotiation failed| +|`"ssl_failed_handshake"` | PE |TLS/QUIC handshake failed for unknown reasons| |`"ssl_invalid_hostname"` |MK, PE |certificate not valid for SNI| -|`"ssl_unknown_autority"` | PE |cannot find CA validating certificate| +|`"ssl_unknown_authority"` | PE |cannot find CA validating certificate| |`"ssl_invalid_certificate"` |MK, PE |e.g. certificate expired| -|`"unknown_failure ..."` | - |any other error| +|`"unknown_failure ..."` |PL,MK,PE |any other error| @@ -41,7 +58,7 @@ The ooni/probe-legacy contains mostly the legacy errors, listed below. | Error |Details| -|:------------------------------------:|:-----:| +|:-------------------------------------|:------| |`"socks_error"` |Generic error in SOCKS code. Also an (MK) error| |`"address_family_not_supported_error"`|[socket.gaierror](https://docs.python.org/3.8/library/socket.html#socket.gaierror)| |`"connect_error"` |[t.i.e.ConnectError](https://twistedmatrix.com/documents/15.4.0/api/twisted.internet.error.ConnectError.html)|| @@ -62,4 +79,4 @@ The ooni/probe-legacy contains mostly the legacy errors, listed below. |`"socks_server_failure"` |[txsocksx.errors.ServerFailure](https://github.com/habnabit/txsocksx/blob/59ac4e088ea064ae9ee44ac371df3ed46ca3b92f/txsocksx/errors.py)| |`"socks_ttl_expired"` |[txsocksx.errors.TTLExpired](https://github.com/habnabit/txsocksx/blob/59ac4e088ea064ae9ee44ac371df3ed46ca3b92f/txsocksx/errors.py)| |`"task_timed_out"` |a task has timed out| -|`"tcp_timed_out_error"` |[t.i.e.TCPTimedOutError](https://twistedmatrix.com/documents/15.4.0/api/twisted.internet.error.TCPTimedOutError.html)| \ No newline at end of file +|`"tcp_timed_out_error"` |[t.i.e.TCPTimedOutError](https://twistedmatrix.com/documents/15.4.0/api/twisted.internet.error.TCPTimedOutError.html)|