GSP/Panel
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

complete codex docs

Browse source
This commit is contained in:
Frank Harris 2026-06-05 11:37:09 -05:00
parent b5dcf01a8c
commit 3cefad183d
62 changed files with 2730 additions and 50 deletions
Download patch file Download diff file Expand all files Collapse all files

66
docs/architecture/AI_GSP_ARCHITECTURE.md Normal file
View file

@ -0,0 +1,66 @@
# GSP Component Architecture
This repository contains the related GSP components together:
- `/Agent-Windows` - Cygwin/Windows game server agent.
- `/Agent_Linux` - Linux game server agent.
- `/Panel` - PHP control panel used by customers and staff.
- `/Website` - public website and related customer-facing pages.
## Panel And Agent Communication
The Panel talks to agents through XML-RPC using the encrypted parameter helpers in `Panel/includes/lib_remote.php`. The Panel should request actions from the agent and treat the agent as the source of truth for server state.
The shared server control backend is still `screen` for both Linux and Cygwin/Windows agents. The Panel should not decide that a game server is online only because a web request, LGSL query, or GameQ query succeeded.
## Status Source Of Truth
The agent is the source of truth for start, stop, restart, and status. Marker files such as `SERVER_STOPPED` or startup flag files may still exist for legacy autorestart and startup bookkeeping, but they are not trusted as the current server state.
The minimum readiness check is:
1. The configured process/session exists.
2. The configured game port is listening.
LGSL/GameQ query data is optional metadata only. It can provide player counts, maps, hostname, and other query details. If query fails while the process/session exists and the game port is listening, the Panel should show the server as online with a small "query info unavailable" note.
## Status Model
- `OFFLINE`: no managed process/session and no listening game port.
- `STARTING`: managed process/session exists, but the game port is not listening yet.
- `ONLINE`: managed process/session exists and the game port is listening.
- `STOPPING`: stop was requested and the managed process/session still exists.
- `UNRESPONSIVE`: the managed process/session exists but the game port did not become ready before timeout, or stop did not complete cleanly.
- `UNKNOWN`: the agent cannot be reached or did not return structured status.
## Start
Start should launch the configured screen/session and immediately report a starting state if the session exists. Slow games, including Arma 2 and DayZ Mod, must not be marked failed just because LGSL/GameQ did not answer quickly.
Startup timeout should be configurable per game XML when possible, with a default of 180 seconds.
## Stop
Stop should issue the configured graceful control command when available. The agent then checks whether the managed screen/session is gone and whether the game port is no longer listening. If the process/session remains after the wait period, the agent escalates by closing the screen session.
The Panel should only show stopped after the agent confirms `OFFLINE`.
## Restart
Restart is intentionally simple:
1. Stop server.
2. Wait 60 seconds.
3. Start server.
Do not use a separate shortcut that skips stop verification or depends on query responses.
## Log Viewer
The gamemanager log viewer should update the log text through AJAX/live fetches only. It should not reload the full page for each refresh and should not show the old manual refresh interval dropdown or plus/update button.
The live log should preserve mobile scrolling behavior and only auto-scroll when the user is already near the bottom.
## Agent Parity
Keep Linux and Cygwin/Windows agent behavior as similar as possible. Both should continue using `screen` as the shared backend for now and expose the same status model to the Panel.

129
docs/architecture/API_REFERENCE.md Normal file
View file

@ -0,0 +1,129 @@
# API Reference
## Overview
Panel-Agent communication uses XML-RPC over HTTP.
Main transport wrapper:
- `Panel/includes/lib_remote.php`
Main agent implementation files:
- `Agent_Linux/ogp_agent.pl`
- `Agent-Windows/ogp_agent.pl`
The Panel encrypts arguments before sending them to the agent. The agent decodes them, performs the requested action locally, then returns a status or payload.
## General Call Pattern
```text
Panel module
-> OGPRemoteLibrary method in lib_remote.php
-> XML-RPC request to agent /RPC2
-> agent subroutine in ogp_agent.pl
-> local screen/process/file/network action
-> return code or structured payload
```
## Core RPC Methods
| RPC / Wrapper | Purpose | Common Callers | Notes |
|---|---|---|---|
| `status_chk` | Quick agent reachability check | Panel health checks | Returns a lightweight online/offline/encryption state. |
| `rfile_exists` | Test if a remote file exists | File/content helpers | Used for safe file checks before read/write actions. |
| `get_log` | Fetch screen or console log text | `gamemanager` | Returns log content plus a status code. |
| `remote_stop_server` / `stop_server` | Stop a game server | `gamemanager`, scheduler actions | Takes control protocol and home path data. |
| `remote_send_rcon_command` / `send_rcon_command` | Send RCON/console command | `gamemanager`, `rcon`, scheduler warnings | Useful for warning messages and admin commands. |
| `remote_readfile` / `readfile` | Read a remote file | File editor, config tools | Must remain path-safe. |
| `remote_writefile` / `writefile` | Write a remote file | File editor, config tools | Must remain path-safe. |
| `universal_start` | Start a game server | `gamemanager` | Launches a managed `screen` session. |
| `is_screen_running` | Test whether a managed screen session exists | `gamemanager`, monitor pages | Legacy/simple screen check, not full readiness. |
| `remote_server_status` / `server_status` | Structured server status | `gamemanager` | The preferred source for online/start/stop state. |
| `remote_restart_server` / `restart_server` | Restart a server | `gamemanager` | Intended to be stop, wait, start. |
| `remote_query` | Query game metadata | `gamemanager` | Optional metadata only. |
| `steam_cmd` / `steam` / `automatic_steam_update` | SteamCMD-based update flows | Update actions, Workshop/install tools | Used by Steam-based server maintenance. |
| `start_file_download` | Download external content | Update/content tools | Returns a PID or progress handle. |
| `uncompress_file` | Extract archives | Content installers | Used for zip/tar package installs. |
| `remote_dirlist` / `remote_dirlistfm` | Read remote directory listings | File manager | Used for browse views. |
| `cpu_count`, `renice_process`, `force_cpu` | System/process control helpers | Update/start flows | Used during server launch optimization. |
| `clone_home` / `remove_home` | Duplicate or delete a server home | Provisioning/admin tools | Used during provisioning and teardown. |
| `secure_path`, `get_chattr` | Path safety and attribute helpers | File and security tools | Helps enforce control-path rules. |
| `ftp_mgr` | FTP management helper | FTP module | Used to manage server FTP state. |
| `compress_files` | Archive files | Backup/content tools | Candidate building block for backups. |
| `start_fastdl` / `stop_fastdl` / `restart_fastdl` / `fastdl_status` | FastDL service management | `fast_download` | Source/GoldSrc web distribution support. |
| `scheduler_*` methods | Task list and task CRUD | `cron` | Agent-owned scheduler implementation. |
| `agent_restart` | Restart the agent itself | Admin maintenance | Node maintenance action. |
| `shell_action` | Run a shell action in a controlled way | Advanced agent operations | Should remain tightly permissioned. |
| `send_steam_guard_code` | Submit Steam Guard code | Steam authenticated installs | Used for authenticated SteamCMD workflows. |
| `steam_workshop` / `get_workshop_mods_info` | Workshop-related helper calls | Workshop/content flows | Active in current module work, but still being consolidated. |
## Status And Return Patterns
Return values differ by method, but common patterns are:
- `1` or positive values for success
- `0` for offline/unavailable
- `-1` or another negative value for error
- structured arrays/hashes for richer status methods
`remote_server_status` is the important structured response. It should return the agent as source of truth for:
- `OFFLINE`
- `STARTING`
- `ONLINE`
- `STOPPING`
- `UNRESPONSIVE`
- `UNKNOWN`
## Sequence Diagrams
### Start
```text
Panel
-> universal_start
Agent
-> create screen session
-> launch server command
Panel
-> remote_server_status polling
Agent
-> session/process + port checks
Panel
-> render STARTING / ONLINE / UNRESPONSIVE
```
### Stop
```text
Panel
-> remote_stop_server
Agent
-> graceful stop command if available
-> wait for session/process exit
-> escalate to kill if needed
Panel
-> remote_server_status polling
Agent
-> confirm OFFLINE or UNRESPONSIVE
```
### Logs
```text
Panel log page
-> get_log
Agent
-> read screen log or console log
Panel
-> refresh textarea via AJAX
```
## Error Handling Notes
- Do not treat query failure as a start failure by itself.
- Do not treat marker-file presence as the source of truth.
- Do not expose raw shell execution to customers through generic RPC routes.
- When a method returns a payload, record the error text in the Panel UI if the operation fails.

29
docs/decisions/0001-screen-vs-tmux.md Normal file
View file

@ -0,0 +1,29 @@
# Decision 0001: Keep `screen` As The Shared Backend
## Status
Accepted
## Decision
GSP should keep `screen` as the shared process/session backend for both Linux and Windows/Cygwin agents for the current platform generation.
## Reasoning
- The existing agents already implement server lifecycle around `screen`.
- Linux and Windows/Cygwin behavior can stay aligned if both sides share the same session model.
- The Panel already expects session-based lifecycle checks.
- Moving to a different backend too early would create a large amount of compatibility work for start/stop/restart, logging, and scheduler flows.
## Alternatives Considered
- `tmux`
- direct process supervision without session wrappers
- custom daemon per server
## Why Those Were Not Chosen
- They would require broader code changes across both agents and the Panel.
- The existing runtime, log, and scheduler flows already assume `screen`.
- Cross-platform parity is easier to maintain with the current backend.

32
docs/decisions/0002-status-detection.md Normal file
View file

@ -0,0 +1,32 @@
# Decision 0002: Agent-Truthed Status Detection
## Status
Accepted
## Decision
Server status should be derived from agent truth:
1. managed process/session existence
2. required game port listening
3. optional query and metadata lookup
## Reasoning
- Marker files become stale after crashes, failed starts, and power loss.
- Query systems like LGSL and GameQ are useful but unreliable as the sole online signal.
- The agent can check the actual runtime state locally.
## Alternatives Considered
- query-only status
- marker-file status
- process-only status
## Why Those Were Not Chosen
- Query-only status can lie for supported games.
- Marker files are not authoritative.
- Process-only status misses the important readiness condition: the port must actually listen.

29
docs/decisions/0003-companion-programs.md Normal file
View file

@ -0,0 +1,29 @@
# Decision 0003: First-Class Companion Programs
## Status
Accepted
## Decision
Companion applications such as BEC, B3, Discord bridges, log watchers, and stats collectors should be modeled as managed companion programs rather than ad hoc customer-editable startup scripts.
## Reasoning
- Customers should not control privileged helper commands through editable startup files.
- Companion processes need to be started, stopped, and restarted alongside the game server.
- PID and log handling should be centralized.
- The same design should work across Linux and Windows/Cygwin.
## Alternatives Considered
- keep `_alsoRun.bat` style helper files
- use only `pre_start` scripts
- rely on manual customer scripts
## Why Those Were Not Chosen
- They are not centrally managed.
- They are hard to secure.
- They are difficult to cleanly stop on server shutdown.

26
docs/decisions/0004-workshop-system.md Normal file
View file

@ -0,0 +1,26 @@
# Decision 0004: Server Content Manager Is The Workshop Layer
## Status
Accepted
## Decision
`Panel/modules/addonsmanager` should remain the primary future home for Workshop items, mods, add-ons, and server content. `steam_workshop` should remain a deprecated compatibility layer only.
## Reasoning
- `addonsmanager` already has the richer schema and more complete product direction.
- It supports content types beyond Steam Workshop.
- It is a better fit for load order, enable/disable, install history, and metadata.
## Alternatives Considered
- keep `steam_workshop` as the main module
- split mods, add-ons, and Workshop into separate modules
## Why Those Were Not Chosen
- `steam_workshop` is explicitly deprecated in the codebase.
- Separate modules would fragment user workflows and duplicate install logic.

26
docs/decisions/0005-control-path-layout.md Normal file
View file

@ -0,0 +1,26 @@
# Decision 0005: Keep Managed Control Paths Outside Customer-Easy Edit Paths
## Status
Accepted
## Decision
Managed control files, manifests, scheduler state, and helper scripts should live in protected control locations rather than in customer-editable startup files where possible.
## Reasoning
- Customer-editable startup areas are too easy to tamper with.
- Managed state should not depend on files that customers can modify through FTP or file manager.
- Secure and auditable behavior is easier when control files are outside the customer content path.
## Alternatives Considered
- keep helper scripts in the game home
- keep runtime manifests next to the game executable
## Why Those Were Not Chosen
- Those options make it too easy for customers to alter managed execution.
- They complicate cleanup and lifecycle tracking.

28
docs/decisions/0006-installers.md Normal file
View file

@ -0,0 +1,28 @@
# Decision 0006: Installers Must Be Game-Capability Driven
## Status
Accepted
## Decision
Installer behavior should be driven by game XML capabilities and module metadata instead of ad hoc shell scripts or one-off module pages.
## Reasoning
- Different games need different install strategies.
- Some games are content-copy based.
- Some are SteamCMD based.
- Some need key copying, startup parameter edits, or profile transforms.
- The Panel needs a structured model to support all of them cleanly.
## Alternatives Considered
- per-game custom shell scripts only
- raw customer-provided installer commands
## Why Those Were Not Chosen
- They are harder to secure and harder to document.
- They do not scale cleanly across games or platforms.

866
docs/decisions/COMPANION_PROGRAMS_DESIGN.md Normal file
View file

@ -0,0 +1,866 @@
# Companion Programs Design Investigation
This is an investigation-only design report for adding first-class companion/sidecar application support to GSP game servers. No implementation is included here.
Repository layout reviewed:
- `/Agent-Windows`
- `/Agent_Linux`
- `/Panel`
- `/Website`
Note: the repository currently uses `Agent_Linux` on disk, not `Agent-Linux`.
## 1. Current Flow Found
### Main Agent Files
Relevant files:
- `Agent_Linux/ogp_agent.pl`
- `Agent-Windows/ogp_agent.pl`
- `Panel/includes/lib_remote.php`
- `Panel/modules/gamemanager/mini_start.php`
- `Panel/modules/gamemanager/home_handling_functions.php`
- `Panel/modules/gamemanager/start_server.php`
- `Panel/modules/gamemanager/stop_server.php`
- `Panel/modules/gamemanager/restart_server.php`
- `Panel/modules/config_games/schema_server_config.xml`
- `Panel/modules/config_games/server_config_parser.php`
- `Panel/modules/config_games/config_servers.php`
- `Panel/modules/config_games/cli-params.php`
### Agent Startup Directory And Autostart
Both agents define an agent run directory and a startup flag directory:
- Linux: `AGENT_RUN_DIR`, `GAME_STARTUP_DIR`, `SCREEN_LOGS_DIR`, `SCREENRC_FILE`
- Windows/Cygwin: same general constants, with Windows-specific SteamCMD executable paths
Both agents create/read the `startups` directory on agent startup. If startup files exist and `--no-startups` is not set, the agent reads each startup file and calls `universal_start_without_decrypt(...)` with the saved startup arguments.
Startup files are CSV-like records containing:
```text
home_id, home_path, server_exe, run_dir, startup_cmd, server_port, server_ip, cpu, nice, preStart, envVars, game_key, console_log
```
These files are useful for agent autostart but should not be treated as runtime status truth.
### Screen Usage
Both agents use `screen` as the shared runtime backend.
Linux:
- `create_screen_id(SCREEN_TYPE_HOME, $home_id)` creates names like `OGP_HOME_000000123`.
- `create_screen_cmd(...)` returns a `screen -d -m -t ... -S ...` command.
- `create_screen_cmd_loop(...)` creates a generated shell script named like `OGP_HOME_000000123_startup_scr.sh`, then runs that script inside `screen`.
- The generated shell script loops/restarts the server when autorestart is enabled.
- The script checks for `SERVER_STOPPED` before respawning.
Windows/Cygwin:
- Uses the same `create_screen_id(...)` naming pattern.
- `create_screen_cmd(...)` launches a command in `screen`.
- `create_screen_cmd_loop(...)` writes `_serverStart.bat`, then runs it through `cmd /Q /C` inside `screen`.
- The generated batch file loops/restarts the server when autorestart is enabled.
- The batch file checks `SERVER_STOPPED` before respawning.
### Start Flow
Panel start path:
- `Panel/modules/gamemanager/mini_start.php` builds `$start_cmd`.
- It collects XML `pre_start`, `environment_variables`, `lock_files`, executable name, executable location, port, IP, CPU affinity, nice value, game key, and console log.
- It calls `$remote->universal_start(...)`.
Linux agent start:
- `universal_start_without_decrypt(...)` validates the home path and executable.
- It may create a per-game Linux user when that preference is enabled.
- It writes/updates the startup flag file in `GAME_STARTUP_DIR`.
- It converts `pre_start` and environment variables between multiline and startup-safe formats.
- It builds the command according to executable type:
- `.exe` / `.bat`: Wine command
- `.jar`: startup command
- other: `./server_exe startup_cmd`
- It creates a generated shell startup script through `create_screen_cmd_loop(...)`.
- It backs up `screenlogs/screenlog.<screen_id>`.
- It runs pre-start commands through `run_before_start_commands(...)`.
- It launches the generated command through `sudo_exec_without_decrypt($cli_bin, $owner)`.
- It renices server processes after launch.
Windows/Cygwin agent start:
- `universal_start_without_decrypt(...)` validates the home path and executable.
- It converts paths with `cygpath -wa`.
- It converts `pre_start` and environment variables.
- It builds Windows commands using `cmd /Q /C start ... /WAIT`.
- With autorestart enabled, it uses `create_screen_cmd_loop(...)` and `_serverStart.bat`.
- Without autorestart, it uses `create_screen_cmd(...)`.
- It backs up `screenlogs/screenlog.<screen_id>`.
- It runs pre-start commands through `run_before_start_commands(...)`.
- It launches the screen command with `system($cli_bin)`.
- It writes a startup file named `_serverStart.bat` under `GAME_STARTUP_DIR`, though the name is generic rather than per IP/port in the current Windows path.
### Stop Flow
Panel stop path:
- `Panel/modules/gamemanager/stop_server.php` calls `$remote->remote_stop_server(...)`.
- Stop parameters include home ID, IP, port, control protocol, control password, control type, and home path.
Linux agent stop:
- `stop_server_without_decrypt(...)` removes the startup flag for `$server_ip-$server_port`.
- If autorestart is enabled, it creates `SERVER_STOPPED` in the game home.
- It attempts a graceful stop when configured:
- `rcon`
- `rcon2`
- `armabe`
- `minecraft`
- If graceful stop does not complete, it collects PIDs from the screen session using `get_home_pids(...)`.
- It sends `kill 15`, then `kill 9` if needed.
- It runs `screen -wipe`.
Windows/Cygwin agent stop:
- `stop_server_without_decrypt(...)` removes the startup flag.
- If autorestart is enabled, it creates `SERVER_STOPPED` in the game home.
- It finds the screen PID from `screen -list`.
- It maps that to a Windows PID using `ps -W`.
- It calls `cmd /C taskkill /f /fi 'PID eq ...' /T`.
- It runs `screen -wipe`.
### Restart Flow
Both agents expose `restart_server` and `restart_server_without_decrypt(...)`.
The current intended restart flow is:
1. Stop server.
2. Wait 60 seconds.
3. Start server.
That flow is now present in the current agent files. Any companion system should hook into this sequence explicitly:
1. Stop companions.
2. Stop game server.
3. Wait 60 seconds.
4. Start game server.
5. Start companions after their configured delays.
### PID Tracking
Current PID tracking exists but is inconsistent:
- The agents write their own `ogp_agent.pid`.
- FastDownload has `fd.pid`.
- Scheduler has `scheduler.pid`.
- Linux game server child PIDs are discovered from the screen PID with `pgrep -P`.
- Windows/Cygwin maps a screen PID to a Windows PID through `ps -W`.
- Some game XML uses the `PID_FILE` CLI param, for example Source-engine servers.
- Windows `_alsoRun.bat` behavior expects `_alsoRun.pid` to contain helper PIDs.
There is no general companion PID registry today.
### Marker Files
Relevant marker files:
- `GAME_STARTUP_DIR/<ip>-<port>` startup flag on Linux.
- Windows writes a startup file under `GAME_STARTUP_DIR`, currently `_serverStart.bat`.
- `SERVER_STOPPED` in the game home when autorestart is enabled.
- `_alsoRun.pid` for the current Windows helper behavior.
`SERVER_STOPPED` is used by generated autorestart scripts to decide whether to respawn. It should not be used as the source of truth for current runtime status.
### Logs
Game screen logs are written under:
```text
screenlogs/screenlog.<screen_id>
```
The agents call `backup_home_log(...)` before starting a server. If XML defines `console_log`, Panel/agent log functions may read the game-specific console log instead.
There is no dedicated companion stdout/stderr log path today.
## 2. Current Helper Script Behavior
### `_alsoRun.bat`
The clearest current companion behavior is Windows-only.
In `Agent-Windows/ogp_agent.pl`, `create_screen_cmd_loop(...)` generates `_serverStart.bat`. That generated batch file contains:
```bat
if exist "_alsoRun.bat" call "_alsoRun.bat"
start ... /wait <game command>
for /f %%p in (_alsoRun.pid) do taskkill /PID %%p /F
```
This means:
- `_alsoRun.bat` is executed before the game server process.
- `_alsoRun.pid` is read after the game server exits.
- Each PID listed in `_alsoRun.pid` is force-killed.
- This only exists in the Windows/Cygwin agent path.
- It only works when the generated `_serverStart.bat` loop path is used.
- It relies on files in or near the game server working directory.
- It depends on the helper script correctly writing `_alsoRun.pid`.
Some DayZ/Arma XML files generate `_alsoRun.bat` in `pre_start`. Examples found include:
- `Panel/modules/config_games/server_configs/dayz_arma2co_win32.xml`
- `Panel/modules/config_games/server_configs/dayz_epoch_mod_win32.xml`
Those XML files build `_alsoRun.bat` to start BEC and use WMIC to find/write the BEC PID into `_alsoRun.pid`.
Problems:
- The helper file lives in a customer-accessible game area.
- The customer may be able to edit/delete `_alsoRun.bat` or `_alsoRun.pid`.
- It is Windows-specific.
- PID capture depends on executable path matching and WMIC.
- Cleanup happens after the game process exits, not as a first-class stop action.
- It is not centrally visible to the Panel as companion state.
### `pre_start`
The XML schema supports `pre_start`.
Panel reads `pre_start` in:
- `Panel/modules/gamemanager/mini_start.php`
- `Panel/modules/gamemanager/restart_server.php`
- `Panel/modules/gamemanager/home_handling_functions.php`
The value is passed to the agent as `$preStart`.
Linux behavior:
- `run_before_start_commands(...)` writes `${home_path}/prestart_ogp.sh`.
- It writes each XML line into the shell file.
- It runs `bash prestart_ogp.sh` as the game owner.
- The script removes itself at the end.
Windows/Cygwin behavior:
- `run_before_start_commands(...)` writes `_prestart.bat` in the Windows-converted home path.
- It writes each XML line into the batch file.
- It runs `cmd /Q /C start /wait "<_prestart.bat>"`.
- It deletes `_prestart.bat`.
Concerns:
- `pre_start` is trusted XML/admin-defined script content, but it executes in/against the customer game home.
- It is not structured.
- It is not tracked.
- It is only "before start"; it is not a companion lifecycle model.
- It cannot reliably stop helper processes unless custom script authors implement that themselves.
### `post_start`
The schema and config editor order include `post_start`.
Found references:
- `Panel/modules/config_games/schema_server_config.xml`
- `Panel/modules/config_games/config_servers.php`
- `Panel/modules/config_games/xml_tag_descriptions.php`
- One example XML: `Panel/modules/config_games/server_configs/nexuiz_win.xml`
I did not find a start path that reads `server_xml->post_start` or sends it to the agents. As currently written, `post_start` appears schema-visible but not operational.
### `post_install`
Both agents include workshop/mod post-install script generation logic. This is install/update-related, not game-server runtime lifecycle management.
`post_install` should not be used for companion processes because it is not tied to server start/stop/restart.
### Custom Fields And Custom Scripts
Custom fields are supported in XML and stored per server. They are used by config replacement logic:
- `Panel/modules/gamemanager/cfg_text_replace.php`
- `Panel/modules/config_games/schema_server_config.xml`
Custom fields can influence config file content. They are not currently a safe or structured way to define executable companion commands.
Customers can also use extra startup parameters where permissions allow. That should not become the companion command source because it would permit arbitrary command injection into managed helper launches.
## 3. Recommended Method 1
### First-Class Companion Programs System
The best design is a first-class, structured companion program system.
Game XML should define the allowed companion programs for that game. The Panel should store per-server choices such as enabled/disabled and optional safe settings. The agent should own runtime launch, PID tracking, log paths, stop, and restart cleanup.
Example XML shape:
```xml
<companion_programs>
<program key="bec" name="BattlEye Extended Controls" os="windows">
<enabled_default>0</enabled_default>
<delay_seconds_default>30</delay_seconds_default>
<working_dir>{GAME_PATH}\BEC</working_dir>
<command>Bec.exe</command>
<args>-f Config.cfg</args>
<process_name>Bec.exe</process_name>
<stop_on_server_stop>1</stop_on_server_stop>
<restart_on_server_restart>1</restart_on_server_restart>
<stdout_log>companions/bec.out.log</stdout_log>
<stderr_log>companions/bec.err.log</stderr_log>
</program>
</companion_programs>
```
Recommended XML fields:
- `key`: stable internal ID.
- `name`: display name.
- `os`: `linux`, `windows`, or `any`.
- `enabled_default`: default panel setting.
- `delay_seconds_default`: default delay after game start.
- `working_dir`: trusted template path.
- `command`: trusted executable/script name or path template.
- `args`: trusted default arguments.
- `process_name`: optional verification aid only, not the kill target by itself.
- `stop_command`: optional graceful stop command.
- `stop_timeout_seconds`: default graceful wait.
- `kill_after_timeout`: boolean.
- `stop_on_server_stop`: boolean.
- `restart_on_server_restart`: boolean.
- `stdout_log` / `stderr_log`: relative managed log paths.
- `required_files`: optional list for Panel validation.
- `requires_game_online`: whether to delay until the game port is online.
### Where XML Defines Allowed Companion Programs
Add `companion_programs` to `Panel/modules/config_games/schema_server_config.xml` as an optional top-level element.
Only admins/editors of game XML should be able to define:
- executable path
- arguments
- working directory
- stop command
- process name
- default delay
- log paths
Customers should not be able to enter arbitrary commands.
### Where Panel Stores Per-Server Settings
Panel should store per-home companion settings in the database, not in customer-editable files.
Possible table:
```sql
server_companion_settings (
id INT AUTO_INCREMENT PRIMARY KEY,
home_id INT NOT NULL,
companion_key VARCHAR(64) NOT NULL,
enabled TINYINT(1) NOT NULL DEFAULT 0,
delay_seconds INT NULL,
settings_json LONGTEXT NULL,
UNIQUE KEY uniq_home_companion (home_id, companion_key)
)
```
`settings_json` should only contain safe, schema-defined options. Do not allow free-form command or shell text. For example:
- config profile selection
- config file name from an allowed list
- delay override within min/max bounds
- environment preset key
### How The Agent Receives Settings
Extend the encrypted XML-RPC start/restart call to include a companion payload, or add a dedicated agent RPC after start:
Recommended:
- `universal_start(..., companion_payload)` for direct lifecycle coupling.
- `server_companion_start(home_id, payload)` for explicit start action.
- `server_companion_stop(home_id)` for explicit stop action.
- `server_companion_status(home_id)` for status display.
The payload should be generated by the Panel from trusted XML plus stored per-server enabled settings.
Payload should contain fully resolved, validated data:
```json
{
"home_id": 123,
"server_ip": "1.2.3.4",
"server_port": 2302,
"companions": [
{
"key": "bec",
"enabled": true,
"delay_seconds": 30,
"working_dir": "/home/ogp_agent/OGP_User_Files/123/BEC",
"command": "Bec.exe",
"args": ["-f", "Config.cfg"],
"stdout_log": "bec.out.log",
"stderr_log": "bec.err.log"
}
]
}
```
For XML-RPC compatibility, this may be passed as JSON text.
### How The Agent Starts Companions
The agent should start companions after the game screen/session has launched.
Recommended approach:
- Use separate `screen` sessions per companion.
- Session naming:
- Game: `OGP_HOME_000000123`
- Companion: `OGP_COMPANION_000000123_bec`
- Write companion runtime state under an agent-controlled path outside the game FTP/file-manager root.
- Start delayed companions through a small agent-owned delay wrapper:
- Linux: `screen -d -m -S OGP_COMPANION_... bash -lc 'sleep 30; cd ...; exec ...'`
- Windows/Cygwin: `screen -d -m -S OGP_COMPANION_... cmd /Q /C "timeout /t 30 ... && cd /d ... && ..."`
This avoids blocking game startup. The Panel can show the game as `STARTING`/`ONLINE` independently while companion statuses move through `PENDING`, `STARTING`, `RUNNING`, or `FAILED`.
### How The Agent Records PIDs
Create an agent-owned runtime directory, for example:
```text
<AGENT_RUN_DIR>/companions/<home_id>/
```
Files:
```text
companions/<home_id>/state.json
companions/<home_id>/pids/<companion_key>.pid
companions/<home_id>/logs/<companion_key>.out.log
companions/<home_id>/logs/<companion_key>.err.log
```
State should include:
- home ID
- companion key
- screen session name
- agent PID/screen PID
- child PID if known
- command hash or executable path
- start time
- last status
- last error
For Linux:
- Prefer launching through `screen`.
- Use the screen PID plus child process lookup.
- If possible, make the wrapper write `echo $$` and the exec child PID to a PID file.
- Use process group/session cleanup where possible.
For Windows/Cygwin:
- Keep `screen` for parity.
- Prefer a wrapper that starts the companion and writes the Windows PID to a PID file.
- Use Cygwin `ps -W` or PowerShell/WMIC alternatives where available.
- Avoid killing by executable name alone.
### How The Agent Stops Companions
Stop by the recorded handle, not by executable name.
Recommended stop order:
1. Load `companions/<home_id>/state.json`.
2. For each running companion:
- If `stop_command` exists, run it in the configured working directory.
- Wait up to `stop_timeout_seconds`.
- If still alive and `kill_after_timeout=1`, kill only recorded PID/process tree/session.
- Close the companion screen session.
- Update state.
3. Clean stale PID files only after verifying the process is gone.
Avoid:
- `pkill Bec.exe`
- `taskkill /IM Bec.exe`
- broad executable-name matching
Those can kill unrelated customer processes.
### Restart Behavior
Recommended restart sequence:
1. Stop companions for the home.
2. Stop game server.
3. Wait 60 seconds.
4. Start game server.
5. Start enabled companions according to delay settings.
Do not let companions survive a restart unless explicitly marked as persistent and safe.
### Companion Logging
Companion stdout/stderr should be logged separately from game screen logs.
Recommended default:
```text
<AGENT_RUN_DIR>/companions/<home_id>/logs/<key>.out.log
<AGENT_RUN_DIR>/companions/<home_id>/logs/<key>.err.log
```
Panel can add a companion log viewer later, separate from the game server log viewer.
For customer visibility, expose logs through the agent RPC after permission checks rather than placing them inside the customer FTP root by default.
### Security
This method is secure because:
- Commands come from trusted game XML/admin configuration.
- Customer UI stores only enable/disable and bounded safe settings.
- Runtime files live outside the customer file manager/FTP root.
- The agent launches only known companion keys for the current game config.
- Stop/kill uses recorded PIDs/screen sessions, not executable names.
- Logs are controlled by the agent.
### Portability
This method is portable because:
- XML can define Linux and Windows variants with the same logical companion key.
- Agent receives normalized companion payload.
- Both agents use screen sessions.
- PID capture is platform-specific behind the same agent RPC model.
## 4. Recommended Method 2
### Agent-Managed Generated Startup/Cleanup Scripts
Alternate design: keep using scripts, but generate and store them in an agent-controlled directory outside customer-editable game files.
Example layout:
```text
<AGENT_RUN_DIR>/companions/<home_id>/
companions.json
start_companions.sh
stop_companions.sh
start_companions.bat
stop_companions.bat
pids/
logs/
```
The Panel still defines companions from trusted XML and stores per-server enabled settings. The agent generates scripts from those trusted definitions.
Start flow:
1. Game server launches.
2. Agent starts an agent-owned companion startup script in its own screen session.
3. Script handles delays and PID capture.
Stop flow:
1. Agent runs an agent-owned cleanup script.
2. Script kills only PIDs listed in the agent-owned `pids` directory.
3. Agent verifies cleanup.
### Pros
- Closer to the existing `_serverStart.bat` and generated shell script model.
- Easier to debug for admins because generated scripts are readable.
- Can work with the existing screen backend.
- Avoids customer-editable `_alsoRun.bat`.
- Can be implemented incrementally.
### Cons
- Still script-heavy.
- Quoting rules remain difficult across Linux, Cygwin, and Windows.
- Risk of script injection if generation is not strict.
- PID capture still needs platform-specific care.
- State management can drift if scripts are edited manually by admins.
- Less clean than direct agent-managed process APIs.
### Comparison To Method 1
Method 1 is better long term because the agent owns lifecycle state directly. Method 2 is a reasonable migration bridge if implementation speed matters, but it should still use trusted XML/admin definitions and agent-owned control paths.
## 5. Security Considerations
### Do Not Trust Customer-Editable Startup Files
Avoid using customer-editable files such as:
- `_alsoRun.bat`
- `_alsoRun.pid`
- arbitrary `.bat` or `.sh` helper files in the game home
Those files can be edited, deleted, replaced, or used to run unintended commands.
### Managed Files Should Live Outside The FTP/File Manager Root
Recommended location:
```text
<AGENT_RUN_DIR>/companions/<home_id>/
```
This directory should be owned by the agent or game server runner user and should not be directly writable by customers.
### Commands Must Come From Trusted Configuration
Companion commands should come from:
- shipped game XML
- admin-managed XML
- a future admin-only companion catalog
They should not come from:
- customer text fields
- startup extra parameters
- uploaded files
- customer-editable config files
### Validate Commands
Validation should include:
- companion key exists in the current game XML
- OS matches the agent OS
- command path resolves under an allowed directory unless explicitly admin-approved
- working directory resolves under game home or an admin-approved path
- no unexpanded `{...}` tokens remain
- no shell metacharacters in fields that are supposed to be argv tokens
- delay is numeric and capped
- log paths are relative and cannot escape managed log directories
### Avoid Arbitrary Command Execution
Use argv-style execution where possible.
When shell/batch is unavoidable:
- generate commands from trusted fields only
- quote every path/argument consistently
- avoid concatenating customer-provided strings into shell code
- keep generated files outside customer write paths
### Avoid Killing Unrelated Processes
Do not kill by executable name alone.
Preferred kill targets:
- recorded companion PID
- recorded process group
- recorded screen session
- recorded Windows process tree for that PID
Process name should be used only as a verification hint, not as the primary kill selector.
## 6. Cross-platform Considerations
### Linux Agent
Linux can use:
- `screen`
- `bash`
- PID files
- `/proc`
- `pgrep -P`
- `kill 15`, then `kill 9`
Recommended Linux companion launch:
```text
screen -d -m -S OGP_COMPANION_<home_id>_<key> bash -lc '<agent-owned wrapper>'
```
Use an agent-owned wrapper or direct fork/exec to record PID and redirect logs.
### Windows/Cygwin Agent
Windows/Cygwin can use:
- `screen`
- `cmd /Q /C`
- `start`
- `taskkill /PID ... /T`
- `ps -W`
- possibly WMIC or PowerShell depending on environment
Current `_alsoRun.bat` depends on WMIC in some XML. WMIC is not reliable on all modern Windows installations, so future code should not require it.
Recommended Windows companion launch:
```text
screen -d -m -S OGP_COMPANION_<home_id>_<key> cmd /Q /C "<agent-owned wrapper.bat>"
```
The wrapper should record the Windows PID or enough process/session information for cleanup.
### Batch vs Shell Differences
Risks:
- quoting spaces in paths
- escaping backslashes
- environment variable syntax differences
- `start` window title behavior on Windows
- delayed expansion in batch files
- Cygwin path vs Windows path conversion
- signal semantics: Linux signals vs Windows taskkill
The Panel should not build platform command strings. It should send trusted structured definitions to the agent and let the agent perform OS-specific quoting/execution.
### Screen Behavior
Screen remains the default shared backend for now.
Use separate screen sessions for companions rather than attaching them to the game server screen. This gives:
- independent status
- independent logs
- safer cleanup
- clearer restart behavior
### Process Cleanup Risks
Companion processes may:
- fork children
- daemonize
- spawn background processes
- exit while leaving children
- fail before writing PID
- be started manually by the customer/admin
The agent should track process trees where possible and verify stop results.
## 7. Suggested Implementation Phases
### Phase 1: Inventory Current Flow And Add Report Only
This report is Phase 1.
No source code changes should be made for companion behavior in this phase.
### Phase 2: XML Schema Design
Add `companion_programs` to:
- `Panel/modules/config_games/schema_server_config.xml`
- `Panel/modules/config_games/config_servers.php`
- `Panel/modules/config_games/xml_tag_descriptions.php`
Create example XML for BEC, B3, and a generic log watcher.
### Phase 3: Panel Storage/UI Design
Add storage for per-server companion settings.
Initial UI:
- show companion list from XML
- enable/disable checkbox
- delay override
- safe predefined options only
Do not expose raw command editing to customers.
### Phase 4: Agent Start/Stop Integration
Add encrypted RPCs:
- `server_companion_start`
- `server_companion_stop`
- `server_companion_status`
Extend start/restart flow to call companion start/stop at the right time.
### Phase 5: PID Tracking And Cleanup
Implement:
- agent-owned state directory
- PID files
- screen session names
- process tree cleanup
- stale PID detection
- companion status reporting
### Phase 6: DayZ/BEC Test
Migrate one DayZ/Arma BEC case away from `_alsoRun.bat`.
Test:
- start game
- delayed BEC start
- BEC status
- stop game
- BEC cleanup
- restart flow
- crash/recovery behavior
- agent restart behavior
### Phase 7: Generalized Docs
Document:
- XML authoring
- admin setup
- supported placeholders
- security rules
- troubleshooting
- log locations
- migration path from `_alsoRun.bat`
## 8. Open Questions
1. Should companions be started after the game process exists, after the game port is listening, or after query/RCON succeeds when available?
2. Should companions be allowed to keep running if the game server crashes and autorestarts, or should they always restart with each game process cycle?
3. Should some companions be marked "persistent" across game restarts?
4. Which user should run companions on Linux when `LINUX_USER_PER_GAME_SERVER` is enabled?
5. Should companion logs be visible to customers by default, or admin-only?
6. Should companion config files be editable through the existing config file module?
7. How should Windows PID capture work on systems without WMIC?
8. Is PowerShell guaranteed available in the supported Windows/Cygwin agent environment?
9. Should the Panel support companion install/update packages, or only runtime start/stop of already-installed files?
10. Should companion definitions live only in game XML, or should there be a reusable global companion catalog?
11. How should firewall rules handle companion ports if a companion needs one?
12. What should happen if a companion fails but the game server is online?
13. Should companion failure affect billing/status/customer-facing uptime?
14. How should agent autostart restore companion state after power loss or agent restart?
15. Should the agent stop companions before or after graceful game stop for tools that send shutdown messages to the game?
16. Should companion environment variables be separate from game environment variables?
17. How should command placeholders be standardized across Linux and Windows?
18. What is the maximum acceptable startup delay for companion programs?
19. Should admins be able to override companion commands per server, or only per game XML?
20. How should existing `_alsoRun.bat` game configs be migrated without breaking current customers?
## Summary Recommendation
Build Method 1: a first-class companion programs system driven by trusted XML/admin configuration, stored per server in the Panel, and executed/owned by the agent.
Do not continue expanding `_alsoRun.bat`. It is a useful proof of need, but it is Windows-specific, customer-editable, hard to audit, and unreliable for stop/restart cleanup.
Use `screen` as the shared backend for now, with one screen session per companion and agent-owned PID/log/state files outside the customer file root.

21
docs/decisions/README.md Normal file
View file

@ -0,0 +1,21 @@
# Decisions
This folder holds permanent architecture decisions and a small set of preserved investigation reports that informed those decisions.
## Decision Records
- `0001-screen-vs-tmux.md`
- `0002-status-detection.md`
- `0003-companion-programs.md`
- `0004-workshop-system.md`
- `0005-control-path-layout.md`
- `0006-installers.md`
## Preserved Reports
- `COMPANION_PROGRAMS_DESIGN.md`
- `SCHEDULER_ACTIONS_DESIGN.md`
- `STEAM_WORKSHOP_DESIGN.md`
Use the numbered decision files for long-term design rules. Use the report files for the investigative context that led to those decisions.

810
docs/decisions/SCHEDULER_ACTIONS_DESIGN.md Normal file
View file

@ -0,0 +1,810 @@
# GSP Scheduler Actions Design
## Scope
This is an investigation and design report only. It does not implement code.
The goal is to redesign GSP's Scheduler / CRON feature into a safer, more useful automation system for game hosting customers and administrators.
Repository layout reviewed:
- `Agent-Windows`
- `Agent_Linux` (the Linux agent directory currently uses an underscore in this repository)
- `Panel`
- `Website`
## 1. Current Scheduler Module Findings
### Files inspected
Panel Scheduler module:
- `Panel/modules/cron/module.php`
- `Panel/modules/cron/navigation.xml`
- `Panel/modules/cron/cron.php`
- `Panel/modules/cron/user_cron.php`
- `Panel/modules/cron/shared_cron_functions.php`
- `Panel/modules/cron/events.php`
- `Panel/modules/cron/thetime.php`
Panel remote/API integration:
- `Panel/includes/lib_remote.php`
- `Panel/includes/api_functions.php`
- `Panel/modules/gamemanager/start_server.php`
- `Panel/modules/gamemanager/stop_server.php`
- `Panel/modules/gamemanager/restart_server.php`
- `Panel/modules/gamemanager/update_actions.php`
- `Panel/modules/gamemanager/rcon.php`
- `Panel/modules/addonsmanager/server_content_actions.php`
Agent scheduler implementation:
- `Agent_Linux/ogp_agent.pl`
- `Agent-Windows/ogp_agent.pl`
### Current database tables used
The current Scheduler module does not appear to own database tables. Module metadata has:
- `Panel/modules/cron/module.php`
- `$db_version = 0`
Scheduled jobs are stored on each agent in a flat file:
- Linux: `AGENT_RUN_DIR/Schedule/scheduler.tasks`
- Linux: `AGENT_RUN_DIR/Schedule/scheduler.pid`
- Linux: `AGENT_RUN_DIR/Schedule/scheduler.log`
- Windows/Cygwin: `AGENT_RUN_DIR/scheduler.tasks`
- Windows/Cygwin: `AGENT_RUN_DIR/scheduler.pid`
- Windows/Cygwin: `AGENT_RUN_DIR/scheduler.log`
This means the agent is currently the storage location for task definitions, and the Panel reconstructs task lists by asking each agent for its task file.
### Current actions
Current customer-visible scheduled actions from `get_action_selector()`:
- `restart`
- `stop`
- `start`
- `steam_auto_update` when the game XML installer is `steamcmd`
Additional server content actions are appended when `addonsmanager` is installed:
- `server_content_check_updates`
- `server_content_check_workshop_updates`
- `server_content_install_updates_if_stopped`
- `server_content_install_updates_next_restart`
- `server_content_install_updates_now`
- `server_content_install_updates_and_restart`
- `server_content_notify_updates_only`
- `server_content_update_all`
- `server_content_validate_files`
- `server_content_backup_before_update`
Admin-only raw command path:
- `Panel/modules/cron/cron.php` exposes a second form where an admin selects a remote server and enters a raw shell command.
### How tasks are created
Customer task creation path:
1. User opens `Panel/modules/cron/user_cron.php`.
2. User selects a game server and action.
3. Panel validates the five CRON fields using `checkCronInput()`.
4. Panel calls `build_cron_scheduler_command()`.
5. The command is built as a `wget` callback to `ogp_api.php`.
6. Panel sends the whole CRON line to the agent through `scheduler_add_task()`.
7. Agent appends the task line to `scheduler.tasks`.
8. Agent restarts its scheduler process.
Admin task creation path:
1. Admin opens `Panel/modules/cron/cron.php`.
2. Admin can use the same server/action selector.
3. Admin can also enter a raw command for a remote server.
4. Panel writes the raw command into the agent task file.
Current scheduled API callback examples:
```text
wget -qO- "<panel>/ogp_api.php?gamemanager/stop&token=<token>&ip=<ip>&port=<port>&mod_key=<mod_key>" --no-check-certificate > /dev/null 2>&1
```
```text
wget -qO- "<panel>/ogp_api.php?server_content/run_scheduled_action&token=<token>&home_id=<home_id>&action=<action>&options=<json>" --no-check-certificate > /dev/null 2>&1
```
### How tasks execute
Both agents use Perl `Schedule::Cron`.
Agent startup:
- Stops prior scheduler process using `scheduler_stop()`.
- Creates a `Schedule::Cron` object.
- Adds a read/reload task that runs every second:
- `* * * * * *`
- Starts scheduler detached with `scheduler.pid`.
Agent task reload:
- `scheduler_read_tasks()` opens `scheduler.tasks`.
- It clears the in-memory timetable.
- It splits each line into five CRON fields plus command args.
- If args start with `%ACTION`, it uses `scheduler_server_action()`.
- Otherwise it adds a generic shell command task.
Current Panel-generated jobs are generic shell commands, not `%ACTION` jobs. They execute through:
- `scheduler_dispatcher()`
- backtick execution of the scheduled command
- append to `scheduler.log`
The older `%ACTION=start|stop|restart` direct-agent scheduler path still exists but does not appear to be the primary current Panel path.
### How task results are logged
Agent logging:
- `scheduler_log_events()` appends plain text to `scheduler.log`.
- Generic commands log:
- the command text
- any response text
Panel viewing:
- `Panel/modules/cron/events.php` reads `scheduler.log` from the selected remote server.
- It refreshes the log area periodically.
Limitations:
- No structured per-task run records.
- No status model such as pending/running/success/failed/skipped.
- No reliable per-run output attached to a task ID.
- No last run / next run / duration / exit code storage in the Panel DB.
- `wget` callbacks redirect output to `/dev/null`, so useful API responses are discarded.
### Current limitations and bugs
1. No Scheduler-owned database tables.
2. Tasks are stored per agent, so offline agents make task state invisible or stale.
3. Tasks contain API tokens in plain text inside agent task files.
4. Generic command scheduler can run arbitrary shell commands.
5. Admin raw command scheduling is powerful and should remain admin-only or be removed from the normal Scheduler UI.
6. Current customer tasks call the Panel through `wget`, so task execution depends on the agent reaching the Panel HTTP URL.
7. `--no-check-certificate` weakens TLS verification.
8. Task output is discarded for Panel API callbacks.
9. No retry policy.
10. No overlap prevention.
11. No conflict prevention, such as update and restart at the same time.
12. No job lock per game server.
13. No missed-run handling after agent downtime.
14. No clear timezone UX.
15. Admin and customer scheduling models are mixed in the same module.
16. Server content scheduled actions include duplicates and placeholders.
17. Some action names are not customer-friendly.
18. There is no typed argument system for warnings, backup paths, retention, RCON command allowlists, or wipe options.
19. There is no first-class notification support.
20. Linux and Windows store scheduler files in different relative locations.
## 2. Current Action Review
| Action | Keep/Remove/Admin Only | Why | Security Risk | Agent Support | Notes |
|---|---|---|---|---|---|
| `restart` | Keep | Core hosting feature. | Low if implemented through safe action. | Existing Panel API and agent restart support. | Should support warnings, save-world, lock, timeout, and result logging. |
| `stop` | Keep | Useful for scheduled shutdown windows and cost/resource control. | Low. | Existing Panel API and agent stop support. | Should verify stopped state through agent status. |
| `start` | Keep | Useful after maintenance windows. | Low. | Existing Panel API and agent start support. | Should show STARTING/ONLINE result, not only command fired. |
| `steam_auto_update` | Keep, rename | Useful but name is technical. | Medium due Steam credentials/update side effects. | Existing `steam_cmd` update path. | Rename to `update_server_files`; require game XML installer support. |
| `server_content_check_updates` | Keep internally, remove from customer dropdown for now | Useful as backend action but unclear to customers. | Low. | Partial Panel support. | Replace with clearer `check_content_updates`. |
| `server_content_check_workshop_updates` | Keep internally, remove from customer dropdown for now | Useful once Workshop system is mature. | Low/medium. | Partial support. | Expose later as `check_workshop_updates`. |
| `server_content_install_updates_if_stopped` | Keep internally | Safe behavior for automatic content updates. | Low. | Panel support. | Customer label should be `Update content when stopped`. |
| `server_content_install_updates_next_restart` | Keep internally | Useful queued-update pattern. | Low. | Panel support. | Needs real next-restart integration. |
| `server_content_install_updates_now` | Keep advanced customer/admin | Updates while server may be running can break files. | Medium. | Partial support. | Gate by game support and require warning. |
| `server_content_install_updates_and_restart` | Keep advanced customer/admin | Very useful but needs locking and warnings. | Medium. | Partial support. | Should become `update_mods_and_restart`. |
| `server_content_update_workshop` | Remove from dropdown; keep as internal alias | Duplicate with Workshop update action. | Medium. | Partial support. | Hide until Workshop redesign is implemented. |
| `server_content_update_all` | Remove/merge | Duplicate with install/update all. | Medium. | Partial support. | Replace with one clear `update_all_content`. |
| `server_content_notify_updates_only` | Remove for now | Name suggests notification but no notification system exists. | Low. | Partial check-only path. | Reintroduce after notifications exist. |
| `server_content_validate_files` | Keep admin/advanced | Useful repair/validate action. | Medium. | Partial support via generic script action. | Rename to `validate_content_files`; game support required. |
| `server_content_backup_before_update` | Remove or redesign | Currently sets an option but there is no clear backup implementation in that path. | Medium due false confidence. | Incomplete. | Replace with first-class backup action and update workflow option. |
| Raw remote shell command | Admin only or remove from normal UI | Powerful but dangerous. | High. | Existing generic scheduler execution. | Should not be available to customers. Should be audited if kept. |
| Legacy `%ACTION=start` | Remove/deprecate | Current Panel uses API callbacks. | Low. | Agent support exists. | Keep only during migration if old task files contain it. |
| Legacy `%ACTION=stop` | Remove/deprecate | Same as above. | Low. | Agent support exists. | Migrate to action registry. |
| Legacy `%ACTION=restart` | Remove/deprecate | Same as above. | Low. | Agent support exists. | Migrate to action registry. |
## 3. Competitor Feature Research
Sources reviewed:
- Nitrado automated tasks guide: https://server.nitrado.net/guides/automated-tasks-en
- Nitrado backup guide/FAQ: https://server.nitrado.net/en-US/guides/how-to-manage-and-restore-nitrado-server-backups/
- BisectHosting Starbase schedules: https://help.bisecthosting.com/hc/en-us/articles/40101097661083-How-to-Schedule-Tasks-on-the-Starbase-panel
- ZAP-Hosting scheduled tasks: https://zap-hosting.com/guides/docs/gameserver-scheduled-tasks
- Pterodactyl client schedules API docs: https://pterodactyl-panel.mintlify.app/api/client/schedules
- Shockbyte backups guide: https://shockbyte.com/help/knowledgebase/articles/how-to-backup-your-server-files
- PingPerfect scheduled server messages guide: https://pingperfect.com/knowledgebase/706/7-Days-to-Die--Scheduled-Server-Messages.html
- Host Havoc scheduled backups guide: https://hosthavoc.com/billing/knowledgebase/479/Creating-Scheduled-Backups.html
- GTXGaming Rust restart warning task guide: https://help.gtxgaming.co.uk/en/article/how-to-setup-restart-tasks-with-messages-for-your-rust-server-15zwnyr/
Common commercial features:
- Scheduled start/stop/restart.
- Scheduled backups.
- Scheduled console/RCON commands.
- Restart warning messages.
- Task offsets within a schedule.
- Backup retention limits.
- Restart-only-if-online option.
- Manual and automatic backup creation.
- Custom task scheduling.
- Game-specific tasks such as Rust wipes or server message tools.
Notable competitor patterns:
- Nitrado exposes simple automated power tasks: restart, start, stop. It also has automatic backups, but docs note timezone issues and game-specific backup behavior.
- BisectHosting Starbase schedules support separate schedules and tasks, including power actions and command tasks with time offsets.
- Pterodactyl's design is strong: schedules have multiple ordered tasks, time offsets, power actions, command actions, backup actions, `only_when_online`, and continue-on-failure behavior.
- ZAP-Hosting exposes start/stop/restart, restart-if-online, create backup, and execute command, with rate limits.
- Shockbyte emphasizes scheduled backup intervals and backup slot/auto-replace retention.
- PingPerfect supports scheduled messages and Console/RCON commands for games like 7 Days to Die.
- GTXGaming documents restart warnings/countdowns for Rust.
What GSP can do better:
- Use typed, safe game-aware actions instead of raw commands.
- Provide prebuilt restart workflows with save-world and warning steps.
- Tie Workshop/mod updates into the Scheduler.
- Add per-task locks and conflict prevention.
- Add structured logs and visible success/failure.
- Add notifications through Discord/email/panel.
- Add game XML capability detection so users only see actions that work.
- Add maintenance windows and "run when empty" automation.
- Add resource-based triggers using existing status/resource collection work.
## 4. Recommended GSP Scheduler Actions
### Customer-safe actions
- Restart server.
- Stop server.
- Start server.
- Backup server.
- Backup selected folders.
- Update Workshop mods.
- Update server content.
- Send warning message.
- Run allowed RCON command.
- Rotate logs.
- Delete old logs using admin-defined retention limits.
- Save world, if the game supports it.
- Check server status.
- Auto-restart if crashed.
### Advanced customer actions
- Scheduled wipe/reset for supported games.
- Validate/repair server files.
- Update SteamCMD game files.
- Clone backup to another server.
- Restore backup.
- Update mods and restart.
- Restart when player count is zero for X minutes.
- Restart if memory too high for X minutes.
- Restart if CPU stuck/high for X minutes.
- Scheduled config file replacement from approved templates.
- Scheduled database backup where applicable.
### Admin-only actions
- Arbitrary shell command.
- Raw script execution.
- Permission repair.
- Force kill process/session.
- Agent/node maintenance.
- Cleanup storage outside a server home.
- Clear global Workshop cache.
- Repair file ownership.
- Restart agent.
- Reboot node.
- Run panel update/maintenance.
## 5. Proposed Action System
Replace free-form action lists with a typed action registry.
Each action definition should include:
- `action_key`
- `display_name`
- `description`
- `category`
- `allowed_roles`
- `required_permissions`
- `supported_os`
- `required_agent_capability`
- `requires_game_running`
- `requires_game_stopped`
- `requires_rcon`
- `requires_workshop_support`
- `requires_steamcmd`
- `arguments_schema`
- `validation_rules`
- `timeout_seconds`
- `retry_policy`
- `overlap_policy`
- `conflict_group`
- `log_policy`
- `notification_events`
Example:
```yaml
scheduled_actions:
restart_server:
display_name: Restart Server
role: customer
agent_action: stop_wait_start
required_permissions: [server.power.restart]
args:
warning_minutes:
type: integer
min: 0
max: 60
default: 5
warning_message:
type: string
max_length: 160
default: "Server restart in {minutes} minutes."
save_world:
type: boolean
default: true
timeout_seconds: 600
conflict_group: server_power
overlap_policy: skip_if_running
```
### Recommended schedule model
Move from "one CRON line equals one command" to:
- Schedule:
- name
- cron expression or interval
- timezone
- enabled
- only_when_online
- missed_run_policy
- Tasks:
- ordered tasks within a schedule
- action key
- arguments
- time offset
- continue on failure
This matches the strongest commercial pattern and allows:
- 10 minutes before restart: send warning.
- 5 minutes before restart: save world.
- At restart time: restart server.
- 5 minutes after restart: send Discord notification.
### Suggested DB tables
`gsp_schedules`
- `id`
- `home_id`
- `remote_server_id`
- `name`
- `cron_minute`
- `cron_hour`
- `cron_day_of_month`
- `cron_month`
- `cron_day_of_week`
- `timezone`
- `enabled`
- `only_when_online`
- `missed_run_policy`
- `max_runtime_seconds`
- `created_by`
- `created_at`
- `updated_at`
`gsp_schedule_tasks`
- `id`
- `schedule_id`
- `sort_order`
- `time_offset_seconds`
- `action_key`
- `arguments_json`
- `continue_on_failure`
- `enabled`
- `created_at`
- `updated_at`
`gsp_schedule_runs`
- `id`
- `schedule_id`
- `home_id`
- `status`
- `scheduled_for`
- `started_at`
- `finished_at`
- `duration_seconds`
- `trigger`
- `last_error`
`gsp_schedule_task_runs`
- `id`
- `schedule_run_id`
- `schedule_task_id`
- `action_key`
- `status`
- `started_at`
- `finished_at`
- `exit_code`
- `message`
- `error`
- `log_path`
- `output_excerpt`
## 6. XML Integration
Game XML should declare game-specific Scheduler support.
Example:
```xml
<scheduler_support>
<action key="restart" enabled="1" />
<action key="rcon_warning" enabled="1" />
<action key="world_save" enabled="1">
<command>save</command>
</action>
<action key="workshop_update" enabled="1" />
<action key="wipe" enabled="1">
<strategy>rust_wipe</strategy>
</action>
</scheduler_support>
```
Global actions:
- Start server.
- Stop server.
- Restart server.
- Backup server files.
- Rotate logs.
- Delete old backups/logs.
- Check status.
Game-specific actions:
- Send RCON warning.
- Save world.
- Run console command.
- Workshop update.
- Mod update.
- Wipe/reset.
- Database backup.
- Validate files.
Actions requiring RCON:
- Warning message.
- Save world.
- Player-count-aware empty restart if query is not enough.
- Allowed RCON command.
- Game-specific graceful shutdown.
Actions requiring SteamCMD:
- Update SteamCMD game files.
- Validate/repair Steam game files.
Actions requiring Workshop support:
- Update Workshop mods.
- Repair Workshop mods.
- Update mods and restart.
Actions requiring backup support:
- Backup server.
- Backup selected folders.
- Restore backup.
- Clone backup.
## 7. Agent Integration
### Preferred direction
The agent should execute typed scheduled actions, not raw customer shell text.
New agent methods could be:
- `scheduler_action_start(home_id, action_manifest_json)`
- `scheduler_action_status(home_id, action_run_id)`
- `scheduler_action_log(home_id, action_run_id, offset)`
- `scheduler_action_cancel(home_id, action_run_id)`
The Panel should store schedules and send due actions to agents, or the agent should receive a structured schedule manifest from Panel. The cleanest long-term design is Panel-owned schedules plus an agent-side runner for actions.
### Start/stop/restart
Agent should:
- Use existing start/stop/restart functions.
- Use the new agent status model as source of truth.
- Wait for state transitions.
- Return structured result.
Restart should:
1. Optional RCON warning.
2. Optional save-world.
3. Stop.
4. Wait configured seconds.
5. Start.
6. Poll until STARTING/ONLINE/UNRESPONSIVE.
### Backup
Agent should:
- Create compressed archives through a typed backup action.
- Support include/exclude folders from safe config.
- Store backup manifests.
- Enforce retention.
- Avoid backing up transient cache/log folders unless configured.
### Update
Agent should:
- Run SteamCMD update or server content update through typed job actions.
- Avoid overlapping update with running backup/restart.
- Mark restart required when applicable.
### RCON/console command
Agent should:
- Use existing `send_rcon_command` support.
- Validate commands against action rules.
- Log command and response.
- Redact credentials.
Customer-safe RCON should use templates:
- `say {message}`
- `save`
- `save-all`
- game-specific warning command
Raw RCON text should be advanced/admin controlled.
### Mod update
Agent should:
- Run Workshop/server-content job runner from the Workshop design.
- Return job status and logs.
- Mark restart required.
### Log cleanup
Agent should:
- Delete only configured log paths.
- Enforce age/size limits.
- Log every removed path count/bytes.
### Status/resource actions
Agent should:
- Check process/session/port status.
- Optionally check memory/CPU samples.
- Execute conditional restart only after threshold duration.
### Timeouts and failure reporting
Every action should have:
- timeout
- retry count
- retry delay
- result status
- error message
- log excerpt
- correlation ID
## 8. Task Logs and User Feedback
Recommended run statuses:
- `pending`
- `running`
- `success`
- `failed`
- `skipped`
- `canceled`
- `timed_out`
The UI should show:
- schedule name
- enabled/disabled
- next run time
- last run time
- last status
- last duration
- current running task
- output log
- error message
- retry count
Run details should show:
- each task in the schedule
- action arguments summary
- start time
- finish time
- result
- output/log
Do not rely only on `scheduler.log`.
## 9. Notifications
Supported notification channels:
- Panel notification.
- Email.
- Discord webhook.
- Generic webhook later.
Notification events:
- Before restart.
- After restart.
- Backup succeeded.
- Backup failed.
- Update available.
- Update installed.
- Task skipped because server was offline/running.
- Task failed.
- Disk retention cleanup ran.
Security:
- Webhook URLs must be stored securely.
- Do not expose tokens in task logs.
- Customers should not be able to send arbitrary webhooks from shared infrastructure unless allowed by policy.
Pre-restart warning types:
- RCON in-game message.
- Console command.
- Discord/webhook message.
- Panel notification.
## 10. Implementation Phases
### Phase 1: Inventory/report only
- Complete this report.
- Do not modify code.
### Phase 2: Remove or hide useless actions
- Hide duplicate server-content actions from customer dropdown.
- Keep internal aliases for backward compatibility.
- Hide `server_content_backup_before_update` until real backup exists.
- Keep raw remote command admin-only.
### Phase 3: Safe action registry
- Add PHP action registry.
- Define roles, permissions, arguments, validation, and display names.
- Replace hardcoded dropdown arrays.
### Phase 4: Task logging
- Add schedule/task/run tables.
- Store run status and results.
- Keep agent `scheduler.log` as low-level debug only.
### Phase 5: Restart/backup/update actions
- Implement typed restart with warning/save-world hooks.
- Implement first-class server backup action.
- Implement update server files action.
### Phase 6: RCON warnings
- Add game XML `scheduler_support`.
- Add allowed warning/save commands.
- Add command templates and validation.
### Phase 7: Workshop update integration
- Integrate with the redesigned Workshop/server-content job system.
- Add update mods and update mods then restart workflows.
### Phase 8: Notifications
- Add panel notifications.
- Add Discord webhook.
- Add email.
### Phase 9: Commercial polish
- Multi-task schedules with offsets.
- Clone schedule to another server.
- Maintenance window mode.
- Conditional empty-server restart.
- Resource threshold triggers.
- Missed-run handling.
- Conflict and overlap visualization.
## 11. Final Recommendation
### Remove or hide
- Hide raw server-content internal actions from customer dropdown.
- Remove customer-facing `server_content_notify_updates_only` until notifications exist.
- Remove customer-facing `server_content_backup_before_update` until backup is real.
- Merge duplicate update actions into clear labels.
- Deprecate legacy `%ACTION=` task format after migration.
### Keep
- Start server.
- Stop server.
- Restart server.
- SteamCMD update, renamed to `Update server files`.
- Server content / Workshop update, once the Workshop system is mature.
- Admin raw command only behind explicit admin permissions.
### Build first
1. Typed action registry.
2. DB-backed schedules and run logs.
3. Restart server with warning and optional save-world.
4. Backup server with retention.
5. Update server files.
6. Update Workshop mods.
7. Notifications.
### Admin-only
- Shell command.
- Raw script execution.
- Force kill.
- Permission repair.
- Node cleanup.
- Agent restart/reboot.
### Delay until later
- Resource-triggered restarts.
- Wipe/reset workflows.
- Restore backup scheduling.
- Clone schedules.
- Generic webhooks.
- Advanced conditional schedules.
## Summary
The current GSP Scheduler is functional but primitive. It stores CRON lines on agents, executes shell commands, and often calls back into the Panel through `wget`. That makes it flexible, but it does not provide the safety, visibility, or polish expected from a modern commercial game hosting panel.
The recommended path is a typed, DB-backed schedule system with safe action definitions, game XML capability flags, agent-side action execution, structured run logs, notifications, and first-class workflows for restart, backup, update, Workshop mods, and RCON warnings.

1396
docs/decisions/STEAM_WORKSHOP_DESIGN.md Normal file
View file

File diff suppressed because it is too large Load diff

31
docs/development/CODEX_GUIDE.md
View file

@ -17,12 +17,15 @@ This file is the first stop for future Codex sessions working in this repository
1. `docs/architecture/REPOSITORY_OVERVIEW.md`
2. `docs/architecture/PANEL_AGENT_FLOW.md`
3. `docs/modules/MODULE_INDEX.md`
4. `docs/modules/GAMEMANAGER.md`
5. `docs/features/STATUS_SYSTEM.md`
6. `docs/features/XML_SYSTEM.md`
7. `docs/modules/SCHEDULER.md`
8. `docs/modules/SERVER_CONTENT_MANAGER.md`
3. `docs/architecture/API_REFERENCE.md`
4. `docs/modules/MODULE_INDEX.md`
5. `docs/modules/GAMEMANAGER.md`
6. `docs/features/STATUS_SYSTEM.md`
7. `docs/features/XML_SYSTEM.md`
8. `docs/modules/SCHEDULER.md`
9. `docs/modules/SERVER_CONTENT_MANAGER.md`
10. `docs/decisions/`
11. `docs/games/`
## Important Files By Topic
@ -76,6 +79,20 @@ This file is the first stop for future Codex sessions working in this repository
- `Agent_Linux/ogp_agent.pl`
- `Agent-Windows/ogp_agent.pl`
### Decisions And Historical Reports
- `docs/architecture/AI_GSP_ARCHITECTURE.md`
- `docs/decisions/0001-screen-vs-tmux.md`
- `docs/decisions/0002-status-detection.md`
- `docs/decisions/0003-companion-programs.md`
- `docs/decisions/0004-workshop-system.md`
- `docs/decisions/0005-control-path-layout.md`
- `docs/decisions/0006-installers.md`
- `docs/decisions/COMPANION_PROGRAMS_DESIGN.md`
- `docs/decisions/SCHEDULER_ACTIONS_DESIGN.md`
- `docs/decisions/STEAM_WORKSHOP_DESIGN.md`
- `docs/development/GSP_PLATFORM_IMPROVEMENT_REPORT.md`
## Common Development Workflows
### Debug a start/stop/restart issue
@ -119,6 +136,7 @@ The repository has already been mapped in these areas:
- current Server Content Manager structure
- current scheduler structure
- module-level roles and dependency patterns
- preserved investigation reports have been moved into the docs tree
## Things Intentionally Not Yet Implemented
@ -135,4 +153,3 @@ This documentation-only pass does not implement:
## Practical Rule for Future Sessions
Before scanning code broadly, read the docs layer first. Only open source files when the documentation does not already answer the question.

1020
docs/development/GSP_PLATFORM_IMPROVEMENT_REPORT.md Normal file
View file

File diff suppressed because it is too large Load diff

39
docs/features/COMPANION_PROGRAMS.md Normal file
View file

@ -0,0 +1,39 @@
# Companion Programs
## Current State
Companion programs are not yet a first-class managed system. Current behavior is mostly script-driven and game-specific.
Important references:
- `docs/decisions/0003-companion-programs.md`
- `Agent_Linux/ogp_agent.pl`
- `Agent-Windows/ogp_agent.pl`
- `Panel/modules/config_games/schema_server_config.xml`
## What The System Needs To Do
- start companion apps with the server
- stop companion apps when the server stops
- restart companion apps when the server restarts
- track PIDs or handles
- log stdout/stderr
- avoid customer-editable privileged startup scripts
## Good Companion Examples
- BEC for Arma/DayZ
- B3
- Discord bots or bridges
- log watchers
- stats collectors
- anti-cheat helpers
## Recommended Shape
The system should be XML/admin-defined and agent-managed.
## Recommendation
Keep the design centralized and game-aware. Do not rely on one-off helper files as the source of truth.

34
docs/features/COMPETITOR_COMPARISON.md Normal file
View file

@ -0,0 +1,34 @@
# Competitor Comparison
## Reviewed Hosts / Panels
- Open Game Panel
- TCAdmin
- Pterodactyl
- GameServers.com
- Nitrado
## Comparison Themes
| Area | Common Market Pattern | GSP Opportunity |
|---|---|---|
| Workshop / mods | Often present in a game-specific or host-specific way | Build a structured, game-capability-driven server content system. |
| Backups | Usually manual plus scheduled | Make backups easy, visible, restorable, and tied to retention policy. |
| Scheduling | Restarts, warnings, backups, updates | Support safer typed actions with task logs and conflict handling. |
| Status | Basic power state plus query metadata | Use agent-truth status and honest fallback messaging. |
| File management | Built-in file manager and FTP | Keep advanced file control but make it safer and clearer. |
| RCON | Often available in host tools | Make RCON presets, warnings, and logs clean and secure. |
| Permissions | Subusers/roles | Continue improving granular permissions and support workflows. |
| Provisioning | One-click create/install | Make provisioning audit-friendly and reliable. |
| Monitoring | State, logs, alerts | Surface startup failures, unresponsive servers, and maintenance notes clearly. |
## Opportunities For GSP To Be Better
- better documentation
- better agent-truth state
- clearer status transitions
- safer advanced control for power users
- more honest error reporting
- cleaner Server Content / Workshop handling
- tighter task history and logs

26
docs/features/FILE_EDITOR.md Normal file
View file

@ -0,0 +1,26 @@
# File Editor
## Current State
File editing is split across LiteFM, FTP, edit-config helpers, and agent remote read/write methods.
Important references:
- `Panel/modules/litefm/`
- `Panel/modules/ftp/`
- `Panel/modules/editconfigfiles/`
- `Panel/includes/lib_remote.php`
## What It Should Provide
- safe browsing inside server home roots
- text editing with syntax highlighting
- backups before save
- restore last saved version
- read-only protected paths
- large-file warnings
## Main Risk
Customer access must never extend into agent control files, shared secrets, or other users' server homes.

25
docs/features/FTP_SYSTEM.md Normal file
View file

@ -0,0 +1,25 @@
# FTP System
## Current State
GSP includes an FTP module and FTP-related provisioning fields.
Important references:
- `Panel/modules/ftp/module.php`
- `Panel/modules/user_games/module.php`
- `Panel/modules/server/module.php`
## Current Notes
- FTP remains useful for advanced users.
- The embedded FTP UI is legacy-heavy and should be treated carefully.
- FTP credentials need to be protected and easy to reset.
## Recommended Direction
- keep FTP as an advanced access method
- document it clearly
- avoid exposing control paths
- audit the legacy embedded file manager code

27
docs/features/INSTALLERS.md Normal file
View file

@ -0,0 +1,27 @@
# Installers
## Current State
Installer behavior is split across game XML, gamemanager startup, addonsmanager, SteamCMD helpers, and agent scripts.
Important references:
- `Panel/modules/config_games/schema_server_config.xml`
- `Panel/modules/gamemanager/home_handling_functions.php`
- `Panel/modules/addonsmanager/module.php`
- `Panel/modules/steam_workshop/module.php`
- `Agent_Linux/ogp_agent.pl`
- `Agent-Windows/ogp_agent.pl`
## Installer Types Seen In The Codebase
- SteamCMD-based installs
- download/extract installs
- script-driven installs
- Workshop/content installs
- profile/content copy workflows
## Recommended Model
Installer strategy should come from game capability metadata. The agent should execute trusted strategies, not arbitrary customer commands.

33
docs/features/LOGGING_SYSTEM.md Normal file
View file

@ -0,0 +1,33 @@
# Logging System
## Current State
Logging comes from multiple places:
- agent screen logs
- console logs
- update logs
- scheduler logs
- admin/logger history
Important references:
- `Panel/modules/gamemanager/log.php`
- `Panel/modules/gamemanager/view_server_log.php`
- `Panel/modules/gamemanager/get_server_log.php`
- `Agent_Linux/ogp_agent.pl`
- `Agent-Windows/ogp_agent.pl`
## What Works
- live log retrieval exists
- logs can be fetched through the Panel
- the viewer can update via AJAX
## What Still Needs Cleanup
- better startup failure diagnostics
- clearer newest-log-file selection
- better error highlighting
- better downloadable log history

38
docs/features/PROVISIONING.md Normal file
View file

@ -0,0 +1,38 @@
# Provisioning
## Current State
Server provisioning flows are centered in `user_games` and supported by billing and server manager modules.
Important references:
- `Panel/modules/user_games/module.php`
- `Panel/modules/user_games/add_home.php`
- `Panel/modules/user_games/edit_home.php`
- `Panel/modules/user_games/assign_home.php`
- `Panel/modules/user_games/clone_home.php`
- `Panel/modules/user_games/check_expire.php`
- `Panel/includes/api_functions.php`
- `Panel/modules/billing/module.php`
- `Panel/modules/server/module.php`
## What Provisioning Must Handle
- server home creation
- port assignment
- passwords
- FTP access
- expiration and suspension
- clone/migrate behavior
- game XML and mod selection
## Recommended Direction
Provisioning should be validated and logged more like a commercial hosting platform:
- clear create/install status
- no port collisions
- secure default passwords
- clear billing lifecycle behavior
- post-create status verification

27
docs/features/RCON_SYSTEM.md Normal file
View file

@ -0,0 +1,27 @@
# RCON System
## Current State
RCON support is part of the gamemanager and a dedicated admin RCON module.
Important references:
- `Panel/modules/gamemanager/module.php`
- `Panel/modules/gamemanager/home_handling_functions.php`
- `Panel/modules/gamemanager/rcon.php`
- `Panel/modules/rcon/module.php`
## Current Uses
- admin console commands
- warning messages before restart
- diagnostic control for supported games
- scheduler-friendly command execution
## Recommended Direction
- keep presets
- validate commands where possible
- do not expose arbitrary commands to customers by default
- log every command with user and server context

35
docs/features/SCHEDULER_SYSTEM.md Normal file
View file

@ -0,0 +1,35 @@
# Scheduler System
## Current State
The scheduler is implemented through the `cron` Panel module and agent-side `Schedule::Cron` execution.
Important references:
- `docs/modules/SCHEDULER.md`
- `Panel/modules/cron/cron.php`
- `Panel/modules/cron/shared_cron_functions.php`
- `Agent_Linux/ogp_agent.pl`
- `Agent-Windows/ogp_agent.pl`
## Current Strengths
- It can schedule server actions.
- It can schedule Steam updates and server content actions.
- It already has a visible UI and agent execution path.
## Current Weaknesses
- It is too command-string oriented.
- Customer-safe and admin-only actions are not separated cleanly enough.
- Task run history is not rich enough.
- Error reporting and conflict handling need work.
## Recommended Direction
- typed actions
- explicit permissions
- stored task history
- clear logs and results
- no customer raw shell commands by default

31
docs/games/README.md Normal file
View file

@ -0,0 +1,31 @@
# Games
This folder is reserved for game-by-game documentation.
## Current Role
The detailed game-specific behavior still lives mainly in:
- `Panel/modules/config_games/schema_server_config.xml`
- `Panel/modules/config_games/server_config_parser.php`
- `Panel/modules/gamemanager/home_handling_functions.php`
- `Panel/modules/addonsmanager/`
- the agent startup and Workshop/content scripts
## Planned Contents
Future game docs should cover:
- startup parameters
- query ports
- RCON ports
- common config files
- Workshop/mod support
- install strategies
- status quirks
- troubleshooting notes
## Current Gap
There is not yet a full game-by-game documentation catalog in this folder. That is the next obvious documentation pass after the module and architecture layers.

85
docs/modules/MODULE_INDEX.md
View file

@ -1,54 +1,54 @@
# Module Index
This is the current Panel module inventory. It is intentionally concise so future Codex sessions can decide which module to inspect in code.
This is the master module inventory for the Panel. Use it as the first stop before opening module code.
| Module | Purpose | Current State | Dependencies | Notes |
|---|---|---|---|---|
| `TS3Admin` | Teamspeak 3 admin interface | Required, legacy niche | TS3 admin files | Keep if TS3 hosting is sold. |
| `addonsmanager` | Server Content Manager | Required, actively evolving | DB tables, game XML, agent install scripts | Best current home for mods, add-ons, Workshop, and content installs. |
| `administration` | Admin utilities | Required | Core admin pages | Includes logger/watch tools. |
| `backup-restore` | Backup/restore UI | Optional, broken/testing | Hard-coded backup host/path logic | Hide until replaced. |
| `billing` | Billing, provisioning, commerce | Optional, large custom module | Payment gateways, invoices, shop/provisioning docs | Important for commercial hosting. |
| `circular` | Notification/circular messages | Optional | Panel UI | Good candidate for maintenance and announcement notices. |
| `config_games` | Game XML definitions and CLI builder | Required | XML schema/parser | Critical for startup templates, queries, custom fields, and game capabilities. |
| `cron` | Scheduler / CRON | Required | Agent scheduler methods, Panel action selection | Needs safe action registry and task history. |
| `dashboard` | Main landing dashboard | Required | Panel auth and server summaries | Should surface status, support, billing, and alerts. |
| `dsi` | Dynamic Server Image | Optional | Game imagery and cached assets | Useful for server cards and branding. |
| `editconfigfiles` | Config file shortcuts | Optional | Game config metadata | Good for surfacing common editable files. |
| `faq` | FAQ/help | Required | Site docs/content | Should link to game docs and common workflows. |
| `fast_download` | FastDL support | Required | Source/GoldSrc-style web distribution | Still useful for older Source engine communities. |
| `ftp` | FTP admin | Required | File transfer service, access rights | Needs security review but remains important. |
| `gamemanager` | Server monitor, lifecycle, logs, RCON | Required | Agent RPC, game XML, query libraries | Core customer workflow module. |
| `lgsl_with_img_mod` | LGSL server status images | Optional legacy | Query/image cache data | Secondary to agent truth. |
| `litefm` | In-panel file manager | Required | File system access rights | Should be the preferred in-panel file tool. |
| `lostpwd` | Password recovery | Required | Auth/account flow | Basic account support. |
| `modulemanager` | Module installation/configuration | Required | Module metadata | Admin maintenance tool. |
| `mysql` | MySQL hosting/admin | Required | MySQL service setup | Good future product tie-in for databases. |
| `news` | Legacy news/announcements | Optional legacy | Old CMS-like data | Consider hiding unless modernized. |
| `rcon` | RCON admin tool | Required | Server protocol support | Useful for commands, warnings, and scheduler integration. |
| `register` | Account registration | Required | Auth flow | Basic customer onboarding. |
| `server` | Server manager | Required | Agent/node management | Admin-facing node controls. |
| `settings` | Global settings | Required | Auth, site config | Admin configuration area. |
| `status` | Status page | Optional alpha | Status data | Not ready for customer-facing critical use. |
| `steam_workshop` | Legacy Workshop module | Optional deprecated | Workshop DB helpers | Hidden/deprecated in favor of `addonsmanager`. |
| `subusers` | Subuser permissions | Required | Authorization model | Important for commercial teams and communities. |
| `support` | Support landing page | Required | Ticketing/docs | Better as an entry point than the full ticket workflow. |
| `teamspeak3` | Teamspeak 3 web interface | Required if sold | TS3 service | Hide if not part of the product offering. |
| `tickets` | Support ticket system | Optional but useful | DB tables, attachments, notifications | Stronger support workflow than `support` alone. |
| `tshock` | Terraria/TShock utilities | Optional niche | Terraria/TShock game support | Expose only for supported games. |
| `update` | Panel updates | Required admin tool | Patch/update system | Admin-only maintenance. |
| `user_admin` | User management | Required | Auth/admin roles | Important for staff administration. |
| `user_games` | Server provisioning and assignment | Required | Game homes, ports, billing integration | Core provisioning path. |
| `util` | Utility tools | Required | Misc tools | Keep useful tools, hide legacy helpers that are not maintained. |
| Module | Purpose | Status | Recommendation |
|---|---|---|---|
| [`TS3Admin`](TS3Admin.md) | Teamspeak 3 admin interface | Functional / niche | Keep or hide depending on product line |
| [`administration`](administration.md) | Admin utilities and logging helpers | Functional / legacy-leaning | Keep |
| [`addonsmanager`](SERVER_CONTENT_MANAGER.md) | Server Content Manager | Functional / actively evolving | Keep / Improve |
| [`backup-restore`](backup-restore.md) | Backup and restore UI | Broken | Remove / Replace |
| [`billing`](billing.md) | Billing, provisioning, commerce | Functional / partial | Keep / Rewrite |
| [`circular`](circular.md) | Notification and circular messages | Functional | Keep / Improve |
| [`config_games`](config_games.md) | XML game definitions and CLI builder | Production / functional | Keep / Improve |
| [`cron`](SCHEDULER.md) | Scheduler / CRON | Functional / partial | Rewrite / Improve |
| [`dashboard`](dashboard.md) | Main landing dashboard | Functional | Keep / Improve |
| [`dsi`](dsi.md) | Dynamic Server Image | Legacy / functional | Keep / Audit |
| [`editconfigfiles`](editconfigfiles.md) | Config file shortcuts | Functional / partial | Keep / Improve |
| [`faq`](faq.md) | FAQ and help content | Functional | Keep / Improve |
| [`fast_download`](fast_download.md) | FastDL support | Functional | Keep |
| [`ftp`](ftp.md) | FTP administration | Functional / legacy-heavy | Keep / Rewrite |
| [`gamemanager`](GAMEMANAGER.md) | Server monitor, lifecycle, logs, RCON | Production / functional | Keep / Improve |
| [`lgsl_with_img_mod`](lgsl_with_img_mod.md) | LGSL server status images | Legacy | Deprecate / Keep as legacy |
| [`litefm`](litefm.md) | In-panel file manager | Functional | Keep / Improve |
| [`lostpwd`](lostpwd.md) | Password recovery | Functional | Keep |
| [`modulemanager`](modulemanager.md) | Module installation and access rights | Functional | Keep |
| [`mysql`](mysql.md) | MySQL hosting/admin | Functional / future-facing | Keep / Future |
| [`news`](news.md) | Legacy news / announcements | Legacy | Deprecate / Hide unless modernized |
| [`rcon`](rcon.md) | RCON admin tool | Functional | Keep / Improve |
| [`register`](register.md) | Account registration | Functional | Keep |
| [`server`](server.md) | Remote server and node manager | Production / administrative | Keep / Improve |
| [`settings`](settings.md) | Panel settings and themes | Production | Keep |
| [`status`](status.md) | Status page | Experimental / alpha | Rewrite / Deprecate |
| [`steam_workshop`](steam_workshop.md) | Legacy Workshop module | Deprecated | Deprecate / Merge |
| [`subusers`](subusers.md) | Subuser permissions | Functional | Keep / Improve |
| [`support`](support.md) | Support landing page | Functional | Keep / Merge with tickets workflow |
| [`teamspeak3`](teamspeak3.md) | Teamspeak 3 web interface | Functional if sold | Keep or hide based on product line |
| [`tickets`](tickets.md) | Support ticket system | Production / functional | Keep / Improve |
| [`tshock`](tshock.md) | Terraria/TShock utilities | Alpha / partial | Keep conditional / Improve |
| [`update`](update.md) | Panel update tooling | Production / admin-only | Keep |
| [`user_admin`](user_admin.md) | User management | Production | Keep / Improve |
| [`user_games`](user_games.md) | Server provisioning and assignment | Production / functional | Keep / Improve |
| [`util`](util.md) | Miscellaneous utility tools | Functional / mixed | Keep / Rewrite selectively |
## Dependency Notes
## Shared Dependencies
Common dependencies across many modules:
- `includes/lib_remote.php`
- `Panel/includes/lib_remote.php`
- auth/session and role checks
- `config_games` XML parsing
- DB access helpers
- database access helpers
- server home and IP/port records
## High-Value Modules
@ -65,4 +65,3 @@ The modules most likely to matter in future investigations are:
8. `billing`
9. `tickets`
10. `subusers`

52
docs/modules/TS3Admin.md Normal file
View file

@ -0,0 +1,52 @@
# TS3Admin
## Purpose
Teamspeak 3 admin interface module.
## Current Status
- Functional
- Niche
## Dependencies
- TS3 server administration data
- Teamspeak 3 service access
## Database Tables
- `ts3_homes`
## Agent Interaction
- indirect through TS3 service administration
## User Workflow
- manage TS3 service associations
## Admin Workflow
- configure TS3 homes and credentials
## Security Concerns
- Teamspeak credentials and host access
## Known Issues
- separate niche module from the game-server core
## Missing Functionality
- clearer docs and product positioning
## Suggested Future Improvements
- keep only if TS3 hosting is part of the offering
## Recommendation
- Keep / Hide depending on product line

60
docs/modules/administration.md Normal file
View file

@ -0,0 +1,60 @@
# Administration
## Purpose
Admin utilities and logging helpers, including the watch logger and external link storage.
## Current Status
- Functional
- Legacy-leaning
## Dependencies
- Panel admin pages
- `adminExternalLinks` table
- `logger` table
## Database Tables
- `adminExternalLinks`
- `logger`
## Agent Interaction
- None directly
## User Workflow
- Not customer-facing
## Admin Workflow
- manage external admin links
- inspect logger records
- use watch logger tools
## Security Concerns
- admin-only access
- log visibility should be role-gated
## Known Issues
- legacy UI patterns
- limited product value compared to newer notification/support systems
## Missing Functionality
- modern audit/log search
- tighter integration with support and notifications
## Suggested Future Improvements
- merge logger views into a unified audit area
- replace old link utilities with clearer admin widgets
## Recommendation
- Keep

62
docs/modules/backup-restore.md Normal file
View file

@ -0,0 +1,62 @@
# Backup Restore
## Purpose
Backup and restore UI for game server homes.
## Current Status
- Broken
- Testing-phase messaging in code
## Dependencies
- Hard-coded backup paths and external backup host details in module code
- Manual shell execution
## Database Tables
- None declared in module metadata
## Agent Interaction
- Not a clean agent-driven workflow
## User Workflow
- Customer-facing but not production-ready
## Admin Workflow
- currently used as an experimental/testing interface only
## Security Concerns
- hard-coded paths
- hard-coded credentials style behavior
- shell command construction
- not safe as a production backup path
## Known Issues
- explicit "not working" messaging
- dry-run style behavior
- restore flow is not a real product workflow
## Missing Functionality
- real backup job model
- retention policy
- restore verification
- download/export
- agent-integrated backup execution
## Suggested Future Improvements
- replace with a managed backup system
- move backup state and logs into the Panel/agent architecture
## Recommendation
- Remove / Replace

73
docs/modules/billing.md Normal file
View file

@ -0,0 +1,73 @@
# Billing
## Purpose
Commercial billing, provisioning, invoices, orders, transactions, coupons, and payment gateway integration.
## Current Status
- Functional
- Partial / complex
## Dependencies
- Payment gateways
- provisioning flow
- server lifecycle and expiration logic
- docs under `Panel/modules/billing/docs/`
## Database Tables
- `billing_services`
- `billing_orders`
- `billing_invoices`
- `billing_transactions`
- `billing_coupons`
- `billing_config`
- `billing_paypal_webhook_events`
- `billing_paypal_errors`
## Agent Interaction
- indirect through provisioning and server lifecycle
## User Workflow
- shop/service purchase
- invoice/payment flow
- renewals
- account/service status
## Admin Workflow
- configure payment gateways
- manage coupons and pricing
- inspect invoices/transactions
- manage provisioning behavior
## Security Concerns
- payment keys and webhook secrets
- user identity and billing data
- service suspension/expiration behavior
## Known Issues
- large and complex module surface
- requires strong testing around provisioning lifecycle
## Missing Functionality
- cleaner linkage from billing events to server state
- clearer expiration/suspension docs and UX
## Suggested Future Improvements
- simplify provisioning audit
- add clearer service lifecycle feedback
- link billing more directly to support and server monitor
## Recommendation
- Keep / Rewrite

57
docs/modules/circular.md Normal file
View file

@ -0,0 +1,57 @@
# Circular
## Purpose
Admin notifications / circular messages for broadcasting announcements to users.
## Current Status
- Functional
## Dependencies
- Panel notification flow
- user recipient tracking
## Database Tables
- `circular`
- `circular_recipients`
## Agent Interaction
- None directly
## User Workflow
- receive announcements / notifications
## Admin Workflow
- create a circular message
- target recipients
- review delivery state
## Security Concerns
- message content should be sanitized
- recipient scoping must be correct
## Known Issues
- older notification pattern
## Missing Functionality
- richer maintenance scheduling integration
- email/Discord bridge
## Suggested Future Improvements
- integrate with support and maintenance alerts
- expose clearer read/unread state
## Recommendation
- Keep / Improve

69
docs/modules/config_games.md Normal file
View file

@ -0,0 +1,69 @@
# Config Games
## Purpose
Game XML definitions, CLI parameter generation, mod definitions, and custom field mapping.
## Current Status
- Production
- Functional
## Dependencies
- XML schema
- XML parser
- gamemanager
- user_games
- file/config editing tools
## Database Tables
- `config_homes`
- `config_mods`
## Agent Interaction
- drives startup command construction
- influences query and control protocol handling
## User Workflow
- select a game definition
- configure startup parameters
- view/edit common CLI values
- work with custom fields
## Admin Workflow
- create/update XML game configs
- define mods, CLI params, ports, and custom fields
- validate XML structure
## Security Concerns
- parameter injection
- shell escaping
- path validation
## Known Issues
- schema is powerful but broad
- some capabilities are encoded implicitly instead of declaratively
## Missing Functionality
- first-class workshop/content capability declarations
- first-class scheduler capability declarations
- richer docs metadata
## Suggested Future Improvements
- extend XML capability model
- document supported variables and examples more clearly
- tie docs generation into XML
## Recommendation
- Keep / Improve

69
docs/modules/cron.md Normal file
View file

@ -0,0 +1,69 @@
# Cron
## Purpose
Scheduler / CRON for game server automation.
## Current Status
- Functional
- Partial
## Dependencies
- Panel action selectors
- agent scheduler tasks
- server monitor and content systems
## Database Tables
- None declared by the module metadata
## Agent Interaction
- `scheduler_add_task`
- `scheduler_edit_task`
- `scheduler_del_task`
- `scheduler_list_tasks`
- `scheduler_read_tasks`
## User Workflow
- create recurring server actions
- review task list and event output
## Admin Workflow
- create server-wide tasks
- create raw command tasks
- manage server content action automation
## Security Concerns
- raw commands can be dangerous
- API tokens in callbacks need careful handling
- customer-safe actions must be separated from admin-only actions
## Known Issues
- too command-string oriented
- limited task history
- overlap and conflict rules are weak
## Missing Functionality
- typed action registry
- task run history
- notifications
- missed-run handling
## Suggested Future Improvements
- rebuild around safe actions
- add structured logs and result states
- make customer-safe actions distinct from admin actions
## Recommendation
- Rewrite / Improve

53
docs/modules/dashboard.md Normal file
View file

@ -0,0 +1,53 @@
# Dashboard
## Purpose
Main landing dashboard with widgets and quick server overview.
## Current Status
- Functional
## Dependencies
- Panel dashboard widgets
- user permissions
## Database Tables
- `widgets`
- `widgets_users`
## Agent Interaction
- indirect through monitor widgets and server summaries
## User Workflow
- view server summary widgets
- access quick links
## Admin Workflow
- manage dashboard widgets and layout
## Security Concerns
- widget visibility should respect permissions
## Known Issues
- some default widgets are legacy
## Missing Functionality
- richer status and alert surfaces
## Suggested Future Improvements
- surface lifecycle state, support, billing, and docs more prominently
## Recommendation
- Keep / Improve

52
docs/modules/dsi.md Normal file
View file

@ -0,0 +1,52 @@
# Dynamic Server Image
## Purpose
Dynamic server image and artwork management for server cards.
## Current Status
- Functional
- Legacy / niche
## Dependencies
- cached server images
- game-specific artwork assets
## Database Tables
- None declared in module metadata
## Agent Interaction
- None directly
## User Workflow
- view server images in dashboard/status contexts
## Admin Workflow
- configure imagery and defaults
## Security Concerns
- image cache and file path safety
## Known Issues
- niche module with limited platform-critical value
## Missing Functionality
- clearer integration with docs and server cards
## Suggested Future Improvements
- keep only if the product uses it heavily
## Recommendation
- Keep / Audit

55
docs/modules/editconfigfiles.md Normal file
View file

@ -0,0 +1,55 @@
# Edit Config Files
## Purpose
Game-specific shortcuts for editing common configuration files.
## Current Status
- Functional
- Partial
## Dependencies
- game XML
- file manager / remote read-write helpers
## Database Tables
- None declared in module metadata
## Agent Interaction
- remote file read/write
## User Workflow
- open common config files quickly
- edit and save them
## Admin Workflow
- define which files are surfaced and how
## Security Concerns
- path validation
- protected file roots
## Known Issues
- can become a simple wrapper around file editing without enough game context
## Missing Functionality
- backup-before-save
- better docs and common file shortcuts
## Suggested Future Improvements
- tie to XML docs and common config templates
## Recommendation
- Keep / Improve

51
docs/modules/faq.md Normal file
View file

@ -0,0 +1,51 @@
# F.A.Q.
## Purpose
Basic help and FAQ content for users.
## Current Status
- Functional
## Dependencies
- site help content
- docs links
## Database Tables
- None declared in module metadata
## Agent Interaction
- None directly
## User Workflow
- read help content
## Admin Workflow
- maintain FAQ content
## Security Concerns
- content sanitization
## Known Issues
- limited compared to full docs system
## Missing Functionality
- game-aware docs integration
## Suggested Future Improvements
- link FAQ entries to module and game docs
## Recommendation
- Keep / Improve

53
docs/modules/fast_download.md Normal file
View file

@ -0,0 +1,53 @@
# Fast Download
## Purpose
FastDL support for Source/GoldSrc style content distribution.
## Current Status
- Functional
## Dependencies
- web server / FastDL setup
- access rules
## Database Tables
- `fastdl_access_rules`
- `fastdl_settings`
## Agent Interaction
- fastdl service management through agent RPC
## User Workflow
- download client assets faster from the server host
## Admin Workflow
- configure rules and server settings
## Security Concerns
- file exposure rules
- bandwidth / access control
## Known Issues
- niche feature set
## Missing Functionality
- better UI and docs
## Suggested Future Improvements
- keep for Source-family communities
## Recommendation
- Keep

59
docs/modules/ftp.md Normal file
View file

@ -0,0 +1,59 @@
# FTP
## Purpose
FTP administration and access control for server homes.
## Current Status
- Functional
- Legacy-heavy
## Dependencies
- FTP service / access credentials
- file management permissions
## Database Tables
- None declared in module metadata
## Agent Interaction
- FTP manager helpers through `lib_remote.php`
## User Workflow
- receive FTP credentials
- upload/download files through FTP client software
## Admin Workflow
- configure FTP access behavior
- manage permissions
## Security Concerns
- credentials
- root/path exposure
- embedded legacy net2ftp code
## Known Issues
- old embedded FTP UI stack
- security review needed
## Missing Functionality
- cleaner modern FTP/SFTP guidance
- clear boundary to protect agent/control files
## Suggested Future Improvements
- keep FTP as an advanced access path
- audit or replace the embedded UI layer
## Recommendation
- Keep / Rewrite

4
docs/modules/gamemanager.md Normal file
View file

@ -0,0 +1,4 @@
# gamemanager
This page is an alias for [GAMEMANAGER.md](GAMEMANAGER.md). The full module documentation lives there.

53
docs/modules/lgsl_with_img_mod.md Normal file
View file

@ -0,0 +1,53 @@
# LGSL With Image Mod
## Purpose
Legacy LGSL status listing and image-based server display.
## Current Status
- Legacy
- Functional for query display
## Dependencies
- LGSL query data
- cached image assets
## Database Tables
- `lgsl`
## Agent Interaction
- query-based display only
## User Workflow
- view public-facing server status images
## Admin Workflow
- manage LGSL entries
## Security Concerns
- query trust should not be treated as server truth
## Known Issues
- legacy status approach
- overlaps with modern agent status reporting
## Missing Functionality
- clearer integration with the current status model
## Suggested Future Improvements
- keep only where the image-based listing is still desired
## Recommendation
- Deprecate / Keep as legacy

61
docs/modules/litefm.md Normal file
View file

@ -0,0 +1,61 @@
# Lite File Manager
## Purpose
In-panel file manager and file editor for customer server homes.
## Current Status
- Functional
- Important core tool
## Dependencies
- file access rights
- remote file read/write/list helpers
- editor assets
## Database Tables
- None declared in module metadata
## Agent Interaction
- remote file listings
- read/write operations
## User Workflow
- browse files
- upload/download
- edit common configs
## Admin Workflow
- set file management permissions
- configure file manager behavior
## Security Concerns
- path traversal
- protected control files
- shared secret exposure
## Known Issues
- should be hardened around safe roots and backups
## Missing Functionality
- stronger backup-before-save
- better large file handling
- clearer read-only protected path UX
## Suggested Future Improvements
- make this the preferred editor and file browsing path
## Recommendation
- Keep / Improve

50
docs/modules/lostpwd.md Normal file
View file

@ -0,0 +1,50 @@
# Lost Password
## Purpose
Password recovery flow for users.
## Current Status
- Functional
## Dependencies
- auth and email recovery flow
## Database Tables
- None declared in module metadata
## Agent Interaction
- None directly
## User Workflow
- request password reset
## Admin Workflow
- not a primary admin surface
## Security Concerns
- reset tokens and email verification must be secure
## Known Issues
- basic account-management module
## Missing Functionality
- richer account recovery UX
## Suggested Future Improvements
- keep stable and simple
## Recommendation
- Keep

52
docs/modules/modulemanager.md Normal file
View file

@ -0,0 +1,52 @@
# Module Manager
## Purpose
Install and manage Panel modules and access rights.
## Current Status
- Functional
## Dependencies
- module metadata
- access rights registry
## Database Tables
- `module_access_rights`
## Agent Interaction
- None directly
## User Workflow
- none, admin-only
## Admin Workflow
- enable/disable modules
- manage access flags
## Security Concerns
- module access rights control what users can see and do
## Known Issues
- older module administration workflow
## Missing Functionality
- better module documentation and dependency graph
## Suggested Future Improvements
- surface module health and compatibility more clearly
## Recommendation
- Keep

53
docs/modules/mysql.md Normal file
View file

@ -0,0 +1,53 @@
# MySQL
## Purpose
MySQL hosting/admin module for servers and databases.
## Current Status
- Functional
- Future-facing
## Dependencies
- MySQL service setup
- server assignment
## Database Tables
- `mysql_servers`
- `mysql_databases`
## Agent Interaction
- indirect service provisioning
## User Workflow
- create/manage databases when enabled
## Admin Workflow
- configure MySQL servers and permissions
## Security Concerns
- database credentials and privilege strings
## Known Issues
- not a central focus of the current product line
## Missing Functionality
- clearer customer-facing DB hosting UX
## Suggested Future Improvements
- improve if DB hosting is part of the offering
## Recommendation
- Keep / Future

51
docs/modules/news.md Normal file
View file

@ -0,0 +1,51 @@
# NewsLister
## Purpose
Legacy news and announcement module.
## Current Status
- Legacy
- Optional
## Dependencies
- old CMS-style content
## Database Tables
- none declared in module metadata
## Agent Interaction
- None directly
## User Workflow
- view announcements/news posts
## Admin Workflow
- create/edit news content
## Security Concerns
- old content system patterns
## Known Issues
- legacy news/lister architecture
## Missing Functionality
- modern notification and maintenance messaging
## Suggested Future Improvements
- replace with circular notifications or a modern announcements system
## Recommendation
- Deprecate / Hide unless modernized

53
docs/modules/rcon.md Normal file
View file

@ -0,0 +1,53 @@
# Rcon
## Purpose
Admin RCON interface for issuing console commands to supported game servers.
## Current Status
- Functional
## Dependencies
- server control protocol support
- gamemanager
## Database Tables
- none declared in module metadata
## Agent Interaction
- sends RCON/console commands through the agent
## User Workflow
- usually not customer-facing
## Admin Workflow
- run commands
- support warning messages and diagnostics
## Security Concerns
- command validation
- log every command
## Known Issues
- command safety depends heavily on module-specific restrictions
## Missing Functionality
- richer presets and command history
## Suggested Future Improvements
- integrate more tightly with scheduler warnings and support workflows
## Recommendation
- Keep / Improve

51
docs/modules/register.md Normal file
View file

@ -0,0 +1,51 @@
# Register
## Purpose
User registration module.
## Current Status
- Functional
## Dependencies
- auth and account creation flow
## Database Tables
- none declared in module metadata
## Agent Interaction
- None directly
## User Workflow
- create an account
## Admin Workflow
- not an admin surface
## Security Concerns
- registration abuse prevention
- email validation
## Known Issues
- basic account onboarding module
## Missing Functionality
- richer onboarding / invitation flows
## Suggested Future Improvements
- keep stable and minimal
## Recommendation
- Keep

59
docs/modules/server.md Normal file
View file

@ -0,0 +1,59 @@
# Server Manager
## Purpose
Remote server/node management in the Panel.
## Current Status
- Production
- Administrative
## Dependencies
- remote server records
- port arrangements
- agent connection settings
## Database Tables
- `remote_server_ips`
- `remote_servers`
- `arrange_ports`
## Agent Interaction
- manages the agent endpoints and node-level data
## User Workflow
- not usually customer-facing
## Admin Workflow
- add/remove remote servers
- manage IPs, ports, NAT, firewall settings
- review node configuration
## Security Concerns
- encryption keys
- timeout settings
- firewall/IP exposure
## Known Issues
- admin UX is older and could be clearer
## Missing Functionality
- richer node health and capacity dashboard
## Suggested Future Improvements
- improve node monitoring and provisioning diagnostics
## Recommendation
- Keep / Improve

51
docs/modules/settings.md Normal file
View file

@ -0,0 +1,51 @@
# Settings
## Purpose
Panel settings, theme settings, and core site configuration.
## Current Status
- Production
## Dependencies
- auth/admin configuration
## Database Tables
- `settings`
## Agent Interaction
- None directly
## User Workflow
- none, admin-only
## Admin Workflow
- update panel settings
- update theme settings
## Security Concerns
- global configuration values need protection
## Known Issues
- basic settings model
## Missing Functionality
- clearer configuration grouping and validation
## Suggested Future Improvements
- improve admin UX and settings validation
## Recommendation
- Keep

52
docs/modules/status.md Normal file
View file

@ -0,0 +1,52 @@
# Status
## Purpose
Admin status page for server/node state.
## Current Status
- Experimental
- Alpha
## Dependencies
- status data
- node/server metadata
## Database Tables
- none declared in module metadata
## Agent Interaction
- may read status summaries
## User Workflow
- not a primary customer workflow
## Admin Workflow
- inspect status information
## Security Concerns
- should not expose sensitive details without permissions
## Known Issues
- alpha-grade module
## Missing Functionality
- stable dashboard integration
## Suggested Future Improvements
- replace with a proper node health/status dashboard
## Recommendation
- Rewrite / Deprecate

55
docs/modules/steam_workshop.md Normal file
View file

@ -0,0 +1,55 @@
# Steam Workshop
## Purpose
Legacy standalone Steam Workshop support.
## Current Status
- Deprecated
- Compatibility only
## Dependencies
- Steam Workshop DB helpers
- legacy helper functions
## Database Tables
- `steam_workshop_game_profiles`
- `steam_workshop_server_mods`
- `steam_workshop_server_settings`
## Agent Interaction
- workshop download/update helpers
## User Workflow
- legacy workshop path only
## Admin Workflow
- legacy migration / compatibility
## Security Concerns
- should not compete with the current Server Content Manager
## Known Issues
- explicitly deprecated in code comments
## Missing Functionality
- modern unified Workshop/content UX
## Suggested Future Improvements
- keep only compatibility helpers
- migrate users into `addonsmanager`
## Recommendation
- Deprecate / Merge

52
docs/modules/subusers.md Normal file
View file

@ -0,0 +1,52 @@
# Subusers
## Purpose
Subuser permissions and delegated access management.
## Current Status
- Functional
## Dependencies
- user/group permission model
- server access rights
## Database Tables
- not declared in the module metadata file itself
## Agent Interaction
- None directly
## User Workflow
- grant access to another user
- share server management rights
## Admin Workflow
- manage permission scope and delegated access
## Security Concerns
- permissions must be scoped tightly to avoid over-sharing
## Known Issues
- module documentation is sparse in code
## Missing Functionality
- clearer UI around per-server and per-feature permissions
## Suggested Future Improvements
- tie subusers into files, scheduler, content, and support permissions more explicitly
## Recommendation
- Keep / Improve

52
docs/modules/support.md Normal file
View file

@ -0,0 +1,52 @@
# Support
## Purpose
Simple support landing page for users.
## Current Status
- Functional
- Landing page only
## Dependencies
- ticketing / docs / contact flows
## Database Tables
- none declared in module metadata
## Agent Interaction
- none directly
## User Workflow
- open support entry point
## Admin Workflow
- connect support entry points to tickets and docs
## Security Concerns
- support forms must respect auth and privacy
## Known Issues
- limited compared with the tickets module
## Missing Functionality
- server context auto-attach
- ticket creation workflow
## Suggested Future Improvements
- keep as a support landing page and route users to tickets/docs
## Recommendation
- Keep / Merge with tickets workflow

50
docs/modules/teamspeak3.md Normal file
View file

@ -0,0 +1,50 @@
# Teamspeak 3 Web Interface
## Purpose
Web interface for Teamspeak 3 hosting.
## Current Status
- Functional if Teamspeak hosting is part of the offering
## Dependencies
- Teamspeak 3 service support
## Database Tables
- none declared in module metadata
## Agent Interaction
- TS3 service control and web interface integration
## User Workflow
- manage Teamspeak 3 resources
## Admin Workflow
- provide or hide TS3 support depending on the product line
## Security Concerns
- TS3 credentials and service access
## Known Issues
- separate from the game server core experience
## Missing Functionality
- clearer product documentation
## Suggested Future Improvements
- keep only if TS3 is a product line
## Recommendation
- Keep / Hide depending on product strategy

63
docs/modules/tickets.md Normal file
View file

@ -0,0 +1,63 @@
# Tickets
## Purpose
Support ticket system with messages, attachments, and settings.
## Current Status
- Production
- Functional
## Dependencies
- auth/session
- support workflows
- attachment storage
## Database Tables
- `tickets`
- `ticket_messages`
- `ticket_attachments`
- `ticket_settings`
## Agent Interaction
- indirect via server-context support requests
## User Workflow
- create ticket
- reply
- upload attachments
- track status
## Admin Workflow
- respond to tickets
- manage settings
- moderate attachments and ratings
## Security Concerns
- attachment size and file type limits
- privacy of server and billing context
## Known Issues
- should be more tightly linked to server monitor and logs
## Missing Functionality
- automatic server context attachment
- support escalation flow
## Suggested Future Improvements
- integrate server state, recent logs, and account context
## Recommendation
- Keep / Improve

4
docs/modules/ts3admin.md Normal file
View file

@ -0,0 +1,4 @@
# ts3admin
This page is an alias for [TS3Admin.md](TS3Admin.md). The full module documentation lives there.

54
docs/modules/tshock.md Normal file
View file

@ -0,0 +1,54 @@
# TShock
## Purpose
Terraria / TShock-specific support module.
## Current Status
- Alpha
- Partial
## Dependencies
- Terraria/TShock server support
- token management
## Database Tables
- `tshock`
## Agent Interaction
- token and server data used for TShock support
## User Workflow
- only for compatible Terraria servers
## Admin Workflow
- configure and manage TShock-specific settings
## Security Concerns
- token storage
- compatibility gating
## Known Issues
- alpha status
- should only appear for the right game types
## Missing Functionality
- complete docs and tighter game capability gating
## Suggested Future Improvements
- expose only when XML/game capability says Terraria/TShock
## Recommendation
- Keep conditional / Improve

55
docs/modules/update.md Normal file
View file

@ -0,0 +1,55 @@
# Update
## Purpose
Panel update and patch management.
## Current Status
- Production
- Admin-only
## Dependencies
- patch and update logs
- admin access
## Database Tables
- `update_blacklist`
- `panel_update_log`
- `update_patches`
## Agent Interaction
- indirect if patch operations touch remote systems
## User Workflow
- none, admin-only
## Admin Workflow
- inspect and apply updates
- review patch logs
## Security Concerns
- updates modify the control plane itself
## Known Issues
- can be confusing if not clearly separated from game-server updates
## Missing Functionality
- clearer update history and rollback guidance
## Suggested Future Improvements
- keep admin-only and document carefully
## Recommendation
- Keep

58
docs/modules/user_admin.md Normal file
View file

@ -0,0 +1,58 @@
# User Admin
## Purpose
User, role, and group administration.
## Current Status
- Production
## Dependencies
- auth system
- role and group tables
## Database Tables
- `users`
- `user_groups`
- `user_role_info`
- `user_group_info`
## Agent Interaction
- none directly
## User Workflow
- account management
## Admin Workflow
- create/edit users
- manage groups and roles
- set page limits and email preferences
## Security Concerns
- password handling
- email uniqueness
- group permissions
## Known Issues
- older role/group model
## Missing Functionality
- more explicit per-feature permissions
## Suggested Future Improvements
- tie roles into server content, scheduler, files, and billing more clearly
## Recommendation
- Keep / Improve

68
docs/modules/user_games.md Normal file
View file

@ -0,0 +1,68 @@
# User Games
## Purpose
Server provisioning, assignment, cloning, expiration, and home management.
## Current Status
- Production
- Functional
## Dependencies
- billing lifecycle
- server manager
- game XML configs
- Panel agent provisioning calls
## Database Tables
- `user_homes`
- `user_group_remote_servers`
- `user_group_homes`
- `master_server_homes`
## Agent Interaction
- provisioning and clone operations
- installation commands
- expiration handling
## User Workflow
- get assigned a server
- edit home details
- clone or migrate when allowed
- check expiration
## Admin Workflow
- create servers
- assign homes
- migrate homes
- manage install commands and custom fields
## Security Concerns
- port allocation
- password generation
- ownership and permission boundaries
## Known Issues
- provisioning is a critical path and needs audit-grade reliability
## Missing Functionality
- clearer install/provisioning progress
- stronger post-create verification
## Suggested Future Improvements
- make provisioning more transparent and testable
## Recommendation
- Keep / Improve

51
docs/modules/util.md Normal file
View file

@ -0,0 +1,51 @@
# Utilities
## Purpose
Miscellaneous utility tools such as Steam ID conversion and game-adjacent helpers.
## Current Status
- Mixed
- Functional but partly legacy
## Dependencies
- PHP BCMath extension
## Database Tables
- None declared in module metadata
## Agent Interaction
- some helper tools may use remote data or agent info
## User Workflow
- use helper tools when relevant
## Admin Workflow
- audit utilities and decide which are still product-relevant
## Security Concerns
- utility tools should not leak secrets or overreach permissions
## Known Issues
- mixed-value tool collection
## Missing Functionality
- clear product grouping and documentation
## Suggested Future Improvements
- keep useful tools, hide obsolete ones, and document by game relevance
## Recommendation
- Keep / Rewrite selectively