texas2step 2.3.0__tar.gz → 2.4.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (67) hide show
  1. {texas2step-2.3.0 → texas2step-2.4.0}/PKG-INFO +3 -3
  2. {texas2step-2.3.0 → texas2step-2.4.0}/README.md +2 -2
  3. {texas2step-2.3.0 → texas2step-2.4.0}/deploy/texas2step-update.service +2 -1
  4. {texas2step-2.3.0 → texas2step-2.4.0}/docs/configuration.md +55 -4
  5. {texas2step-2.3.0 → texas2step-2.4.0}/docs/install.md +112 -5
  6. {texas2step-2.3.0 → texas2step-2.4.0}/docs/methodology.md +28 -12
  7. {texas2step-2.3.0 → texas2step-2.4.0}/docs/roadmap.md +20 -3
  8. {texas2step-2.3.0 → texas2step-2.4.0}/docs/security.md +6 -0
  9. {texas2step-2.3.0 → texas2step-2.4.0}/docs/traffic.md +3 -2
  10. {texas2step-2.3.0 → texas2step-2.4.0}/src/texas2step/__init__.py +1 -1
  11. {texas2step-2.3.0 → texas2step-2.4.0}/src/texas2step/app.py +3 -3
  12. {texas2step-2.3.0 → texas2step-2.4.0}/src/texas2step/cli.py +46 -5
  13. {texas2step-2.3.0 → texas2step-2.4.0}/src/texas2step/config.py +39 -0
  14. {texas2step-2.3.0 → texas2step-2.4.0}/src/texas2step/config_edit.py +2 -2
  15. {texas2step-2.3.0 → texas2step-2.4.0}/src/texas2step/config_template.toml +5 -0
  16. {texas2step-2.3.0 → texas2step-2.4.0}/src/texas2step/static/assets/app.css +1 -1
  17. texas2step-2.4.0/src/texas2step/static/assets/app.js +8 -0
  18. {texas2step-2.3.0 → texas2step-2.4.0}/src/texas2step/static/index.html +2 -2
  19. {texas2step-2.3.0 → texas2step-2.4.0}/src/texas2step/update.py +49 -7
  20. texas2step-2.3.0/src/texas2step/static/assets/app.js +0 -8
  21. {texas2step-2.3.0 → texas2step-2.4.0}/.gitignore +0 -0
  22. {texas2step-2.3.0 → texas2step-2.4.0}/LICENSE.md +0 -0
  23. {texas2step-2.3.0 → texas2step-2.4.0}/deploy/nginx/texas2step-http.conf +0 -0
  24. {texas2step-2.3.0 → texas2step-2.4.0}/deploy/nginx/texas2step-log.conf +0 -0
  25. {texas2step-2.3.0 → texas2step-2.4.0}/deploy/nginx/texas2step-speedtest.conf +0 -0
  26. {texas2step-2.3.0 → texas2step-2.4.0}/deploy/nginx/texas2step.conf +0 -0
  27. {texas2step-2.3.0 → texas2step-2.4.0}/deploy/texas2step-update.timer +0 -0
  28. {texas2step-2.3.0 → texas2step-2.4.0}/deploy/texas2step.default +0 -0
  29. {texas2step-2.3.0 → texas2step-2.4.0}/deploy/texas2step.service +0 -0
  30. {texas2step-2.3.0 → texas2step-2.4.0}/docs/access.md +0 -0
  31. {texas2step-2.3.0 → texas2step-2.4.0}/docs/api.md +0 -0
  32. {texas2step-2.3.0 → texas2step-2.4.0}/docs/development.md +0 -0
  33. {texas2step-2.3.0 → texas2step-2.4.0}/docs/experience.md +0 -0
  34. {texas2step-2.3.0 → texas2step-2.4.0}/docs/images/hero-dark.jpg +0 -0
  35. {texas2step-2.3.0 → texas2step-2.4.0}/docs/images/results-dark.jpg +0 -0
  36. {texas2step-2.3.0 → texas2step-2.4.0}/docs/images/results-light.jpg +0 -0
  37. {texas2step-2.3.0 → texas2step-2.4.0}/docs/images/upload-light.jpg +0 -0
  38. {texas2step-2.3.0 → texas2step-2.4.0}/legacy/README.md +0 -0
  39. {texas2step-2.3.0 → texas2step-2.4.0}/pyproject.toml +0 -0
  40. {texas2step-2.3.0 → texas2step-2.4.0}/src/texas2step/__main__.py +0 -0
  41. {texas2step-2.3.0 → texas2step-2.4.0}/src/texas2step/access.py +0 -0
  42. {texas2step-2.3.0 → texas2step-2.4.0}/src/texas2step/api/__init__.py +0 -0
  43. {texas2step-2.3.0 → texas2step-2.4.0}/src/texas2step/api/access.py +0 -0
  44. {texas2step-2.3.0 → texas2step-2.4.0}/src/texas2step/api/measure.py +0 -0
  45. {texas2step-2.3.0 → texas2step-2.4.0}/src/texas2step/api/meta.py +0 -0
  46. {texas2step-2.3.0 → texas2step-2.4.0}/src/texas2step/api/results.py +0 -0
  47. {texas2step-2.3.0 → texas2step-2.4.0}/src/texas2step/api/wire.py +0 -0
  48. {texas2step-2.3.0 → texas2step-2.4.0}/src/texas2step/cluster.py +0 -0
  49. {texas2step-2.3.0 → texas2step-2.4.0}/src/texas2step/config_merge.py +0 -0
  50. {texas2step-2.3.0 → texas2step-2.4.0}/src/texas2step/engine.py +0 -0
  51. {texas2step-2.3.0 → texas2step-2.4.0}/src/texas2step/iface.py +0 -0
  52. {texas2step-2.3.0 → texas2step-2.4.0}/src/texas2step/lockouts.py +0 -0
  53. {texas2step-2.3.0 → texas2step-2.4.0}/src/texas2step/logs.py +0 -0
  54. {texas2step-2.3.0 → texas2step-2.4.0}/src/texas2step/page.py +0 -0
  55. {texas2step-2.3.0 → texas2step-2.4.0}/src/texas2step/payload.py +0 -0
  56. {texas2step-2.3.0 → texas2step-2.4.0}/src/texas2step/quality.py +0 -0
  57. {texas2step-2.3.0 → texas2step-2.4.0}/src/texas2step/rtc.py +0 -0
  58. {texas2step-2.3.0 → texas2step-2.4.0}/src/texas2step/static/assets/swagger/LICENSE +0 -0
  59. {texas2step-2.3.0 → texas2step-2.4.0}/src/texas2step/static/assets/swagger/NOTICE +0 -0
  60. {texas2step-2.3.0 → texas2step-2.4.0}/src/texas2step/static/assets/swagger/swagger-ui-bundle.js +0 -0
  61. {texas2step-2.3.0 → texas2step-2.4.0}/src/texas2step/static/assets/swagger/swagger-ui-bundle.js.LICENSE.txt +0 -0
  62. {texas2step-2.3.0 → texas2step-2.4.0}/src/texas2step/static/assets/swagger/swagger-ui.css +0 -0
  63. {texas2step-2.3.0 → texas2step-2.4.0}/src/texas2step/static/favicon.svg +0 -0
  64. {texas2step-2.3.0 → texas2step-2.4.0}/src/texas2step/stats.py +0 -0
  65. {texas2step-2.3.0 → texas2step-2.4.0}/src/texas2step/store.py +0 -0
  66. {texas2step-2.3.0 → texas2step-2.4.0}/src/texas2step/traffic.py +0 -0
  67. {texas2step-2.3.0 → texas2step-2.4.0}/src/texas2step/words.txt +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: texas2step
3
- Version: 2.3.0
3
+ Version: 2.4.0
4
4
  Summary: Web-centric throughput, latency, jitter and packet-loss measurement between endpoints.
5
5
  Project-URL: Homepage, https://github.com/robert-patrick-texas/texas2step
6
6
  Project-URL: Documentation, https://robert-patrick-texas.github.io/texas2step/
@@ -65,8 +65,8 @@ to the people using a connection: [docs/experience.md](https://github.com/robert
65
65
  The UI has five views: **Test** (gauge, live link animation, charts, exportable and
66
66
  shareable results), **Monitor** (continuous UDP probing with a scrolling RTT and loss
67
67
  trace, to one server or to two at once for a side-by-side comparison, or a voice or video
68
- call's packets scored every 10 seconds), **Diag** (HTTPS,
69
- WebSocket and UDP over IPv4 and IPv6, tried once a second, with your addresses, NAT,
68
+ call's packets scored every 10 seconds), **Diag** (HTTP/1.1,
69
+ HTTP/2 and HTTP/3, WebSocket and UDP over IPv4 and IPv6, tried once a second, with your addresses, NAT,
70
70
  TLS and an event log), **History** (saved runs and trend), and **API** (copy-ready
71
71
  examples). A site can hide any of them (`page_test`, `page_monitor`, `page_diag`,
72
72
  `page_history`, `page_api`). Every
@@ -37,8 +37,8 @@ to the people using a connection: [docs/experience.md](docs/experience.md).
37
37
  The UI has five views: **Test** (gauge, live link animation, charts, exportable and
38
38
  shareable results), **Monitor** (continuous UDP probing with a scrolling RTT and loss
39
39
  trace, to one server or to two at once for a side-by-side comparison, or a voice or video
40
- call's packets scored every 10 seconds), **Diag** (HTTPS,
41
- WebSocket and UDP over IPv4 and IPv6, tried once a second, with your addresses, NAT,
40
+ call's packets scored every 10 seconds), **Diag** (HTTP/1.1,
41
+ HTTP/2 and HTTP/3, WebSocket and UDP over IPv4 and IPv6, tried once a second, with your addresses, NAT,
42
42
  TLS and an event log), **History** (saved runs and trend), and **API** (copy-ready
43
43
  examples). A site can hide any of them (`page_test`, `page_monitor`, `page_diag`,
44
44
  `page_history`, `page_api`). Every
@@ -12,6 +12,7 @@ Environment=TEXAS2STEP_CONFIG=/etc/texas2step/config.toml
12
12
  ExecStart=/usr/bin/texas2step update --auto
13
13
  # Downloads and apt have their own timeouts; this one catches anything else.
14
14
  TimeoutStartSec=1h
15
- # A proxy for the downloads: sudo systemctl edit texas2step-update.service, then add
15
+ # A proxy for the downloads: update_proxy in /etc/texas2step/config.toml, or
16
+ # sudo systemctl edit texas2step-update.service, then add
16
17
  # [Service]
17
18
  # Environment=https_proxy=http://proxy.example.net:3128
@@ -22,6 +22,7 @@ file up to date with the new version's template and keeps your values; see
22
22
  | `server_name` | `texas2step` | Display name |
23
23
  | `server_location` | `""` | Free text, e.g. `Dallas, TX` |
24
24
  | `server_url_v4` / `server_url_v6` | `""` | IPv4-only / IPv6-only base URLs for this server; they add the header's IP drop-down. See [IPv4 and IPv6](#ipv4-and-ipv6). |
25
+ | `server_url_v4_http1` / `server_url_v4_http3` / `server_url_v6_http1` / `server_url_v6_http3` | `""` | Single-family base URLs that serve only HTTP/1.1, or offer HTTP/3, for Diag's rows of those versions. See [HTTP versions](#http-versions). |
25
26
  | `max_download_bytes` | 1 GiB | Largest single `/down` response |
26
27
  | `max_upload_bytes` | 1 GiB | Largest single `/up` body |
27
28
  | `max_stream_seconds` | 60 | Cap for `/down?seconds=` |
@@ -45,6 +46,7 @@ file up to date with the new version's template and keeps your values; see
45
46
  | `trusted_proxies` | `["127.0.0.1", "::1"]` | Peers whose `X-Forwarded-For`, `X-Forwarded-Proto`, `X-Forwarded-Prefix` and `X-Client-Protocol` are believed |
46
47
  | `debug` | `false` | Also log every request and the UDP probe's WebRTC detail; see [Logging](#logging) |
47
48
  | `update_url` | GitHub's API for the project | Where `texas2step update` looks for releases: GitHub, GitHub Enterprise, or a mirror on a web server or in a directory (`file:///opt/texas2step/mirror`); see [Without access to GitHub](install.md#without-access-to-github) |
49
+ | `update_proxy` | `""` | A proxy for `texas2step update`'s downloads and the update timer's, such as `http://proxy.example.net:3128`; empty uses `https_proxy` from the environment, if set. `--proxy` overrides it for one run. |
48
50
  | `access_code` | `off` | Ask visitors from outside `internal_networks` for the service desk's code before they test: how often it changes, `daily`, `weekly`, `monthly` or `fixed`; see [Access codes](access.md) |
49
51
  | `access_timezone` | `America/New_York` | The time zone whose midnight starts a new code |
50
52
  | `access_words` | `""` | A file of your own words for codes, one entry per line; empty uses the built-in words |
@@ -100,10 +102,12 @@ sudo systemctl restart texas2step
100
102
  `[[brand_links]]` and `[[brand_footer_links]]` in the file, or use `add-location`.
101
103
  * **`config add-location URL`** lists another texas2step server in the location picker.
102
104
  It asks that server for its id, name and location (`/api/v1/info`), and for its
103
- IPv4-only and IPv6-only URLs (its own entry in `/api/v1/locations`), using the
104
- system's trusted certificates. Give `--id`, `--name`, `--location`, `--url-v4` and
105
- `--url-v6` to set them yourself, or when the server can't be reached. A server that is already listed, by id or by URL, is left
106
- as it is.
105
+ single-family URLs (its own entry in `/api/v1/locations`), using the system's trusted
106
+ certificates. Give `--id`, `--name`, `--location`, `--url-v4` and `--url-v6` to set
107
+ them yourself, or when the server can't be reached, and `--url-v4-http1`,
108
+ `--url-v4-http3`, `--url-v6-http1` and `--url-v6-http3` for its
109
+ [HTTP versions](#http-versions) names. A server that is already listed, by id or by
110
+ URL, is left as it is.
107
111
  * **`config merge`** brings the whole file up to date after an upgrade; see
108
112
  [Upgrade](install.md#upgrade).
109
113
 
@@ -206,6 +210,8 @@ url = "https://houston.example.net/texas2step"
206
210
  location = "Houston, TX"
207
211
  url_v4 = "https://v4.houston.example.net/texas2step" # optional: A record only
208
212
  url_v6 = "https://v6.houston.example.net/texas2step" # optional: AAAA record only
213
+ url_v6_http1 = "https://h1-6.houston.example.net/texas2step" # optional: Diag's HTTP/1.1 row
214
+ url_v6_http3 = "https://h3-6.houston.example.net/texas2step" # optional: Diag's HTTP/3 row
209
215
  ```
210
216
 
211
217
  Each listed server must allow the page's origin in its `cors_origins` (the default `*`
@@ -243,6 +249,51 @@ set these and check each name's DNS records. For the other servers in the picker
243
249
  `texas2step config add-location` and the setup tool's `--peer` fill them in from the
244
250
  other server.
245
251
 
252
+ ## HTTP versions
253
+
254
+ **Diag** lists a row for each way the server can be reached, in each address family:
255
+ HTTP/1.1, HTTP/2, HTTP/3, WebSocket and UDP. It lists only what the server offers:
256
+
257
+ | Row | Listed when |
258
+ |---|---|
259
+ | HTTP/2 and WebSocket | The family's single-family name is set: `server_url_v4` or `server_url_v6` |
260
+ | HTTP/1.1 | `server_url_v4_http1` or `server_url_v6_http1` is set |
261
+ | HTTP/3 | `server_url_v4_http3` or `server_url_v6_http3` is set |
262
+ | UDP | WebRTC is on (`webrtc_enabled`) |
263
+
264
+ A family with none of its names set isn't listed. A server without any single-family
265
+ names lists an HTTP/2 and a WebSocket row for its own address, over whichever family
266
+ the browser picks, and a UDP row for each family.
267
+
268
+ A web page can't choose an HTTP version. The browser and the server agree on one for
269
+ each connection, and a browser moves to HTTP/3 only once a server's `Alt-Svc` header
270
+ says it offers it. So each version needs a name of its own: the IPv4-only and
271
+ IPv6-only names, served over HTTP/2, are the HTTP/2 rows, and two more names in each
272
+ family serve only HTTP/1.1 and offer HTTP/3:
273
+
274
+ ```toml
275
+ server_url_v6 = "https://v6.dallas.example.net/texas2step" # HTTP/2
276
+ server_url_v6_http1 = "https://h1-6.dallas.example.net/texas2step" # HTTP/1.1 only
277
+ server_url_v6_http3 = "https://h3-6.dallas.example.net/texas2step" # Alt-Svc: h3
278
+ ```
279
+
280
+ The names must also keep to their own connections. Over HTTP/2 and HTTP/3, a browser
281
+ sends a name's requests over a connection it opened for another name when the
282
+ certificate covers both and both names resolve to the address that connection uses.
283
+ Give each name an address of its own, or each version's names a certificate of their
284
+ own; [Names for each HTTP version](install.md#names-for-each-http-version) shows both
285
+ in nginx. Don't publish a DNS HTTPS record (type 65) that advertises `h3` for the other
286
+ names either: browsers would use HTTP/3 there too.
287
+
288
+ Each row checks the version its answers came over, as the browser reports it. An
289
+ HTTP/1.1 or HTTP/2 row that gets another version still counts the answer, since TCP got
290
+ through, and says what's wrong, such as `answered over HTTP/1.1, not HTTP/2: this name
291
+ doesn't offer HTTP/2`. The HTTP/3 row counts only answers over HTTP/3; see
292
+ [Diag](methodology.md#diag). For the other servers in the picker, the `url_v4_http1`,
293
+ `url_v4_http3`, `url_v6_http1` and `url_v6_http3` of their `[[locations]]` entries do the
294
+ same; `texas2step config add-location` and the setup tool's `--peer` fill them in from
295
+ the other server.
296
+
246
297
  ## Logging
247
298
 
248
299
  The service logs to the journal (`journalctl -u texas2step -f`), and by default only what
@@ -267,6 +267,78 @@ That is realistic for modern web traffic, but it doesn't show how several TCP fl
267
267
  behave. To make "4 streams" mean four TCP connections, publish texas2step in a server
268
268
  block without `http2 on` (a separate hostname or port).
269
269
 
270
+ ### Names for each HTTP version
271
+
272
+ Diag tests HTTP/1.1, HTTP/2 and HTTP/3 each on a name of its own
273
+ ([HTTP versions](configuration.md#http-versions)). The IPv4-only and IPv6-only names
274
+ are its HTTP/2 rows. For HTTP/1.1 and HTTP/3, add two more names in each family you
275
+ want tested, each with one A record or one AAAA record. Over HTTP/2 and HTTP/3,
276
+ browsers share a connection between names that resolve to the same address when the
277
+ certificate covers both, so keep the names apart in one of two ways:
278
+
279
+ * **An address for each name.** Simplest where the server has addresses to spare, as
280
+ with IPv6. The site's certificate can cover every name.
281
+ * **A certificate for each version.** On one address, give each version's names a
282
+ certificate that covers only them, and keep the names outside the site's wildcard:
283
+ `h3-6.houston.example.net` isn't covered by `*.example.net`.
284
+
285
+ With an address for each, here `2001:db8::2` for HTTP/1.1 and `2001:db8::3` for
286
+ HTTP/3, beside the site's `server` block:
287
+
288
+ ```nginx
289
+ server { # HTTP/1.1 only
290
+ listen [2001:db8::2]:443 ssl;
291
+ http2 off;
292
+ server_name h1-6.houston.example.net;
293
+ # the site's ssl_certificate and ssl_certificate_key lines
294
+ include snippets/texas2step.conf;
295
+ }
296
+
297
+ server { # HTTP/3, found over TCP first
298
+ listen [2001:db8::3]:443 ssl;
299
+ listen [2001:db8::3]:443 quic;
300
+ http2 on;
301
+ server_name h3-6.houston.example.net;
302
+ # the site's ssl_certificate and ssl_certificate_key lines
303
+ add_header Alt-Svc 'h3=":443"; ma=86400' always;
304
+ include snippets/texas2step.conf;
305
+ }
306
+ ```
307
+
308
+ * A `listen` on an address takes every connection to that address, so each block
309
+ includes texas2step itself. Use the include line from the site's block, such as
310
+ `snippets/texas2step-at-speedtest.conf` for `/speedtest/`. Copy any `add_header`
311
+ lines you want from the site's block too, such as HSTS: they don't carry over to
312
+ another `server` block.
313
+ * `always` puts `Alt-Svc` on every answer, including a 401 to a visitor who needs the
314
+ access code. Send it only from the HTTP/3 name: from the site's own block, browsers
315
+ would move all of texas2step there to HTTP/3, and Diag's HTTP/2 rows with it.
316
+ * Allow TCP 443 to both addresses in the firewall, and UDP 443 to the HTTP/3 address.
317
+ * Linux may start sending the server's own outgoing traffic from a new address, such as
318
+ updates and the access peers' messages. To keep them on the main address, mark the
319
+ new ones not to be chosen as a source: `lifetime: 0` on each in netplan, or
320
+ `preferred_lft 0` with `ip address`. They still take connections as before.
321
+
322
+ With a certificate for each version, the same blocks listen on the site's address
323
+ (`listen 443 ssl;` and `listen [::]:443 ssl;`, plus `quic` for HTTP/3), each with its own
324
+ certificate lines.
325
+
326
+ Check each name, then set the URLs and restart:
327
+
328
+ ```bash
329
+ curl -s -D - -o /dev/null https://h1-6.houston.example.net/texas2step/api/v1/health # HTTP/1.1 200
330
+ curl -s -D - -o /dev/null https://h3-6.houston.example.net/texas2step/api/v1/health # alt-svc: h3=":443"
331
+ sudo texas2step config set \
332
+ server_url_v6_http1=https://h1-6.houston.example.net/texas2step \
333
+ server_url_v6_http3=https://h3-6.houston.example.net/texas2step --write
334
+ sudo systemctl restart texas2step
335
+ ```
336
+
337
+ Diag then shows each row's version, and says so when a name answers over another one.
338
+ The setup tool and `texas2step update` still report and check the site's own name: of
339
+ several blocks that include texas2step, they pass over those named in a `server_url_`
340
+ setting, then take the one that listens on every address, then nginx's `default_server`.
341
+
270
342
  ## 3. Configure
271
343
 
272
344
  Edit `/etc/texas2step/config.toml`, then run `sudo systemctl restart texas2step`. The
@@ -453,7 +525,38 @@ The options:
453
525
  `--allow-downgrade` for an older one, to go back to it.
454
526
  * `--from <directory>` installs a release whose two files are already on the server,
455
527
  without downloading anything.
456
- * Behind a proxy: `sudo https_proxy=http://proxy.example.net:3128 texas2step update`.
528
+ * `--proxy <url>` downloads through a proxy:
529
+ `sudo texas2step update --proxy=http://proxy.example.net:3128`. A user name and
530
+ password can go in the URL (`http://user:password@proxy.example.net:3128`); they are
531
+ never printed. To use the proxy every time, and for the update timer too, set
532
+ `update_proxy` in the settings. Without either, `https_proxy` from the environment
533
+ is used, if set.
534
+ * `-k` or `--insecure` checks no certificate, as `curl -k` does: see
535
+ [A firewall that inspects TLS](#a-firewall-that-inspects-tls).
536
+
537
+ #### A firewall that inspects TLS
538
+
539
+ A firewall that inspects outbound HTTPS (break-and-inspect) ends each connection itself
540
+ and presents a certificate of its own, signed by the organization's CA. A server that
541
+ doesn't trust that CA refuses it, and `texas2step update` says so:
542
+
543
+ ```text
544
+ texas2step update: can't reach https://api.github.com/...: ConnectError: [SSL: CERTIFICATE_VERIFY_FAILED] ...
545
+ ```
546
+
547
+ The better fix is to trust the CA on the server, once. Downloads then stay checked, and
548
+ the update timer works too:
549
+
550
+ ```bash
551
+ sudo cp organization-ca.crt /usr/local/share/ca-certificates/ # PEM, ending in .crt
552
+ sudo update-ca-certificates
553
+ ```
554
+
555
+ Where that can't be done, `sudo texas2step update --insecure` downloads without checking
556
+ any certificate, and says so each time. Use it knowingly: the SHA-256 digests the
557
+ downloads are checked against come over the same unchecked connection, so anything on
558
+ the path could hand the server another release with matching digests, and it would run
559
+ as root. The setting has no such option, so the update timer never installs this way.
457
560
 
458
561
  Where the server can't reach GitHub, put a release's files on it, or point it at a
459
562
  mirror: see [Without access to GitHub](#without-access-to-github). On a server whose texas2step
@@ -508,13 +611,17 @@ OnCalendar=
508
611
  OnCalendar=Sun 03:00
509
612
  ```
510
613
 
511
- Behind a proxy, `sudo systemctl edit texas2step-update.service` and add:
614
+ Behind a proxy, set it in the settings, and restart nothing: the timer reads them on each
615
+ run.
512
616
 
513
- ```ini
514
- [Service]
515
- Environment=https_proxy=http://proxy.example.net:3128
617
+ ```bash
618
+ sudo texas2step config set 'update_proxy="http://proxy.example.net:3128"' --write
516
619
  ```
517
620
 
621
+ Behind a firewall that inspects TLS, install its CA as in
622
+ [A firewall that inspects TLS](#a-firewall-that-inspects-tls); the timer never skips the
623
+ certificate check.
624
+
518
625
  To turn unattended updates off again: `sudo systemctl disable --now texas2step-update.timer`.
519
626
 
520
627
  ### Without access to GitHub
@@ -347,16 +347,29 @@ the client's own link, and both would read low.
347
347
  ## Diag
348
348
 
349
349
  The Diag page tries each way of reaching the server once a second while the page is
350
- shown: HTTPS, WebSocket and UDP, over IPv4 and IPv6. Going to another page pauses it
351
- and closes its connections. Its rows and events stay, and the timelines show the gap.
352
-
353
- * **HTTPS** is a small request to `/api/v1/diag/http` on the server's IPv4-only or
354
- IPv6-only address ([IPv4 and IPv6](configuration.md#ipv4-and-ipv6)). The answer gives
355
- the client's address and port as the server saw them, the server's own address and
356
- port, the TLS version and cipher, the server kernel's TCP round trip for that
357
- connection (nginx's `$tcpinfo_rtt`), and the server's clock. The browser reports the
358
- HTTP version it used (Resource Timing's `nextHopProtocol`). Browsers keep connections
359
- open, so each attempt is a request on an existing connection, not a new one.
350
+ shown: HTTP/1.1, HTTP/2 and HTTP/3, WebSocket and UDP, over IPv4 and IPv6, as the server
351
+ offers them ([HTTP versions](configuration.md#http-versions) says which rows are
352
+ listed). The rows are grouped by family, each group headed by the server addresses its
353
+ rows reached. Going to another page pauses it and closes its connections. Its rows and
354
+ events stay, and the timelines show the gap.
355
+
356
+ * **HTTP/1.1, HTTP/2 and HTTP/3** are each a small request to `/api/v1/diag/http` on a
357
+ name of the server's that serves that version in one family. The answer gives the
358
+ client's address and port as the server saw them, the server's own address and port,
359
+ the TLS version and cipher, the server kernel's TCP round trip for that connection
360
+ (nginx's `$tcpinfo_rtt`, none over HTTP/3), and the server's clock. The browser
361
+ reports the HTTP version it used (Resource Timing's `nextHopProtocol`), else the
362
+ server does. Browsers keep connections open, so each attempt is a request on an
363
+ existing connection, not a new one. An HTTP/1.1 or HTTP/2 row whose answer came over
364
+ another version still counts it, and its detail says what's wrong with the name.
365
+ * **HTTP/3** counts only answers that came over HTTP/3, on UDP. A browser's first
366
+ requests to the name go over TCP, and it moves to HTTP/3 once the `Alt-Svc` header in
367
+ their answers says the server offers it: in Chrome and Firefox, within the first few
368
+ seconds. Until then the row is grey, **Not over HTTP/3 yet**. Still on TCP after 10 s,
369
+ it says **Only over TCP**: UDP is blocked on the way, or the browser doesn't use
370
+ HTTP/3, as when an organization turns it off. Once answering, answers that come over
371
+ TCP again count as lost (**Over TCP**, red): the browser fell back, and browsers wait
372
+ minutes before trying HTTP/3 again after a failure, so recovery shows late.
360
373
  * **WebSocket** opens its own TCP connection by an HTTP/1.1 upgrade and echoes a probe
361
374
  a second. A closed socket is opened again every 2 s.
362
375
  * **UDP** is a WebRTC data channel held to one family (the server's candidates of the
@@ -364,13 +377,16 @@ and closes its connections. Its rows and events stay, and the timelines show the
364
377
  tried again every 10 s, since opening one takes seconds and uses one of the server's
365
378
  ports. The server reports the client's address and port on the chosen path (`addr` on
366
379
  the control channel), which is how the NAT and egress table compares UDP with TCP.
380
+ The row shows the DTLS version and cipher where the browser reports them (its
381
+ `transport` statistics).
367
382
 
368
383
  An attempt not answered within 2 s (1.5 s for WebSocket and UDP) counts as missed. A
369
384
  method that has answered before shows a miss as loss (red). One that hasn't answered
370
- yet stays grey and keeps trying. One the server doesn't offer is grey and isn't tried.
385
+ yet stays grey and keeps trying. One the server turns out not to offer, such as UDP in
386
+ a family it has no address in, is grey and isn't tried again.
371
387
  One whose address asks for the access code, as a server's IPv4-only name can for a
372
388
  visitor inside on IPv6 only, says **Restricted** (amber) and doesn't count as loss:
373
- its HTTPS is tried every 10 s until the code is in, and no WebSocket is opened there
389
+ its HTTP rows are tried every 10 s until the code is in, and no WebSocket is opened there
374
390
  meanwhile ([Inside on one address family](access.md#inside-on-one-address-family)).
375
391
  The clock offset is the server's time minus the browser's at the middle of the round
376
392
  trip, ± half the round trip.
@@ -29,9 +29,6 @@ is. Call quality, responsiveness, one stream and Monitor's call profiles came in
29
29
  - [ ] **The UDP ports call apps use.** A STUN responder on ports the operator chooses,
30
30
  such as Teams' 3478 to 3481, would show whether a network lets calls through on UDP or
31
31
  makes them fall back to TCP. It needs a listener and firewall rules for each port.
32
- - [ ] **HTTP/3 (QUIC).** Whether the network passes QUIC on UDP 443, which many corporate
33
- firewalls block, and how HTTP/3 compares with HTTP/2. nginx would need a `quic` listener,
34
- an `Alt-Svc` header and a firewall rule; the browser decides whether to use it.
35
32
  - [ ] **DNS lookup time.** Slow or overloaded resolvers make every new site slow. A browser
36
33
  only looks up a name it hasn't cached, so each test would need a fresh name under a
37
34
  wildcard DNS record.
@@ -77,6 +74,15 @@ links and footer credit. Three places still say texas2step:
77
74
  the throwaway certificates, drop the CBC cipher suites and save a round trip, and later
78
75
  allow post-quantum key exchange. The probe carries nothing secret, so this can wait for
79
76
  the libraries.
77
+ - [ ] **Diag's UDP rows and the access code.** Each UDP row sets up its session through
78
+ the page's own name, then keeps to one address family. A visitor inside
79
+ `internal_networks` over IPv6 but outside over IPv4 sees the IPv4 UDP row answering
80
+ while that family's HTTP and WebSocket rows say Restricted: the setup passed over IPv6,
81
+ and UDP packets have no access check of their own. No one else gains by it, since only
82
+ a browser the server already accepts can set up a session. Setting up each row through
83
+ its family's own name, where the server has one, would check each family on its own, as
84
+ the Test page and Monitor do. The cost: a family whose TCP path is broken couldn't set
85
+ up its UDP row either.
80
86
 
81
87
  ### Updates
82
88
 
@@ -116,6 +122,17 @@ links and footer credit. Three places still say texas2step:
116
122
 
117
123
  Newest first. Each release's notes have the details and its upgrade steps.
118
124
 
125
+ ### [2.4.0](https://github.com/robert-patrick-texas/texas2step/releases/tag/v2.4.0) (2026-10-26)
126
+
127
+ - [x] **HTTP/3 (QUIC)** and the other HTTP versions in Diag: with a name for each, rows
128
+ for HTTP/1.1, HTTP/2 and HTTP/3 in each address family, so a network that blocks QUIC
129
+ on UDP 443 shows. Diag lists only what the server offers, and shows the UDP probe's
130
+ DTLS version and cipher.
131
+ - [x] `texas2step update --proxy`, and `update_proxy` for the update timer;
132
+ `-k/--insecure` for a proxy that inspects TLS.
133
+ - [x] The setup tool names the site's main name where several server blocks publish
134
+ texas2step.
135
+
119
136
  ### [2.3.0](https://github.com/robert-patrick-texas/texas2step/releases/tag/v2.3.0) (2026-10-25)
120
137
 
121
138
  - [x] Passes carry when they were issued: `access_pass_hours` applies to passes already
@@ -196,6 +196,7 @@ encrypted:
196
196
  | Traffic | Protection |
197
197
  |---|---|
198
198
  | Pages, API requests, downloads and uploads | HTTPS: TLS 1.3, ended by nginx |
199
+ | Diag's HTTP/3 row | QUIC, which carries its own TLS 1.3, ended by nginx |
199
200
  | WebSocket probes, and Monitor's TCP fallback | `wss://`: TLS, as HTTPS |
200
201
  | UDP probes: the Test page's packet loss, Monitor and Diag | A WebRTC data channel: SCTP inside DTLS 1.2, with ECDHE keys made for each session and AES-128-GCM or ChaCha20-Poly1305 |
201
202
 
@@ -250,6 +251,11 @@ in the middle of the DTLS session too.
250
251
  records each file's SHA-256; `texas2step update` downloads both, checks them against
251
252
  it, and stops on any difference. The setup tool carries its package's SHA-256 and
252
253
  refuses any other. On a closed network, `--from` and mirrors are checked the same way.
254
+ Certificates are checked against the system's trust store. `--insecure`, for a
255
+ firewall that inspects TLS with a CA the server doesn't trust, checks none, and then
256
+ nothing shows the release is genuine; it is a command-line option only, never a setting,
257
+ so the update timer always checks. Trusting the firewall's CA is the better fix
258
+ ([A firewall that inspects TLS](install.md#a-firewall-that-inspects-tls)).
253
259
  * **Nothing installs by surprise.** The update timer is off until turned on, and even then
254
260
  installs a release by itself only if it changes nothing but the package and the
255
261
  settings, never nginx or the firewall. Settings are merged into the new template with
@@ -162,10 +162,11 @@ profiles. The bill also has:
162
162
  |---|---|---|---|
163
163
  | Monitor, 10 probes a second (its default) | 257 MB | 174 MB | 431 MB |
164
164
  | Monitor, 50 probes a second | 1.26 GB | 839 MB | 2.1 GB |
165
- | Diag | 219 MB | 128 MB | 347 MB |
165
+ | Diag, six rows (HTTP/2, WebSocket and UDP over both families) | 219 MB | 128 MB | 347 MB |
166
166
 
167
167
  So a month of one Monitor tab at its default rate costs the server about 7.7 GB sent,
168
- and a Diag tab 6.6 GB. A Monitor comparing two servers costs each the same.
168
+ and a Diag tab 6.6 GB. A Monitor comparing two servers costs each the same. Diag's
169
+ HTTP/1.1 and HTTP/3 rows add a request a second each, as its HTTP/2 rows make.
169
170
  * **Anything else on the server**: operating system updates, other sites behind the same
170
171
  nginx.
171
172
 
@@ -1,3 +1,3 @@
1
1
  """texas2step: web-centric throughput, latency, jitter and packet-loss measurement."""
2
2
 
3
- __version__ = "2.3.0"
3
+ __version__ = "2.4.0"
@@ -77,10 +77,10 @@ INLINE_SCRIPT = re.compile(r"<script(?![^>]*\bsrc=)[^>]*>(.*?)</script>", re.S |
77
77
 
78
78
  def server_origins(settings: Settings) -> list[str]:
79
79
  """The other servers the page reaches, for its Content-Security-Policy: each in the
80
- picker and this server's own IPv4-only and IPv6-only names, over HTTP and WebSocket."""
81
- urls = [settings.server_url_v4, settings.server_url_v6]
80
+ picker and this server's own single-family names, over HTTP and WebSocket."""
81
+ urls = settings.all_locations()[0].urls()
82
82
  for loc in settings.locations:
83
- urls += [loc.url, loc.url_v4, loc.url_v6]
83
+ urls += loc.urls()
84
84
  origins: list[str] = []
85
85
  for url in filter(None, urls):
86
86
  parts = urlsplit(url)
@@ -371,6 +371,7 @@ def cmd_config_add_location(args: argparse.Namespace) -> None:
371
371
  import shlex
372
372
 
373
373
  from . import config_edit
374
+ from .config import PROTOCOL_URLS
374
375
 
375
376
  location = {
376
377
  "id": args.id,
@@ -380,7 +381,9 @@ def cmd_config_add_location(args: argparse.Namespace) -> None:
380
381
  "url_v4": args.url_v4,
381
382
  "url_v6": args.url_v6,
382
383
  }
383
- if not all(location.values()):
384
+ basics = list(location)
385
+ location |= {key: getattr(args, key) for key in PROTOCOL_URLS}
386
+ if not all(location[key] for key in basics):
384
387
  try:
385
388
  server, own = _fetch_peer(args.url)
386
389
  except (httpx.HTTPError, ValueError) as exc:
@@ -393,8 +396,9 @@ def cmd_config_add_location(args: argparse.Namespace) -> None:
393
396
  print(f"Couldn't reach {args.url}; adding it with what was given.")
394
397
  for key in ("id", "name", "location"):
395
398
  location[key] = location[key] or server.get(key) or ""
396
- # Its single-family URLs, so the IP drop-down works for it here too.
397
- for key in ("url_v4", "url_v6"):
399
+ # Its single-family URLs, so the IP drop-down works for it here too, and those that
400
+ # serve one HTTP version, for Diag's rows.
401
+ for key in ("url_v4", "url_v6", *PROTOCOL_URLS):
398
402
  found = str(own.get(key) or "")
399
403
  if not location[key] and found.startswith(("https://", "http://")):
400
404
  location[key] = found
@@ -405,12 +409,30 @@ def cmd_config_add_location(args: argparse.Namespace) -> None:
405
409
  _apply_edit(args, lambda text: config_edit.add_location(text, location), again)
406
410
 
407
411
 
412
+ def _proxy(value: str) -> str:
413
+ from .config import proxy_problem
414
+
415
+ value = value.strip()
416
+ if why := proxy_problem(value):
417
+ raise argparse.ArgumentTypeError(why)
418
+ return value
419
+
420
+
408
421
  def cmd_update(args: argparse.Namespace) -> None:
409
422
  from . import update
410
423
  from .config import load_settings
411
424
 
412
- if args.auto and (args.check or args.release or args.allow_downgrade or args.source):
413
- sys.exit("texas2step update: --auto takes no other options")
425
+ if args.auto and (
426
+ args.check
427
+ or args.release
428
+ or args.allow_downgrade
429
+ or args.source
430
+ or args.proxy
431
+ or args.insecure
432
+ ):
433
+ sys.exit("texas2step update: --auto takes no other options (its proxy: update_proxy)")
434
+ if args.source and (args.proxy or args.insecure):
435
+ sys.exit("texas2step update: --from downloads nothing; leave out --proxy and --insecure")
414
436
  if args.release and args.source:
415
437
  sys.exit("texas2step update: --from installs the release in DIR; leave out --version")
416
438
  if args.allow_downgrade and not (args.release or args.source):
@@ -1237,6 +1259,10 @@ def build_parser() -> argparse.ArgumentParser:
1237
1259
  add_location.add_argument("--location", help="free text, e.g. 'Houston, TX'")
1238
1260
  add_location.add_argument("--url-v4", help="IPv4-only base URL")
1239
1261
  add_location.add_argument("--url-v6", help="IPv6-only base URL")
1262
+ add_location.add_argument("--url-v4-http1", help="IPv4-only base URL serving only HTTP/1.1")
1263
+ add_location.add_argument("--url-v4-http3", help="IPv4-only base URL that offers HTTP/3")
1264
+ add_location.add_argument("--url-v6-http1", help="IPv6-only base URL serving only HTTP/1.1")
1265
+ add_location.add_argument("--url-v6-http3", help="IPv6-only base URL that offers HTTP/3")
1240
1266
  settings_file(add_location)
1241
1267
  add_location.set_defaults(func=cmd_config_add_location)
1242
1268
 
@@ -1272,6 +1298,21 @@ def build_parser() -> argparse.ArgumentParser:
1272
1298
  help="with --version or --from: install an older release",
1273
1299
  )
1274
1300
  upd.add_argument("-y", "--yes", action="store_true", help="install without asking")
1301
+ upd.add_argument(
1302
+ "--proxy",
1303
+ type=_proxy,
1304
+ metavar="URL",
1305
+ help="download through this proxy, e.g. http://proxy.example.net:3128 "
1306
+ "(default: update_proxy, else https_proxy)",
1307
+ )
1308
+ upd.add_argument(
1309
+ "-k",
1310
+ "--insecure",
1311
+ action="store_true",
1312
+ help="check no certificate, as curl -k: for a firewall that inspects TLS with a CA "
1313
+ "this server doesn't trust. Nothing then shows the release is genuine; trusting "
1314
+ "that CA is better (docs/install.md)",
1315
+ )
1275
1316
  upd.add_argument(
1276
1317
  "--auto",
1277
1318
  action="store_true",
@@ -46,10 +46,23 @@ class Location:
46
46
  location: str = "" # free text, e.g. "Dallas, TX"
47
47
  url_v4: str = "" # optional IPv4-only hostname for forcing the address family
48
48
  url_v6: str = "" # optional IPv6-only hostname
49
+ # Optional single-family names that each serve one HTTP version, for Diag's HTTP/1.1
50
+ # and HTTP/3 rows; url_v4 and url_v6 are its HTTP/2 rows.
51
+ url_v4_http1: str = ""
52
+ url_v4_http3: str = ""
53
+ url_v6_http1: str = ""
54
+ url_v6_http3: str = ""
49
55
 
50
56
  def public(self) -> dict[str, str]:
51
57
  return dataclasses.asdict(self)
52
58
 
59
+ def urls(self) -> list[str]:
60
+ """Every base URL it may be reached at, empty where it isn't set."""
61
+ return [self.url, self.url_v4, self.url_v6, *(getattr(self, k) for k in PROTOCOL_URLS)]
62
+
63
+
64
+ PROTOCOL_URLS = ("url_v4_http1", "url_v4_http3", "url_v6_http1", "url_v6_http3")
65
+
53
66
 
54
67
  @dataclass(frozen=True)
55
68
  class Link:
@@ -59,6 +72,21 @@ class Link:
59
72
  url: str
60
73
 
61
74
 
75
+ def proxy_problem(url: str) -> str:
76
+ """Why ``url`` isn't a proxy to download through, or "": http:// or https://, a host,
77
+ and a port if it isn't the scheme's own."""
78
+ from urllib.parse import urlsplit
79
+
80
+ try:
81
+ parts = urlsplit(url)
82
+ parts.port # noqa: B018 - raises for a port that isn't a number
83
+ except ValueError as exc:
84
+ return f"{url!r} isn't a URL: {exc}"
85
+ if parts.scheme not in ("http", "https") or not parts.hostname:
86
+ return f"expected http://host:port or https://host:port, not {url!r}"
87
+ return ""
88
+
89
+
62
90
  @dataclass
63
91
  class Settings:
64
92
  # Identity of this server, shown in the UI and returned by /api/v1/info.
@@ -68,6 +96,11 @@ class Settings:
68
96
  # Optional single-family hostnames for this server (enables the IPv4/IPv6 switch).
69
97
  server_url_v4: str = ""
70
98
  server_url_v6: str = ""
99
+ # Optional single-family hostnames that each serve one HTTP version (Diag's rows).
100
+ server_url_v4_http1: str = ""
101
+ server_url_v4_http3: str = ""
102
+ server_url_v6_http1: str = ""
103
+ server_url_v6_http3: str = ""
71
104
 
72
105
  # Wire endpoint limits.
73
106
  max_download_bytes: int = 1 << 30
@@ -130,6 +163,9 @@ class Settings:
130
163
  # or a mirror that answers <update_url>/releases/latest the same way, on a web
131
164
  # server or in a directory (file:///opt/texas2step/mirror).
132
165
  update_url: str = "https://api.github.com/repos/robert-patrick-texas/texas2step"
166
+ # A proxy for its downloads, the update timer's too, such as
167
+ # "http://proxy.example.net:3128"; empty: https_proxy from the environment, if set.
168
+ update_proxy: str = ""
133
169
 
134
170
  # Internet-facing servers (docs/access.md). access_code asks visitors from outside
135
171
  # internal_networks for the service desk's code before they can test: "off", or how
@@ -224,6 +260,8 @@ class Settings:
224
260
  raise ValueError(f"brand_credit: expected one of {', '.join(CREDITS)}")
225
261
  if not self.update_url.startswith(("https://", "http://", "file:///")):
226
262
  raise ValueError("update_url: expected an https:// URL, or file:/// and a directory")
263
+ if self.update_proxy and (why := proxy_problem(self.update_proxy)):
264
+ raise ValueError(f"update_proxy: {why}")
227
265
  if self.access_code not in INTERVALS:
228
266
  raise ValueError(f"access_code: expected one of {', '.join(INTERVALS)}")
229
267
  try:
@@ -318,6 +356,7 @@ class Settings:
318
356
  location=self.server_location,
319
357
  url_v4=self.server_url_v4,
320
358
  url_v6=self.server_url_v6,
359
+ **{key: getattr(self, f"server_{key}") for key in PROTOCOL_URLS},
321
360
  )
322
361
  return [me, *[loc for loc in self.locations if loc.id != self.server_id]]
323
362
 
@@ -20,10 +20,10 @@ import typing
20
20
  from dataclasses import dataclass, field
21
21
  from typing import Any
22
22
 
23
- from .config import Settings, _coerce, parse_toml
23
+ from .config import PROTOCOL_URLS, Settings, _coerce, parse_toml
24
24
  from .config_merge import SETTING, TABLE, _tables, toml_value
25
25
 
26
- LOCATION_FIELDS = ("id", "name", "url", "location", "url_v4", "url_v6")
26
+ LOCATION_FIELDS = ("id", "name", "url", "location", "url_v4", "url_v6", *PROTOCOL_URLS)
27
27
 
28
28
 
29
29
  @dataclass