docs: add Debian runtime notes
This commit is contained in:
server
15
docs/README.md
Normal file
15
docs/README.md
Normal file
@@ -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
|
||||
114
docs/debian-runtime.md
Normal file
114
docs/debian-runtime.md
Normal file
@@ -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.
|
||||
88
docs/healthchecks.md
Normal file
88
docs/healthchecks.md
Normal file
@@ -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 <login> <password>
|
||||
```
|
||||
|
||||
Or with password passed through the environment:
|
||||
|
||||
```bash
|
||||
sudo -iu mt2.jakubkadlec.dev env METIN_LOGIN_SMOKE_PASSWORD='<password>' \
|
||||
/home/mt2.jakubkadlec.dev/metin/build/server-src/bin/metin_login_smoke \
|
||||
173.249.9.66 11000 11011 <login> --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
|
||||
Reference in New Issue
Block a user