better permission warnings

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

.gitea/workflows/release.yaml

@@ -0,0 +1,66 @@
+# Builds the .deb when a version tag is pushed and publishes it as a release,
+# with that version's CHANGELOG.md section as the release notes. To release,
+# set VERSION and CHANGELOG.md, commit, then:
+#   git tag v$(cat VERSION) && git push origin v$(cat VERSION)
+name: release
+
+on:
+  push:
+    tags: ['v*']
+
+jobs:
+  deb:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Check that the tag matches VERSION
+        run: |
+          if [ "$GITHUB_REF_NAME" != "v$(cat VERSION)" ]; then
+            echo "tag $GITHUB_REF_NAME doesn't match VERSION ($(cat VERSION))"
+            exit 1
+          fi
+
+      - name: Install build tools
+        env:
+          DEBIAN_FRONTEND: noninteractive
+        run: |
+          SUDO=$(command -v sudo || true)
+          $SUDO apt-get update -qq
+          $SUDO apt-get install -y -qq make python3 dpkg curl shellcheck python3-pyflakes
+
+      - name: Build (make check runs first)
+        run: make deb
+
+      - name: Publish the release
+        env:
+          GITEA_URL: ${{ gitea.server_url }}
+          GITEA_REPO: ${{ gitea.repository }}
+          # The job's own token; set a RELEASE_TOKEN secret instead if it isn't allowed to write releases
+          GITEA_TOKEN: ${{ secrets.RELEASE_TOKEN || secrets.GITEA_TOKEN }}
+        run: python3 packaging/gitea-release.py "$GITHUB_REF_NAME" build/*.deb
+
+      # Gitea's Debian registry, as an apt repository:
+      #   deb <server>/api/packages/<owner>/debian stable main
+      - name: Publish to the apt repository
+        env:
+          POOL: ${{ gitea.server_url }}/api/packages/${{ gitea.repository_owner }}/debian/pool/stable/main
+          # The job's own token; set a PACKAGE_TOKEN secret (scope write:package) if it isn't allowed to
+          TOKEN: ${{ secrets.PACKAGE_TOKEN || secrets.GITEA_TOKEN }}
+        run: |
+          deb=$(echo build/*.deb)
+          upload() {
+            curl -sS -o response.txt -w '%{http_code}' --user "$GITHUB_ACTOR:$TOKEN" \
+              --upload-file "$deb" "$POOL/upload"
+          }
+          status=$(upload)
+          if [ "$status" = 409 ]; then
+            # This version is there already (the tag was pushed again): replace it
+            curl -sS -f --user "$GITHUB_ACTOR:$TOKEN" -X DELETE \
+              "$POOL/terraria-server-manager/$(cat VERSION)/all"
+            status=$(upload)
+          fi
+          if [ "$status" != 201 ]; then
+            echo "upload failed: HTTP $status"; cat response.txt; echo; exit 1
+          fi
+          echo "published $(basename "$deb") to $POOL"

.gitignore

@@ -1,2 +1,3 @@
 build/
 *.deb
+__pycache__/

CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changelog
 
+## Unreleased
+
+- `list` warns about zips in `dist/` that the `terraria` user can't read (e.g. copied in with `scp -p` from a private file), and `info` lists them as `unreadable_zip=`. A server that fails to install because of one now says how to fix it (`sudo chmod 644 <zip>`) instead of just "cannot read", and a missing zip is reported as not found.
+
 ## 0.0.11 - 2026-09-30
 
 - The servers now log to their own journal (systemd log namespace `terraria`), which members of the `terraria` group can read. `attach` and `cmd` therefore show output to `terraria` group members without `sudo` or the `systemd-journal` group, and without access to the rest of the system's logs. Read it directly with `journalctl --namespace=terraria -u terraria@<name>`.
@@ -11,7 +15,7 @@
 - `list` has a new `BOOT` column showing whether each server starts at boot (`enabled`, `disabled`, or e.g. `masked`).
 - Manage other hosts, like LXD/Incus remotes:
   - `sudo terractl daemon enable` starts `terractld.service`, a daemon other hosts connect to (HTTPS, TCP port 7776; `TERRACTL_LISTEN` in `/etc/default/terractl` changes it). It's off until enabled. `daemon disable` and `daemon status` turn it off and show its state.
-  - `sudo terractl daemon trust add <name>` creates a one-time token for a computer, valid for 24 hours; `daemon trust list` and `daemon trust remove <name>` show and revoke access. On that computer, `terractl remote add <remote> <token>` adds the host; `remote list` and `remote remove` manage remotes, which are stored per user.
+  - `daemon enable` prints a command with a one-time token (valid for 24 hours); running it on another computer, `terractl remote add <token>`, adds the host as a remote named after its hostname (or `remote add <name> <token>`). `sudo terractl daemon token` makes tokens for more computers, `daemon status` lists the trusted ones, and `daemon revoke <name>` removes one. Adding a host again replaces the old remote, e.g. after a revoke. `remote list` and `remote remove` manage remotes, which are stored per user.
   - `terractl --host <remote> <command>` runs any command on a remote, including `attach`, `watch` and `export`/`import`/`mods add` with files from your computer. The daemon runs it as root there, with messages adjusted to `terractl --host <remote> ...`.
   - `terractl copy` and `terractl move` copy, move or rename instances, on one host or between hosts (`[<remote>:]<name>`). Paths and ports follow the destination's settings, and a missing server zip is copied along. `move` stops the source first, starts it again if the transfer fails, and starts the moved instance where it was running before.
   - Security: the token carries the daemon's certificate fingerprint, which the client checks on every connection; each computer gets its own key, and the daemon stores only hashes. The daemon runs as root with systemd sandboxing.

README.md

@@ -32,7 +32,19 @@ sudo terractl attach calamity
 
 ## Install
 
-Download the `.deb` from the releases page, then:
+From the apt repository, which also brings updates with `sudo apt upgrade`:
+
+```bash
+sudo install -d -m 0755 /etc/apt/keyrings
+sudo curl -fsSL https://gitea.adbraun.lol/api/packages/adam/debian/repository.key \
+  -o /etc/apt/keyrings/terraria-server-manager.asc
+echo "deb [signed-by=/etc/apt/keyrings/terraria-server-manager.asc] https://gitea.adbraun.lol/api/packages/adam/debian stable main" |
+  sudo tee /etc/apt/sources.list.d/terraria-server-manager.list
+sudo apt update
+sudo apt install terraria-server-manager
+```
+
+Or download the `.deb` from the releases page, then:
 
 ```bash
 sudo apt install ./terraria-server-manager_<version>_all.deb
@@ -69,7 +81,13 @@ make check     # bash -n on all scripts, plus shellcheck if installed
 make deb       # build/terraria-server-manager_<version>_all.deb
 ```
 
-To release: update `VERSION` and `CHANGELOG.md`, run `make deb`, and attach the `.deb` to the release.
+To release, update `VERSION` and `CHANGELOG.md`, commit, and push a matching tag:
+
+```bash
+git tag v$(cat VERSION) && git push origin v$(cat VERSION)
+```
+
+The `release` workflow (`.gitea/workflows/release.yaml`, Gitea Actions) then builds the `.deb`, publishes it as a release with that version's changelog section as the notes, and adds it to the apt repository. It needs a runner with the `ubuntu-latest` label. To build a package by hand instead, run `make deb`.
 
 ## Disclaimer
 

bin/terractl

@@ -96,13 +96,12 @@ Other hosts:
                                            copy an instance, on this host or between hosts
   move [<remote>:]<name> [<remote>:][<new name>] [--with-server]
                                            move (or rename) an instance; stops it while moving
-  remote add <name> <token>                add a host to manage (token from 'daemon trust add')
+  remote add [<name>] <token> [--address <host>[:<port>]]
-  remote add <name> <address> [<token>]    ... when the token's addresses don't work from here
+                                           add a host to manage (token from its 'daemon enable')
   remote list | remote remove <name>       show or forget remotes
   daemon enable|disable|status             let other hosts manage this one (terractld.service)
-  daemon trust add <client>                create a one-time token for a computer to join
+  daemon token                             a one-time token for another computer to add this host
-  daemon trust list | trust remove <client>
+  daemon revoke <name>                     take a computer's access away
-                                           show or revoke computers that may manage this host
 
 Used by terraria@.service:
   journal-access                           let the terraria group read the servers' journal
@@ -230,7 +229,8 @@ install_server() {
 
   command -v unzip >/dev/null || die "unzip is not installed"
   zip=$(pick_zip)
-  [[ -r $zip ]] || die "cannot read $zip"
+  [[ -e $zip ]] || die "$zip not found"
+  [[ -r $zip ]] || die "the '$SVC_USER' user can't read $zip; fix it with: sudo chmod 644 $zip"
   log "installing $TYPE from $(basename "$zip") into $dir/server"
 
   EXTRACT_TMP=$(mktemp -d "$dir/.extract.XXXXXX")
@@ -1050,6 +1050,36 @@ cmd_enable() {
   fi
 }
 
+# Can the service user read <file>? Worked out from the file's owner, group and
+# mode, because whoever runs terractl may be someone else.
+svc_can_read() {
+  local owner group mode
+  read -r owner group mode < <(stat -c '%U %G %a' "$1" 2>/dev/null) || return 1
+  if [[ $owner == "$SVC_USER" ]]; then (( 8#$mode & 0400 ))
+  elif [[ $group == "$SVC_USER" ]]; then (( 8#$mode & 0040 ))
+  else (( 8#$mode & 0004 )); fi
+}
+
+# Zips in dist/ the servers can't unpack, e.g. copied in with 'scp -p' from a
+# private file. Instances fail on their first start with such a zip.
+unreadable_zips() {
+  local f
+  for f in "$DIST_DIR"/*.zip; do
+    if [[ -f $f ]] && ! svc_can_read "$f"; then echo "$f"; fi
+  done
+}
+
+zip_warning() {
+  local where=""
+  local -a bad=()
+  mapfile -t bad < <(unreadable_zips)
+  [[ ${#bad[@]} -gt 0 ]] || return 0
+  if [[ -n ${TERRACTL_VIA:-} ]]; then where=" (on $(hostname 2>/dev/null || echo that host))"; fi
+  log "warning: the '$SVC_USER' user can't read these zips, so servers can't be installed from them:"
+  printf '  %s\n' "${bad[@]}" >&2
+  log "fix it with$where: sudo chmod 644 ${bad[*]@Q}"
+}
+
 cmd_list() {
   local d n port boot state
   printf '%-20s %-11s %-6s %-9s %s\n' INSTANCE TYPE PORT BOOT STATE
@@ -1066,6 +1096,7 @@ cmd_list() {
       printf '%-20s %-11s %-6s %-9s %s\n' "$n" "$TYPE" "${port:--}" "${boot:--}" "$state"
     ) 2>/dev/null || printf '%-20s %s\n' "$n" "(cannot read config - try sudo)"
   done
+  zip_warning
 }
 
 cmd_reinstall() {
@@ -1102,6 +1133,7 @@ cmd_info() {
     for f in "$DIST_DIR"/*.zip; do
       if [[ -f $f ]]; then echo "dist_zip=$(basename "$f")"; fi
     done
+    while IFS= read -r f; do echo "unreadable_zip=$(basename "$f")"; done < <(unreadable_zips)
     for f in "$BASE_DIR"/*/instance.conf; do
       if [[ -f $f ]]; then echo "instance=$(basename "$(dirname "$f")")"; fi
     done

completions/bash/terractl

@@ -153,9 +153,7 @@ _terractl() {
             return ;;
         daemon)
             if (( cword == 2 )); then
-                _terractl_reply "enable disable status trust"
+                _terractl_reply "enable disable status token revoke"
-            elif (( cword == 3 )) && [[ ${words[2]} == trust ]]; then
-                _terractl_reply "add list remove"
             fi
             return ;;
     esac

docs/guide.md

@@ -100,13 +100,25 @@ The server can write only inside `instances/`. It reads `dist/` but can never ch
 
 ## Installation
 
-The package works on Debian 12 or newer and Ubuntu 22.04 or newer.
+The package works on Debian 12 or newer and Ubuntu 22.04 or newer. The easiest way is the apt repository, since `sudo apt upgrade` then keeps it up to date:
+
+```bash
+sudo install -d -m 0755 /etc/apt/keyrings
+sudo curl -fsSL https://gitea.adbraun.lol/api/packages/adam/debian/repository.key \
+  -o /etc/apt/keyrings/terraria-server-manager.asc
+echo "deb [signed-by=/etc/apt/keyrings/terraria-server-manager.asc] https://gitea.adbraun.lol/api/packages/adam/debian stable main" |
+  sudo tee /etc/apt/sources.list.d/terraria-server-manager.list
+sudo apt update
+sudo apt install terraria-server-manager
+```
+
+The repository is signed; the first two commands fetch its key and let apt trust it for this repository only. Alternatively, download a `.deb` from the releases page and install it directly:
 
 ```bash
 sudo apt install ./terraria-server-manager_0.0.9_all.deb
 ```
 
-Using `apt install ./file.deb` (rather than `dpkg -i`) installs the dependencies automatically. `unzip` is required. `curl` and the ICU library are "recommended", which apt installs by default; they're only needed for tModLoader instances, which crash with `Aborted` without ICU. `polkitd` is also recommended: it lets members of the `terraria` group start and stop servers without `sudo` (see [Permissions](#permissions)).
+Using `apt install` (rather than `dpkg -i`) installs the dependencies automatically. `unzip` is required. `curl` and the ICU library are "recommended", which apt installs by default; they're only needed for tModLoader instances, which crash with `Aborted` without ICU. `polkitd` is also recommended: it lets members of the `terraria` group start and stop servers without `sudo` (see [Permissions](#permissions)).
 
 Installing the package:
 
@@ -125,7 +137,8 @@ sudo ufw allow 7777/tcp     # example with ufw
 ### Upgrading the package
 
 ```bash
-sudo apt install ./terraria-server-manager_<new-version>_all.deb
+sudo apt update && sudo apt upgrade                          # from the apt repository
+sudo apt install ./terraria-server-manager_<new-version>_all.deb   # or from a downloaded .deb
 ```
 
 Running servers are not restarted. Each one picks up the new version the next time it starts. Your changes to `/etc/default/terractl` are kept; if the new package also changes that file, dpkg asks which version to keep.
@@ -255,6 +268,8 @@ Zips are only read, never changed, and one zip can serve any number of instances
 
 **tModLoader zips don't include .NET.** Each tModLoader instance downloads the .NET runtime it needs into `server/dotnet/` on its first start, so that start needs internet access and `curl`. The download is kept when you upgrade or re-unpack the instance. tModLoader checks the .NET version on every start and fetches a different one itself if a new release needs it.
 
+**The `terraria` user must be able to read the zips.** Files copied in normally are fine, but `scp -p` or `cp -p` of a private file keeps its `600` mode, and a server can't be installed from that. `terractl list` warns about such zips, and a server that fails to start because of one says so in its log. Fix them with `sudo chmod 644 /var/lib/terraria/dist/*.zip`.
+
 Members of the `terraria` group can copy zips into `dist/` without `sudo`:
 
 ```bash
@@ -670,7 +685,7 @@ sudo terractl move calamity nas:             # this host → nas
 terractl copy nas:calamity pi:test           # nas → pi, as 'test'
 ```
 
-### Turning on the daemon
+### Setting it up
 
 On the host to be managed:
 
@@ -678,29 +693,31 @@ On the host to be managed:
 sudo terractl daemon enable
 ```
 
-This starts `terractld.service` and makes it start at boot. It listens on **TCP port 7776**, on all addresses. If a firewall is active, allow that port (for example `sudo ufw allow 7776/tcp`), ideally only from the computers that will manage the host. To listen on one address or on another port, set `TERRACTL_LISTEN` in `/etc/default/terractl` (e.g. `TERRACTL_LISTEN=10.0.10.77:7776`) and run `sudo systemctl restart terractld`.
+It prints a command with a one-time token. Run that command on the computer that should manage the host:
 
-`sudo terractl daemon disable` turns it off again. `terractl daemon status` shows whether it's running, where it listens and its certificate's fingerprint, and with `sudo`, which computers it trusts.
+```bash
+terractl remote add tctl1_eyJ2IjoxLCJmcCI6...
+```
+
+That's all: the host is now a remote called by its hostname (say `nas`), and `terractl --host nas list` works. To call it something else, put a name before the token: `terractl remote add nas tctl1_...`. The host, in turn, knows the computer by the computer's hostname.
+
+For each further computer, run `sudo terractl daemon token` on the host for a new token. A token works **once**, **within 24 hours**.
+
+### The daemon
+
+`daemon enable` starts `terractld.service` and makes it start at boot. It listens on **TCP port 7776**, on all addresses. If a firewall is active, allow that port (for example `sudo ufw allow 7776/tcp`), ideally only from the computers that will manage the host. To listen on one address or on another port, set `TERRACTL_LISTEN` in `/etc/default/terractl` (e.g. `TERRACTL_LISTEN=10.0.10.77:7776`) and run `sudo systemctl restart terractld`.
+
+`sudo terractl daemon disable` turns it off again. `terractl daemon status` shows whether it's running, where it listens and its certificate's fingerprint, and with `sudo`, which computers it trusts. `sudo terractl daemon revoke <name>` takes a computer's access away.
 
 The daemon is an ordinary systemd service: systemd starts it at boot, restarts it if it crashes, and keeps its log. `journalctl -u terractld` lists every command it ran and for which computer.
 
-### Adding a remote
+### Remotes
 
-Each computer that should manage the host needs a one-time token. On the host with the daemon:
+The token contains the host's addresses, so usually `remote add` needs nothing else. If none of them works from the computer (behind NAT, for example), add one that does: `terractl remote add tctl1_... --address 203.0.113.5`, or `--address nas.example.com:7800` for another port.
 
-```bash
+Adding a host that's already a remote replaces that remote, keeping its name unless you give a new one. So if a remote stops working because its access was revoked, just get a new token and add it again.
-sudo terractl daemon trust add laptop
-```
 
-`laptop` is a name for the computer, used in the host's log and to revoke it later. The command prints what to run on that computer:
+Remotes are kept per user in `~/.config/terractl/remotes.json`, readable only by you. Under `sudo`, the remotes of the person who ran sudo are used.
-
-```bash
-terractl remote add nas tctl1_eyJ2IjoxLCJmcCI6...
-```
-
-`nas` is the name you'll use for the host there; choose any. The token contains the host's addresses, so usually nothing else is needed. If none of them works from the computer (behind NAT, for example), add the address: `terractl remote add nas 203.0.113.5 tctl1_...`, or `nas.example.com:7800` for another port.
-
-A token works **once**, **within 24 hours**. Remotes are kept per user in `~/.config/terractl/remotes.json`, readable only by you. Under `sudo`, the remotes of the person who ran sudo are used.
 
 ```bash
 terractl remote list                # your remotes
@@ -757,7 +774,7 @@ On this host, copying *from* it works for members of the `terraria` group. Copyi
 - **Encrypted and pinned.** Traffic is HTTPS (TLS 1.2 or newer). The daemon's certificate is self-signed, the token carries its fingerprint, and every connection checks it, so nothing in between can pose as the daemon. If the fingerprint ever changes, `terractl` refuses to connect and says so.
 - **Keys, not passwords.** Joining trades the token for a random key for that computer. The daemon keeps only hashes of keys and tokens, in `/var/lib/terractl/trust.json` (root only).
 - **A trusted computer is an admin of the host's servers.** It can do what `sudo terractl` can: create, delete, import, start and stop instances, and install mods or server files, which run as the `terraria` user. It can't change the daemon or run anything other than `terractl`. Give tokens only to computers you'd trust with `sudo terractl`.
-- **Revoking.** `sudo terractl daemon trust list` shows the trusted computers, and `sudo terractl daemon trust remove laptop` takes one's access away immediately.
+- **Revoking.** `sudo terractl daemon status` shows the trusted computers, and `sudo terractl daemon revoke laptop` takes one's access away immediately.
 - **Firewall.** The daemon doesn't need to be reachable from the internet. Limit port 7776 to your LAN or VPN, or set `TERRACTL_LISTEN` to a LAN or VPN address.
 
 The daemon runs as root, because it creates and removes instances and starts services, but with systemd's protections it can't write to `/usr`, `/boot`, `/etc` or home folders. Its certificate, key and trust list are in `/var/lib/terractl/`. Files in transit are kept in `/var/lib/terractl/transfers/`, and removed once used, after 6 hours unused, or when the daemon restarts.
@@ -798,7 +815,7 @@ The servers always run as the `terraria` user. Administration is simplest with `
 | `import` | root (or `terraria`) | Run as root, it gives the new instance to `terraria`. |
 | `prepare`, `run` | Normally only the service | Run as root, they automatically switch to the `terraria` user, so no files end up owned by root. Any other user is refused. |
 | `service-stop` | Only the service | Needs the server's process ID from systemd. |
-| `daemon enable`, `daemon disable`, `daemon trust ...` | root only | |
+| `daemon enable`, `disable`, `token`, `revoke` | root only | |
 | `daemon status` | anyone | Shows the trusted computers only with `sudo`. |
 | `remote ...`, `--host ...` | anyone | Uses your own remotes. On the remote, the daemon runs the command as root. |
 | `copy`, `move` | depends on this host's part | Copying from this host: the group is enough. Copying to it, or moving away from it: root. |
@@ -918,7 +935,7 @@ The daemon isn't running on that host (check with `terractl daemon status` there
 The daemon has a different certificate than when you added it. That's expected if `/var/lib/terractl` was deleted there, or the package was purged and installed again; remove the remote and add it again. If nothing like that happened, don't work around it: something may be intercepting the connection.
 
 **`doesn't trust this computer (any more)`.**
-Its access was revoked with `daemon trust remove`, or that computer was added again under the same name elsewhere. Get a new token.
+Its access was revoked with `daemon revoke`, or the host's `/var/lib/terractl` was reset. Run `sudo terractl daemon token` there and `terractl remote add <token>` here; that replaces the old remote.
 
 ---
 
@@ -972,12 +989,12 @@ terractl copy [<remote>:]<name> [<remote>:][<new name>] [--with-server]
                                                   Copy an instance, here or between hosts
 terractl move [<remote>:]<name> [<remote>:][<new name>] [--with-server]
                                                   Move or rename an instance
-terractl remote add <name> <token>                Add a remote (token from 'daemon trust add')
+terractl remote add [<name>] <token> [--address <host>[:<port>]]
-terractl remote add <name> <address> [<token>]    ... at an address the token doesn't list
+                                                  Add (or replace) a remote
 terractl remote list | remove <name>              Show or forget remotes
 terractl daemon enable|disable|status             Let other hosts manage this one
-terractl daemon trust add|remove <name>           Create a token for a computer, or revoke one
+terractl daemon token                             A one-time token for another computer
-terractl daemon trust list                        Show trusted computers and unused tokens
+terractl daemon revoke <name>                     Take a computer's access away
 
 Used by the service:
 terractl prepare <name>                           Create dirs/configs, unpack zip if needed

lib/terractl-remote

@@ -14,7 +14,7 @@
 # the instance to the destination's folders and free ports.
 #
 # Security: the daemon's certificate is self-signed. A computer joins with a
-# one-time token from 'terractl daemon trust add', which holds the certificate's
+# one-time token from 'terractl daemon enable' or 'daemon token', which holds the certificate's
 # fingerprint and a secret. The client checks that fingerprint on every
 # connection, so nothing in between can pose as the daemon, and trades the
 # secret for a random key of its own, sent with each request. The daemon stores
@@ -27,7 +27,6 @@ import base64
 import codecs
 import errno
 import fcntl
-import getpass
 import hashlib
 import hmac
 import http.client
@@ -212,7 +211,7 @@ def open_state(cmdline):
 
 
 class StateLock:
-    """Serialises changes to trust.json between the daemon and 'terractl daemon trust'."""
+    """Serialises changes to trust.json between the daemon and 'terractl daemon token/revoke'."""
 
     def __enter__(self):
         self.fd = os.open(state_path(".lock"), os.O_RDWR | os.O_CREAT, 0o600)
@@ -427,6 +426,15 @@ def extract_upload(tar_path, dest):
         raise HttpError(400, f"the files sent aren't a valid archive ({e})")
 
 
+def unique_client_name(wanted, clients):
+    base = wanted[:60] if isinstance(wanted, str) and CLIENT_RE.fullmatch(wanted[:60]) else "computer"
+    taken = {c.get("name") for c in clients}
+    name, n = base, 2
+    while name in taken:
+        name, n = f"{base}-{n}", n + 1
+    return name
+
+
 class Handler(http.server.BaseHTTPRequestHandler):
     protocol_version = "HTTP/1.1"
     server_version = "terractld"
@@ -579,7 +587,8 @@ class Handler(http.server.BaseHTTPRequestHandler):
     # ---- endpoints
 
     def join(self):
-        secret = self.read_json().get("secret")
+        req = self.read_json()
+        secret, wanted, old_key = req.get("secret"), req.get("name"), req.get("old_key")
         if not isinstance(secret, str):
             raise HttpError(400, "bad request")
         digest = sha256(secret)
@@ -593,11 +602,20 @@ class Handler(http.server.BaseHTTPRequestHandler):
                 save_trust(trust)
                 dlog(f"{self.client_address[0]}: refused a join (unknown, used or expired token)")
                 raise HttpError(403, "this token is not valid (it may have been used already, or "
-                                     "expired); create a new one there: sudo terractl daemon trust add <name>")
+                                     "expired); create a new one there: sudo terractl daemon token")
             trust["tokens"].remove(token)
             key = secrets.token_urlsafe(32)
-            name = token["name"]
+            # A computer that's trusted already (it sends its old key) keeps its
-            trust["clients"] = [c for c in trust["clients"] if c.get("name") != name]
+            # entry and name; a new one is named after its hostname
+            old = None
+            if isinstance(old_key, str):
+                old = next((c for c in trust["clients"]
+                            if hmac.compare_digest(c.get("key_sha256", ""), sha256(old_key))), None)
+            if old:
+                name = old["name"]
+                trust["clients"].remove(old)
+            else:
+                name = unique_client_name(wanted, trust["clients"])
             trust["clients"].append({"name": name, "key_sha256": sha256(key),
                                      "added": time.strftime("%Y-%m-%d %H:%M"),
                                      "from": self.client_address[0]})
@@ -969,11 +987,12 @@ def daemon_enable():
     if not wait_listening(host, port, 10):
         die(f"terractld isn't listening on {describe_listen(host, port)}; see: journalctl -u terractld")
     print(f"terractld is running and starts at boot, listening on {describe_listen(host, port)}.")
-    print(f"Certificate fingerprint (SHA-256): {cert_fingerprint()}")
-    print()
-    print("To let a computer manage this host, create a token for it:")
-    print("  sudo terractl daemon trust add <name for that computer>")
     print(f"If a firewall is active, allow TCP port {port} (e.g. sudo ufw allow {port}/tcp).")
+    print()
+    if load_trust()["clients"]:
+        print("To add another computer: sudo terractl daemon token")
+    else:
+        print_token()
     return 0
 
 
@@ -983,7 +1002,7 @@ def daemon_disable():
     if proc.returncode != 0:
         die(f"stopping terractld failed: {proc.stderr.strip()}")
     print("terractld is stopped and won't start at boot, so other hosts can't manage this one.")
-    print("The computers it trusts are kept for next time (terractl daemon trust list).")
+    print("The computers it trusts are kept for next time (sudo terractl daemon status).")
     return 0
 
 
@@ -1001,76 +1020,54 @@ def daemon_status():
     except PermissionError:
         print("trusted:      (run with sudo to see which computers)")
         trust = None
-    if trust is not None:
+    if trust is not None and not trust["clients"]:
-        names = ", ".join(c["name"] for c in trust["clients"]) or "none yet"
+        print("trusted:      none yet (add one: sudo terractl daemon token)")
-        print(f"trusted:      {names}")
+    elif trust is not None:
-        waiting = [t["name"] for t in trust["tokens"] if t["expires"] > time.time()]
+        print()
-        if waiting:
+        print(f"{'TRUSTED':<24} {'ADDED':<17} FROM")
-            print(f"tokens for:   {', '.join(waiting)} (not used yet)")
+        for c in trust["clients"]:
+            print(f"{c['name']:<24} {c.get('added', '-'):<17} {c.get('from', '-')}")
+        unused = [t for t in trust["tokens"] if t["expires"] > time.time()]
+        if unused:
+            print(f"(and {len(unused)} unused token{'s' if len(unused) > 1 else ''})")
     if active != "active":
         print("Start it with: sudo terractl daemon enable")
     return 0
 
 
-def trust_add(name):
+def print_token():
-    if not CLIENT_RE.fullmatch(name):
+    """Creates a one-time token and prints the command that uses it."""
-        die(f"invalid name '{name}' (letters, digits and _ . - @, up to 64)")
+    open_state("daemon token")
-    open_state(f"daemon trust add {name}")
     ensure_cert()
     secret = secrets.token_hex(32)
     with StateLock():
         trust = load_trust()
         now = time.time()
-        trust["tokens"] = [t for t in trust["tokens"] if t["expires"] > now and t["name"] != name]
+        trust["tokens"] = [t for t in trust["tokens"] if t["expires"] > now]
-        trust["tokens"].append({"name": name, "secret_sha256": sha256(secret),
+        trust["tokens"].append({"secret_sha256": sha256(secret), "expires": int(now + TOKEN_HOURS * 3600)})
-                                "expires": int(now + TOKEN_HOURS * 3600)})
         save_trust(trust)
-        known = any(c["name"] == name for c in trust["clients"])
     host, port = listen_setting()
-    token = make_token({"v": 1, "fp": cert_fingerprint(), "s": secret, "a": host_addresses(host, port)})
+    fields = {"v": 1, "fp": cert_fingerprint(), "s": secret, "a": host_addresses(host, port)}
     here = (socket.gethostname() or "").split(".")[0]
-    if not NAME_RE.fullmatch(here):
+    if NAME_RE.fullmatch(here):
-        here = "<name>"
+        fields["n"] = here            # the remote's name, unless the other computer picks one
-    print(f"On '{name}', run this to add this host as a remote called '{here}':")
+    print(f"To manage this host from another computer, run this there (works once, within {TOKEN_HOURS} hours):")
     print()
-    print(f"  terractl remote add {here} {token}")
+    print(f"  terractl remote add {make_token(fields)}")
     print()
-    print(f"The token works once, within {TOKEN_HOURS} hours.")
-    if known:
-        print(f"'{name}' is trusted already; joining again gives it a new key and the old one stops working.")
     if systemctl("is-active", DAEMON_UNIT).stdout.strip() != "active":
         print("The daemon isn't running yet; start it with: sudo terractl daemon enable")
     return 0
 
 
-def trust_list():
+def daemon_revoke(name):
-    try:
+    open_state(f"daemon revoke {name}")
-        trust = load_trust()
-    except PermissionError:
-        die("this needs root: sudo terractl daemon trust list")
-    if not trust["clients"]:
-        print("No computers are trusted yet. Add one with: sudo terractl daemon trust add <name>")
-    else:
-        print(f"{'NAME':<24} {'ADDED':<17} FROM")
-        for c in trust["clients"]:
-            print(f"{c['name']:<24} {c.get('added', '-'):<17} {c.get('from', '-')}")
-    now = time.time()
-    for t in trust["tokens"]:
-        if t["expires"] > now:
-            hours = max(1, round((t["expires"] - now) / 3600))
-            print(f"Token for '{t['name']}' not used yet (expires in {hours} h)")
-    return 0
-
-
-def trust_remove(name):
-    open_state(f"daemon trust remove {name}")
     with StateLock():
         trust = load_trust()
         clients = [c for c in trust["clients"] if c["name"] != name]
-        tokens = [t for t in trust["tokens"] if t["name"] != name]
+        if len(clients) == len(trust["clients"]):
-        if len(clients) == len(trust["clients"]) and len(tokens) == len(trust["tokens"]):
+            die(f"no computer called '{name}' is trusted (see: sudo terractl daemon status)")
-            die(f"'{name}' isn't trusted (see: terractl daemon trust list)")
+        trust["clients"] = clients
-        trust["clients"], trust["tokens"] = clients, tokens
         save_trust(trust)
     print(f"'{name}' can't manage this host any more.")
     return 0
@@ -1078,20 +1075,13 @@ def trust_remove(name):
 
 def daemon_main(argv):
     sub, rest = (argv[0], argv[1:]) if argv else ("", [])
-    if sub == "trust":
+    if sub == "revoke" and len(rest) == 1:
-        what = rest[0] if rest else "list"
+        return daemon_revoke(rest[0])
-        if what == "add" and len(rest) == 2:
-            return trust_add(rest[1])
-        if what == "list" and len(rest) <= 1:
-            return trust_list()
-        if what == "remove" and len(rest) == 2:
-            return trust_remove(rest[1])
-        die("usage: terractl daemon trust add <name> | trust list | trust remove <name>")
     commands = {"enable": daemon_enable, "disable": daemon_disable, "status": daemon_status,
-                "serve": daemon_serve}
+                "token": print_token, "serve": daemon_serve}
     if sub in commands and not rest:
         return commands[sub]()
-    die("usage: terractl daemon enable | disable | status | trust ...")
+    die("usage: terractl daemon enable | disable | status | token | revoke <name>")
 
 
 # --------------------------------------------------------------- client ----
@@ -1244,9 +1234,8 @@ class Remote:
             except (ValueError, KeyError, TypeError):
                 message = f"HTTP error {resp.status}"
             if resp.status == 401:
-                die(f"{self.label} doesn't trust this computer (any more). On {self.label}, run "
+                die(f"{self.label} doesn't trust this computer (any more). Run 'sudo terractl daemon "
-                    f"'sudo terractl daemon trust add <name for this computer>', then here: terractl "
+                    f"token' there, then here: terractl remote add <token>")
-                    f"remote remove {self.name} && terractl remote add {self.name} {self.addr} <token>")
             die(f"{self.label}: {message}")
         return resp
 
@@ -1384,40 +1373,50 @@ def find_remote(spec):
         if host and conf["address"].lower() == host.lower() and int(conf["port"]) == port:
             return Remote(name, conf, via=f"--host {spec}")
     die(f"'{spec}' isn't one of your remotes (see: terractl remote list). To add it, run "
-        f"'sudo terractl daemon trust add <name for this computer>' there, then here: "
+        f"'sudo terractl daemon token' there, then here: terractl remote add <token>")
-        f"terractl remote add <name> <token>")
 
 
 def remote_add(args):
-    if len(args) not in (2, 3):
+    usage = "usage: terractl remote add [<name>] <token> [--address <host>[:<port>]]"
-        die("usage: terractl remote add <name> <token>, or: terractl remote add <name> <address> [<token>]")
+    address, rest = None, []
-    name = args[0]
+    args = iter(args)
+    for arg in args:
+        if arg == "--address":
+            address = next(args, None) or die(usage)
+        elif arg.startswith("--address="):
+            address = arg.split("=", 1)[1]
+        elif arg.startswith("-"):
+            die(f"unknown option '{arg}'")
+        else:
+            rest.append(arg)
+    if len(rest) not in (1, 2):
+        die(usage)
+    name, token = (None, rest[0]) if len(rest) == 1 else rest
+    fields = read_token(token)
+    remotes = load_remotes()
+    # Adding a host that's a remote already (same certificate) replaces that
+    # remote: after its access was revoked, say, or to rename it
+    old = next((n for n, c in sorted(remotes.items()) if c["fingerprint"] == fields["fp"]), None)
+    name = name or old or fields.get("n")
+    if not name:
+        die("give the remote a name: terractl remote add <name> <token>")
     if not NAME_RE.fullmatch(name):
         die(f"invalid remote name '{name}' (letters, digits and _ . -, not starting with . or -)")
-    remotes = load_remotes()
+    if name in remotes and name != old:
-    if name in remotes:
+        die(f"'{name}' is already the name of another remote; choose another: terractl remote add <name> <token>")
-        die(f"there's a remote called '{name}' already (to replace it: terractl remote remove {name})")
-    if len(args) == 3:
-        address, token = args[1], args[2]
-    elif args[1].startswith(TOKEN_PREFIX):
-        address, token = None, args[1]
-    else:
-        address = args[1]
-        if not sys.stdin.isatty():
-            die("no token given")
-        token = getpass.getpass("Token (from 'sudo terractl daemon trust add' on that host): ")
-    fields = read_token(token)
     candidates = [split_hostport(address)] if address else [split_hostport(a) for a in fields.get("a", [])]
     if not candidates:
-        die("the token doesn't say where the host is; give its address: "
+        die("the token doesn't say where the host is; add --address <host>")
-            "terractl remote add <name> <address> <token>")
+    join = {"secret": fields["s"], "name": (socket.gethostname() or "").split(".")[0]}
+    if old:
+        join["old_key"] = remotes[old].get("key", "")
     problems = []
     for host, port in candidates:
         remote = Remote(name, {"address": host, "port": port, "fingerprint": fields["fp"]})
         remote.joining = True
         remote.label = remote.addr
         try:
-            reply = remote.call("POST", "/1.0/trust/join", {"secret": fields["s"]}, auth=False, timeout=5)
+            reply = remote.call("POST", "/1.0/trust/join", join, auth=False, timeout=5)
             break
         except Unreachable as e:
             problems.append(str(e))
@@ -1425,7 +1424,9 @@ def remote_add(args):
         if len(problems) == 1:
             die(problems[0])
         die("couldn't reach the host at any address in the token:\n  " + "\n  ".join(problems) +
-            "\nGive an address that works from here: terractl remote add <name> <address> <token>")
+            "\nGive an address that works from here: terractl remote add <token> --address <host>")
+    if old:
+        del remotes[old]
     remotes[name] = {"address": host, "port": port, "fingerprint": fields["fp"], "key": reply["key"],
                      "client_name": reply["name"], "added": time.strftime("%Y-%m-%d %H:%M")}
     save_remotes(remotes)
@@ -1437,7 +1438,7 @@ def remote_add(args):
         about = f"{info['hostname']} at {remote.addr}, terractl {info['version']}"
     except Fail:
         about = remote.addr
-    print(f"added remote '{name}' ({about}); it knows this computer as '{reply['name']}'")
+    print(f"{'updated' if old else 'added'} remote '{name}' ({about}); it knows this computer as '{reply['name']}'")
     print(f"Try: terractl --host {name} list")
     return 0
 
@@ -1447,7 +1448,7 @@ def remote_list(args):
         die("usage: terractl remote list")
     remotes = load_remotes()
     if not remotes:
-        print("No remotes yet. Add one with: terractl remote add <name> <token>")
+        print("No remotes yet. Run 'sudo terractl daemon token' on a host, then here: terractl remote add <token>")
         return 0
     print(f"{'NAME':<20} {'ADDRESS':<30} FINGERPRINT")
     for name, conf in sorted(remotes.items()):
@@ -1463,8 +1464,8 @@ def remote_remove(args):
     if conf is None:
         die(f"there's no remote called '{args[0]}' (see: terractl remote list)")
     save_remotes(remotes)
-    print(f"removed remote '{args[0]}'. It still lists this computer as '{conf.get('client_name', '?')}'; "
+    print(f"removed remote '{args[0]}'. It still trusts this computer; to revoke that too, run there: "
-          f"to revoke that too, run there: sudo terractl daemon trust remove {conf.get('client_name', '<name>')}")
+          f"sudo terractl daemon revoke {conf.get('client_name', '<name>')}")
     return 0
 
 
@@ -1940,6 +1941,10 @@ if __name__ == "__main__":
     except Fail as e:
         print(f"terractl: {e}", file=sys.stderr)
         sys.exit(1)
+    except BrokenPipeError:
+        # Output went into something that stopped reading (e.g. head)
+        os.dup2(os.open(os.devnull, os.O_WRONLY), sys.stdout.fileno())
+        sys.exit(1)
     except OSError as e:
         where = f": {e.filename}" if e.filename else ""
         print(f"terractl: {e.strerror or e}{where}", file=sys.stderr)

packaging/deb/control

@@ -4,7 +4,7 @@ Section: games
 Priority: optional
 Architecture: all
 Installed-Size: @INSTALLED_SIZE@
-Maintainer: Your Name <you@example.com>
+Maintainer: Adam Brown <adam@adbraun.lol>
 Depends: unzip, systemd, python3, openssl
 Recommends: curl, libicu76 | libicu74 | libicu72 | libicu70 | libicu-dev, polkitd
 Conflicts: terraria-instance

packaging/gitea-release.py

@@ -0,0 +1,91 @@
+#!/usr/bin/env python3
+# Creates or updates the Gitea release for a tag and attaches files to it. Its
+# notes are that version's section of CHANGELOG.md. Run again for the same tag,
+# it updates the notes and replaces files of the same name.
+#
+#   gitea-release.py <tag> <file>...
+#
+# Needs GITEA_URL (https://gitea.example.com), GITEA_REPO (owner/name) and
+# GITEA_TOKEN. Used by .gitea/workflows/release.yaml.
+
+import json
+import os
+import sys
+import urllib.error
+import urllib.parse
+import urllib.request
+import uuid
+
+
+def api(method, path, body=None, content_type="application/json"):
+    url = f"{os.environ['GITEA_URL'].rstrip('/')}/api/v1/repos/{os.environ['GITEA_REPO']}{path}"
+    if isinstance(body, dict):
+        body = json.dumps(body).encode()
+    headers = {"Authorization": f"token {os.environ['GITEA_TOKEN']}", "Accept": "application/json"}
+    if body is not None:
+        headers["Content-Type"] = content_type
+    request = urllib.request.Request(url, data=body, method=method, headers=headers)
+    try:
+        with urllib.request.urlopen(request, timeout=300) as response:
+            data = response.read()
+            return json.loads(data) if data else None
+    except urllib.error.HTTPError as e:
+        if e.code == 404 and method == "GET":
+            return None
+        sys.exit(f"{method} {url}: HTTP {e.code}: {e.read().decode(errors='replace')}")
+
+
+def changelog_section(version):
+    """The lines under '## <version>' in CHANGELOG.md, up to the next '## '."""
+    lines, found = [], False
+    with open("CHANGELOG.md") as f:
+        for line in f:
+            if line.startswith("## "):
+                if found:
+                    break
+                found = line[3:].split()[0] == version
+                continue
+            if found:
+                lines.append(line)
+    if not found:
+        sys.exit(f"CHANGELOG.md has no '## {version}' section")
+    return "".join(lines).strip() + "\n"
+
+
+def upload(release_id, path):
+    name = os.path.basename(path)
+    boundary = uuid.uuid4().hex
+    with open(path, "rb") as f:
+        content = f.read()
+    body = (f"--{boundary}\r\nContent-Disposition: form-data; name=\"attachment\"; filename=\"{name}\"\r\n"
+            f"Content-Type: application/octet-stream\r\n\r\n").encode() + content + f"\r\n--{boundary}--\r\n".encode()
+    api("POST", f"/releases/{release_id}/assets?name={urllib.parse.quote(name)}", body,
+        f"multipart/form-data; boundary={boundary}")
+    print(f"attached {name}")
+
+
+def main(tag, files):
+    notes = changelog_section(tag[1:] if tag.startswith("v") else tag)
+    release = api("GET", f"/releases/tags/{urllib.parse.quote(tag)}")
+    if release is None:
+        release = api("POST", "/releases", {"tag_name": tag, "name": tag, "body": notes})
+        print(f"created release {tag}")
+    else:
+        release = api("PATCH", f"/releases/{release['id']}", {"body": notes})
+        print(f"updated release {tag}")
+    names = {os.path.basename(p) for p in files}
+    for asset in release.get("assets") or []:
+        if asset["name"] in names:
+            api("DELETE", f"/releases/{release['id']}/assets/{asset['id']}")
+    for path in files:
+        upload(release["id"], path)
+    print(release.get("html_url", ""))
+
+
+if __name__ == "__main__":
+    if len(sys.argv) < 3:
+        sys.exit("usage: gitea-release.py <tag> <file>...")
+    for var in ("GITEA_URL", "GITEA_REPO", "GITEA_TOKEN"):
+        if not os.environ.get(var):
+            sys.exit(f"{var} is not set")
+    main(sys.argv[1], sys.argv[2:])

systemd/terractld.service

@@ -8,7 +8,7 @@ Wants=network-online.target
 Type=simple
 # Listens on TERRACTL_LISTEN from /etc/default/terractl (default: all addresses,
 # port 7776). Its certificate and the list of trusted computers are kept in
-# /var/lib/terractl. Manage it with: terractl daemon enable|disable|status|trust
+# /var/lib/terractl. Manage it with: terractl daemon enable|disable|status|token|revoke
 ExecStart=@BINDIR@/terractl daemon serve
 Restart=on-failure
 RestartSec=5