texas2step 2.2.4__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 (68) hide show
  1. {texas2step-2.2.4 → texas2step-2.4.0}/PKG-INFO +3 -3
  2. {texas2step-2.2.4 → texas2step-2.4.0}/README.md +2 -2
  3. {texas2step-2.2.4 → texas2step-2.4.0}/deploy/texas2step-update.service +2 -1
  4. {texas2step-2.2.4 → texas2step-2.4.0}/docs/access.md +114 -7
  5. {texas2step-2.2.4 → texas2step-2.4.0}/docs/api.md +5 -4
  6. {texas2step-2.2.4 → texas2step-2.4.0}/docs/configuration.md +59 -6
  7. {texas2step-2.2.4 → texas2step-2.4.0}/docs/install.md +147 -13
  8. {texas2step-2.2.4 → texas2step-2.4.0}/docs/methodology.md +35 -12
  9. {texas2step-2.2.4 → texas2step-2.4.0}/docs/roadmap.md +33 -3
  10. {texas2step-2.2.4 → texas2step-2.4.0}/docs/security.md +16 -4
  11. {texas2step-2.2.4 → texas2step-2.4.0}/docs/traffic.md +6 -3
  12. {texas2step-2.2.4 → texas2step-2.4.0}/src/texas2step/__init__.py +1 -1
  13. {texas2step-2.2.4 → texas2step-2.4.0}/src/texas2step/access.py +47 -20
  14. {texas2step-2.2.4 → texas2step-2.4.0}/src/texas2step/api/access.py +59 -15
  15. {texas2step-2.2.4 → texas2step-2.4.0}/src/texas2step/api/meta.py +6 -2
  16. {texas2step-2.2.4 → texas2step-2.4.0}/src/texas2step/api/wire.py +11 -5
  17. {texas2step-2.2.4 → texas2step-2.4.0}/src/texas2step/app.py +11 -8
  18. {texas2step-2.2.4 → texas2step-2.4.0}/src/texas2step/cli.py +234 -18
  19. {texas2step-2.2.4 → texas2step-2.4.0}/src/texas2step/cluster.py +18 -5
  20. {texas2step-2.2.4 → texas2step-2.4.0}/src/texas2step/config.py +53 -4
  21. {texas2step-2.2.4 → texas2step-2.4.0}/src/texas2step/config_edit.py +2 -2
  22. {texas2step-2.2.4 → texas2step-2.4.0}/src/texas2step/config_template.toml +9 -1
  23. {texas2step-2.2.4 → texas2step-2.4.0}/src/texas2step/lockouts.py +86 -8
  24. {texas2step-2.2.4 → texas2step-2.4.0}/src/texas2step/rtc.py +19 -5
  25. texas2step-2.4.0/src/texas2step/static/assets/app.css +1 -0
  26. texas2step-2.4.0/src/texas2step/static/assets/app.js +8 -0
  27. {texas2step-2.2.4 → texas2step-2.4.0}/src/texas2step/static/index.html +2 -2
  28. {texas2step-2.2.4 → texas2step-2.4.0}/src/texas2step/update.py +49 -7
  29. texas2step-2.2.4/src/texas2step/static/assets/app.css +0 -1
  30. texas2step-2.2.4/src/texas2step/static/assets/app.js +0 -8
  31. {texas2step-2.2.4 → texas2step-2.4.0}/.gitignore +0 -0
  32. {texas2step-2.2.4 → texas2step-2.4.0}/LICENSE.md +0 -0
  33. {texas2step-2.2.4 → texas2step-2.4.0}/deploy/nginx/texas2step-http.conf +0 -0
  34. {texas2step-2.2.4 → texas2step-2.4.0}/deploy/nginx/texas2step-log.conf +0 -0
  35. {texas2step-2.2.4 → texas2step-2.4.0}/deploy/nginx/texas2step-speedtest.conf +0 -0
  36. {texas2step-2.2.4 → texas2step-2.4.0}/deploy/nginx/texas2step.conf +0 -0
  37. {texas2step-2.2.4 → texas2step-2.4.0}/deploy/texas2step-update.timer +0 -0
  38. {texas2step-2.2.4 → texas2step-2.4.0}/deploy/texas2step.default +0 -0
  39. {texas2step-2.2.4 → texas2step-2.4.0}/deploy/texas2step.service +0 -0
  40. {texas2step-2.2.4 → texas2step-2.4.0}/docs/development.md +0 -0
  41. {texas2step-2.2.4 → texas2step-2.4.0}/docs/experience.md +0 -0
  42. {texas2step-2.2.4 → texas2step-2.4.0}/docs/images/hero-dark.jpg +0 -0
  43. {texas2step-2.2.4 → texas2step-2.4.0}/docs/images/results-dark.jpg +0 -0
  44. {texas2step-2.2.4 → texas2step-2.4.0}/docs/images/results-light.jpg +0 -0
  45. {texas2step-2.2.4 → texas2step-2.4.0}/docs/images/upload-light.jpg +0 -0
  46. {texas2step-2.2.4 → texas2step-2.4.0}/legacy/README.md +0 -0
  47. {texas2step-2.2.4 → texas2step-2.4.0}/pyproject.toml +0 -0
  48. {texas2step-2.2.4 → texas2step-2.4.0}/src/texas2step/__main__.py +0 -0
  49. {texas2step-2.2.4 → texas2step-2.4.0}/src/texas2step/api/__init__.py +0 -0
  50. {texas2step-2.2.4 → texas2step-2.4.0}/src/texas2step/api/measure.py +0 -0
  51. {texas2step-2.2.4 → texas2step-2.4.0}/src/texas2step/api/results.py +0 -0
  52. {texas2step-2.2.4 → texas2step-2.4.0}/src/texas2step/config_merge.py +0 -0
  53. {texas2step-2.2.4 → texas2step-2.4.0}/src/texas2step/engine.py +0 -0
  54. {texas2step-2.2.4 → texas2step-2.4.0}/src/texas2step/iface.py +0 -0
  55. {texas2step-2.2.4 → texas2step-2.4.0}/src/texas2step/logs.py +0 -0
  56. {texas2step-2.2.4 → texas2step-2.4.0}/src/texas2step/page.py +0 -0
  57. {texas2step-2.2.4 → texas2step-2.4.0}/src/texas2step/payload.py +0 -0
  58. {texas2step-2.2.4 → texas2step-2.4.0}/src/texas2step/quality.py +0 -0
  59. {texas2step-2.2.4 → texas2step-2.4.0}/src/texas2step/static/assets/swagger/LICENSE +0 -0
  60. {texas2step-2.2.4 → texas2step-2.4.0}/src/texas2step/static/assets/swagger/NOTICE +0 -0
  61. {texas2step-2.2.4 → texas2step-2.4.0}/src/texas2step/static/assets/swagger/swagger-ui-bundle.js +0 -0
  62. {texas2step-2.2.4 → texas2step-2.4.0}/src/texas2step/static/assets/swagger/swagger-ui-bundle.js.LICENSE.txt +0 -0
  63. {texas2step-2.2.4 → texas2step-2.4.0}/src/texas2step/static/assets/swagger/swagger-ui.css +0 -0
  64. {texas2step-2.2.4 → texas2step-2.4.0}/src/texas2step/static/favicon.svg +0 -0
  65. {texas2step-2.2.4 → texas2step-2.4.0}/src/texas2step/stats.py +0 -0
  66. {texas2step-2.2.4 → texas2step-2.4.0}/src/texas2step/store.py +0 -0
  67. {texas2step-2.2.4 → texas2step-2.4.0}/src/texas2step/traffic.py +0 -0
  68. {texas2step-2.2.4 → 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.2.4
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
@@ -18,7 +18,8 @@ no user names or passwords. The desk's own tools stay on your networks: saved re
18
18
  works out the same code from it, with nothing shared between them while they run.
19
19
  * **A code buys a pass.** The visitor enters the code once. The server answers with a
20
20
  pass, good for 12 hours (`access_pass_hours`), which the browser then sends with every
21
- request, to every server in the picker. A server with the same key accepts it.
21
+ request, to every server in the picker. A server with the same key accepts it. To end
22
+ every pass at once, see [Ending every pass](#ending-every-pass).
22
23
  * **The desk's tools stay inside.** Visitors from addresses in `internal_networks` need no
23
24
  code, and only they get History, the API tab, saved results and the code itself.
24
25
  Everyone else gets the Test, Monitor and Diag tabs.
@@ -88,7 +89,8 @@ To turn codes off again: `sudo texas2step config set access_code=off --write`, t
88
89
  | `access_timezone` | `America/New_York` | The time zone whose midnight starts a new code; the same on every server |
89
90
  | `access_words` | `""` | Your own word list; empty uses the built-in words |
90
91
  | `access_digits` | `2` | The digits that end a code: 2, 3 or 4 |
91
- | `access_pass_hours` | `12` | How long an entered code lets a browser keep testing |
92
+ | `access_pass_hours` | `12` | How long a pass lasts from when it was issued (1 to 168). Each server applies its own as passes are used, so a change applies to passes already given; use the same on every server. |
93
+ | `access_note` | `Contact the service desk for assistance.` | The line under the code box, such as how to reach the desk; `""` for none |
92
94
  | `access_key_file` | `/etc/texas2step/access.key` | The key |
93
95
  | `access_phrases_file` | `/etc/texas2step/access-phrases.toml` | [Standing phrases](#standing-phrases), if the file exists |
94
96
  | `internal_networks` | `[]` | Your own networks: no code, and the desk's tools. A list of IPv4 and IPv6 addresses and networks in CIDR form, mixed freely: `["192.168.0.0/16", "2001:db8::/32", "203.0.113.7"]`. An address alone is a single host. Bits past the prefix are ignored, so `10.2.1.30/24` means all of `10.2.1.0/24`. Give the addresses as the server sees them: staff who come in through your firewall's NAT arrive from its public address. |
@@ -112,8 +114,9 @@ tests until it changes, but for a short list, or a `fixed` code, consider
112
114
  `access_digits = 3` or `4`.
113
115
 
114
116
  **When it changes.** A new code starts at midnight in `access_timezone`. The previous
115
- code keeps working for 24 hours after the change, for a call that spans midnight. A
116
- `fixed` code changes only with a new key:
117
+ code keeps working for 24 hours after the change, for a call that spans midnight. To
118
+ change it before then, or to change a `fixed` code, [shuffle the codes](#shuffling-the-codes),
119
+ or make a new key:
117
120
 
118
121
  ```bash
119
122
  sudo texas2step access key --new
@@ -123,6 +126,42 @@ That makes a new key at once: every code and pass from the old one stops working
123
126
  the new key to the other servers as in step 1, and restart the service on each. Without
124
127
  `--yes`, it asks first.
125
128
 
129
+ ### Shuffling the codes
130
+
131
+ When a code has gone further than it should, shuffle the codes. The current code and the
132
+ previous one stop working at once, and a new one takes their place:
133
+
134
+ ```console
135
+ $ sudo texas2step access shuffle
136
+ Shuffle the codes? The current and previous codes stop working, and the desk reads the new one. [y/N] y
137
+ Codes shuffled here. Today's code is now copper.lantern.42; the codes before it don't work.
138
+ Passes already given keep working: add --end-passes to end them as well.
139
+ Other servers: sent to dallas, houston.
140
+ ```
141
+
142
+ A shuffle is a random value mixed into every code from then on. It is kept in
143
+ `access_lockouts_file`, so it needs no new key and no restart, and outlasts a restart.
144
+ Every code entered after it is checked against it, on every worker. The desk reads the
145
+ new code at the top of History, or with `sudo texas2step access show`, which also says
146
+ when the codes were shuffled. There is no previous code until the next change: at
147
+ midnight, the shuffled code becomes yesterday's and works for 24 hours as usual. Phrases
148
+ are not codes, so they keep working.
149
+
150
+ Every server must hold the same shuffle, or they give different codes. With
151
+ [servers that defend together](#servers-that-defend-together), it goes to every server in
152
+ `[[locations]]`, and each keeps the latest it is given. Without them, the command prints
153
+ the value for the others; run that on each:
154
+
155
+ ```bash
156
+ sudo texas2step access shuffle --to 3f9a0c7e12b4d856
157
+ ```
158
+
159
+ `access show`'s fingerprint includes the shuffle, so servers that agree show the same one.
160
+
161
+ Passes already given keep working. Add `--end-passes` to [end them](#ending-every-pass)
162
+ too, which has everyone outside enter the new code: the same as a new key, without
163
+ copying a key to every server.
164
+
126
165
  **Typing it.** Case and separators don't matter: `Maple River 42`, `maple-river-42` and
127
166
  `maple.river.42` are the same code, and `7` counts for `07`.
128
167
 
@@ -204,7 +243,8 @@ journalctl -u texas2step --grep 'access phrase'
204
243
  stays guessable: several words that don't belong together, such as
205
244
  `copper lantern harbor violet`, rather than `vip access`. texas2step takes any phrase
206
245
  you choose. To withdraw one, `sudo texas2step access phrase remove vip` on every server,
207
- and restart; passes it already bought last until they expire (`access_pass_hours`).
246
+ and restart. Passes it already bought last until they run out (`access_pass_hours`),
247
+ unless you [end every pass](#ending-every-pass).
208
248
  A new key doesn't change the phrases.
209
249
 
210
250
  A phrase buys the same pass as the day's code, so the visitor gets what any visitor
@@ -273,6 +313,30 @@ inside.
273
313
  Without `internal_networks`, every visitor needs a code, and anyone with one can read the
274
314
  saved results. `texas2step access show` warns about that.
275
315
 
316
+ ### Inside on one address family
317
+
318
+ A visitor with both IPv4 and IPv6 comes from two addresses, and `internal_networks` may
319
+ list only one of them: an office's IPv6 network, say, but not the NAT address its IPv4
320
+ leaves by. The page asks its own server, at the address it was opened at, whether the
321
+ code is needed, and the browser reaches that over either family. When the answer is no
322
+ but another address the page tests refuses it, the page asks for the code over itself,
323
+ in a box the visitor can put aside with **Not now**. That other address is this server's
324
+ IPv4-only or IPv6-only name ([IPv4 and IPv6](configuration.md#ipv4-and-ipv6)), or another
325
+ server in the picker. The pass the code buys works over both families and on every
326
+ server with the same key.
327
+
328
+ The box comes up by itself until the visitor puts it aside, which holds until the page
329
+ is loaded again. Meanwhile Test and Monitor say the function is restricted over that
330
+ address, with a button to enter the code, and Diag's rows for it say **Restricted**, with
331
+ the same button.
332
+ Diag then tries that address every 10 seconds instead of every second, and opens no
333
+ WebSocket there until the code is in. A server with `access_code = "off"` has no pass to
334
+ give, so its page doesn't ask: it only says which address wants a code.
335
+
336
+ A pass that hasn't run out but is refused anyway, as from a network blocked by hand
337
+ ([lockouts and blocks](#lockouts-and-blocks)), isn't asked for again by itself. To have
338
+ neither family asked, list both of a site's addresses in `internal_networks`.
339
+
276
340
  ## Lockouts and blocks
277
341
 
278
342
  Wrong codes count against the visitor's network, its IPv4 /24 or IPv6 /48, not its
@@ -377,6 +441,44 @@ every 30 minutes. One with 10,000 networks gets about 1.4 million a day:
377
441
  For a server open to the Internet, use `access_digits = 4`, and standing phrases of
378
442
  several unrelated words.
379
443
 
444
+ ## Ending every pass
445
+
446
+ A pass holds the time it was issued, signed with the key: `1793030400.q7GxN0x2rY8vLmKp3TfWcA9b`.
447
+ No server keeps a list of them. Each server checks a pass as it is used:
448
+
449
+ * The signature matches, so a server with the same key issued it.
450
+ * It was issued less than `access_pass_hours` ago, by this server's setting now. Lower
451
+ the setting, and restart, and passes already given end sooner; raise it, and they last
452
+ longer.
453
+ * It wasn't issued more than 5 minutes ahead of this server's clock.
454
+ * It was issued after passes were last ended.
455
+
456
+ To end every pass given so far, such as when a code or a phrase went further than it
457
+ should have:
458
+
459
+ ```console
460
+ $ sudo texas2step access passes --end
461
+ End every pass issued so far? Everyone testing from outside enters the code again. [y/N] y
462
+ Every pass issued before 2026-10-25 14:02 EDT is ended here, within seconds; tests running with one stop too.
463
+ Other servers: sent to dallas, houston.
464
+ ```
465
+
466
+ The time is kept in `access_lockouts_file`, beside the lockouts, so it needs no restart
467
+ and outlasts one. Each of the service's workers reads it within 5 seconds. From then on,
468
+ a pass issued before it is refused as if there were none (`401`), and the WebSockets and
469
+ UDP sessions opened with one close within a few seconds. The page asks for the code
470
+ again. The codes and phrases still work, so everyone with the current code is back in at
471
+ once, with a new pass. Visitors from `internal_networks` need no pass, so nothing changes
472
+ for them.
473
+
474
+ With [servers that defend together](#servers-that-defend-together), the end goes to every
475
+ server in `[[locations]]`, and each keeps the later of its own and the one it is sent.
476
+ Without them, run the command on each server: until then, the others still take the
477
+ passes. `sudo texas2step access passes` says how long passes last here and when they were
478
+ last ended, and `access show` does too. To end the codes too, use
479
+ `sudo texas2step access shuffle --end-passes` ([Shuffling the codes](#shuffling-the-codes)).
480
+ A new key also ends every pass, and every code with it.
481
+
380
482
  ## Servers that defend together
381
483
 
382
484
  When a lockout begins on one server, the others can block that network too, so an
@@ -391,8 +493,9 @@ access_peer_networks = ["198.51.100.20", "2001:db8:20::20", "203.0.113.30"]
391
493
  * **What goes to the others.** A lockout here goes, as a block, to every server in
392
494
  `[[locations]]`, at once. While the attacker keeps trying here, it goes again every
393
495
  third of `access_lockout_minutes`, so the others' blocks don't run out first.
394
- `sudo texas2step access block` and `access lockouts --clear` go to every server too:
395
- `--clear` on any one of them lets a caller back in everywhere. The
496
+ `sudo texas2step access block`, `access lockouts --clear`, `access passes --end` and
497
+ `access shuffle` go to every server too: `--clear` on any one of them lets a caller
498
+ back in everywhere. The
396
499
  [API's blocks](#lockouts-and-blocks) stay on the server they are sent to. A block from
397
500
  `access block` ends passes on every server, as here; a lockout ends none anywhere. A
398
501
  server on an earlier version sends either as a lockout.
@@ -407,6 +510,10 @@ access_peer_networks = ["198.51.100.20", "2001:db8:20::20", "203.0.113.30"]
407
510
  compromised: a block from another server covers at most a /24 or a /48, never
408
511
  `internal_networks` or loopback, lasts at most a week, and isn't passed on. A server
409
512
  holds at most 1,000 of them. A wider block by hand stays on the server where it was set.
513
+ Another server can end every pass issued before its request, which at worst has
514
+ everyone enter the code again, but not set that time later than the receiving server's
515
+ clock allows, which would stamp new passes there too far ahead. It can shuffle the
516
+ codes, which at worst has the desk read the new one.
410
517
  * **Counts stay on each server.** Wrong codes count where they are entered, so with three
411
518
  servers an attacker gets up to about seven guesses, two at each and one more, before
412
519
  the whole cluster locks them out.
@@ -78,7 +78,8 @@ sending the offer. The offer must include data channels:
78
78
  profiles the session runs. A voice or video session counts toward a
79
79
  [traffic limit](traffic.md#monitors-call-profiles). The answer is
80
80
  `{"op":"profile","ok":true,"name":"voice"}`, or `"ok": false` with a `reason`: the
81
- server withholds video (`monitor_video = false`), or a traffic limit is reached, when
81
+ server withholds that profile (`monitor_voice` or `monitor_video` is `false`, as
82
+ `/api/v1/info`'s `monitor` says), or a traffic limit is reached, when
82
83
  the site's `message` and `url` come with it. Past a limit while a session runs, the
83
84
  server sends `{"op":"limit","message":…,"url":…}` unasked and from then on echoes only
84
85
  probes of up to 64 bytes.
@@ -91,7 +92,7 @@ every port in its `rtc_port_min`–`rtc_port_max` range is taken.
91
92
 
92
93
  | Method | Path | Returns |
93
94
  |---|---|---|
94
- | GET | `/api/v1/info` | name, version (left out for clients outside `internal_networks`), server identity, capabilities (`stamps`: the UDP probe can [stamp](#udp-probe-protocol) its echoes), limits, ICE servers, UI defaults (`one_stream`: whether a test downloads over one stream too, unless asked otherwise), `monitor` (`profile`: Monitor's until a visitor picks; `video`: whether the Video call profile is offered); with a [traffic limit](traffic.md), `traffic` (below) |
95
+ | GET | `/api/v1/info` | name, version (left out for clients outside `internal_networks`), server identity, capabilities (`stamps`: the UDP probe can [stamp](#udp-probe-protocol) its echoes), limits, ICE servers, UI defaults (`one_stream`: whether a test downloads over one stream too, unless asked otherwise), `monitor` (`profile`: Monitor's until a visitor picks; `voice`, `video`: whether the Voice call and Video call profiles are offered); with a [traffic limit](traffic.md), `traffic` (below) |
95
96
  | GET | `/api/v1/whoami` | client IP, port, family, scheme, HTTP version, user agent |
96
97
  | GET | `/api/v1/diag/http` | both ends of this HTTP connection, its HTTP version and TLS, the server's TCP RTT and clock (below) |
97
98
  | GET | `/api/v1/locations` | servers offered in the picker (this one first) |
@@ -187,13 +188,13 @@ clients that would need a pass.
187
188
 
188
189
  | Method | Path | Purpose |
189
190
  |---|---|---|
190
- | GET | `/api/v1/access?pass=<pass>` | `{"required", "desk"}`: whether this client needs a pass, and gets the desk's functions; with `pass`, also whether that pass is valid and when it expires |
191
+ | GET | `/api/v1/access?pass=<pass>` | `{"required", "desk", "codes", "note"}`: whether this client needs a pass, gets the desk's functions, and whether this server gives passes at all (`access_code` is on), and the site's line under the code box (`access_note`, empty for none); with `pass`, also whether that pass is valid and when it expires |
191
192
  | POST | `/api/v1/access` | `{"code": "maple.river.42"}` (any case and separators, or a standing phrase) returns `{"pass", "expires"}`. A wrong code is `403`. After `access_lockout_after` wrong codes in a row from one /24 or /48, every code from it gets that same `403`, unread, until `access_lockout_minutes` pass without one ([Lockouts and blocks](access.md#lockouts-and-blocks)). A body over 1 KB is `413` |
192
193
  | GET | `/api/v1/access/code` | The current code, when it changes, and the previous one while it still works; only from `internal_networks` |
193
194
  | GET | `/api/v1/access/blocks` | `{"lockouts": [{"network", "source", "wrong_codes", "since", "until", "by_hand"}], "counting"}` (`by_hand`: a block, which ends the passes used from the network too); only from `internal_networks` and the server itself |
194
195
  | POST | `/api/v1/access/blocks` | `{"network": "198.51.100.0/24", "minutes": 120}` locks a network out by hand, or keeps its lockout going, and ends the passes used from it; `minutes` defaults to `access_lockout_minutes`. One that overlaps `internal_networks`, or is wider than a /16 or a /32, is `400` |
195
196
  | DELETE | `/api/v1/access/blocks?network=<network>` | Ends the lockouts that overlap it (`all`: every one); returns `{"cleared": [...]}` |
196
- | POST | `/api/v1/access/peer` | For [servers that defend together](access.md#servers-that-defend-together): `{"from", "to", "action": "block" \| "clear" \| "check", "network", "minutes", "kind": "lockout" \| "block"}` (`kind`: a block set by hand, which ends passes there too; `lockout` when left out), signed in `X-Texas2step-Time`, `-Nonce` and `-Signature`. Only from `access_peer_networks`, with `access_share_lockouts` on; `404` to everyone else |
197
+ | POST | `/api/v1/access/peer` | For [servers that defend together](access.md#servers-that-defend-together): `{"from", "to", "action": "block" \| "clear" \| "check" \| "end-passes" \| "shuffle", "network", "minutes", "kind": "lockout" \| "block", "at", "value"}` (`kind`: a block set by hand, which ends passes there too; `lockout` when left out. `end-passes` ends every pass issued before `at`, in Unix seconds; `shuffle` mixes `value`, 16 hex digits, into the codes from `at`, the latest shuffle staying; neither `at` may be later than the receiving server's clock allows), signed in `X-Texas2step-Time`, `-Nonce` and `-Signature`. Only from `access_peer_networks`, with `access_share_lockouts` on; `404` to everyone else |
197
198
 
198
199
  ```bash
199
200
  pass=$(curl -s -X POST https://speedtest.example.net/texas2step/api/v1/access \
@@ -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=` |
@@ -38,17 +39,20 @@ file up to date with the new version's template and keeps your values; see
38
39
  | `page_test` / `page_monitor` / `page_diag` / `page_history` / `page_api` | `true` | Show that tab of the web UI. Any can be hidden, but not all. A hidden page's address opens the first page shown. The API stays on: `results_enabled` and `measure_enabled` turn parts of it off, and `/api/docs` stays reachable without the API tab. |
39
40
  | `default_streams` / `default_seconds` / `default_packets` | 4 / 10 / 500 | Defaults advertised by `/api/v1/info` |
40
41
  | `monitor_profile` | `path` | Monitor's profile until a visitor picks one: `path` (small probes, to follow the path), `voice` or `video` (a call's packets, scored every 10 seconds); see [Live monitor](methodology.md#live-monitor) |
41
- | `monitor_video` | `true` | Offer Monitor's Video call profile, about 1.4 Mb/s each way while a tab runs it. Voice and video count toward a [traffic limit](traffic.md#monitors-call-profiles). |
42
+ | `monitor_voice` | `true` | Offer Monitor's Voice call profile, about 150 kb/s each way while a tab runs it. With `false`, the page shows no Voice call button and the server refuses the profile. |
43
+ | `monitor_video` | `true` | Offer Monitor's Video call profile, about 1.4 Mb/s each way while a tab runs it. With `false`, the page shows no Video call button and the server refuses the profile. With both `false`, Monitor runs Path only, and shows no profile switch. Voice and video count toward a [traffic limit](traffic.md#monitors-call-profiles). |
42
44
  | `default_one_stream` | `true` | Whether a test also downloads over [one stream](methodology.md#one-stream), unless the visitor chooses in Test options or the command line with `--one-stream` or `--no-one-stream`. It can add up to half again to a test's traffic, so a server whose traffic is billed may want `false`; see [Traffic limits](traffic.md#what-a-test-moves). |
43
45
  | `cors_origins` | `["*"]` | Origins allowed to call the API from a browser |
44
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 |
45
47
  | `debug` | `false` | Also log every request and the UDP probe's WebRTC detail; see [Logging](#logging) |
46
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. |
47
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) |
48
51
  | `access_timezone` | `America/New_York` | The time zone whose midnight starts a new code |
49
52
  | `access_words` | `""` | A file of your own words for codes, one entry per line; empty uses the built-in words |
50
53
  | `access_digits` | 2 | The digits that end a code: 2, 3 or 4 |
51
- | `access_pass_hours` | 12 | How long an entered code lets a browser keep testing |
54
+ | `access_pass_hours` | 12 | How long a pass lasts from when it was issued; applied as passes are used, so a change applies to passes already given. See [Ending every pass](access.md#ending-every-pass). |
55
+ | `access_note` | `Contact the service desk for assistance.` | The line under the code box, such as how to reach the desk; `""` for none |
52
56
  | `access_key_file` | `/etc/texas2step/access.key` | The key codes come from; the same on every server of an organization |
53
57
  | `access_phrases_file` | `/etc/texas2step/access-phrases.toml` | Standing phrases that work as codes, if the file exists; see [Standing phrases](access.md#standing-phrases) |
54
58
  | `access_lockout_after` | 3 | Wrong codes in a row from one /24 or /48 that lock it out of entering codes; see [Lockouts and blocks](access.md#lockouts-and-blocks) |
@@ -98,10 +102,12 @@ sudo systemctl restart texas2step
98
102
  `[[brand_links]]` and `[[brand_footer_links]]` in the file, or use `add-location`.
99
103
  * **`config add-location URL`** lists another texas2step server in the location picker.
100
104
  It asks that server for its id, name and location (`/api/v1/info`), and for its
101
- IPv4-only and IPv6-only URLs (its own entry in `/api/v1/locations`), using the
102
- system's trusted certificates. Give `--id`, `--name`, `--location`, `--url-v4` and
103
- `--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
104
- 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.
105
111
  * **`config merge`** brings the whole file up to date after an upgrade; see
106
112
  [Upgrade](install.md#upgrade).
107
113
 
@@ -204,6 +210,8 @@ url = "https://houston.example.net/texas2step"
204
210
  location = "Houston, TX"
205
211
  url_v4 = "https://v4.houston.example.net/texas2step" # optional: A record only
206
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
207
215
  ```
208
216
 
209
217
  Each listed server must allow the page's origin in its `cors_origins` (the default `*`
@@ -241,6 +249,51 @@ set these and check each name's DNS records. For the other servers in the picker
241
249
  `texas2step config add-location` and the setup tool's `--peer` fill them in from the
242
250
  other server.
243
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
+
244
297
  ## Logging
245
298
 
246
299
  The service logs to the journal (`journalctl -u texas2step -f`), and by default only what
@@ -51,7 +51,8 @@ To do the same by hand, follow steps 1 to 5 below instead.
51
51
  ```
52
52
 
53
53
  It logs to `texas2step-install.log` beside itself. When it finishes, the service
54
- answers both on `127.0.0.1:8080` and through nginx, and it prints the address to open.
54
+ answers both on `127.0.0.1:8080` (or the `--port` you gave) and through nginx, and it
55
+ prints the address to open.
55
56
  You can run it again safely: it skips each step that is already done.
56
57
 
57
58
  What the check looks at, and what the script then does:
@@ -66,7 +67,7 @@ What the check looks at, and what the script then does:
66
67
  | Peers | Each `--peer URL` is asked who it is (`/api/v1/info`). A peer that can't be reached is left out, with the command to add it later. | `texas2step config add-location ... --write` |
67
68
  | nginx | nginx is installed and running, its configuration passes `nginx -t`, and it loads `conf.d/*.conf`. It finds your HTTPS site, and checks that nothing else on that site uses `/texas2step/`. If texas2step is already published, nginx is left alone. | Adds `include snippets/texas2step.conf;` after the site's `server_name` line, runs `nginx -t` and reloads. The file is backed up to `/var/backups/texas2step/` first, and put back if the test fails. |
68
69
  | UDP | The probe's port range: the one you set, or 61000–61999. It checks this range against the firewall and the kernel's ephemeral ports. | Pins the range in the settings. Opens it in ufw or firewalld if one of them is active. |
69
- | Port 8080 | Nothing else listens there | |
70
+ | Port | Nothing else listens on texas2step's TCP port: 8080, `LISTEN_PORT` in `/etc/default/texas2step`, or `--port`. nginx's `upstream` in `/etc/nginx/conf.d/texas2step.conf` points at that port. | With `--port`, sets `LISTEN_PORT` and the `upstream` before the package is installed, so the service never starts on 8080. An `upstream` that points elsewhere is pointed at the port. |
70
71
 
71
72
  Options:
72
73
 
@@ -79,6 +80,7 @@ Options:
79
80
  | `--path PATH` | Publish texas2step at `PATH` instead of `/texas2step/`, e.g. `/speedtest`. The check moves the package's snippet to that path and shows it in the install script, which writes it as `snippets/texas2step-at-speedtest.conf` and includes that. Each later run writes it again from the new package. Use the same path in `--url-v4` and `--url-v6`. |
80
81
  | `--no-nginx` | Install the service only, and publish it yourself |
81
82
  | `--udp-ports MIN-MAX` | The probe's UDP range, e.g. `61000-61999` |
83
+ | `--port PORT` | The TCP port texas2step listens on, on `127.0.0.1` behind nginx, when another program needs 8080. Choose one from 1024 to 32767. Later runs and `texas2step update` keep it. See [Another port](#another-port). |
82
84
  | `--url-v4 URL`, `--url-v6 URL` | This server's IPv4-only and IPv6-only base URLs, for the header's IP drop-down; see [IPv4 and IPv6](configuration.md#ipv4-and-ipv6). The check looks up each name: it should have only an A record (or only AAAA), pointing at this server. After the install, the script checks that nginx answers for each name. |
83
85
  | `--no-firewall` | Leave the firewall alone; the report lists the rule to add |
84
86
  | `--allow-downgrade` | Allow installing an older version than the one installed |
@@ -128,6 +130,32 @@ yourself.
128
130
  To make the second server by cloning the first's virtual machine instead, see
129
131
  [Clone a server](#clone-a-server).
130
132
 
133
+ ### Another port
134
+
135
+ texas2step listens on `127.0.0.1:8080`, and nginx reaches it there through the
136
+ `upstream` in `/etc/nginx/conf.d/texas2step.conf`. When another program needs 8080,
137
+ give the setup tool another port, the same way for a new install or an installed server:
138
+
139
+ ```bash
140
+ sudo ./texas2step-setup --port 8081
141
+ sudo ./texas2step-install.sh
142
+ ```
143
+
144
+ The install script sets `LISTEN_PORT=8081` in `/etc/default/texas2step` and points the
145
+ `upstream` at `127.0.0.1:8081`, keeping a dated copy of each file it changes in
146
+ `/var/backups/texas2step/`. It does this before installing the package, so the service
147
+ never starts on 8080, even on a new install. Then it restarts texas2step, reloads nginx
148
+ and checks both.
149
+
150
+ Choose a port from 1024 to 32767. texas2step runs as its own user, which can't listen
151
+ below 1024, and Linux takes the ports of outgoing connections from 32768 up. If the port
152
+ is in use, the check says by what. Both files are kept on upgrades, and the setup tool
153
+ and `texas2step update` read the port from `LISTEN_PORT`. When a new version changes the
154
+ `upstream` file, the update installs the new one with your port in it.
155
+
156
+ If you changed `LISTEN_PORT` by hand and not the `upstream`, the next run of the setup
157
+ tool points the `upstream` at it.
158
+
131
159
  ## 1. Install the package
132
160
 
133
161
  Download the newest `.deb` from the
@@ -239,6 +267,78 @@ That is realistic for modern web traffic, but it doesn't show how several TCP fl
239
267
  behave. To make "4 streams" mean four TCP connections, publish texas2step in a server
240
268
  block without `http2 on` (a separate hostname or port).
241
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
+
242
342
  ## 3. Configure
243
343
 
244
344
  Edit `/etc/texas2step/config.toml`, then run `sudo systemctl restart texas2step`. The
@@ -264,12 +364,11 @@ choose the default theme (Light, Dark, America, Energy, Federal, Military or Tex
264
364
  that site directly. Sites can also measure each other with `POST /api/v1/measure/full`,
265
365
  but only toward listed locations.
266
366
 
267
- **Listen address and workers.** These are set in `/etc/default/texas2step`. If you move
268
- the service off `127.0.0.1:8080`, change the `upstream` in
269
- `/etc/nginx/conf.d/texas2step.conf` to match. More workers help on multi-gigabit links,
270
- where Python's per-connection CPU cost is the limit. Each worker keeps its own UDP
271
- sessions, which is fine, because a session lives entirely in the worker that answered
272
- it.
367
+ **Listen address and workers.** These are set in `/etc/default/texas2step`. To move the
368
+ service to another port, see [Another port](#another-port). More workers help on
369
+ multi-gigabit links, where Python's per-connection CPU cost is the limit. Each worker
370
+ keeps its own UDP sessions, which is fine, because a session lives entirely in the
371
+ worker that answered it.
273
372
 
274
373
  ## 4. Firewall and UDP
275
374
 
@@ -426,7 +525,38 @@ The options:
426
525
  `--allow-downgrade` for an older one, to go back to it.
427
526
  * `--from <directory>` installs a release whose two files are already on the server,
428
527
  without downloading anything.
429
- * 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.
430
560
 
431
561
  Where the server can't reach GitHub, put a release's files on it, or point it at a
432
562
  mirror: see [Without access to GitHub](#without-access-to-github). On a server whose texas2step
@@ -481,13 +611,17 @@ OnCalendar=
481
611
  OnCalendar=Sun 03:00
482
612
  ```
483
613
 
484
- 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.
485
616
 
486
- ```ini
487
- [Service]
488
- Environment=https_proxy=http://proxy.example.net:3128
617
+ ```bash
618
+ sudo texas2step config set 'update_proxy="http://proxy.example.net:3128"' --write
489
619
  ```
490
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
+
491
625
  To turn unattended updates off again: `sudo systemctl disable --now texas2step-update.timer`.
492
626
 
493
627
  ### Without access to GitHub