From 6c744ee323eb8c21ba2ee07e266cf160123715a8 Mon Sep 17 00:00:00 2001 From: server Date: Tue, 14 Apr 2026 08:59:56 +0200 Subject: [PATCH] docs: add Debian runtime notes --- README.md | 7 +++ docs/README.md | 15 ++++++ docs/debian-runtime.md | 114 +++++++++++++++++++++++++++++++++++++++++ docs/healthchecks.md | 88 +++++++++++++++++++++++++++++++ 4 files changed, 224 insertions(+) create mode 100644 docs/README.md create mode 100644 docs/debian-runtime.md create mode 100644 docs/healthchecks.md diff --git a/README.md b/README.md index 16ec082..5e79118 100644 --- a/README.md +++ b/README.md @@ -4,6 +4,8 @@ This repository contains the core server files and configurations. It includes f **For installation and configuration, see [instructions](#installationconfiguration) below.** +Operational Debian/Linux documentation lives under [docs](docs/README.md). + --- ## 📋 Changelog @@ -55,6 +57,11 @@ This tutorial will be showing how to install in both FreeBSD and Windows environ For the Debian runtime used in production, the repository now also contains versioned `systemd` deployment files under [deploy/systemd](deploy/systemd/README.md). +Additional operational notes: + +- [Debian Runtime](docs/debian-runtime.md) +- [Healthchecks](docs/healthchecks.md) + Example installation: ```bash diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..3c533a6 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,15 @@ +# Docs + +This directory contains the Debian/Linux-first operational documentation for the serverfiles repository. + +Current documents: + +- [Debian Runtime](debian-runtime.md) +- [Healthchecks](healthchecks.md) + +Suggested next additions: + +- database/bootstrap notes +- deployment workflow +- rollback procedure +- configuration/secrets contract diff --git a/docs/debian-runtime.md b/docs/debian-runtime.md new file mode 100644 index 0000000..1d7b432 --- /dev/null +++ b/docs/debian-runtime.md @@ -0,0 +1,114 @@ +# Debian Runtime + +This document describes the current Debian runtime layout used for the production VPS. + +## Scope + +There are two separate repositories in the deployment: + +- `m2dev-server-src`: source code, build system, smoke/login test binary +- `m2dev-server`: runtime files, configs, quests, systemd deployment files + +The server does not run directly from a git checkout. The live instance runs from a separate runtime directory. + +## Directory Layout + +Current layout on the VPS: + +```text +/home/mt2.jakubkadlec.dev/metin/ + repos/ + m2dev-server-src/ + m2dev-server/ + build/ + server-src/ + runtime/ + server/ +``` + +Meaning: + +- `repos/m2dev-server-src`: code changes, git history, tests +- `repos/m2dev-server`: runtime template and deployment assets +- `build/server-src`: out-of-tree CMake build +- `runtime/server`: live runtime tree used by `systemd` + +## Runtime User + +The runtime user is: + +```text +mt2.jakubkadlec.dev +``` + +The user owns the runtime tree and build artifacts. Operational wrappers that need direct database access or privileged installation steps are run as `root`. + +## Services + +The Debian deployment uses direct `systemd` units instead of a custom bash/python supervisor. + +Main orchestration unit: + +- `metin-server.service` + +Sub-units: + +- `metin-db.service` +- `metin-db-ready.service` +- `metin-auth.service` +- `metin-game@channel1_core1.service` +- `metin-game@channel1_core2.service` +- `metin-game@channel1_core3.service` +- `metin-game@channel99_core1.service` + +Important behavior: + +- `metin-db-ready.service` waits until the DB socket is actually listening before `auth` and `game` start +- clean shutdown exits now return success instead of fake failure codes +- Linux runtime currently uses `epoll` for fdwatch and a watchdog-thread checkpoint backend + +## Ports + +Current service ports: + +- `9000`: internal DB socket listener +- `11000`: auth +- `11011`: channel 1 core 1 +- `11012`: channel 1 core 2 +- `11013`: channel 1 core 3 +- `11991`: channel 99 core 1 + +Client-facing login flow currently uses: + +- auth: `11000` +- first public channel: `11011` + +## Deployment Notes + +Typical operational commands: + +```bash +ssh mt2 +systemctl status metin-server +systemctl restart metin-server +journalctl -u metin-auth.service -n 100 --no-pager +``` + +Rebuild the login smoke utility: + +```bash +sudo -iu mt2.jakubkadlec.dev \ + cmake --build /home/mt2.jakubkadlec.dev/metin/build/server-src \ + --target metin_login_smoke +``` + +## Security Notes + +Current operational stance: + +- password SSH login is disabled +- `root` login is allowed only by SSH key +- production helper scripts that touch the DB directly are root-only +- runtime repo and source repo do not store secrets + +Do not store production secrets in markdown, `systemd` templates, or git-tracked shell scripts. diff --git a/docs/healthchecks.md b/docs/healthchecks.md new file mode 100644 index 0000000..80eb6ee --- /dev/null +++ b/docs/healthchecks.md @@ -0,0 +1,88 @@ +# Healthchecks + +This repository contains the operational wrapper for the headless login healthcheck. The underlying smoke client lives in `m2dev-server-src`. + +## What Exists + +Source repository: + +- `tests/login_smoke.cpp` +- binary target: `metin_login_smoke` + +Runtime repository: + +- `deploy/healthcheck/metin-login-healthcheck.sh` + +Installed on the VPS: + +- `/usr/local/sbin/metin-login-healthcheck` + +## What The Headless Login Check Verifies + +The check performs the real two-step Metin login flow without a GUI client: + +1. Connect to the auth socket. +2. Complete the secure handshake. +3. Send login credentials. +4. Receive `AUTH_SUCCESS` and the login key. +5. Open a second connection to the channel socket. +6. Complete the secure handshake again. +7. Send `LOGIN2` with `login` + `login_key`. +8. Verify `EMPIRE`. +9. Verify `LOGIN_SUCCESS4`. + +This is an end-to-end login verification, not just a TCP port check. + +## How The Wrapper Works + +`metin-login-healthcheck.sh` does the following: + +- creates a temporary account in MariaDB +- runs `metin_login_smoke` +- verifies a successful auth + channel login +- deletes the temporary account on exit + +It is intended for manual admin use on the VPS. + +## Usage + +On the VPS: + +```bash +ssh mt2 +/usr/local/sbin/metin-login-healthcheck +``` + +The smoke binary can also be run directly: + +```bash +sudo -iu mt2.jakubkadlec.dev \ + /home/mt2.jakubkadlec.dev/metin/build/server-src/bin/metin_login_smoke \ + 173.249.9.66 11000 11011 +``` + +Or with password passed through the environment: + +```bash +sudo -iu mt2.jakubkadlec.dev env METIN_LOGIN_SMOKE_PASSWORD='' \ + /home/mt2.jakubkadlec.dev/metin/build/server-src/bin/metin_login_smoke \ + 173.249.9.66 11000 11011 --password-env=METIN_LOGIN_SMOKE_PASSWORD +``` + +## Security Notes + +This does not open a new public network surface. It is a local operational tool. + +Current guardrails: + +- no new listening port +- root-only installed wrapper (`/usr/local/sbin/metin-login-healthcheck`, mode `700`) +- temporary credentials +- cleanup trap removes the test account +- wrapper passes the password through environment instead of command-line plaintext +- secrets are not committed to git + +Remaining trust boundary: + +- anyone with effective root access can still inspect or run the check +- therefore this tool assumes root is already trusted