use journal namespace

docs/guide.md

@@ -50,6 +50,7 @@ Everything is installed by the `terraria-server-manager` package:
 | `/usr/lib/systemd/system/terraria@.socket` | Creates the console pipe the server reads commands from. |
 | `/usr/bin/terractl` | Helper script. The service calls it to set up, run and stop servers; you use it for everyday management. |
 | `/etc/default/terractl` | Optional overrides (locations, stop timeout). |
+| `/etc/systemd/journald@terraria.conf` | Size and retention of the servers' own journal (see [Logs](#logs)). |
 | `/usr/lib/sysusers.d/terractl.conf` | Defines the `terraria` system user. |
 | `/usr/lib/tmpfiles.d/terractl.conf` | Creates `/var/lib/terraria` and its subdirectories. |
 | `/usr/share/terraria-server-manager/export-tmod-mods.ps1` | Optional. Copy to your Windows PC to collect your enabled tModLoader mods. |
@@ -58,7 +59,7 @@ What happens when an instance starts:
 
 1. systemd creates the console pipe `/run/terraria/<name>.stdin` (from the socket unit).
 2. `terractl prepare <name>` creates the instance directory and default configs if they're missing, and unpacks the server zip if it hasn't been unpacked yet.
-3. `terractl run <name>` starts the vanilla or tModLoader server, reading commands from the pipe and logging to the journal.
+3. `terractl run <name>` starts the vanilla or tModLoader server, reading commands from the pipe and logging to the servers' own journal (see [Logs](#logs)).
 
 On stop, `terractl stop` sends `exit` through the pipe so the world is saved before the server shuts down.
 
@@ -130,7 +131,7 @@ sudo apt remove terraria-server-manager      # stops all instances (worlds are s
 sudo apt purge terraria-server-manager       # also removes config and boot-time enablement
 ```
 
-Neither command deletes `/var/lib/terraria` or the `terraria` user, so your worlds survive even a purge. To delete everything:
+Neither command deletes `/var/lib/terraria`, the servers' journal or the `terraria` user, so your worlds survive even a purge. To delete everything:
 
 ```bash
 sudo rm -rf /var/lib/terraria && sudo userdel terraria
@@ -319,7 +320,7 @@ Behaviour to be aware of:
 
 ## The server console
 
-Each server reads console commands (`save`, `say`, `kick`, `playing`, and so on) from its pipe, and its output goes to the systemd journal.
+Each server reads console commands (`save`, `say`, `kick`, `playing`, and so on) from its pipe, and its output goes to the servers' own journal.
 
 ### Interactive: `attach`
 
@@ -340,16 +341,32 @@ sudo terractl cmd calamity save
 sudo terractl cmd calamity say Restarting in 5 minutes
 ```
 
-This is useful in scripts and cron jobs. The command's output appears in the journal.
+`cmd` prints the server's reply, then returns once the server has been quiet for a second (at most 5 seconds). For example, `terractl cmd calamity playing` lists who's online. That makes it handy in scripts and cron jobs too. If the server doesn't answer within 5 seconds (for instance while it's still loading), `cmd` says so; the command has still been sent.
 
-### Logs only
+Members of the `terraria` group can use `attach` and `cmd` fully, output included, without `sudo`. See [Logs](#logs) for how that's arranged.
+
+### Logs
+
+The servers don't log into the main system journal. They have **their own journal**, a systemd *log namespace* called `terraria`. That keeps them separate for two reasons:
+
+- **Access.** The `terraria` group is given read access to the servers' journal and nothing else, so moderators can follow the game servers without being able to read the rest of the system's logs (logins, `sudo` use, other services).
+- **Space.** Chatty game servers can't push system logs out of a size-limited journal, or the other way round.
+
+To read it with `journalctl`, add `--namespace=terraria`:
 
 ```bash
-journalctl -u terraria@calamity -f          # follow
-journalctl -u terraria@calamity -n 100      # last 100 lines
-journalctl -u terraria@calamity --since today
+journalctl --namespace=terraria -u terraria@calamity -f           # follow
+journalctl --namespace=terraria -u terraria@calamity -n 100       # last 100 lines
+journalctl --namespace=terraria -u terraria@calamity --since today
+journalctl --namespace=+terraria -u terraria@calamity             # also systemd's own start/stop messages
 ```
 
+Plain `journalctl -u terraria@calamity`, without `--namespace`, only shows systemd's messages about the service (started, stopped, failed), not the server's output. With `+terraria`, both are shown together; that part needs root or the `systemd-journal` group, because systemd's messages are in the system journal.
+
+**Size and retention** are set in `/etc/systemd/journald@terraria.conf`, which by default allows up to 256 MB on disk. After editing it, run `sudo systemctl restart systemd-journald@terraria`.
+
+**How the group access works.** Before each server starts, a small root step (`terractl journal-access`) creates the servers' journal folder, `<machine-id>.terraria` under `/var/log/journal` (or `/run/log/journal` if the system doesn't keep logs across reboots). It gives that folder a read permission for the `terraria` group, which journald's files inherit, including after log rotation. It never creates `/var/log/journal` itself, because that would switch the whole system to persistent logging.
+
 tModLoader also writes its own logs to `/var/lib/terraria/instances/<name>/server/tModLoader-Logs/`:
 
 - `Launch.log` covers the .NET download and startup.
@@ -620,8 +637,8 @@ The servers always run as the `terraria` user. Administration is simplest with `
 | `new` | root (or `terraria`) | Run as root, it sets ownership of the new instance to `terraria` itself. |
 | `list` | root, or members of the `terraria` group | `/var/lib/terraria` is not readable by other users. |
 | Adding zips to `dist/` | root, or members of the `terraria` group | |
-| `attach` | root, or members of **both** `terraria` and `systemd-journal` | Needs to write to the console pipe and read the journal. |
-| `cmd` | root, or members of the `terraria` group | Writes to the console pipe. |
+| `attach` | root, or members of the `terraria` group | Writes to the console pipe and reads the servers' journal. |
+| `cmd` | root, or members of the `terraria` group | Same as `attach`. |
 | `reinstall` | root (or `terraria`) | |
 | `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`. |
@@ -631,12 +648,13 @@ The servers always run as the `terraria` user. Administration is simplest with `
 | `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 | |
-| `journalctl -u terraria@...` | root, or members of `systemd-journal` or `adm` | |
+| `journalctl --namespace=terraria ...` | root, or members of the `terraria` group | The servers' output only; see [Logs](#logs). |
+| `journalctl -u terraria@...` (system journal) | root, or members of `systemd-journal` or `adm` | systemd's start/stop messages. |
 
 To run the everyday commands without `sudo`:
 
 ```bash
-sudo usermod -aG terraria,systemd-journal youruser     # then log out and back in
+sudo usermod -aG terraria youruser     # then log out and back in
 ```
 
 Members of the `terraria` group can read server files (useful for backups) but cannot change them. Files the service creates are readable, not writable, by the group.
@@ -728,6 +746,9 @@ The instance's server is already running, so the command was refused to protect
 **The service starts but you can't connect.**
 Check the port in `serverconfig.txt`, your firewall (TCP), and router port forwarding.
 
+**`attach` or `cmd` sends commands but shows no output.**
+Both commands print a note explaining why. If you were just added to the `terraria` group, log out and back in. If you're already in it, the servers' journal hasn't been set up for the group yet; that happens automatically when a server starts, or run `sudo terractl journal-access`. Servers that were running before upgrading to 0.0.11 keep logging to the system journal until they're restarted.
+
 **The server isn't restarting after it stopped.**
 It exited cleanly, probably via `exit` in the console, so systemd leaves it stopped. Start it again with `systemctl start`.
 
@@ -782,5 +803,5 @@ terractl stop <name> <pid>                        Save and shut down via the con
 ```
 systemctl start|stop|restart|status terraria@<name>
 systemctl enable|disable [--now] terraria@<name>
-journalctl -u terraria@<name> [-f] [-n N]
+journalctl --namespace=terraria -u terraria@<name> [-f] [-n N]
 ```