terraria-server-manager/CHANGELOG.md

# Changelog

## Unreleased

- 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.