terraria-server-manager/CHANGELOG.md

# Changelog

## 0.0.12 - 2026-10-02

- New `fetch` command to download server zips into `dist/`, named with their version:
  - `terractl fetch tmodloader [<version>]` downloads from tModLoader's GitHub releases (default: the latest stable) and checks it against the SHA-256 checksum GitHub publishes. `terractl fetch vanilla [<version>]` downloads from terraria.org (default: its newest; older versions by number, `1449` or `1.4.4.9`).
  - `--list` shows the versions available (tModLoader: stable and preview), and which are already downloaded. `--upgrade <name>` switches an instance to the zip with `upgrade` right after.
  - Every zip is checked (complete, and the right kind) before it's put in `dist/`; zips already there aren't downloaded again. If a site doesn't have the version or can't be reached, it says so and where to download it by hand.
  - Members of the `terraria` group can use it without `sudo` (except `--upgrade`). Needs `curl`.
- Scheduled backups, with a systemd timer per instance (`terraria-backup@<name>.timer`):
  - `sudo terractl backup enable <name> [--every <when>] [--keep <number>]` (default: daily, keeping the newest 14). `--every` takes `hourly`, `daily`, `weekly`, a time such as `04:30`, or any systemd calendar expression. Missed backups are made after the machine starts again.
  - `backup now <name>` makes one immediately, `backup disable <name>` stops the schedule (existing backups are kept), and `backup list [<name>]` shows schedules, the last and next run, and the backups.
  - Each backup saves the world first if the server is running (as `export` does) and goes in `/var/lib/terraria/backups/<name>/` (`TERRARIA_BACKUPS` in `/etc/default/terractl`), readable by the `terraria` group. Only scheduled backups are pruned.
  - `rename` takes the schedule along, `delete` turns it off, and purging the package removes the schedules (not the backups).
- New `doctor` command: `terractl doctor [<name>] [--fix]` checks the system (user, programs including ICU and curl, folders, zips, the systemd units and old copies in `/etc` that replace them, sandbox access to moved folders, journal access, polkit, the daemon, leftovers of deleted instances) and each instance (file ownership and modes, its server zip, paths in `serverconfig.txt`, missing mods, shared ports, failed starts and backups). Each problem comes with the command that fixes it. `--fix` applies the safe fixes: `fix-perms`, folder and zip permissions, journal access, the `ReadWritePaths=` drop-in for moved folders, and boot links or backup schedules of instances that are gone. It exits with status 1 if a problem remains.
- The daemon (`terractld.service`) may now write to `/etc/systemd/system`, so `backup enable` and `doctor --fix` also work through `--host`.
- Warnings about moved folders now also suggest `terractl doctor --fix`.
- New `upgrade` command to change an instance's server version, up or down:
  - `terractl upgrade <name>` lists the zips in `dist/` for its type, marking the installed, pinned and newest ones. The `terraria` group can use it without `sudo`.
  - `sudo terractl upgrade <name> <zip>|latest` checks the zip first (right type, readable by `terraria`, contains the server, passes `unzip -t`), stops the server (saving the world), backs up its worlds and configs to `/var/lib/terraria/backups/<name>/`, pins `ZIP=`, unpacks the zip right away and starts the server again if it was running. If unpacking fails, the instance is left as it was. `--no-backup` skips the backup.
  - Going to an older version needs `--downgrade`, because worlds saved by a newer version can't be opened by an older one.
  - Bash completion offers the instance's zips. Works with `--host`.
- `reinstall` now always unpacks the **same** version again. Before, an instance with a blank `ZIP=` picked the newest zip in `dist/`, so `reinstall` could silently upgrade it. It now pins the zip the instance runs first, and refuses if that zip is gone from `dist/`. It also keeps the record of the installed version (`server/.installed`) until the new unpack is done.
- `list`, `new`, `import` and `enable` warn when `TERRARIA_BASE` or `TERRARIA_DIST` is somewhere the services' sandbox doesn't allow (the instances folder not in `ReadWritePaths=`, or either folder under `/home`), and print the exact drop-in to add. The daemon (`terractld.service`) is checked too when it's on. A server that can't create its folder now says why in its log, instead of only "Read-only file system".
- The guide's "Changing locations" now covers bind mounts (the simplest way to use another disk) as well as drop-ins, and a new section explains keeping instances or zips under `/home`.
- `journal-access` is offered by tab completion and listed in the guide's command reference.
- `upgrade`, and `prepare`/`run` started as root, check first that the `terraria` user can run the terractl being used. A copy under `/root` is refused with an explanation, before `upgrade` stops the server, instead of failing with `env: Permission denied`.
- `terractl` run by a relative path (e.g. `sudo ./bin/terractl prepare <name>` from a source tree) no longer fails to switch to the `terraria` user.
- New `fix-perms` command: `sudo terractl fix-perms <name>` gives every file of an instance back to the `terraria` user and reapplies the usual modes (group can read, others nothing; server binaries executable), e.g. after copying worlds in as root. Symlinks are not followed. Works with `--host` too.
- `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>`.
- New `/etc/systemd/journald@terraria.conf` for the servers' journal size and retention (default: up to 256 MB).
- New internal `terractl journal-access`, run as root before each server start: creates the servers' journal folder (never `/var/log/journal` itself) and gives the `terraria` group read access, repairing existing journal files too.
- The note shown by `attach` and `cmd` when output can't be read now distinguishes "not in the `terraria` group" from "in it, but the journal isn't set up yet".
- New polkit rule (`/usr/share/polkit-1/rules.d/50-terractl.rules`): members of the `terraria` group can `systemctl start`, `stop` and `restart` `terraria@<name>` without `sudo`. `enable`, `disable` and all other units still need root. Needs `polkitd` 0.106 or newer, now a recommended package; Ubuntu 22.04's polkit can't run the rule.
- New `enable` and `disable` commands: `terractl enable <name> [--now]` makes a server start at boot (`--now` also starts it), `terractl disable <name> [--now]` stops that (`--now` also stops it, saving the world). They need root, like `systemctl enable`. `enable` refuses names without an instance, so a typo can't create a new instance at boot. `new` and `import` now suggest `terractl enable <name> --now`.
- `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.
  - `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.
  - Written in Python (standard library only), in `/usr/lib/terraria-server-manager/terractl-remote`. The package now depends on `python3` and `openssl`.
- New `start`, `stop` and `restart` commands, the same as `systemctl start|stop|restart terraria@<name>`, for this host and for `--host`. `start` refuses names that have no instance. The service's own stop step is now `terractl service-stop`; units that still call `terractl stop <name> <pid>` keep working.
- New `rename` command: `terractl rename <name> <new name>` renames the folder, updates `serverconfig.txt`, and carries over the service (stopped and started again if it was running, and still starting at boot). The port and unpacked server are kept. `move` within one host uses it.
- New `info` command: this host's folders, zips and instances, or an instance's type, port, server zip and state, as `key=value` lines.
- `import` replaces a `ZIP=` pin that's an absolute path not present on this host with the zip of the same name in this host's `dist/`.
- Messages that suggest a command now suggest `terractl` commands (`terractl stop <name>` rather than `systemctl stop terraria@<name>`), with `sudo` only when it's needed: not in a root shell, and not for `terraria` group members starting, stopping or restarting a server.
- New `watch` command: `terractl watch <name> [-n <lines>] [-q]` follows the server's output like `attach`, but never sends input, so it's safe to leave open. Works for the `terraria` group without `sudo`, and while the server is stopped. `-q` leaves out the lines about what it's doing.
- Bash completion for the new commands, remote names after `--host`, and `<remote>:<name>` for `copy` and `move`.
- Clearer messages when `run` or `prepare` is typed without `sudo` (the old one, "must run as root or 'terraria'", read as if the `terraria` group were enough), and when `stop` is typed by hand.
- Upgrading: running servers keep logging to the system journal until restarted; the package lists the ones to restart.

## 0.0.10 - 2026-09-30

- `cmd` now prints the server's reply to the command, instead of only saying where to find it. It waits until the server has been quiet for a second, up to 5 seconds.
- `attach` and `cmd` now explain when you can send commands but not see the server's output. That happens for members of the `terraria` group who aren't root or in `systemd-journal`. Previously `attach` showed nothing, without saying why.
- Replaced a `${var:+...}` expansion with an explicit `if` in `import`'s summary message (ShellCheck SC2016). The output is unchanged.

## 0.0.9 - 2026-09-28

- New `export` command: `terractl export <name> [file.tar.gz] [--with-server]` archives an instance's `instance.conf`, `serverconfig.txt` and `data/` (worlds, mods, mod configs). If the server is running under systemd, it is asked to save first. Archives are created readable only by their owner, since `serverconfig.txt` can contain the server password. `--with-server` also includes the unpacked server software (and tModLoader's .NET), for hosts without internet access.
- New `import` command: `terractl import <name> <file.tar.gz>` creates an instance from an export, a `delete` backup, or an archive of an old `/opt/terraria` instance. Archives are checked before extracting (no paths outside the instance folder, no links or special files). Paths in `serverconfig.txt` are updated, a port already used by another instance is replaced with a free one, the server version the world was exported with is pinned, and ownership is set to the `terraria` user.
- One server per instance: `run` holds a lock (`<instance>/.lock`) for the server's whole lifetime, released automatically when it exits or crashes. A second `run`, or starting the service while a copy started by hand is running, is refused.
- `prepare` and `reinstall --clean` refuse to run while the instance's server is running, so `server/` and .NET are never replaced or deleted under it.
- `delete` refuses to continue if the server is still running outside systemd.
- `list` shows servers started by hand as `running (outside systemd)`.
- `stop` typed by hand now explains to use `systemctl stop` instead of silently doing nothing.
- Fixed relative paths given on the command line (e.g. `terractl mods <name> add tmod-export`) being looked up from `/` instead of the current directory.
- Bash completion for `export` and `import`.

## 0.0.8 - 2026-09-28

- Bash completion for `terractl`: commands, instance names, `new` types, console commands for `cmd`, `reinstall`/`delete` options, and `mods` actions and mod names. Installed to `share/bash-completion/completions/terractl` by both `make install` and the package.

## 0.0.7 - 2026-09-28

- Fixed ShellCheck warnings that made `make check` (and therefore `make deb`) fail when ShellCheck is installed: simplified the development-copy check in `--version` (SC2140), and marked the intentional unquoted unit list in `prerm` (SC2086).

## 0.0.6 - 2026-09-28

- Renamed the command from `terraria-instance` to `terractl`, and the package from `terraria-instance` to `terraria-server-manager`. The new package replaces the old one automatically; see "Upgrading from the terraria-instance package" in the guide.
- Settings file moved from `/etc/default/terraria-instance` to `/etc/default/terractl`.
- New `terractl --version`.
- New Makefile: `make check`, `make deb`, `make install`, `make uninstall`.
- Restructured the source into a git repository layout.

## 0.0.5 - 2026-09-28

- Fixed `attach`: detaching with Ctrl-D printed "jpid: unbound variable" and left a `journalctl` process running.

## 0.0.4 - 2026-09-28

- The .NET runtime that tModLoader downloads on first start (and its logs) is now kept when an instance is upgraded or re-unpacked.
- New `reinstall --clean` to discard .NET as well and download it again.

## 0.0.3 - 2026-09-28

- New `mods` command: `list`, `add`, `enable`, `disable`, `remove`. Accepts the Windows export folder directly and sets file ownership.
- `new` and `prepare` now create `data/Mods` for tModLoader instances.

## 0.0.2 - 2026-09-28

- Fixed `prepare` failing for tModLoader zips when run as root from a directory the `terraria` user can't enter (e.g. `/root`).

## 0.0.1 - 2026-09-28

- First Debian package. Uses `/var/lib/terraria` instead of `/opt/terraria` and `/terraria`, creates the `terraria` user and directories with sysusers.d and tmpfiles.d, and stops instances cleanly when removed.
- `prepare` and `run` switch to the `terraria` user when started as root, so no files end up owned by root.
- New `delete` command, with an automatic backup.
- `list` no longer aborts when an instance's config can't be read.