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

doc changes and reference folder

Browse source
This commit is contained in:
Frank Harris 2026-06-06 17:18:49 -05:00
parent 11691a5876
commit 82cbc206eb
33 changed files with 1514 additions and 2855 deletions
Download patch file Download diff file Expand all files Collapse all files

103
docs/features/SCHEDULER_ACTIONS.md Normal file
View file

@ -0,0 +1,103 @@
# Scheduler Actions
## Scope
This file is the command reference for the current scheduler system.
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/ogp_agent.pl`
## Current Model
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`
The agent stores the cron entry and executes it locally.
## Action Catalog
| 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 |
| `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 |
| `server_content_install_updates_now` | same | same | `cron`, `addonsmanager` | immediate content install |
| `server_content_install_updates_and_restart` | same | same | `cron`, `addonsmanager`, `gamemanager` | content update plus restart |
| `server_content_notify_updates_only` | same | same | `cron`, `addonsmanager` | check-and-notify |
| `server_content_update_all` | same | same | `cron`, `addonsmanager` | aggregate update flow |
| `server_content_validate_files` | same | same | `cron`, `addonsmanager` | validation flow |
| `server_content_backup_before_update` | same | same | `cron`, `addonsmanager`, backup-related helpers | backup hook before content update |
## Agent Scheduler RPCs
| RPC | Purpose |
|---|---|
| `scheduler_add_task` | add cron line |
| `scheduler_edit_task` | update cron line |
| `scheduler_del_task` | delete cron line |
| `scheduler_list_tasks` | list cron lines |
## Internal Agent Scheduler Subroutines
| Subroutine | Purpose |
|---|---|
| `scheduler_dispatcher` | top-level cron callback |
| `scheduler_server_action` | execute parsed action |
| `scheduler_log_events` | append `scheduler.log` |
| `scheduler_read_tasks` | reload current cron entries |
| `scheduler_stop` | stop and rebuild cron object |
## Runtime Flow
```text
User/admin saves scheduler job in Panel
-> Panel builds cron line
-> 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
-> those paths may call the agent again for actual server/content work
```
This means the current scheduler is two-hop:
1. agent cron executes a Panel API URL
2. the Panel API route often calls back to the same or another agent
## Logging
Current observable logs:
- agent-side `scheduler.log`
- panel-side UI through `Panel/modules/cron/events.php`
- module-specific logs from `gamemanager` or `addonsmanager`
## Limitations
| Limitation | Effect |
|---|---|
| string-based cron commands | weaker typing and validation |
| action permissions are implicit | customer-safe vs admin-only is not strongly modeled |
| result storage is agent-log-centric | poor user-facing job history |
| jobs depend on Panel URL/token validity | token rotations require cron rewrite |
| many actions are API callbacks, not local structured tasks | more moving parts and harder debugging |
## 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/ogp_agent.pl`
- `rg -n "gamemanager/(start|stop|restart)|server_content/run_scheduled_action" Panel/modules/cron`

171
docs/features/USER_API.md Normal file
View file

@ -0,0 +1,171 @@
# User API
## Scope
This file documents the externally reachable API and webhook surfaces discovered in the repository.
Primary files:
- `Panel/ogp_api.php`
- `Panel/status_api.php`
- `Website/api/create_order.php`
- `Website/api/capture_order.php`
- `Website/api/log_error.php`
- `Website/webhook.php`
- `Website/paypal/webhook.php`
## Panel Automation API
Main endpoint:
- `Panel/ogp_api.php`
Transport:
- GET, POST, or JSON request body
- response is usually JSON
- `setting/get` returns plain text
Authentication:
- token-based
- token created through `token/create`
- host allowlist can be enforced with `api_authorized.hosts` and `api_authorized.fwd_hosts`
Important notes:
- the API is not a public anonymous API
- some routes are meaningful for normal users
- many routes are effectively admin-only because they mutate remote servers, create homes, or manage users
### Authentication Endpoints
| 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 |
### User-Visible Game Server Actions
| Endpoint | Auth | Purpose | Parameters | Returns |
|---|---|---|---|---|
| `gamemanager/start` | token + home access | start server | `ip`, `port`, optional `mod_key` | JSON status |
| `gamemanager/stop` | token + home access | stop server | `ip`, `port`, optional `mod_key` | JSON status |
| `gamemanager/restart` | token + home access | restart server | `ip`, `port`, optional `mod_key` | JSON status |
| `gamemanager/rcon` | token + home access | send RCON/console command | `ip`, `port`, optional `mod_key`, `command` | JSON command result |
| `gamemanager/update` | token + home access | update server | `ip`, `port`, optional `mod_key`, `type`, optional `manual_url` | JSON status |
| `litefm/list` | token + home access | list files | `ip`, `port`, `relative_path` | JSON listing |
| `litefm/get` | token + home access | read file | `ip`, `port`, `relative_path` | JSON file content |
| `litefm/save` | token + home access | write file | `ip`, `port`, `relative_path`, `contents` | JSON status |
| `litefm/remove` | token + home access | delete file | `ip`, `port`, `relative_path` | JSON status |
| `addonsmanager/list` | token | list add-on templates | `token` | JSON list |
| `addonsmanager/install` | token + home access | install named add-on | `ip`, `port`, `addon_id` | JSON status |
| `steam_workshop/install` | token + home access | legacy Workshop install | `ip`, `port`, optional `mod_key`, `mods_list` | JSON status |
| `server_content/run_scheduled_action` | token + home access | trigger typed server-content action | `home_id`, `action`, optional `options` | JSON status |
### Admin-Oriented API Routes
| Endpoint | Auth | Purpose | Parameters | Returns |
|---|---|---|---|---|
| `server/list` | admin token | list remote agents | `token` | JSON list |
| `server/status` | admin token | status of remote agent | `remote_server_id` | JSON status |
| `server/restart` | admin token | restart agent | `remote_server_id` | JSON status |
| `server/create` | admin token | create remote agent record | agent connection fields | JSON status |
| `server/remove` | admin token | remove remote agent record | `remote_server_id` | JSON status |
| `server/add_ip` | admin token | add IP to agent | `remote_server_id`, `ip` | JSON status |
| `server/remove_ip` | admin token | remove IP from agent | `remote_server_id`, `ip` | JSON status |
| `server/list_ips` | admin token | list assigned IPs | `remote_server_id` | JSON list |
| `server/edit_ip` | admin token | edit assigned IP | `remote_server_id`, `old_ip`, `new_ip` | JSON status |
| `user_games/list_games` | token | list game configs | `system`, `architecture` | JSON list |
| `user_games/list_servers` | token | list homes visible to token | none | JSON list |
| `user_games/create` | admin token | create game home | remote server, config, port, passwords, slots, affinity, nice | JSON status |
| `user_games/clone` | admin token | clone home | origin + new home fields | JSON status |
| `user_games/set_expiration` | admin token | change home expiry | `home_id`, `timestamp` | JSON status |
| `user_admin/*` | admin token | user CRUD and assignments | varies | JSON status |
| `gamemanager_admin/reorder` | admin token | reorder homes in UI | token | JSON status |
| `setting/get` | token | read setting | `setting_name` | plain text or `-1` |
## Public Status API
Endpoint:
- `Panel/status_api.php?token=...`
Authentication:
- shared query token stored in `status_api_local.php`
Purpose:
- public, read-only node summary
- intended for lightweight dashboards or public status pages
Behavior:
- caches agent stats locally for 30 seconds
- probes agents with TCP reachability
- normalizes CPU, memory, and disk stats when available
Returns:
- JSON object with `generated_at` and `nodes[]`
## Scheduler-As-API
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`
This makes `ogp_api.php` part of the internal scheduler runtime contract.
## Website API Endpoints
### Payment Creation And Capture
| Endpoint | Auth | Purpose | Parameters | Returns |
|---|---|---|---|---|
| `Website/api/create_order.php` | storefront session / checkout context | create PayPal order | checkout/cart payload | JSON PayPal order response |
| `Website/api/capture_order.php` | storefront session / checkout context | capture approved PayPal order | order/capture payload | JSON capture result |
These are thin compatibility wrappers that dispatch into the current billing runtime selected by:
- `Website/_compat_include.php`
- `website_billing_runtime_file(...)`
### Client Error Logging
| Endpoint | Auth | Purpose | Parameters | Returns |
|---|---|---|---|---|
| `Website/api/log_error.php` | none | receive cart/client JS error payloads | JSON body | JSON `{status: logged}` or error |
Security note:
- this endpoint is intentionally open
- it writes to `Website/logs/client_errors.log`
- rate limiting is not obvious in the current implementation
### Webhooks
| Endpoint | Source | Purpose | Auth Model |
|---|---|---|---|
| `Website/webhook.php` | PayPal | verify and process payment webhook | PayPal OAuth + webhook signature verification |
| `Website/paypal/webhook.php` | PayPal | compatibility entrypoint forwarding to `Website/webhook.php` runtime | same |
| `Panel/modules/billing/webhook.php` | payment runtime compatibility | billing-side webhook entrypoint | gateway-specific |
## Security Controls
| Control | Where |
|---|---|
| token auth | `Panel/ogp_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` |
| 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`
- `sed -n '1,240p' Panel/status_api.php`
- `find Website/api -maxdepth 1 -type f`
- `sed -n '1,220p' Website/webhook.php`

52
docs/features/WORKSHOP_SYSTEM.md
View file

@ -68,9 +68,33 @@ Default install paths:
App ID rules:
- `workshop_app_id` must come from a Server Content template, Steam Workshop profile, or game XML.
- Game XML should declare Workshop support in the canonical `workshop_support` block.
- Do not silently use the dedicated server Steam app ID as the Workshop app ID unless a legacy profile explicitly does so.
- Arma 3 XML declares Workshop app ID `107410`; its dedicated server Steam app ID remains `233780`.
Canonical XML:
```xml
<workshop_support>
<enabled>1</enabled>
<provider>steam</provider>
<steam_app_id>107410</steam_app_id>
<workshop_app_id>107410</workshop_app_id>
<download_method>steamcmd</download_method>
<install_strategy>arma_mod_folder</install_strategy>
<install_path>{SERVER_ROOT}/{MOD_FOLDER}</install_path>
<startup_param_format>-mod={MOD_LIST}</startup_param_format>
<mod_separator>;</mod_separator>
<mod_prefix>@</mod_prefix>
<copy_keys enabled="1">
<source_pattern>{MOD_PATH}/keys/*.bikey</source_pattern>
<target_path>{SERVER_ROOT}/keys</target_path>
</copy_keys>
</workshop_support>
```
The Panel helper parser reads `workshop_support` first. Older direct tags are tolerated only as a compatibility fallback in helper code; they are not the canonical XML format.
## Database State
`server_content_workshop` tracks:
@ -140,3 +164,31 @@ Use `addonsmanager` as the main future home for:
- install history
Treat `steam_workshop` as a legacy bridge for migration only.
## Panel-Agent Contract
Phase 1 does not use the legacy `steam_workshop` XML-RPC method for the primary user workflow. Instead:
1. Panel parses customer input into numeric Workshop IDs.
2. Panel writes `{SERVER_HOME}/gsp_server_content/workshop_manifest.json`.
3. Panel stages the OS-appropriate bundled handler under `{SERVER_HOME}/gsp_server_content/scripts/workshop/`.
4. Panel invokes the handler through the existing authenticated agent `exec` RPC.
5. The handler writes `workshop_install.log` or `workshop_install_windows.log` under `gsp_server_content`.
6. Panel updates `server_content_workshop.install_state` from queued/installing to installed/failed/removed.
Important manifest fields:
- `home_id`
- `home_cfg_id`
- `game_path`
- `server_path`
- `workshop_app_id`
- `steam_app_id`
- `items`
- `item_details`
- `install_strategy`
- `target_path`
- `extra.copy_keys`
- `extra.keys_target_path`
Both bundled handlers validate numeric item IDs, keep writes under the server home, use SteamCMD, copy files into the resolved target path, and copy `.bikey` files for DayZ/Arma strategies when enabled.

46
docs/features/XML_SYSTEM.md
View file

@ -24,6 +24,7 @@ The schema supports:
- query port calculation
- control protocol selection
- mod definitions
- Workshop / Server Content capability declarations
- custom fields
- server parameter groups
- text replacement helpers
@ -89,6 +90,50 @@ XML definitions also feed:
- reserved ports
- mod or content behavior
## Workshop / Server Content Capability
Workshop-enabled games must use the canonical `workshop_support` block. Loose top-level tags such as `workshop_app_id` are compatibility parser fallbacks only and should not be used in new game XML because schema validation is intentionally strict.
Example:
```xml
<workshop_support>
<enabled>1</enabled>
<provider>steam</provider>
<steam_app_id>107410</steam_app_id>
<workshop_app_id>107410</workshop_app_id>
<download_method>steamcmd</download_method>
<install_strategy>arma_mod_folder</install_strategy>
<install_path>{SERVER_ROOT}/{MOD_FOLDER}</install_path>
<startup_param_format>-mod={MOD_LIST}</startup_param_format>
<mod_separator>;</mod_separator>
<mod_prefix>@</mod_prefix>
<copy_keys enabled="1">
<source_pattern>{MOD_PATH}/keys/*.bikey</source_pattern>
<target_path>{SERVER_ROOT}/keys</target_path>
</copy_keys>
</workshop_support>
```
Supported `install_strategy` values:
- `game_managed_workshop`
- `steamcmd_download_only`
- `copy_to_game_root`
- `copy_to_mod_folder`
- `dayz_mod_folder`
- `arma_mod_folder`
- `config_only`
- `custom_scripted_install`
`workshop_app_id` is the Steam Workshop app ID used by `steamcmd +workshop_download_item`. It is not automatically the same as a dedicated server installer app ID. For Arma 3, Workshop content uses `107410` while the dedicated server installer remains defined on the normal mod installer entry.
The current XML schema is validated by:
```bash
php Panel/modules/config_games/tests/validate_server_configs.php
```
## Recommended Mental Model
Think of the XML system as the capability definition layer:
@ -102,4 +147,3 @@ game XML
-> docs links
-> scheduler and status hints
```