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

cleanup

Browse source
This commit is contained in:
Frank Harris 2026-07-02 18:11:32 -05:00
parent a49371c3dd
commit 251af10faf
1190 changed files with 12636 additions and 12476 deletions
Download patch file Download diff file Expand all files Collapse all files

4
docs/AGENT_COMMUNICATION.md
View file

@ -6,14 +6,14 @@ This document is the short-form overview of how the Panel talks to the Linux and
## Transport
The Panel uses its remote communication layer to send commands to an agent, which in turn forwards work to the OGP Perl agent and the host OS.
The Panel uses its remote communication layer to send commands to an agent, which in turn forwards work to the GSP Perl agent and the host OS.
## Common flow
1. Panel module builds a request.
2. `Panel/includes/lib_remote.php` sends it.
3. The agent receives the request.
4. The OGP Perl agent executes the requested action.
4. The GSP Perl agent executes the requested action.
5. The agent returns status, logs, or command results.
## Key properties

2
docs/ARCHITECTURE.md
View file

@ -38,7 +38,7 @@ User action
→ remote command generation
→ agent communication
→ Linux or Windows agent
→ OGP Perl agent
→ GSP Perl agent
→ operating system
→ hosted game server

2
docs/COMMAND_FLOW.md
View file

@ -9,7 +9,7 @@ User
→ panel request builder
→ communication layer
→ Linux or Windows agent
→ OGP Perl agent
→ GSP Perl agent
→ OS command or process control
→ game server process

18
docs/agents/LINUX_AGENT.md
View file

@ -4,7 +4,7 @@ Workspace reference: [`GSP-WORKSPACE.md`](../../../GSP-WORKSPACE.md)
## Role
`Agent_Linux/ogp_agent.pl` is the Linux execution agent for GSP. It is responsible for:
`Agent_Linux/gsp_agent.pl` is the Linux execution agent for GSP. It is responsible for:
- starting and stopping game servers
- managing `screen` sessions
@ -15,7 +15,7 @@ Workspace reference: [`GSP-WORKSPACE.md`](../../../GSP-WORKSPACE.md)
## Important Files
- `Agent_Linux/ogp_agent.pl`
- `Agent_Linux/gsp_agent.pl`
- `Agent_Linux/startups/`
- `Agent_Linux/includes/`
- `Agent_Linux/php-query/`
@ -28,12 +28,12 @@ Workspace reference: [`GSP-WORKSPACE.md`](../../../GSP-WORKSPACE.md)
The Linux agent creates a managed `screen` session per server.
Key flow in `ogp_agent.pl`:
Key flow in `gsp_agent.pl`:
- `universal_start_without_decrypt`
- `create_screen_cmd`
- `create_screen_cmd_loop`
- `replace_OGP_Env_Vars`
- `replace_GSP_Env_Vars`
The agent builds the startup command from:
@ -43,10 +43,10 @@ The agent builds the startup command from:
- control password
- path variables
The session name follows the OGP naming convention, for example:
The session name follows the GSP naming convention, for example:
```text
OGP_HOME_000000123
GSP_HOME_000000123
```
## Status Logic
@ -100,7 +100,7 @@ For legacy `steam_workshop` RPC installs:
## Scheduler
Linux scheduler functions live in `ogp_agent.pl`:
Linux scheduler functions live in `gsp_agent.pl`:
- `scheduler_dispatcher`
- `scheduler_server_action`
@ -138,8 +138,8 @@ Flow:
5. The script clones the configured branch into staging.
6. It copies only the configured Linux agent source folder, usually `Agent_Linux`.
7. It preserves `Cfg/`, `ServerFiles/`, `Schedule/`, logs, screen logs, `steamcmd/`, `startups/`, temporary folders, backups, and PID files.
8. It validates the updated `ogp_agent.pl` with `perl -c`.
9. It restarts `ogp_agent.service` through `systemd` if available, otherwise uses the existing `screen` startup fallback.
8. It validates the updated `gsp_agent.pl` with `perl -c`.
9. It restarts `gsp_agent.service` through `systemd` if available, otherwise uses the existing `screen` startup fallback.
The agent returns `queued` immediately with the log path `gsp_component_update.log`. A queued response means the updater launched; check the log for final success/failure.

73
docs/agents/WINDOWS_AGENT.md
View file

@ -4,17 +4,17 @@ Workspace reference: [`GSP-WORKSPACE.md`](../../../GSP-WORKSPACE.md)
## Role
`Agent-Windows/OGP64/OGP/ogp_agent.pl` is the Windows/Cygwin execution agent currently tracked in this repository. It mirrors the Linux agent as closely as practical, while using Windows-compatible paths, processes, and wrappers.
`Agent-Windows/GSP64/GSP/gsp_agent.pl` is the Windows/Cygwin execution agent currently tracked in this repository. It mirrors the Linux agent as closely as practical, while using Windows-compatible paths, processes, and wrappers.
## Important Files
- `Agent-Windows/OGP64/OGP/ogp_agent.pl`
- `Agent-Windows/OGP64/OGP/Cfg/Config.pm`
- `Agent-Windows/OGP64/OGP/Cfg/Preferences.pm`
- `Agent-Windows/OGP64/OGP/Cfg/bash_prefs.cfg`
- `Agent-Windows/OGP64/OGP/Cfg/*.default`
- `Agent-Windows/OGP64/agent_start.bat`
- `Agent-Windows/OGP64/agent_stop.bat`
- `Agent-Windows/GSP64/GSP/gsp_agent.pl`
- `Agent-Windows/GSP64/GSP/Cfg/Config.pm`
- `Agent-Windows/GSP64/GSP/Cfg/Preferences.pm`
- `Agent-Windows/GSP64/GSP/Cfg/bash_prefs.cfg`
- `Agent-Windows/GSP64/GSP/Cfg/*.default`
- `Agent-Windows/GSP64/agent_start.bat`
- `Agent-Windows/GSP64/agent_stop.bat`
- `Agent-Windows/php-query/`
- `Agent-Windows/ArmaBE/`
- `Agent-Windows/Cfg/`
@ -40,32 +40,32 @@ Relevant functions:
- `universal_start_without_decrypt`
- `create_screen_cmd`
- `create_screen_cmd_loop`
- `replace_OGP_Env_Vars`
- `replace_GSP_Env_Vars`
The Windows agent also uses `screen` sessions for managed server execution. Depending on the game and binary type, it may wrap commands in `cmd /Q /C start` or run a batch file wrapper.
The session naming scheme also follows the OGP convention:
The session naming scheme also follows the GSP convention:
```text
OGP_HOME_000000123
GSP_HOME_000000123
```
### Windows Startup Launcher
Relevant files:
- `Agent-Windows/OGP64/agent_start.bat`
- `Agent-Windows/OGP64/agent_stop.bat`
- `/OGP/Cfg/bash_prefs.cfg` on an installed node
- `Agent-Windows/GSP64/agent_start.bat`
- `Agent-Windows/GSP64/agent_stop.bat`
- `/GSP/Cfg/bash_prefs.cfg` on an installed node
The batch launcher must not assume that `bash` is in the Windows `PATH`. It explicitly checks:
- `%~dp0bin\bash.exe`
- `C:\OGP64\bin\bash.exe`
- `C:\GSP64\bin\bash.exe`
- `C:\cygwin64\bin\bash.exe`
- `C:\cygwin\bin\bash.exe`
The supported manual launcher is `C:\OGP64\agent_start.bat`. The Cygwin root is the folder containing that BAT file, so the path checks stay simple and deterministic.
The supported manual launcher is `C:\GSP64\agent_start.bat`. The Cygwin root is the folder containing that BAT file, so the path checks stay simple and deterministic.
Manual launches pause on fatal errors so the error remains visible.
@ -73,26 +73,26 @@ The launcher prints the detected Cygwin root and agent user before validation, t
The BAT launcher performs the shell work directly:
1. enter `/OGP`
2. normalize CRLF to LF for `.pl`, `.pm`, `.sh`, and `.cfg` files under `/OGP`
1. enter `/GSP`
2. normalize CRLF to LF for `.pl`, `.pm`, `.sh`, and `.cfg` files under `/GSP`
3. create missing `Cfg/Config.pm`, `Cfg/Preferences.pm`, and `Cfg/bash_prefs.cfg` from tracked `.default` files
4. strip CRLF and leading whitespace before assignments in `/OGP/Cfg/bash_prefs.cfg`
5. source `/OGP/Cfg/bash_prefs.cfg`
4. strip CRLF and leading whitespace before assignments in `/GSP/Cfg/bash_prefs.cfg`
5. source `/GSP/Cfg/bash_prefs.cfg`
6. verify the Windows account `gameserver` exists
7. run `perl -c ./ogp_agent.pl` before launch
8. launch `/OGP/ogp_agent.pl`
7. run `perl -c ./gsp_agent.pl` before launch
8. launch `/GSP/gsp_agent.pl`
Default optional update source:
- repo: `http://forge.runlevelsystems.com/dev/GSP.git`
- branch: `Panel-unstable`
- source file: `Agent-Windows/OGP64/OGP/ogp_agent.pl` in the current repo layout
- raw URL: `http://forge.runlevelsystems.com/dev/GSP/raw/branch/Panel-unstable/Agent-Windows/OGP64/OGP/ogp_agent.pl`
- target file: `/OGP/ogp_agent.pl`
- source file: `Agent-Windows/GSP64/GSP/gsp_agent.pl` in the current repo layout
- raw URL: `http://forge.runlevelsystems.com/dev/GSP/raw/branch/Panel-unstable/Agent-Windows/GSP64/GSP/gsp_agent.pl`
- target file: `/GSP/gsp_agent.pl`
Auto-update failure is non-fatal. Missing `curl`/`git`, download failure, clone failure, missing source file, HTTP error-page downloads, empty files, or failed validation should warn and continue with the current installed agent.
Restart-time auto-update is allowlisted. It may replace only `/OGP/ogp_agent.pl`. It must never overwrite `Cfg/Config.pm`, `Cfg/Preferences.pm`, `Cfg/bash_prefs.cfg`, service settings, passwords, generated installer config, server homes, logs, or user-created files. Broader agent updates belong to the admin-only Panel `component_update` flow, which also preserves `Cfg/`.
Restart-time auto-update is allowlisted. It may replace only `/GSP/gsp_agent.pl`. It must never overwrite `Cfg/Config.pm`, `Cfg/Preferences.pm`, `Cfg/bash_prefs.cfg`, service settings, passwords, generated installer config, server homes, logs, or user-created files. Broader agent updates belong to the admin-only Panel `component_update` flow, which also preserves `Cfg/`.
### Startup Log And Troubleshooting
@ -100,7 +100,7 @@ The launcher does not create a separate startup wrapper window. If startup fails
Manual troubleshooting flow:
1. Launch `C:\OGP64\agent_start.bat` directly from the Windows console or Explorer.
1. Launch `C:\GSP64\agent_start.bat` directly from the Windows console or Explorer.
2. Read the path summary printed at the top of the window.
3. Inspect the same window for the real Perl/config error.
4. Check the current Cygwin output if you need more context.
@ -109,7 +109,7 @@ Manual troubleshooting flow:
Restart-time auto-update must not touch production config files. Only the following file is allowed to be replaced automatically:
- `/OGP/ogp_agent.pl`
- `/GSP/gsp_agent.pl`
It must never overwrite:
@ -153,6 +153,19 @@ The old `SERVER_STOPPED` file should not be the source of truth.
If the game port is listening but the managed screen session is not found, the agent reports `ONLINE` with a warning. This protects customers from false offline/unknown states when a process survives a screen/session mismatch or an older agent cannot report the session correctly.
## Server Content Runtime
The Windows agent mirrors the Linux server-owned content runtime:
- `_gsp_content/hooks/`
- `_gsp_content/generated/`
- `_gsp_content/runtime/`
- `_gsp_content/runtime/server_content.pids`
Stop and restart clean this PID registry before main server escalation. Watchdog PIDs are stopped before app PIDs. Main game server PIDs remain in `runtime_status/pid-<home_id>.kv` and must not be written to `server_content.pids`.
Legacy `_alsoRun.bat` is compatibility-only. When `_alsoRun.pid` exists, the Windows agent imports those PIDs into the server-content cleanup path so helper processes do not survive Panel Stop or Restart.
## Logging
Relevant function:
@ -201,12 +214,12 @@ The Windows agent exposes the same admin-only `component_update` XML-RPC method
Flow:
1. Panel sends an encrypted payload containing repo URL, branch, Windows agent source folder, optional Git path, optional backup path, and optional admin post-update command.
2. Agent validates the request and writes `gsp_component_update_<timestamp>.sh` under the current agent run directory, usually `/OGP`.
2. Agent validates the request and writes `gsp_component_update_<timestamp>.sh` under the current agent run directory, usually `/GSP`.
3. The updater runs detached in `screen`.
4. The updater clones the configured branch into staging.
5. It copies only the configured Windows agent source folder, usually `Agent-Windows`.
6. It preserves `Cfg/`, `ServerFiles/`, `Schedule/`, logs, screen logs, `steamcmd/`, `startups/`, temporary folders, backups, and PID files.
7. It validates `ogp_agent.pl` with `perl -c`.
7. It validates `gsp_agent.pl` with `perl -c`.
8. It restarts the agent using the existing Cygwin/screen fallback.
The immediate response is `queued` with the agent-side log path `gsp_component_update.log`.

28
docs/architecture/API_REFERENCE.md
View file

@ -29,7 +29,7 @@ home.php module request
-> optional agent RPC through lib_remote.php
external automation
-> Panel/ogp_api.php
-> Panel/gsp_api.php
-> api_* handler
-> same module/library logic
-> optional agent RPC
@ -51,7 +51,7 @@ Transport:
- XML-RPC over HTTP
- endpoint path `/RPC2`
- wrapper `Panel/includes/lib_remote.php`
- server implementations in `Agent_Linux/ogp_agent.pl` and `Agent-Windows/OGP64/OGP/ogp_agent.pl`
- server implementations in `Agent_Linux/gsp_agent.pl` and `Agent-Windows/GSP64/GSP/gsp_agent.pl`
Primary categories:
@ -70,7 +70,7 @@ See the full command table in:
## Panel Wrapper Methods
Most Panel modules do not build XML-RPC directly. They call `OGPRemoteLibrary`.
Most Panel modules do not build XML-RPC directly. They call `GSPRemoteLibrary`.
| Wrapper Method | Agent Command | Common Modules |
|---|---|---|
@ -90,7 +90,7 @@ Most Panel modules do not build XML-RPC directly. They call `OGPRemoteLibrary`.
Primary endpoint:
- `Panel/ogp_api.php`
- `Panel/gsp_api.php`
Auth model:
@ -99,7 +99,7 @@ Auth model:
- requests can be GET, POST, or JSON body
- host allowlist can be enforced
Top-level API handlers implemented in `ogp_api.php`:
Top-level API handlers implemented in `gsp_api.php`:
| Handler Function | Route Prefix | Purpose |
|---|---|---|
@ -179,7 +179,7 @@ Return shape:
## Internal Module Endpoints
These are not public APIs in the same sense as `ogp_api.php`, but they matter architecturally.
These are not public APIs in the same sense as `gsp_api.php`, but they matter architecturally.
| Endpoint | Module | Purpose |
|---|---|---|
@ -278,18 +278,18 @@ Panel fallback behavior:
Agent cron jobs often execute URLs like:
- `ogp_api.php?gamemanager/start`
- `ogp_api.php?gamemanager/stop`
- `ogp_api.php?gamemanager/restart`
- `ogp_api.php?gamemanager/update&type=steam`
- `ogp_api.php?server_content/run_scheduled_action`
- `gsp_api.php?gamemanager/start`
- `gsp_api.php?gamemanager/stop`
- `gsp_api.php?gamemanager/restart`
- `gsp_api.php?gamemanager/update&type=steam`
- `gsp_api.php?server_content/run_scheduled_action`
This means `ogp_api.php` is part of the scheduler runtime and must stay backward compatible with those generated URLs.
This means `gsp_api.php` is part of the scheduler runtime and must stay backward compatible with those generated URLs.
## Search Coverage Used For This Document
- `sed -n '1,240p' Panel/ogp_api.php`
- `rg -n "^function api_" Panel/ogp_api.php`
- `sed -n '1,240p' Panel/gsp_api.php`
- `rg -n "^function api_" Panel/gsp_api.php`
- `sed -n '1,240p' Panel/status_api.php`
- `find Website/api -maxdepth 1 -type f`
- `sed -n '1,220p' Website/webhook.php`

8
docs/architecture/LIBRARY_REFERENCE.md
View file

@ -31,7 +31,7 @@ No separate `Panel/libraries/` or `Panel/common/` tree is currently used as the
| `Panel/includes/refreshed.php` | refresh helper | cron/events and refresh-style pages |
| `Panel/includes/debug.php` | debug support | limited / diagnostic use |
| `Panel/includes/ip_in_range.php` | CIDR / IP-range helper | API host authorization |
| `Panel/includes/api_functions.php` | `ogp_api.php` argument maps and API-side helper logic | external API, scheduler URLs |
| `Panel/includes/api_functions.php` | `gsp_api.php` argument maps and API-side helper logic | external API, scheduler URLs |
## `lib_remote.php` Wrapper Surface
@ -83,7 +83,7 @@ Practical rule:
## API Helper Layer
`Panel/includes/api_functions.php` supports `Panel/ogp_api.php`.
`Panel/includes/api_functions.php` supports `Panel/gsp_api.php`.
Responsibilities:
@ -92,7 +92,7 @@ Responsibilities:
- RCON dispatch helper
- API host authorization checks
This file is also indirectly used by the scheduler because cron jobs call back into `ogp_api.php`.
This file is also indirectly used by the scheduler because cron jobs call back into `gsp_api.php`.
## XML / Game Config Parsing
@ -149,7 +149,7 @@ These are not in `includes/`, but they function as shared update infrastructure
|---|---|
| Agent RPC | `includes/lib_remote.php` |
| Database | `includes/database_mysqli.php` |
| API | `includes/api_functions.php`, `ogp_api.php` |
| API | `includes/api_functions.php`, `gsp_api.php` |
| Routing / page shell | `includes/navig.php`, `includes/view.php` |
| XML config | `modules/config_games/server_config_parser.php` |
| Query metadata | `protocol/lgsl`, `protocol/GameQ` |

14
docs/architecture/MODULE_DEPENDENCIES.md
View file

@ -27,7 +27,7 @@ User / admin UI
-> Linux / Windows agents
AJAX / external API
-> module endpoint PHP files or ogp_api.php / status_api.php
-> module endpoint PHP files or gsp_api.php / status_api.php
-> same shared libraries and DB layer
-> agent RPC where needed
```
@ -52,7 +52,7 @@ AJAX / external API
| `billing` | Yes for server provisioning/expiry actions | embeds storefront runtime; shares logic with `Website/` | DB layer, `lib_remote.php`, payment helpers | orders, invoices, coupons, server provisioning state | webhook and checkout entrypoints under module and website | PayPal, Stripe/manual gateways, email |
| `circular` | No | own helper file | DB layer | announcement/content records | `show_circular.php` | none |
| `config_games` | No direct agent use in main UI | `server_config_parser.php`, `cli-params.php`, `set_mods.php`, `set_params.php` | XML parser, DB layer | `config_homes`, `config_mods` | XML editor-like pages | GameQ, LGSL references |
| `cron` | Yes | `shared_cron_functions.php`, uses `ogp_api.php` URLs as scheduled payloads | `lib_remote.php`, XML parser, DB layer | Panel-side scheduler intent; agent-owned cron entries | `events.php`, `thetime.php`, `user_cron.php` | agent scheduler, `wget`, panel API |
| `cron` | Yes | `shared_cron_functions.php`, uses `gsp_api.php` URLs as scheduled payloads | `lib_remote.php`, XML parser, DB layer | Panel-side scheduler intent; agent-owned cron entries | `events.php`, `thetime.php`, `user_cron.php` | agent scheduler, `wget`, panel API |
| `dashboard` | Yes | `query_ref.php`, `updateWidgets.php` | `lib_remote.php`, DB layer | widget prefs, server overview | `updateWidgets.php` | query protocols |
| `dsi` | Yes | shared DSI includes, `gamemanager/home_handling_functions.php`, XML parser | `lib_remote.php`, XML parser, GameQ, LGSL | server and game metadata | `image.php`, list/admin pages | GameQ, LGSL, GeoIP |
| `editconfigfiles` | Yes | its own helpers/config lists | `lib_remote.php`, DB layer | file edit permissions by home | `modify.php` | remote file editing |
@ -88,8 +88,8 @@ AJAX / external API
|---|---|---|
| `gamemanager` | `config_games/server_config_parser.php` | build startup commands, query definitions, control protocol metadata |
| `gamemanager` | `addonsmanager/monitor_buttons.php` and content helpers indirectly | content/update actions shown on monitor pages |
| `cron` | `addonsmanager/server_content_actions.php` via `ogp_api.php?server_content/run_scheduled_action` | scheduled content checks and installs |
| `cron` | `gamemanager` via `ogp_api.php?gamemanager/*` | start, stop, restart, Steam auto update |
| `cron` | `addonsmanager/server_content_actions.php` via `gsp_api.php?server_content/run_scheduled_action` | scheduled content checks and installs |
| `cron` | `gamemanager` via `gsp_api.php?gamemanager/*` | start, stop, restart, Steam auto update |
| `user_games` | `gamemanager/home_handling_functions.php` | delete / teardown and lifecycle-related helpers |
| `user_games` | `billing/create_servers.php` | provisioning integration |
| `dsi` | `gamemanager/home_handling_functions.php` | shared game-home status logic |
@ -107,7 +107,7 @@ AJAX / external API
| `Panel/modules/cron/events.php` | `cron` | scheduler log refresh |
| `Panel/modules/litefm/get_file.php` | `litefm` | streamed download chunks |
| `Panel/status_api.php` | architecture / public status | panel-local public node summary API |
| `Panel/ogp_api.php` | architecture / external API | token-authenticated external automation API |
| `Panel/gsp_api.php` | architecture / external API | token-authenticated external automation API |
## Major Database Ownership
@ -120,7 +120,7 @@ This is not a full schema map. It identifies ownership boundaries.
| `remote_servers`, `remote_server_ips` | `server`, provisioning, `status`, `dashboard` |
| `server_homes`, `home_ip_ports`, `game_mods` | `user_games`, `gamemanager`, `cron`, provisioning |
| `config_homes`, `config_mods` | `config_games`, `user_games`, `gamemanager` |
| `api_tokens` | `ogp_api.php`, user session helpers |
| `api_tokens` | `gsp_api.php`, user session helpers |
| `server_content_manifest`, `server_content_workshop`, `addons` | `addonsmanager` |
| billing/order/invoice/coupon tables | `billing`, `Website/` |
| ticket/support tables | `tickets`, `support` |
@ -145,6 +145,6 @@ This is not a full schema map. It identifies ownership boundaries.
Key searches:
- `rg -n "new OGPRemoteLibrary|->remote_|->scheduler_|->component_update|->steam_workshop" Panel/modules Panel/includes`
- `rg -n "new GSPRemoteLibrary|->remote_|->scheduler_|->component_update|->steam_workshop" Panel/modules Panel/includes`
- `rg -n "require|require_once|include|include_once" Panel/modules -g '*.php'`
- `find Panel/modules -maxdepth 2 -type f \\( -name '*.php' -o -name '*.js' \\)`

14
docs/architecture/PANEL_AGENT_COMMANDS.md
View file

@ -9,24 +9,24 @@ This file is the command catalog for the XML-RPC surface between the Panel and t
Primary files:
- `Panel/includes/lib_remote.php`
- `Agent_Linux/ogp_agent.pl`
- `Agent-Windows/OGP64/OGP/ogp_agent.pl`
- `Agent_Linux/gsp_agent.pl`
- `Agent-Windows/GSP64/GSP/gsp_agent.pl`
Transport:
- Panel -> agent uses XML-RPC over HTTP to `/RPC2`
- Arguments are encrypted by `OGPRemoteLibrary`
- Arguments are encrypted by `GSPRemoteLibrary`
- Agents validate the encryption marker before executing commands
## Command Dispatch
Linux dispatch table:
- `Agent_Linux/ogp_agent.pl`
- `Agent_Linux/gsp_agent.pl`
Windows dispatch table:
- `Agent-Windows/OGP64/OGP/ogp_agent.pl`
- `Agent-Windows/GSP64/GSP/gsp_agent.pl`
Important parity note:
@ -149,7 +149,7 @@ Important implementation note:
- the Panel scheduler stores intent in the UI
- the agent owns execution timing and the actual cron entries
- many agent cron commands are `wget` calls back into `Panel/ogp_api.php`
- many agent cron commands are `wget` calls back into `Panel/gsp_api.php`
## Internal Agent Scheduler Actions
@ -213,5 +213,5 @@ Notable wrapper methods:
Commands were confirmed from:
- `rg -n "methods =>" Agent_Linux Agent-Windows`
- `rg -n "^sub .*without_decrypt|^sub component_update|^sub remote_query|^sub steam_workshop|^sub scheduler_" Agent_Linux/ogp_agent.pl Agent-Windows/OGP64/OGP/ogp_agent.pl`
- `rg -n "^sub .*without_decrypt|^sub component_update|^sub remote_query|^sub steam_workshop|^sub scheduler_" Agent_Linux/gsp_agent.pl Agent-Windows/GSP64/GSP/gsp_agent.pl`
- `rg -n "public function .*\\(" Panel/includes/lib_remote.php`

4
docs/architecture/PANEL_AGENT_FLOW.md
View file

@ -9,9 +9,9 @@ The Panel does not directly run servers. It prepares the request, sends it to th
```text
User action
-> Panel module page
-> OGPRemoteLibrary in lib_remote.php
-> GSPRemoteLibrary in lib_remote.php
-> XML-RPC request to agent /RPC2
-> ogp_agent.pl method
-> gsp_agent.pl method
-> local screen/process/port work
-> return status or payload
-> Panel renders result

6
docs/architecture/REPOSITORY_OVERVIEW.md
View file

@ -56,8 +56,8 @@ The agents are the execution layer. They:
Important agent files:
- `Agent_Linux/ogp_agent.pl`
- `Agent-Windows/OGP64/OGP/ogp_agent.pl`
- `Agent_Linux/gsp_agent.pl`
- `Agent-Windows/GSP64/GSP/gsp_agent.pl`
- `Agent_Linux/startups/`
- `Agent-Windows/ServerFiles/`
- `Agent_Linux/php-query/`
@ -74,7 +74,7 @@ The Website is separate from the server runtime path. It is used for:
## Panel <-> Agent Communication
The Panel uses XML-RPC over HTTP to call methods exposed by `ogp_agent.pl`.
The Panel uses XML-RPC over HTTP to call methods exposed by `gsp_agent.pl`.
The remote wrapper lives in:

12
docs/architecture/RPC_STATUS_REPAIR_REPORT.md
View file

@ -16,8 +16,8 @@ The scope of this pass was status/RPC communication only. Steam Workshop, update
The repository agents currently expose the structured `server_status` RPC on both Linux and Windows/Cygwin:
- Linux: `Agent_Linux/ogp_agent.pl`
- Windows/Cygwin: `Agent-Windows/OGP64/OGP/ogp_agent.pl`
- Linux: `Agent_Linux/gsp_agent.pl`
- Windows/Cygwin: `Agent-Windows/GSP64/GSP/gsp_agent.pl`
The Panel also contains a fallback path for older or stale live agents where `server_status` is unavailable:
@ -153,7 +153,7 @@ Linux also exposes `renice_process` and `lock_additional_files`, which are absen
| Mismatch | Impact |
|---|---|
| Documentation referenced `Agent-Windows/ogp_agent.pl`, but the current tracked file is `Agent-Windows/OGP64/OGP/ogp_agent.pl`. | Confuses future debugging and validation. Documentation was updated. |
| Documentation referenced `Agent-Windows/gsp_agent.pl`, but the current tracked file is `Agent-Windows/GSP64/GSP/gsp_agent.pl`. | Confuses future debugging and validation. Documentation was updated. |
| Panel fallback port regex inserted a shell-quoted port into a grep regex. | Prevented `ss`/`netstat` fallback from detecting running servers after `server_status` RPC was unavailable. Fixed. |
| Some non-status wrappers in `lib_remote.php` reference legacy RPC names whose current support should be checked before future work, such as `steam` and `game_update_active`. | Out of scope for this status repair. |
@ -173,9 +173,9 @@ Run from repository root:
```bash
php -l Panel/modules/gamemanager/home_handling_functions.php
perl -c Agent_Linux/ogp_agent.pl
perl -c Agent-Windows/OGP64/OGP/ogp_agent.pl
rg -n "p=\\$port_arg|\\[:\\.\\]\\$p|Agent-Windows/ogp_agent\\.pl" \
perl -c Agent_Linux/gsp_agent.pl
perl -c Agent-Windows/GSP64/GSP/gsp_agent.pl
rg -n "p=\\$port_arg|\\[:\\.\\]\\$p|Agent-Windows/gsp_agent\\.pl" \
Panel/modules/gamemanager/home_handling_functions.php \
docs/features/STATUS_SYSTEM.md \
docs/modules/GAMEMANAGER.md \

134
docs/codex-history/2026/2026-07-02-1631-lifecycle-hardening.md Normal file
View file

@ -0,0 +1,134 @@
# Task
## User Request
Review, verify, and production-harden the integrated GSP workspace with emphasis on reliable remote server lifecycle control across Panel, Linux Agent, and Windows Agent. Review Server Content sidecars, bots, and hooks; bring Windows lifecycle behavior into parity with the current Linux architecture where appropriate; update permanent Codex workflow policy; validate modified PHP and Perl; create focused commits where safe.
## Problem
Panel lifecycle commands depend on the agents to translate Start, Stop, Restart, and Status into process/session control. Recent Linux-side lifecycle work had newer Server Content runtime handling than Windows. Windows still relied on legacy `_alsoRun.bat` and `_alsoRun.pid` patterns for sidecars, which made sidecar cleanup less explicit and increased the chance that restart/stop would leave auxiliary processes running after the main game server stopped.
## Root Cause
The product had two lifecycle models:
- Linux had server-owned Server Content runtime state under `_gsp_content/runtime/server_content.pids`.
- Windows still treated companion processes primarily as legacy `_alsoRun` processes emitted by game XML hooks.
The Linux cleanup helper also had a bug: a cleanup pass for one PID group could discard lines for other PID groups, so watchdog cleanup could remove app PID entries before app cleanup killed them.
## Repositories Inspected
- `/home/dev/Projects/GSP/Panel`
- `/home/dev/Projects/GSP/GSP-Agent-Linux`
- `/home/dev/Projects/GSP/GSP-Agent-Windows`
- `/home/dev/Projects/GSP/Panel.wiki`
- `/home/dev/Projects/GSP/references/OGP/OGP-Website.wiki` as read-only upstream reference
## Files Read
- `/home/dev/Projects/GSP/AGENTS.md`
- `Panel/README.md`
- `Panel/docs/ARCHITECTURE.md`
- `Panel/docs/PANEL_ARCHITECTURE.md`
- `Panel/docs/AGENT_COMMUNICATION.md`
- `Panel/docs/COMMAND_FLOW.md`
- `Panel/docs/architecture/PANEL_AGENT_FLOW.md`
- `Panel/docs/architecture/PANEL_AGENT_COMMANDS.md`
- `Panel/docs/features/STATUS_SYSTEM.md`
- `Panel/docs/modules/SERVER_CONTENT_MANAGER.md`
- `Panel/docs/modules/GAMEMANAGER.md`
- `Panel/docs/features/COMPANION_PROGRAMS.md`
- `Panel/docs/decisions/COMPANION_PROGRAMS_DESIGN.md`
- `Panel/docs/agents/LINUX_AGENT.md`
- `Panel/docs/agents/WINDOWS_AGENT.md`
- `Panel/includes/lib_remote.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/gamemanager/server_monitor.php`
- `Panel/modules/gamemanager/mini_start.php`
- `Panel/modules/gamemanager/update_actions.php`
- `Panel/modules/addonsmanager/server_content_actions.php`
- `Panel/modules/addonsmanager/server_content_helpers.php`
- `GSP-Agent-Linux/README.md`
- `GSP-Agent-Linux/docs/PANEL_INTEGRATION.md`
- `GSP-Agent-Linux/gsp_agent.pl`
- `GSP-Agent-Windows/README.md`
- `GSP-Agent-Windows/docs/AGENT_ARCHITECTURE.md`
- `GSP-Agent-Windows/docs/PROCESS_MANAGEMENT.md`
- `GSP-Agent-Windows/docs/PANEL_INTEGRATION.md`
- `GSP-Agent-Windows/docs/COMMAND_EXECUTION.md`
- `GSP-Agent-Windows/docs/GSP_WINDOWS_AGENT_PORT_VALIDATION.md`
- `GSP-Agent-Windows/GSP64/GSP/gsp_agent.pl`
- `GSP-Agent-Windows/GSP64/GSP/Cfg/Preferences.pm.default`
- `GSP-Agent-Windows/GSP64/GSP/Cfg/bash_prefs.cfg.default`
- `Panel.wiki/Home.md`
- `Panel.wiki/Remote-Servers-and-Agents.md`
- `Panel.wiki/Game-Server-Management.md`
- `Panel.wiki/OGP-Fork-Notes.md`
- `Panel.wiki/Development.md`
## Files Changed
- `/home/dev/Projects/GSP/AGENTS.md`
- `Panel/docs/agents/WINDOWS_AGENT.md`
- `Panel/docs/features/COMPANION_PROGRAMS.md`
- `Panel/docs/codex-history/2026/2026-07-02-1631-lifecycle-hardening.md`
- `GSP-Agent-Linux/gsp_agent.pl`
- `GSP-Agent-Windows/GSP64/GSP/gsp_agent.pl`
- `GSP-Agent-Windows/docs/PROCESS_MANAGEMENT.md`
- `GSP-Agent-Windows/docs/PANEL_INTEGRATION.md`
## Architecture Decisions
- Panel remains authoritative for lifecycle intent; agents execute process/session operations.
- `screen` remains the shared lifecycle backend.
- Main game server PIDs remain distinct from Server Content sidecar/hook PIDs.
- Server Content runtime state is server-owned under `_gsp_content/runtime/server_content.pids`.
- Windows now mirrors the Linux Server Content runtime model while retaining `_alsoRun.bat` compatibility for existing XML-generated integrations.
- Stop/restart cleanup must kill server-owned sidecars before main process fallback cleanup completes.
- PID cleanup must preserve non-target PID lines across cleanup passes.
## Validation Performed
- `php -l Panel/includes/lib_remote.php`
- `php -l Panel/modules/gamemanager/home_handling_functions.php`
- `php -l Panel/modules/addonsmanager/server_content_actions.php`
- `php -l Panel/modules/addonsmanager/server_content_helpers.php`
- `perl -I/tmp/gsp-perl-stubs.SqnOSl -c GSP-Agent-Linux/gsp_agent.pl`
- `perl -I/tmp/gsp-perl-stubs.SqnOSl -c GSP-Agent-Windows/GSP64/GSP/gsp_agent.pl`
Direct Perl validation required temporary stubs outside the repositories for missing local validation dependencies/configuration. Linux direct validation without stubs failed because `Archive::Extract` is not installed in this environment. Windows direct validation without stubs failed because `GSP64/GSP/Cfg/Config.pm` is not present in the checkout.
Live Start, Stop, Restart, Status, and Server Content sidecar cleanup validation was not performed because this environment does not provide configured live Panel, Linux Agent, Windows Agent, or game server hosts.
## Git Commits
Repository: `/home/dev/Projects/GSP/Panel`
Commit: Not created during this pass.
Hash: TODO
Repository: `/home/dev/Projects/GSP/GSP-Agent-Linux`
Commit: Not created during this pass.
Hash: TODO
Repository: `/home/dev/Projects/GSP/GSP-Agent-Windows`
Commit: Not created during this pass.
Hash: TODO
Reason: the modified repositories already contained large pre-existing staged and unstaged rename/rebrand/package changes. Creating commits without first separating that owner work would require staging unrelated files or committing on top of unrelated staged state, violating the task rule to stage only task-related files.
## Remaining Work
- Run live lifecycle validation against real Linux and Windows agents: Start, Stop, Restart, Status.
- Verify Windows `_alsoRun.bat` sidecar imports and cleanup against a real server that starts companion processes.
- Move game XML sidecars from legacy `_alsoRun` generation into first-class Server Content sidecar definitions where product scope allows.
- Resolve the pre-existing staged rename/rebrand changes so future Codex work can produce focused commits safely.

26
docs/decisions/COMPANION_PROGRAMS_DESIGN.md
View file

@ -19,8 +19,8 @@ Note: the repository currently uses `Agent_Linux` on disk, not `Agent-Linux`.
Relevant files:
- `Agent_Linux/ogp_agent.pl`
- `Agent-Windows/ogp_agent.pl`
- `Agent_Linux/gsp_agent.pl`
- `Agent-Windows/gsp_agent.pl`
- `Panel/includes/lib_remote.php`
- `Panel/modules/gamemanager/mini_start.php`
- `Panel/modules/gamemanager/home_handling_functions.php`
@ -55,9 +55,9 @@ 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_id(SCREEN_TYPE_HOME, $home_id)` creates names like `GSP_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`.
- `create_screen_cmd_loop(...)` creates a generated shell script named like `GSP_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.
@ -157,7 +157,7 @@ That flow is now present in the current agent files. Any companion system should
Current PID tracking exists but is inconsistent:
- The agents write their own `ogp_agent.pid`.
- The agents write their own `gsp_agent.pid`.
- FastDownload has `fd.pid`.
- Scheduler has `scheduler.pid`.
- Linux game server child PIDs are discovered from the screen PID with `pgrep -P`.
@ -196,7 +196,7 @@ There is no dedicated companion stdout/stderr log path today.
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:
In `Agent-Windows/gsp_agent.pl`, `create_screen_cmd_loop(...)` generates `_serverStart.bat`. That generated batch file contains:
```bat
if exist "_alsoRun.bat" call "_alsoRun.bat"
@ -407,7 +407,7 @@ Payload should contain fully resolved, validated data:
"key": "bec",
"enabled": true,
"delay_seconds": 30,
"working_dir": "/home/ogp_agent/OGP_User_Files/123/BEC",
"working_dir": "/home/gsp_agent/GSP_User_Files/123/BEC",
"command": "Bec.exe",
"args": ["-f", "Config.cfg"],
"stdout_log": "bec.out.log",
@ -427,12 +427,12 @@ Recommended approach:
- Use separate `screen` sessions per companion.
- Session naming:
- Game: `OGP_HOME_000000123`
- Companion: `OGP_COMPANION_000000123_bec`
- Game: `GSP_HOME_000000123`
- Companion: `GSP_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 ... && ..."`
- Linux: `screen -d -m -S GSP_COMPANION_... bash -lc 'sleep 30; cd ...; exec ...'`
- Windows/Cygwin: `screen -d -m -S GSP_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`.
@ -693,7 +693,7 @@ Linux can use:
Recommended Linux companion launch:
```text
screen -d -m -S OGP_COMPANION_<home_id>_<key> bash -lc '<agent-owned wrapper>'
screen -d -m -S GSP_COMPANION_<home_id>_<key> bash -lc '<agent-owned wrapper>'
```
Use an agent-owned wrapper or direct fork/exec to record PID and redirect logs.
@ -714,7 +714,7 @@ Current `_alsoRun.bat` depends on WMIC in some XML. WMIC is not reliable on all
Recommended Windows companion launch:
```text
screen -d -m -S OGP_COMPANION_<home_id>_<key> cmd /Q /C "<agent-owned wrapper.bat>"
screen -d -m -S GSP_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.

10
docs/decisions/SCHEDULER_ACTIONS_DESIGN.md
View file

@ -42,8 +42,8 @@ Panel remote/API integration:
Agent scheduler implementation:
- `Agent_Linux/ogp_agent.pl`
- `Agent-Windows/ogp_agent.pl`
- `Agent_Linux/gsp_agent.pl`
- `Agent-Windows/gsp_agent.pl`
### Current database tables used
@ -97,7 +97,7 @@ Customer task creation path:
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`.
5. The command is built as a `wget` callback to `gsp_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.
@ -112,11 +112,11 @@ Admin task creation path:
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
wget -qO- "<panel>/gsp_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
wget -qO- "<panel>/gsp_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

12
docs/decisions/STEAM_WORKSHOP_DESIGN.md
View file

@ -155,7 +155,7 @@ Relevant methods:
There are two Workshop paths:
1. Legacy agent RPC:
- Panel method: `OGPRemoteLibrary::steam_workshop(...)`
- Panel method: `GSPRemoteLibrary::steam_workshop(...)`
- Agent subroutine: `steam_workshop_without_decrypt(...)`
- Runs SteamCMD in a screen update session.
- Generates post-install shell snippets that edit a config file.
@ -172,20 +172,20 @@ The second path is cleaner for future Server Content work because it is manifest
Linux agent:
- File: `Agent_Linux/ogp_agent.pl`
- File: `Agent_Linux/gsp_agent.pl`
- SteamCMD path constants:
- `AGENT_RUN_DIR/steamcmd`
- `steamcmd.sh`
- `check_steam_cmd_client` downloads and installs SteamCMD if missing.
- `steam_cmd_without_decrypt` creates a SteamCMD runscript and runs it in a screen update session.
- `steam_workshop_without_decrypt` creates a SteamCMD runscript containing `workshop_download_item` lines and runs it in a screen update session.
- `get_workshop_mods_info` reads `.ogpmod` files from `AGENT_RUN_DIR/WorkshopModsInfo`.
- `get_workshop_mods_info` reads `.gspmod` files from `AGENT_RUN_DIR/WorkshopModsInfo`.
Windows/Cygwin agent:
- File: `Agent-Windows/ogp_agent.pl`
- File: `Agent-Windows/gsp_agent.pl`
- SteamCMD path constants:
- `/OGP/steamcmd`
- `/GSP/steamcmd`
- `steamcmd.exe`
- `steam_cmd_without_decrypt` uses Cygwin path conversion for `force_install_dir`.
- `steam_workshop_without_decrypt` uses Cygwin path conversion for the mods path and the SteamCMD runscript.
@ -692,7 +692,7 @@ Example:
"manifest_version": 2,
"job_uuid": "uuid",
"home_id": 123,
"home_path": "/home/ogp_agent/OGP_User_Files/123",
"home_path": "/home/gsp_agent/GSP_User_Files/123",
"provider": "steam",
"action": "install_update",
"strategy": "dayz_mod_folder",

18
docs/development/CODEX_GUIDE.md
View file

@ -44,24 +44,24 @@ This file is the first stop for future Codex sessions working in this repository
- `Panel/modules/config_games/schema_server_config.xml`
- `Panel/modules/config_games/server_config_parser.php`
- `Panel/includes/lib_remote.php`
- `Agent_Linux/ogp_agent.pl`
- `Agent-Windows/OGP64/OGP/ogp_agent.pl`
- `Agent_Linux/gsp_agent.pl`
- `Agent-Windows/GSP64/GSP/gsp_agent.pl`
### Status Logic
- `Panel/includes/lib_remote.php`
- `Panel/modules/gamemanager/home_handling_functions.php`
- `Panel/modules/gamemanager/server_monitor.php`
- `Agent_Linux/ogp_agent.pl`
- `Agent-Windows/OGP64/OGP/ogp_agent.pl`
- `Agent_Linux/gsp_agent.pl`
- `Agent-Windows/GSP64/GSP/gsp_agent.pl`
### Scheduler Logic
- `Panel/modules/cron/module.php`
- `Panel/modules/cron/cron.php`
- `Panel/modules/cron/shared_cron_functions.php`
- `Agent_Linux/ogp_agent.pl`
- `Agent-Windows/OGP64/OGP/ogp_agent.pl`
- `Agent_Linux/gsp_agent.pl`
- `Agent-Windows/GSP64/GSP/gsp_agent.pl`
### Workshop / Server Content Logic
@ -83,8 +83,8 @@ This file is the first stop for future Codex sessions working in this repository
### Agent Communication
- `Panel/includes/lib_remote.php`
- `Agent_Linux/ogp_agent.pl`
- `Agent-Windows/OGP64/OGP/ogp_agent.pl`
- `Agent_Linux/gsp_agent.pl`
- `Agent-Windows/GSP64/GSP/gsp_agent.pl`
### Decisions And Historical Reports
@ -107,7 +107,7 @@ This file is the first stop for future Codex sessions working in this repository
1. Read `docs/modules/GAMEMANAGER.md`.
2. Check `Panel/includes/lib_remote.php`.
3. Check `Panel/modules/gamemanager/home_handling_functions.php`.
4. Check the matching `ogp_agent.pl`.
4. Check the matching `gsp_agent.pl`.
5. Compare session/process/port logic in both agents.
### Debug a status issue

8
docs/development/GSP_PLATFORM_IMPROVEMENT_REPORT.md
View file

@ -70,7 +70,7 @@ The Panel communicates with agents through `Panel/includes/lib_remote.php`, whic
- scheduler operations
- update/install operations
The agents expose corresponding Perl subroutines through `ogp_agent.pl`. Both agents use `screen` as the shared backend for game server sessions and update/install jobs.
The agents expose corresponding Perl subroutines through `gsp_agent.pl`. Both agents use `screen` as the shared backend for game server sessions and update/install jobs.
### Lifecycle Status Direction
@ -85,7 +85,7 @@ The intended direction is correct: marker files and LGSL/GameQ query success sho
### Screen Backend
Both agents use screen sessions named in the `OGP_<TYPE>_<HOME_ID>` pattern. This makes Linux and Windows/Cygwin behavior similar, which is useful for portability.
Both agents use screen sessions named in the `GSP_<TYPE>_<HOME_ID>` pattern. This makes Linux and Windows/Cygwin behavior similar, which is useful for portability.
Current screen-related behavior includes:
@ -117,7 +117,7 @@ It should not determine whether a server is online. A server can be healthy whil
The current system mixes:
- OGP legacy modules.
- GSP legacy modules.
- GSP custom business/billing modules.
- Newer partial systems such as Server Content Manager.
- Older modules that are present but not production-ready.
@ -969,7 +969,7 @@ Admin pages should distinguish:
| Phase | Priority | Files/Modules Involved | Notes |
|---|---|---|---|
| Phase 1: Lifecycle validation | Critical | `Agent-Windows/ogp_agent.pl`, `Agent_Linux/ogp_agent.pl`, `Panel/includes/lib_remote.php`, `Panel/modules/gamemanager` | Finish and test agent-truth status, start, stop, restart, log viewer. |
| Phase 1: Lifecycle validation | Critical | `Agent-Windows/gsp_agent.pl`, `Agent_Linux/gsp_agent.pl`, `Panel/includes/lib_remote.php`, `Panel/modules/gamemanager` | Finish and test agent-truth status, start, stop, restart, log viewer. |
| Phase 2: Hide unsafe legacy modules | Critical | `backup-restore`, `steam_workshop`, `news`, `status`, nav/module settings | Hide customer access to broken/deprecated modules before launch. |
| Phase 3: Live logs and diagnostics | Critical | `gamemanager/log.php`, `view_server_log.php`, agent `get_log` | Dated log discovery, startup logs, download logs, error highlighting. |
| Phase 4: File/FTP safety audit | High | `litefm`, `ftp`, `editconfigfiles`, agent file methods | Safe roots, editor backups, protected dirs, FTP docs, credential reset. |

12
docs/features/COMPANION_PROGRAMS.md
View file

@ -9,10 +9,18 @@ Companion programs are not yet a first-class managed system. Current behavior is
Important references:
- `docs/decisions/0003-companion-programs.md`
- `Agent_Linux/ogp_agent.pl`
- `Agent-Windows/OGP64/OGP/ogp_agent.pl`
- `Agent_Linux/gsp_agent.pl`
- `Agent-Windows/GSP64/GSP/gsp_agent.pl`
- `Panel/modules/config_games/schema_server_config.xml`
Current lifecycle hardening:
- Linux and Windows both prepare `_gsp_content/runtime/server_content.pids` under each server home.
- Stop and restart clean server-owned content PIDs before main server process escalation.
- Main game server PIDs stay in agent runtime metadata, not in the server-content PID registry.
- Windows imports legacy `_alsoRun.pid` entries into the server-content cleanup path for compatibility.
- New sidecars, bots, and hooks should use server-owned content runtime, not agent-global or customer-editable helper processes.
## What The System Needs To Do
- start companion apps with the server

2
docs/features/COMPETITOR_COMPARISON.md
View file

@ -4,7 +4,7 @@ Workspace reference: [`GSP-WORKSPACE.md`](../../../GSP-WORKSPACE.md)
## Reviewed Hosts / Panels
- Open Game Panel
- GameServer Panel
- TCAdmin
- Pterodactyl
- GameServers.com

22
docs/features/INSTALLERS.md
View file

@ -12,8 +12,8 @@ Important references:
- `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/OGP64/OGP/ogp_agent.pl`
- `Agent_Linux/gsp_agent.pl`
- `Agent-Windows/GSP64/GSP/gsp_agent.pl`
## Installer Types Seen In The Codebase
@ -29,18 +29,18 @@ Installer strategy should come from game capability metadata. The agent should e
## Windows Agent Install Notes
The Windows agent is Cygwin-based under `Agent-Windows/OGP64`.
The Windows agent is Cygwin-based under `Agent-Windows/GSP64`.
Common installed layout:
- Cygwin root: `C:\OGP64`
- Bash: `C:\OGP64\bin\bash.exe`
- Agent root: `C:\OGP64\OGP`
- Maintained launcher: `C:\OGP64\agent_start.bat`
- Stop launcher: `C:\OGP64\agent_stop.bat`
- Cygwin root: `C:\GSP64`
- Bash: `C:\GSP64\bin\bash.exe`
- Agent root: `C:\GSP64\GSP`
- Maintained launcher: `C:\GSP64\agent_start.bat`
- Stop launcher: `C:\GSP64\agent_stop.bat`
The launcher checks `%~dp0bin\bash.exe`, `C:\OGP64\bin\bash.exe`, `C:\cygwin64\bin\bash.exe`, and `C:\cygwin\bin\bash.exe`. Missing-bash errors should print every checked path and pause in manual use.
The launcher checks `%~dp0bin\bash.exe`, `C:\GSP64\bin\bash.exe`, `C:\cygwin64\bin\bash.exe`, and `C:\cygwin\bin\bash.exe`. Missing-bash errors should print every checked path and pause in manual use.
Generated config files under `/OGP/Cfg` are production state. `C:\OGP64\agent_start.bat` may create them from `.default` templates if missing, but update logic must preserve them. Restart-time auto-update may replace only `/OGP/ogp_agent.pl`; it must not overwrite `Cfg/Config.pm`, `Cfg/Preferences.pm`, `Cfg/bash_prefs.cfg`, service settings, passwords, server data, or logs.
Generated config files under `/GSP/Cfg` are production state. `C:\GSP64\agent_start.bat` may create them from `.default` templates if missing, but update logic must preserve them. Restart-time auto-update may replace only `/GSP/gsp_agent.pl`; it must not overwrite `Cfg/Config.pm`, `Cfg/Preferences.pm`, `Cfg/bash_prefs.cfg`, service settings, passwords, server data, or logs.
When the Windows agent starts, `C:\OGP64\agent_start.bat` should be launched from the Cygwin root itself. It verifies the `gameserver` account, normalizes text files, validates `OGP\ogp_agent.pl`, and then launches the agent in the same console window. It should not call an installer wrapper from the start script.
When the Windows agent starts, `C:\GSP64\agent_start.bat` should be launched from the Cygwin root itself. It verifies the `gameserver` account, normalizes text files, validates `GSP\gsp_agent.pl`, and then launches the agent in the same console window. It should not call an installer wrapper from the start script.

4
docs/features/LOGGING_SYSTEM.md
View file

@ -17,8 +17,8 @@ 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/OGP64/OGP/ogp_agent.pl`
- `Agent_Linux/gsp_agent.pl`
- `Agent-Windows/GSP64/GSP/gsp_agent.pl`
## What Works

22
docs/features/SCHEDULER_ACTIONS.md
View file

@ -11,8 +11,8 @@ Primary files:
- `Panel/modules/cron/cron.php`
- `Panel/modules/cron/user_cron.php`
- `Panel/modules/cron/shared_cron_functions.php`
- `Agent_Linux/ogp_agent.pl`
- `Agent-Windows/OGP64/OGP/ogp_agent.pl`
- `Agent_Linux/gsp_agent.pl`
- `Agent-Windows/GSP64/GSP/gsp_agent.pl`
## Current Model
@ -20,7 +20,7 @@ The Panel scheduler builds a cron expression and a command string.
In the common case, that command string is a `wget` call back into:
- `Panel/ogp_api.php`
- `Panel/gsp_api.php`
The agent stores the cron entry and executes it locally.
@ -28,11 +28,11 @@ The agent stores the cron entry and executes it locally.
| Action Key | Built By | Effective Runtime Target | Modules Affected | Agent Calls Eventually Performed |
|---|---|---|---|---|
| `start` | `cron/shared_cron_functions.php` | `ogp_api.php?gamemanager/start` | `cron`, `gamemanager` | `universal_start` |
| `stop` | same | `ogp_api.php?gamemanager/stop` | `cron`, `gamemanager` | `stop_server` |
| `restart` | same | `ogp_api.php?gamemanager/restart` | `cron`, `gamemanager` | `restart_server` |
| `steam_auto_update` | same | `ogp_api.php?gamemanager/update&type=steam` | `cron`, `gamemanager` | `steam_cmd` / auto-update path |
| `server_content_check_updates` | same | `ogp_api.php?server_content/run_scheduled_action` | `cron`, `addonsmanager` | server-content manifest flow, remote `exec` / helper scripts |
| `start` | `cron/shared_cron_functions.php` | `gsp_api.php?gamemanager/start` | `cron`, `gamemanager` | `universal_start` |
| `stop` | same | `gsp_api.php?gamemanager/stop` | `cron`, `gamemanager` | `stop_server` |
| `restart` | same | `gsp_api.php?gamemanager/restart` | `cron`, `gamemanager` | `restart_server` |
| `steam_auto_update` | same | `gsp_api.php?gamemanager/update&type=steam` | `cron`, `gamemanager` | `steam_cmd` / auto-update path |
| `server_content_check_updates` | same | `gsp_api.php?server_content/run_scheduled_action` | `cron`, `addonsmanager` | server-content manifest flow, remote `exec` / helper scripts |
| `server_content_check_workshop_updates` | same | same | `cron`, `addonsmanager` | Workshop/content check flow |
| `server_content_install_updates_if_stopped` | same | same | `cron`, `addonsmanager`, `gamemanager` | conditional install |
| `server_content_install_updates_next_restart` | same | same | `cron`, `addonsmanager`, `gamemanager` | deferred install marker |
@ -74,8 +74,8 @@ User/admin saves scheduler job in Panel
-> Panel sends cron line to agent with scheduler_add_task/edit_task
-> Agent stores job
-> Agent executes cron job later
-> cron job usually calls ogp_api.php
-> ogp_api.php dispatches to gamemanager or server_content action
-> cron job usually calls gsp_api.php
-> gsp_api.php dispatches to gamemanager or server_content action
-> those paths may call the agent again for actual server/content work
```
@ -105,5 +105,5 @@ Current observable logs:
## Search Coverage Used For This Document
- `sed -n '1,260p' Panel/modules/cron/shared_cron_functions.php`
- `rg -n "scheduler_" Agent_Linux/ogp_agent.pl Agent-Windows/OGP64/OGP/ogp_agent.pl`
- `rg -n "scheduler_" Agent_Linux/gsp_agent.pl Agent-Windows/GSP64/GSP/gsp_agent.pl`
- `rg -n "gamemanager/(start|stop|restart)|server_content/run_scheduled_action" Panel/modules/cron`

4
docs/features/SCHEDULER_SYSTEM.md
View file

@ -11,8 +11,8 @@ 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/OGP64/OGP/ogp_agent.pl`
- `Agent_Linux/gsp_agent.pl`
- `Agent-Windows/GSP64/GSP/gsp_agent.pl`
## Current Strengths

6
docs/features/STATUS_SYSTEM.md
View file

@ -18,8 +18,8 @@ Important files:
- `Panel/includes/lib_remote.php`
- `Panel/modules/gamemanager/home_handling_functions.php`
- `Panel/modules/gamemanager/server_monitor.php`
- `Agent_Linux/ogp_agent.pl`
- `Agent-Windows/OGP64/OGP/ogp_agent.pl`
- `Agent_Linux/gsp_agent.pl`
- `Agent-Windows/GSP64/GSP/gsp_agent.pl`
## Panel Display Behavior
@ -81,7 +81,7 @@ The Panel fallback does not replace a full agent-owned status model. It exists s
- Marker files can become stale after crashes or power loss.
- A game can be online even if query metadata is temporarily unavailable.
- Some games need long startup windows, so timeouts must be configurable per game.
- `Agent status RPC unavailable` usually means the Panel could not complete the `server_status` call. On Windows/Cygwin nodes, first verify `/OGP/ogp_agent.pl` is valid Perl, `/OGP/Cfg/bash_prefs.cfg` has LF line endings and no leading spaces before assignments, and the agent starts cleanly from `Agent-Windows/OGP64/agent_start.bat` or `/OGP/Install/agent_start.bat`.
- `Agent status RPC unavailable` usually means the Panel could not complete the `server_status` call. On Windows/Cygwin nodes, first verify `/GSP/gsp_agent.pl` is valid Perl, `/GSP/Cfg/bash_prefs.cfg` has LF line endings and no leading spaces before assignments, and the agent starts cleanly from `Agent-Windows/GSP64/agent_start.bat` or `/GSP/Install/agent_start.bat`.
## Planned Improvement Shape

22
docs/features/USER_API.md
View file

@ -8,7 +8,7 @@ This file documents the externally reachable API and webhook surfaces discovered
Primary files:
- `Panel/ogp_api.php`
- `Panel/gsp_api.php`
- `Panel/status_api.php`
- `Website/api/create_order.php`
- `Website/api/capture_order.php`
@ -20,7 +20,7 @@ Primary files:
Main endpoint:
- `Panel/ogp_api.php`
- `Panel/gsp_api.php`
Transport:
@ -44,8 +44,8 @@ Important notes:
| Endpoint | Auth | Purpose | Parameters | Returns |
|---|---|---|---|---|
| `ogp_api.php?token/create` | panel username/password | issue API token | `user`, `password` | JSON token payload |
| `ogp_api.php?token/test` | token | verify token | `token` | role/status |
| `gsp_api.php?token/create` | panel username/password | issue API token | `user`, `password` | JSON token payload |
| `gsp_api.php?token/test` | token | verify token | `token` | role/status |
### User-Visible Game Server Actions
@ -116,10 +116,10 @@ Returns:
The scheduler does not call agents directly at runtime. It stores cron lines on the agent that usually call back into:
- `Panel/ogp_api.php?gamemanager/*`
- `Panel/ogp_api.php?server_content/run_scheduled_action`
- `Panel/gsp_api.php?gamemanager/*`
- `Panel/gsp_api.php?server_content/run_scheduled_action`
This makes `ogp_api.php` part of the internal scheduler runtime contract.
This makes `gsp_api.php` part of the internal scheduler runtime contract.
## Website API Endpoints
@ -159,15 +159,15 @@ Security note:
| Control | Where |
|---|---|
| token auth | `Panel/ogp_api.php` |
| token auth | `Panel/gsp_api.php` |
| host allowlist | `api_authorized.hosts`, `api_authorized.fwd_hosts`, `settings/api_hosts.php` |
| role / ownership checks | inside `api_*` handlers in `ogp_api.php` |
| role / ownership checks | inside `api_*` handlers in `gsp_api.php` |
| webhook signature verification | `Website/webhook.php` |
## Search Coverage Used For This Document
- `rg -n "^function api_" Panel/ogp_api.php`
- `sed -n '1,240p' Panel/ogp_api.php`
- `rg -n "^function api_" Panel/gsp_api.php`
- `sed -n '1,240p' Panel/gsp_api.php`
- `sed -n '1,240p' Panel/status_api.php`
- `find Website/api -maxdepth 1 -type f`
- `sed -n '1,220p' Website/webhook.php`

2
docs/modules/GAMEMANAGER.md
View file

@ -95,7 +95,7 @@ Current display mapping:
Query metadata remains optional. A running process/session or listening game port must not be shown as red/offline only because query details are unavailable.
If the monitor says `Agent status RPC unavailable`, treat it as an agent reachability/startup problem before changing query logic. For Windows/Cygwin nodes, validate `/OGP/ogp_agent.pl` with `perl -c`, check `/OGP/Cfg/bash_prefs.cfg` for CRLF or leading whitespace before assignments, and start the agent through the maintained launcher in `Agent-Windows/OGP64/agent_start.bat` or `/OGP/Install/agent_start.bat`.
If the monitor says `Agent status RPC unavailable`, treat it as an agent reachability/startup problem before changing query logic. For Windows/Cygwin nodes, validate `/GSP/gsp_agent.pl` with `perl -c`, check `/GSP/Cfg/bash_prefs.cfg` for CRLF or leading whitespace before assignments, and start the agent through the maintained launcher in `Agent-Windows/GSP64/agent_start.bat` or `/GSP/Install/agent_start.bat`.
## Log Viewer

8
docs/modules/SCHEDULER.md
View file

@ -11,8 +11,8 @@ Important files:
- `Panel/modules/cron/module.php`
- `Panel/modules/cron/cron.php`
- `Panel/modules/cron/shared_cron_functions.php`
- `Agent_Linux/ogp_agent.pl`
- `Agent-Windows/OGP64/OGP/ogp_agent.pl`
- `Agent_Linux/gsp_agent.pl`
- `Agent-Windows/GSP64/GSP/gsp_agent.pl`
## How It Works Today
@ -93,8 +93,8 @@ If scheduler behavior needs deeper investigation, start with:
- `Panel/modules/cron/cron.php`
- `Panel/modules/cron/shared_cron_functions.php`
- `Agent_Linux/ogp_agent.pl` scheduler subroutines
- `Agent-Windows/OGP64/OGP/ogp_agent.pl` scheduler subroutines
- `Agent_Linux/gsp_agent.pl` scheduler subroutines
- `Agent-Windows/GSP64/GSP/gsp_agent.pl` scheduler subroutines
## Current Panel Update Finding