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.
- {texas2step-2.2.4 → texas2step-2.4.0}/PKG-INFO +3 -3
- {texas2step-2.2.4 → texas2step-2.4.0}/README.md +2 -2
- {texas2step-2.2.4 → texas2step-2.4.0}/deploy/texas2step-update.service +2 -1
- {texas2step-2.2.4 → texas2step-2.4.0}/docs/access.md +114 -7
- {texas2step-2.2.4 → texas2step-2.4.0}/docs/api.md +5 -4
- {texas2step-2.2.4 → texas2step-2.4.0}/docs/configuration.md +59 -6
- {texas2step-2.2.4 → texas2step-2.4.0}/docs/install.md +147 -13
- {texas2step-2.2.4 → texas2step-2.4.0}/docs/methodology.md +35 -12
- {texas2step-2.2.4 → texas2step-2.4.0}/docs/roadmap.md +33 -3
- {texas2step-2.2.4 → texas2step-2.4.0}/docs/security.md +16 -4
- {texas2step-2.2.4 → texas2step-2.4.0}/docs/traffic.md +6 -3
- {texas2step-2.2.4 → texas2step-2.4.0}/src/texas2step/__init__.py +1 -1
- {texas2step-2.2.4 → texas2step-2.4.0}/src/texas2step/access.py +47 -20
- {texas2step-2.2.4 → texas2step-2.4.0}/src/texas2step/api/access.py +59 -15
- {texas2step-2.2.4 → texas2step-2.4.0}/src/texas2step/api/meta.py +6 -2
- {texas2step-2.2.4 → texas2step-2.4.0}/src/texas2step/api/wire.py +11 -5
- {texas2step-2.2.4 → texas2step-2.4.0}/src/texas2step/app.py +11 -8
- {texas2step-2.2.4 → texas2step-2.4.0}/src/texas2step/cli.py +234 -18
- {texas2step-2.2.4 → texas2step-2.4.0}/src/texas2step/cluster.py +18 -5
- {texas2step-2.2.4 → texas2step-2.4.0}/src/texas2step/config.py +53 -4
- {texas2step-2.2.4 → texas2step-2.4.0}/src/texas2step/config_edit.py +2 -2
- {texas2step-2.2.4 → texas2step-2.4.0}/src/texas2step/config_template.toml +9 -1
- {texas2step-2.2.4 → texas2step-2.4.0}/src/texas2step/lockouts.py +86 -8
- {texas2step-2.2.4 → texas2step-2.4.0}/src/texas2step/rtc.py +19 -5
- texas2step-2.4.0/src/texas2step/static/assets/app.css +1 -0
- texas2step-2.4.0/src/texas2step/static/assets/app.js +8 -0
- {texas2step-2.2.4 → texas2step-2.4.0}/src/texas2step/static/index.html +2 -2
- {texas2step-2.2.4 → texas2step-2.4.0}/src/texas2step/update.py +49 -7
- texas2step-2.2.4/src/texas2step/static/assets/app.css +0 -1
- texas2step-2.2.4/src/texas2step/static/assets/app.js +0 -8
- {texas2step-2.2.4 → texas2step-2.4.0}/.gitignore +0 -0
- {texas2step-2.2.4 → texas2step-2.4.0}/LICENSE.md +0 -0
- {texas2step-2.2.4 → texas2step-2.4.0}/deploy/nginx/texas2step-http.conf +0 -0
- {texas2step-2.2.4 → texas2step-2.4.0}/deploy/nginx/texas2step-log.conf +0 -0
- {texas2step-2.2.4 → texas2step-2.4.0}/deploy/nginx/texas2step-speedtest.conf +0 -0
- {texas2step-2.2.4 → texas2step-2.4.0}/deploy/nginx/texas2step.conf +0 -0
- {texas2step-2.2.4 → texas2step-2.4.0}/deploy/texas2step-update.timer +0 -0
- {texas2step-2.2.4 → texas2step-2.4.0}/deploy/texas2step.default +0 -0
- {texas2step-2.2.4 → texas2step-2.4.0}/deploy/texas2step.service +0 -0
- {texas2step-2.2.4 → texas2step-2.4.0}/docs/development.md +0 -0
- {texas2step-2.2.4 → texas2step-2.4.0}/docs/experience.md +0 -0
- {texas2step-2.2.4 → texas2step-2.4.0}/docs/images/hero-dark.jpg +0 -0
- {texas2step-2.2.4 → texas2step-2.4.0}/docs/images/results-dark.jpg +0 -0
- {texas2step-2.2.4 → texas2step-2.4.0}/docs/images/results-light.jpg +0 -0
- {texas2step-2.2.4 → texas2step-2.4.0}/docs/images/upload-light.jpg +0 -0
- {texas2step-2.2.4 → texas2step-2.4.0}/legacy/README.md +0 -0
- {texas2step-2.2.4 → texas2step-2.4.0}/pyproject.toml +0 -0
- {texas2step-2.2.4 → texas2step-2.4.0}/src/texas2step/__main__.py +0 -0
- {texas2step-2.2.4 → texas2step-2.4.0}/src/texas2step/api/__init__.py +0 -0
- {texas2step-2.2.4 → texas2step-2.4.0}/src/texas2step/api/measure.py +0 -0
- {texas2step-2.2.4 → texas2step-2.4.0}/src/texas2step/api/results.py +0 -0
- {texas2step-2.2.4 → texas2step-2.4.0}/src/texas2step/config_merge.py +0 -0
- {texas2step-2.2.4 → texas2step-2.4.0}/src/texas2step/engine.py +0 -0
- {texas2step-2.2.4 → texas2step-2.4.0}/src/texas2step/iface.py +0 -0
- {texas2step-2.2.4 → texas2step-2.4.0}/src/texas2step/logs.py +0 -0
- {texas2step-2.2.4 → texas2step-2.4.0}/src/texas2step/page.py +0 -0
- {texas2step-2.2.4 → texas2step-2.4.0}/src/texas2step/payload.py +0 -0
- {texas2step-2.2.4 → texas2step-2.4.0}/src/texas2step/quality.py +0 -0
- {texas2step-2.2.4 → texas2step-2.4.0}/src/texas2step/static/assets/swagger/LICENSE +0 -0
- {texas2step-2.2.4 → texas2step-2.4.0}/src/texas2step/static/assets/swagger/NOTICE +0 -0
- {texas2step-2.2.4 → texas2step-2.4.0}/src/texas2step/static/assets/swagger/swagger-ui-bundle.js +0 -0
- {texas2step-2.2.4 → texas2step-2.4.0}/src/texas2step/static/assets/swagger/swagger-ui-bundle.js.LICENSE.txt +0 -0
- {texas2step-2.2.4 → texas2step-2.4.0}/src/texas2step/static/assets/swagger/swagger-ui.css +0 -0
- {texas2step-2.2.4 → texas2step-2.4.0}/src/texas2step/static/favicon.svg +0 -0
- {texas2step-2.2.4 → texas2step-2.4.0}/src/texas2step/stats.py +0 -0
- {texas2step-2.2.4 → texas2step-2.4.0}/src/texas2step/store.py +0 -0
- {texas2step-2.2.4 → texas2step-2.4.0}/src/texas2step/traffic.py +0 -0
- {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.
|
|
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** (
|
|
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** (
|
|
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:
|
|
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
|
|
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.
|
|
116
|
-
`fixed` code
|
|
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
|
|
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
|
|
395
|
-
`--clear` on any one of them lets a caller
|
|
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
|
|
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
|
|
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,
|
|
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
|
-
| `
|
|
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
|
|
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
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
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
|
|
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
|
|
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`.
|
|
268
|
-
|
|
269
|
-
|
|
270
|
-
|
|
271
|
-
|
|
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
|
-
*
|
|
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,
|
|
614
|
+
Behind a proxy, set it in the settings, and restart nothing: the timer reads them on each
|
|
615
|
+
run.
|
|
485
616
|
|
|
486
|
-
```
|
|
487
|
-
|
|
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
|