adam/terraria-server-manager
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 3 Wiki Activity

add import and export

Browse Source
This commit is contained in:
abrown38 committed 2026-09-29 16:40:56 +00:00
1 parent d4bd93bbe1
commit 35f541458c
7 files changed
+369 -38
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

docs/guide.md
+96 -26
View File
@@ -17,12 +17,13 @@ Run any number of vanilla Terraria and tModLoader dedicated servers on one Linux
11. [Mods (tModLoader)](#mods-tmodloader)
12. [Versions and upgrades](#versions-and-upgrades)
13. [Deleting and restoring](#deleting-and-restoring)
14. [Backups](#backups)
15. [Permissions](#permissions)
16. [Running by hand for debugging](#running-by-hand-for-debugging)
17. [Troubleshooting](#troubleshooting)
18. [Tab completion](#tab-completion)
19. [Command reference](#command-reference)
14. [Exporting and importing](#exporting-and-importing)
15. [Backups](#backups)
16. [Permissions](#permissions)
17. [Running by hand for debugging](#running-by-hand-for-debugging)
18. [Troubleshooting](#troubleshooting)
19. [Tab completion](#tab-completion)
20. [Command reference](#command-reference)
---
@@ -95,7 +96,7 @@ The server can write only inside `instances/`. It reads `dist/` but can never ch
The package works on Debian 12 or newer and Ubuntu 22.04 or newer.
```bash
sudo apt install ./terraria-server-manager_2.0.0_all.deb
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.
@@ -137,10 +138,10 @@ sudo rm -rf /var/lib/terraria && sudo userdel terraria
### Upgrading from the `terraria-instance` package
Versions before 2.0.0 were packaged as `terraria-instance`, and the command had the same name. The new package declares that it replaces the old one, so installing it removes `terraria-instance` automatically:
Versions before 0.0.6 were packaged as `terraria-instance`, and the command had the same name. The new package declares that it replaces the old one, so installing it removes `terraria-instance` automatically:
```bash
sudo apt install ./terraria-server-manager_2.0.0_all.deb
sudo apt install ./terraria-server-manager_0.0.9_all.deb
```
Things to know:
@@ -203,7 +204,7 @@ sudo rm /etc/systemd/system/terraria@.service /etc/systemd/system/terraria@.sock
sudo rm /usr/local/bin/terraria-instance
# 3. Install the package (keeps the existing 'terraria' user)
sudo apt install ./terraria-server-manager_2.0.0_all.deb
sudo apt install ./terraria-server-manager_0.0.9_all.deb
# 4. Move instances and zips
for d in /opt/terraria/*/; do
@@ -222,6 +223,8 @@ sudo systemctl reenable terraria@calamity # repeat for each instance from
sudo systemctl start terraria@calamity
```
Alternatively, you can move instances one at a time with `import`, which updates the paths in `serverconfig.txt` and sets ownership for you: `sudo tar -czf /tmp/calamity.tar.gz -C /opt/terraria calamity`, then `sudo terractl import calamity /tmp/calamity.tar.gz`.
Once everything works, remove the old directories: `sudo rm -rf /terraria /opt/terraria`. If you set `ZIP=` in an `instance.conf` to an absolute path under `/terraria`, change it to just the file name.
The existing `terraria` user keeps `/opt/terraria` as its home directory. That's harmless, because the script sets a per-instance home itself. To tidy it anyway, run `sudo usermod -d /var/lib/terraria terraria` after deleting `/opt/terraria`.
@@ -533,11 +536,10 @@ sudo terractl delete calamity -y --no-backup # permanently, no backup
This stops and disables the service, then removes the whole instance directory. Unless you pass `--no-backup`, it first archives the configs and `data/` to `/var/lib/terraria/instances/.deleted/<name>-<timestamp>.tar.gz`. `server/` is left out of the archive because it can be recreated from the zip.
To restore an instance:
To restore an instance, import its backup. You can give it back its old name, or a new one:
```bash
sudo tar -xzf /var/lib/terraria/instances/.deleted/calamity-20260928-134422.tar.gz -C /var/lib/terraria/instances
sudo chown -R terraria:terraria /var/lib/terraria/instances/calamity
sudo terractl import calamity /var/lib/terraria/instances/.deleted/calamity-20260928-134422.tar.gz
sudo systemctl enable --now terraria@calamity # server/ is unpacked again on start
```
@@ -545,20 +547,67 @@ sudo systemctl enable --now terraria@calamity # server/ is unpacked ag
---
## Backups
## Exporting and importing
Everything worth keeping is in `data/`, `instance.conf` and `serverconfig.txt`.
To back up a running server, save it first so the world file on disk is current:
`export` packs an instance into a single `.tar.gz` file, and `import` turns such a file back into an instance. Use them for backups, for moving a server to another machine, or for making a copy to experiment on.
```bash
sudo terractl cmd calamity save
sleep 10
sudo tar -czf /root/calamity-$(date +%F).tar.gz -C /var/lib/terraria/instances \
--exclude=calamity/server calamity
sudo terractl export calamity # ./calamity-<date>-<time>.tar.gz
sudo terractl export calamity /root/backups/cal.tar.gz # choose the file
sudo terractl export calamity --with-server # also include server/ (see below)
sudo terractl import calamity2 calamity-20260928-1830.tar.gz
```
Stopping the server first is the safest option. Terraria also keeps a `.bak` copy of each world alongside the world file.
### What an export contains
It contains `instance.conf`, `serverconfig.txt` and all of `data/`: worlds (`.wld` and `.twld`), their `.bak` copies, mods, `enabled.json`, mod configs and the ban list. It also includes a small `terractl-export.txt`, which records where the export came from, the server type, and the server zip it was running.
`server/` is left out by default, because it can be recreated from the zip in `dist/`. `--with-server` includes it, together with the .NET runtime tModLoader downloaded. That makes the archive much larger, but an import can then start without a zip and without internet access.
**If the server is running**, `export` sends it `save` and waits until the world files have been written, which usually takes a few seconds. A server started by hand with `terractl run` can't be asked to save that way, so `export` refuses; stop it first.
**The archive is readable only by you** (mode 600), because `serverconfig.txt` can contain the server password. Keep that in mind before sharing an export.
### What an import does
`import <name> <file>` creates a new instance called `<name>`. It never overwrites an existing one, so pick a free name or delete the old instance first. Before extracting anything, it checks the archive: it must hold one instance folder, and nothing that could land outside it (no absolute or `../` paths, no links or special files).
After extracting, it adjusts the instance for its new home:
- **Paths.** The paths in `serverconfig.txt` (`world=`, `worldpath=`, `banlist=`) are updated for the new name and location.
- **Port.** If the port is already used by another instance, a free port is assigned and printed.
- **Server version.** If `ZIP=` in `instance.conf` is blank, it's set to the zip the world was exported with, so the server runs the same Terraria or tModLoader version as before. That matters for mods. Make sure that zip is in `/var/lib/terraria/dist`; `import` warns you if it isn't.
- **Ownership.** All files are given to the `terraria` user.
`import` also accepts:
- the backups that `delete` makes (see [Deleting and restoring](#deleting-and-restoring));
- a plain archive of an instance folder, including one from the old `/opt/terraria` manual setup, e.g. `tar -czf old.tar.gz -C /opt/terraria calamity`.
### Moving a server to another machine
```bash
# old machine
sudo terractl export calamity /tmp/calamity.tar.gz
scp /tmp/calamity.tar.gz newhost:/tmp/
# new machine (with terraria-server-manager installed, and the same zip in dist/)
sudo terractl import calamity /tmp/calamity.tar.gz
sudo systemctl enable --now terraria@calamity
```
---
## Backups
Everything worth keeping is in `data/`, `instance.conf` and `serverconfig.txt`, which is exactly what `export` saves. A nightly backup kept for 14 days, as a root cron job (`sudo crontab -e`):
```cron
30 4 * * * /usr/bin/terractl export calamity /var/backups/terraria/calamity-$(date +\%F).tar.gz && find /var/backups/terraria -name 'calamity-*.tar.gz' -mtime +14 -delete
```
Create the folder first with `sudo mkdir -p /var/backups/terraria`. In a crontab, `%` has a special meaning and must be written as `\%`, as above. Terraria also keeps a `.bak` copy of each world next to the world file, which is useful if the latest save is damaged.
---
@@ -577,6 +626,8 @@ The servers always run as the `terraria` user. Administration is simplest with `
| `mods <name>` (list) | root, or members of the `terraria` group | |
| `mods add/enable/disable/remove` | root (or `terraria`) | Run as root, it sets ownership of the files it installs to `terraria`. |
| `delete` | root only | Checked by the script. |
| `export` | root, or members of the `terraria` group | Reads the instance, and asks a running server to save. |
| `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. |
| `stop` | Only the service | Needs the server's process ID from systemd. |
| `systemctl start/stop/enable` | root | |
@@ -610,7 +661,7 @@ Editing an existing file with `sudo nano` keeps its owner, so it's fine.
## Running by hand for debugging
Stop the service first, so two copies of the same server don't run at once on the same port and world:
Stop the service first. `terractl` won't let two copies of the same server run at once: if the service is running, `run` refuses and tells you to stop it.
```bash
sudo systemctl stop terraria@calamity
@@ -623,6 +674,18 @@ The server runs in your terminal and you can type commands into it directly. Typ
sudo systemctl start terraria@calamity
```
### How running servers are protected
While a server runs, whether systemd started it or you did, it holds a lock on the file `<instance>/.lock`. The lock is released automatically when the server exits, even if it crashes, so it can never be left behind. While the lock is held:
- **A second `run` is refused**, and so is starting the service while a copy started by hand is running. In that case the service keeps retrying every 10 seconds and starts by itself once the other copy exits.
- **`prepare` is refused**, so `server/` can't be replaced under the running server.
- **`reinstall --clean` is refused**, so `.NET` can't be deleted under it. Plain `reinstall` is allowed, because it only takes effect at the next start.
- **`delete` stops the service**, but refuses to go on if a copy started by hand is still running.
- **`list` shows a copy started by hand** as `running (outside systemd)`.
`terractl stop` is only for the service's own use. Typed by hand, it tells you to use `systemctl stop terraria@<name>` instead.
---
## Troubleshooting
@@ -657,7 +720,10 @@ Run `terractl mods <name>` to check for mods that are enabled but missing. Then
- the files are owned by root.
**The server fails with "address already in use".**
Two instances share a port, or a copy you started by hand is still running. Check with `sudo terractl list` and `pgrep -af 'tModLoader.dll|TerrariaServer'`.
Two instances share a port. Check the ports with `sudo terractl list`. A second copy of the *same* instance can't be the cause, because `terractl` prevents it.
**"already running outside systemd" or "is active; stop it first".**
The instance's server is already running, so the command was refused to protect it. Stop the server first. If it was started with `terractl run` in another terminal, type `exit` there; otherwise use `sudo systemctl stop terraria@<name>`.
**The service starts but you can't connect.**
Check the port in `serverconfig.txt`, your firewall (TCP), and router port forwarding.
@@ -678,7 +744,8 @@ It was generated before the mods were added. Delete the world files in `data/Wor
- instance names;
- `vanilla`/`tmodloader` for `new`;
- common server console commands for `cmd` (`save`, `say`, `playing`, `kick`...);
- the options of `reinstall` and `delete`;
- the options of `reinstall`, `delete` and `export`;
- `.tar.gz` files for `export` and `import`;
- `mods` actions. For `mods add` it completes `.tmod` files and folders; for `mods enable` and `mods remove`, the installed mods; for `mods disable`, the enabled ones.
It works with `sudo terractl` too. It needs the `bash-completion` package, which most Debian and Ubuntu systems already have (`sudo apt install bash-completion`). It takes effect in new terminal sessions.
@@ -701,12 +768,15 @@ terractl mods <name> add <folder|file.tmod>... Install and enable mods (and M
terractl mods <name> enable|disable <Mod>... Change which mods load
terractl mods <name> remove <Mod>... Uninstall mods
terractl delete <name> [-y] [--no-backup] Stop, disable, back up and remove
terractl export <name> [file.tar.gz] [--with-server]
Archive an instance (configs, worlds, mods)
terractl import <name> <file.tar.gz> Create an instance from an archive
terractl --version Show the installed version
Used by the service:
terractl prepare <name> Create dirs/configs, unpack zip if needed
terractl run <name> Run the server
terractl stop <name> <pid> Save and shut down via the console
terractl stop <name> <pid> Save and shut down via the console (service only)
```
```