doc changes and reference folder
This commit is contained in:
parent
11691a5876
commit
82cbc206eb
33 changed files with 1514 additions and 2855 deletions
|
|
@ -79,6 +79,18 @@ Relevant function:
|
|||
|
||||
The agent reads screen logs and may also copy a local log file into the game home. Logs should be treated as runtime output, not as a state store.
|
||||
|
||||
## Workshop / Server Content
|
||||
|
||||
The primary Workshop workflow is owned by the Panel `addonsmanager`, not the legacy `steam_workshop` RPC. For Linux servers the Panel:
|
||||
|
||||
1. writes `gsp_server_content/workshop_manifest.json` under the server home
|
||||
2. stages `generic_steam_workshop_linux.sh` under `gsp_server_content/scripts/workshop/`
|
||||
3. invokes the staged script through the authenticated `exec` RPC
|
||||
|
||||
The staged script uses Python and SteamCMD, validates numeric Workshop IDs, keeps writes under the server home, logs to `gsp_server_content/workshop_install.log`, and supports DayZ/Arma-style `@mod` folders plus `.bikey` copying.
|
||||
|
||||
The older `steam_workshop` XML-RPC method remains for legacy compatibility only and should not be treated as the primary customer workflow.
|
||||
|
||||
## Scheduler
|
||||
|
||||
Linux scheduler functions live in `ogp_agent.pl`:
|
||||
|
|
|
|||
|
|
@ -107,6 +107,18 @@ Relevant function:
|
|||
|
||||
Windows/Cygwin logs come from screen logs and/or local copies. Log retrieval should remain compatible with the Panel's AJAX log view.
|
||||
|
||||
## Workshop / Server Content
|
||||
|
||||
The primary Workshop workflow is owned by the Panel `addonsmanager`, not the legacy `steam_workshop` RPC. For Windows/Cygwin servers the Panel:
|
||||
|
||||
1. writes `gsp_server_content/workshop_manifest.json` under the server home
|
||||
2. stages `generic_steam_workshop_windows_cygwin.sh` under `gsp_server_content/scripts/workshop/`
|
||||
3. invokes the staged script through the authenticated `exec` RPC
|
||||
|
||||
The staged script uses Python and SteamCMD, validates numeric Workshop IDs, keeps writes under the server home, logs to `gsp_server_content/workshop_install_windows.log`, and supports DayZ/Arma-style `@mod` folders plus `.bikey` copying.
|
||||
|
||||
The older `steam_workshop` XML-RPC method remains for legacy compatibility only and should not be treated as the primary customer workflow.
|
||||
|
||||
## Scheduler
|
||||
|
||||
Relevant functions:
|
||||
|
|
|
|||
|
|
@ -1,166 +1,267 @@
|
|||
# API Reference
|
||||
|
||||
## Overview
|
||||
## Scope
|
||||
|
||||
Panel-Agent communication uses XML-RPC over HTTP.
|
||||
This is the master reference for:
|
||||
|
||||
Main transport wrapper:
|
||||
- Panel -> agent XML-RPC
|
||||
- external Panel API routes
|
||||
- public status API
|
||||
- Website payment/webhook endpoints
|
||||
|
||||
- `Panel/includes/lib_remote.php`
|
||||
Detailed command catalog:
|
||||
|
||||
Main agent implementation files:
|
||||
- `docs/architecture/PANEL_AGENT_COMMANDS.md`
|
||||
|
||||
- `Agent_Linux/ogp_agent.pl`
|
||||
- `Agent-Windows/ogp_agent.pl`
|
||||
Scheduler action catalog:
|
||||
|
||||
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.
|
||||
- `docs/features/SCHEDULER_ACTIONS.md`
|
||||
|
||||
## General Call Pattern
|
||||
## Architecture Overview
|
||||
|
||||
```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
|
||||
home.php module request
|
||||
-> module PHP page
|
||||
-> shared include libraries
|
||||
-> database layer
|
||||
-> optional agent RPC through lib_remote.php
|
||||
|
||||
external automation
|
||||
-> Panel/ogp_api.php
|
||||
-> api_* handler
|
||||
-> same module/library logic
|
||||
-> optional agent RPC
|
||||
|
||||
public node status
|
||||
-> Panel/status_api.php
|
||||
-> direct remote host probe + optional agent stats
|
||||
|
||||
website checkout/webhook
|
||||
-> Website/api/* or Website/webhook.php
|
||||
-> billing runtime
|
||||
-> DB and payment gateway APIs
|
||||
```
|
||||
|
||||
## Core RPC Methods
|
||||
## Panel -> Agent XML-RPC
|
||||
|
||||
| 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. |
|
||||
| `exec` | Execute a constrained agent-side command | `gamemanager` fallback status checks, admin tooling | The Game Monitor currently uses this only as a fallback to test whether the configured game port is listening with `ss`/`netstat`. Customer input must not be passed through this path. |
|
||||
| `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. |
|
||||
| `component_update` | Queue a Git-based agent code update | Update module | Admin-only. Uses encrypted XML-RPC, validates repo/branch/source/destination, launches a detached updater, preserves agent config/runtime/server data, and returns queued status plus an agent log path. |
|
||||
| `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. |
|
||||
Transport:
|
||||
|
||||
## Status And Return Patterns
|
||||
- XML-RPC over HTTP
|
||||
- endpoint path `/RPC2`
|
||||
- wrapper `Panel/includes/lib_remote.php`
|
||||
- server implementations in `Agent_Linux/ogp_agent.pl` and `Agent-Windows/ogp_agent.pl`
|
||||
|
||||
Return values differ by method, but common patterns are:
|
||||
Primary categories:
|
||||
|
||||
- `1` or positive values for success
|
||||
- `0` for offline/unavailable
|
||||
- `-1` or another negative value for error
|
||||
- structured arrays/hashes for richer status methods
|
||||
| Category | Examples |
|
||||
|---|---|
|
||||
| lifecycle | `server_status`, `universal_start`, `stop_server`, `restart_server` |
|
||||
| files | `readfile`, `writefile`, `dirlist`, `get_file_part` |
|
||||
| updates | `steam_cmd`, `component_update`, `stop_update` |
|
||||
| system | `exec`, `sudo_exec`, `rebootnow`, `what_os`, `discover_ips`, `mon_stats` |
|
||||
| scheduler | `scheduler_add_task`, `scheduler_edit_task`, `scheduler_del_task`, `scheduler_list_tasks` |
|
||||
| content | `steam_workshop`, `get_workshop_mods_info` |
|
||||
|
||||
`remote_server_status` is the important structured response. It should return the agent as source of truth for:
|
||||
See the full command table in:
|
||||
|
||||
- `docs/architecture/PANEL_AGENT_COMMANDS.md`
|
||||
|
||||
## Panel Wrapper Methods
|
||||
|
||||
Most Panel modules do not build XML-RPC directly. They call `OGPRemoteLibrary`.
|
||||
|
||||
| Wrapper Method | Agent Command | Common Modules |
|
||||
|---|---|---|
|
||||
| `status_chk()` | `quick_chk` | `cron`, `server`, `status`, `dashboard`, update pages |
|
||||
| `remote_server_status()` | `server_status` | `gamemanager` |
|
||||
| `universal_start()` | `universal_start` | `gamemanager`, API start |
|
||||
| `remote_stop_server()` | `stop_server` | `gamemanager`, billing, API stop |
|
||||
| `remote_restart_server()` | `restart_server` | `gamemanager`, API restart |
|
||||
| `remote_send_rcon_command()` | `send_rcon_command` | `gamemanager`, `rcon`, util helpers |
|
||||
| `remote_readfile()` / `remote_writefile()` | `readfile` / `writefile` | `litefm`, `editconfigfiles`, `addonsmanager`, `mysql`, `server` |
|
||||
| `remote_query()` | `remote_query` | `gamemanager`, dashboards |
|
||||
| `component_update()` | `component_update` | update/admin pages |
|
||||
| `scheduler_*()` | `scheduler_*` | `cron` |
|
||||
| `steam_workshop()` | `steam_workshop` | legacy workshop path |
|
||||
|
||||
## External Panel API
|
||||
|
||||
Primary endpoint:
|
||||
|
||||
- `Panel/ogp_api.php`
|
||||
|
||||
Auth model:
|
||||
|
||||
- token-based
|
||||
- token issued by `token/create`
|
||||
- requests can be GET, POST, or JSON body
|
||||
- host allowlist can be enforced
|
||||
|
||||
Top-level API handlers implemented in `ogp_api.php`:
|
||||
|
||||
| Handler Function | Route Prefix | Purpose |
|
||||
|---|---|---|
|
||||
| `api_token()` | `token/*` | create/test tokens |
|
||||
| `api_server()` | `server/*` | remote agent CRUD/status |
|
||||
| `api_user_games()` | `user_games/*` | home provisioning and listing |
|
||||
| `api_user_admin()` | `user_admin/*` | user CRUD and assignments |
|
||||
| `api_gamemanager_admin()` | `gamemanager_admin/*` | admin game manager actions |
|
||||
| `api_gamemanager()` | `gamemanager/*` | start/stop/restart/update/RCON |
|
||||
| `api_litefm()` | `litefm/*` | file listing/read/write/delete |
|
||||
| `api_addonsmanager()` | `addonsmanager/*` | content template listing/install |
|
||||
| `api_server_content()` | `server_content/*` | scheduled content actions |
|
||||
| `api_steam_workshop()` | `steam_workshop/*` | legacy workshop installs |
|
||||
| `api_setting()` | `setting/*` | setting read helper |
|
||||
|
||||
Detailed route list:
|
||||
|
||||
| Route | Purpose |
|
||||
|---|---|
|
||||
| `token/create`, `token/test` | auth bootstrap |
|
||||
| `server/list`, `server/status`, `server/restart`, `server/create`, `server/remove`, `server/add_ip`, `server/remove_ip`, `server/list_ips`, `server/edit_ip` | remote host management |
|
||||
| `user_games/list_games`, `user_games/list_servers`, `user_games/create`, `user_games/clone`, `user_games/set_expiration` | server-home management |
|
||||
| `user_admin/list`, `user_admin/get`, `user_admin/create`, `user_admin/remove`, `user_admin/set_expiration`, `user_admin/list_assigned`, `user_admin/assign`, `user_admin/remove_assign` | user management |
|
||||
| `gamemanager/start`, `gamemanager/stop`, `gamemanager/restart`, `gamemanager/rcon`, `gamemanager/update` | lifecycle automation |
|
||||
| `gamemanager_admin/reorder` | admin ordering helper |
|
||||
| `litefm/list`, `litefm/get`, `litefm/save`, `litefm/remove` | remote file operations |
|
||||
| `addonsmanager/list`, `addonsmanager/install` | add-on templates |
|
||||
| `steam_workshop/install` | legacy Workshop install |
|
||||
| `server_content/run_scheduled_action` | typed content action trigger |
|
||||
| `setting/get` | panel setting read |
|
||||
|
||||
See:
|
||||
|
||||
- `docs/features/USER_API.md`
|
||||
|
||||
## Public Status API
|
||||
|
||||
Endpoint:
|
||||
|
||||
- `Panel/status_api.php`
|
||||
|
||||
Purpose:
|
||||
|
||||
- public or semi-public read-only summary of remote nodes
|
||||
|
||||
Auth:
|
||||
|
||||
- shared query token
|
||||
|
||||
Behavior:
|
||||
|
||||
- probes remote agents with TCP
|
||||
- optionally calls agent stats method names if available
|
||||
- caches JSON locally for 30 seconds
|
||||
|
||||
Return shape:
|
||||
|
||||
- `generated_at`
|
||||
- `nodes[]`
|
||||
- `name`
|
||||
- `host`
|
||||
- `agent_port`
|
||||
- `online`
|
||||
- `cpu_percent`
|
||||
- `mem_percent`
|
||||
- `disk_percent`
|
||||
|
||||
## Website API And Webhooks
|
||||
|
||||
| Endpoint | Purpose | Auth / Verification |
|
||||
|---|---|---|
|
||||
| `Website/api/create_order.php` | create PayPal order | storefront checkout/session context |
|
||||
| `Website/api/capture_order.php` | capture PayPal order | storefront checkout/session context |
|
||||
| `Website/api/log_error.php` | client-side error logging | open endpoint, writes log |
|
||||
| `Website/webhook.php` | verified PayPal webhook processing | OAuth + webhook signature verification |
|
||||
| `Website/paypal/webhook.php` | compatibility wrapper to active webhook runtime | same |
|
||||
|
||||
## Internal Module Endpoints
|
||||
|
||||
These are not public APIs in the same sense as `ogp_api.php`, but they matter architecturally.
|
||||
|
||||
| Endpoint | Module | Purpose |
|
||||
|---|---|---|
|
||||
| `Panel/modules/gamemanager/get_server_log.php` | `gamemanager` | AJAX log refresh |
|
||||
| `Panel/modules/dashboard/updateWidgets.php` | `dashboard` | dashboard async refresh |
|
||||
| `Panel/modules/tickets/notificationCount.php` | `tickets` | unread count |
|
||||
| `Panel/modules/cron/events.php` | `cron` | scheduler log refresh |
|
||||
| `Panel/modules/litefm/get_file.php` | `litefm` | chunked file downloads |
|
||||
|
||||
## Workshop Manifest Contract
|
||||
|
||||
Current preferred Workshop/content flow:
|
||||
|
||||
1. Panel validates Workshop IDs
|
||||
2. Panel writes manifest JSON to server home
|
||||
3. Panel stages bundled helper script to agent host via `writefile`
|
||||
4. Panel runs helper with `exec`
|
||||
5. Agent logs/install output is returned to Panel
|
||||
|
||||
Common manifest fields:
|
||||
|
||||
- `manifest_version`
|
||||
- `home_id`
|
||||
- `home_cfg_id`
|
||||
- `content_type`
|
||||
- `action`
|
||||
- `items`
|
||||
- `options`
|
||||
|
||||
For Workshop-specific manifests, the broader fields documented in `WORKSHOP_SYSTEM.md` also apply, including app IDs, install strategy, and target paths.
|
||||
|
||||
## Status Contract
|
||||
|
||||
`server_status` is the preferred runtime contract.
|
||||
|
||||
Expected fields:
|
||||
|
||||
- `status`
|
||||
- `ready`
|
||||
- `process_running`
|
||||
- `session_running`
|
||||
- `game_port_listening`
|
||||
- `query_port_listening`
|
||||
- `rcon_port_listening`
|
||||
- `pid`
|
||||
- `session_name`
|
||||
- `ip`
|
||||
- `port`
|
||||
- `query_port`
|
||||
- `rcon_port`
|
||||
- `last_error`
|
||||
- `query_info`
|
||||
|
||||
State meanings:
|
||||
|
||||
- `OFFLINE`
|
||||
- `STARTING`
|
||||
- `ONLINE`
|
||||
- `STARTING`
|
||||
- `STOPPING`
|
||||
- `OFFLINE`
|
||||
- `UNRESPONSIVE`
|
||||
- `UNKNOWN`
|
||||
|
||||
The Panel Game Monitor has a defensive fallback path while the structured status system is still being hardened:
|
||||
Rules:
|
||||
|
||||
```text
|
||||
remote_server_status if available
|
||||
-> is_screen_running fallback
|
||||
-> agent-side port listening check through exec
|
||||
-> LGSL/GameQ only for optional player/map/query metadata
|
||||
```
|
||||
- query failure alone must not imply offline
|
||||
- agent process/session or game-port evidence is sufficient for online
|
||||
- `UNKNOWN` is reserved for unreachable or inconclusive agent state
|
||||
|
||||
A confirmed managed screen/session, process flag, or listening game port is enough for the Panel to display `ONLINE`. Query failure alone must not produce `OFFLINE` or `UNKNOWN`.
|
||||
## Scheduler-As-API Contract
|
||||
|
||||
Current compatibility behavior:
|
||||
Agent cron jobs often execute URLs like:
|
||||
|
||||
- New agents should expose `server_status` / `remote_server_status`.
|
||||
- Older agents may only expose `is_screen_running` and generic `exec`.
|
||||
- The Panel therefore falls back to `is_screen_running` and an agent-side port check.
|
||||
- Agents report `ONLINE` when the configured game port is listening even if the managed screen/session cannot be found, with `last_error` carrying the warning.
|
||||
- LGSL/GameQ/Steam query data is optional metadata only.
|
||||
- `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`
|
||||
|
||||
## Sequence Diagrams
|
||||
This means `ogp_api.php` is part of the scheduler runtime and must stay backward compatible with those generated URLs.
|
||||
|
||||
### Start
|
||||
## Search Coverage Used For This Document
|
||||
|
||||
```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 dedicated preformatted log panel via AJAX
|
||||
```
|
||||
|
||||
### Remote Agent Component Update
|
||||
|
||||
```text
|
||||
Panel update page
|
||||
-> component_update(payload)
|
||||
Agent
|
||||
-> validate repo, branch, source folder, destination
|
||||
-> write detached updater script
|
||||
-> return queued + log path
|
||||
Updater script
|
||||
-> clone/fetch repository into staging
|
||||
-> copy Agent_Linux or Agent-Windows folder only
|
||||
-> preserve Cfg, ServerFiles, Schedule, logs, steamcmd, startups, pid files
|
||||
-> validate ogp_agent.pl
|
||||
-> restart agent through systemd or screen fallback
|
||||
```
|
||||
|
||||
## 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.
|
||||
- `sed -n '1,240p' Panel/ogp_api.php`
|
||||
- `rg -n "^function api_" 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`
|
||||
|
|
|
|||
159
docs/architecture/LIBRARY_REFERENCE.md
Normal file
159
docs/architecture/LIBRARY_REFERENCE.md
Normal file
|
|
@ -0,0 +1,159 @@
|
|||
# Library Reference
|
||||
|
||||
## Scope
|
||||
|
||||
This file documents the shared Panel libraries and helper entrypoints that multiple modules reuse.
|
||||
|
||||
Primary directories:
|
||||
|
||||
- `Panel/includes/`
|
||||
- `Panel/protocol/`
|
||||
|
||||
No separate `Panel/libraries/` or `Panel/common/` tree is currently used as the main shared layer.
|
||||
|
||||
## Core Include Files
|
||||
|
||||
| File | Purpose | Used By |
|
||||
|---|---|---|
|
||||
| `Panel/includes/config.inc.php` | Main runtime configuration | global bootstrap, APIs, installers |
|
||||
| `Panel/includes/database.php` | DB abstraction selector | bootstrap |
|
||||
| `Panel/includes/database_mysqli.php` | Main database implementation and business-query layer | almost all stateful modules |
|
||||
| `Panel/includes/functions.php` | general utility helpers, formatting, logging, Discord webhook helper | global |
|
||||
| `Panel/includes/helpers.php` | session, auth, panel helper functions | global |
|
||||
| `Panel/includes/html_functions.php` | HTML rendering helpers | module UIs |
|
||||
| `Panel/includes/form_table_class.php` | form builder helper | admin and config forms |
|
||||
| `Panel/includes/lang.php` | translation loading | global |
|
||||
| `Panel/includes/lib_remote.php` | XML-RPC wrapper for agent commands | every agent-aware module |
|
||||
| `Panel/includes/navig.php` | module/page routing | main panel request flow |
|
||||
| `Panel/includes/view.php` | page shell and shared JS injection | main panel request flow |
|
||||
| `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 |
|
||||
|
||||
## `lib_remote.php` Wrapper Surface
|
||||
|
||||
`Panel/includes/lib_remote.php` is the most important shared library in the repository.
|
||||
|
||||
Responsibilities:
|
||||
|
||||
- XML-RPC request creation
|
||||
- encryption of parameters
|
||||
- RPC request transport
|
||||
- decoding return payloads
|
||||
- compatibility fallbacks for older agents
|
||||
|
||||
Major consumers:
|
||||
|
||||
- `gamemanager`
|
||||
- `cron`
|
||||
- `server`
|
||||
- `user_games`
|
||||
- `addonsmanager`
|
||||
- `litefm`
|
||||
- `ftp`
|
||||
- `mysql`
|
||||
- `status`
|
||||
- `dashboard`
|
||||
- `util`
|
||||
|
||||
See:
|
||||
|
||||
- `docs/architecture/PANEL_AGENT_COMMANDS.md`
|
||||
|
||||
## Database Layer
|
||||
|
||||
`Panel/includes/database_mysqli.php` is more than a raw DB adapter. It acts as a domain service layer.
|
||||
|
||||
It owns:
|
||||
|
||||
- users and roles
|
||||
- remote servers
|
||||
- game homes
|
||||
- config homes and mods
|
||||
- API tokens
|
||||
- widget settings
|
||||
- many module-specific table helpers
|
||||
|
||||
Practical rule:
|
||||
|
||||
- before adding direct SQL inside a module, check whether `database_mysqli.php` already exposes the needed operation
|
||||
|
||||
## API Helper Layer
|
||||
|
||||
`Panel/includes/api_functions.php` supports `Panel/ogp_api.php`.
|
||||
|
||||
Responsibilities:
|
||||
|
||||
- endpoint argument definitions
|
||||
- startup command generation
|
||||
- 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`.
|
||||
|
||||
## XML / Game Config Parsing
|
||||
|
||||
Shared files:
|
||||
|
||||
- `Panel/modules/config_games/server_config_parser.php`
|
||||
- `Panel/modules/config_games/schema_server_config.xml`
|
||||
- `Panel/modules/config_games/xml_tag_descriptions.php`
|
||||
|
||||
Responsibilities:
|
||||
|
||||
- validate game XML files
|
||||
- load startup/query/install metadata
|
||||
- expose game config values to `gamemanager`, `user_games`, `addonsmanager`, `dsi`, and APIs
|
||||
|
||||
## Protocol Libraries
|
||||
|
||||
| Path | Purpose | Used By |
|
||||
|---|---|---|
|
||||
| `Panel/protocol/lgsl/` | LGSL query implementation | `gamemanager`, `dsi`, XML helpers |
|
||||
| `Panel/protocol/GameQ/` | GameQ query implementation | `gamemanager`, `dsi`, XML helpers |
|
||||
|
||||
Important note:
|
||||
|
||||
- query libraries provide optional metadata
|
||||
- they are not the source of truth for runtime status
|
||||
|
||||
## Bundled Third-Party Libraries In Modules
|
||||
|
||||
These are module-local, not general-purpose shared libs, but they matter for architecture.
|
||||
|
||||
| Path | Purpose | Main Module |
|
||||
|---|---|---|
|
||||
| `Panel/modules/ftp/` bundled net2ftp code | browser-based FTP UI | `ftp` |
|
||||
| `Panel/modules/TS3Admin/` | TeamSpeak admin webapp | `TS3Admin` |
|
||||
| `Panel/modules/teamspeak3/ts3admin.class.php` and related files | TeamSpeak integration | `teamspeak3` |
|
||||
| `Panel/modules/gamemanager/MinecraftRcon.class.php` | Minecraft-specific RCON client | `gamemanager` |
|
||||
| `Panel/modules/news/include/library/HTMLPurifier/` | content sanitization | `news` |
|
||||
|
||||
## Filesystem And Update Helpers
|
||||
|
||||
Notable update-related shared logic currently lives in:
|
||||
|
||||
- `Panel/modules/administration/panel_update.php`
|
||||
- `Panel/modules/update/updating.php`
|
||||
- `Panel/modules/update/patch_manager.php`
|
||||
- `Panel/modules/update/post_update.php`
|
||||
|
||||
These are not in `includes/`, but they function as shared update infrastructure used by the admin-facing update UI.
|
||||
|
||||
## Consumers By Concern
|
||||
|
||||
| Concern | Primary Shared Files |
|
||||
|---|---|
|
||||
| Agent RPC | `includes/lib_remote.php` |
|
||||
| Database | `includes/database_mysqli.php` |
|
||||
| API | `includes/api_functions.php`, `ogp_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` |
|
||||
| Auth/session helpers | `includes/helpers.php`, `includes/functions.php` |
|
||||
|
||||
## Search Coverage Used For This Document
|
||||
|
||||
- `find Panel/includes -maxdepth 1 -type f`
|
||||
- `rg -n "require_once\\('includes/lib_remote.php'|require_once\\(\"modules/config_games/server_config_parser.php\"|require_once\\('protocol/" Panel/modules`
|
||||
148
docs/architecture/MODULE_DEPENDENCIES.md
Normal file
148
docs/architecture/MODULE_DEPENDENCIES.md
Normal file
|
|
@ -0,0 +1,148 @@
|
|||
# Module Dependencies
|
||||
|
||||
## Scope
|
||||
|
||||
This file maps how Panel modules depend on:
|
||||
|
||||
- agents
|
||||
- shared libraries
|
||||
- other modules
|
||||
- database tables
|
||||
- AJAX endpoints
|
||||
- external services
|
||||
|
||||
It answers the practical question: what can call what?
|
||||
|
||||
## Core Dependency Layers
|
||||
|
||||
```text
|
||||
User / admin UI
|
||||
-> home.php module routing
|
||||
-> module page PHP files
|
||||
-> shared include libraries
|
||||
-> database layer
|
||||
-> agent RPC wrapper (lib_remote.php)
|
||||
-> Linux / Windows agents
|
||||
|
||||
AJAX / external API
|
||||
-> module endpoint PHP files or ogp_api.php / status_api.php
|
||||
-> same shared libraries and DB layer
|
||||
-> agent RPC where needed
|
||||
```
|
||||
|
||||
## Shared Internal Hubs
|
||||
|
||||
| Hub | Called By | Purpose |
|
||||
|---|---|---|
|
||||
| `Panel/includes/lib_remote.php` | `gamemanager`, `cron`, `server`, `user_games`, `litefm`, `ftp`, `mysql`, `addonsmanager`, `status`, `dashboard`, `util`, `fast_download`, `billing`, `editconfigfiles` | Agent XML-RPC transport |
|
||||
| `Panel/modules/config_games/server_config_parser.php` | `gamemanager`, `user_games`, `addonsmanager`, `cron`, `dsi`, `config_games`, API | Game XML loading and interpretation |
|
||||
| `Panel/includes/database_mysqli.php` | effectively all stateful modules | Database abstraction and business queries |
|
||||
| `Panel/includes/functions.php` and `helpers.php` | global | auth, logging, formatting, small helpers |
|
||||
| `Panel/includes/view.php` and `navig.php` | routing / page shell | module dispatch and page rendering |
|
||||
|
||||
## Module Dependency Table
|
||||
|
||||
| Module | Calls Agent | Calls Other Modules / Files | Shared Libraries | Major DB / State | AJAX / API Endpoints | External Integrations |
|
||||
|---|---|---|---|---|---|---|
|
||||
| `administration` | Indirectly, for update and logger views | `panel_update.php`, backup/log helpers | `functions.php`, DB layer, `lib_remote.php` | settings, remote server metadata | `watch_logger.php` | Git / Forgejo, filesystem |
|
||||
| `addonsmanager` | Yes | `workshop_action.php`, `server_content_actions.php`, `server_content_helpers.php`, `config_games` | `lib_remote.php`, XML parser | `addons`, `server_content_manifest`, `server_content_workshop` | `workshop_action.php` | SteamCMD, Workshop, archive installers |
|
||||
| `backup-restore` | Limited / indirect | local helper function file | DB layer, filesystem helpers | backup metadata if present | module pages | zip/tar filesystem work |
|
||||
| `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 |
|
||||
| `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 |
|
||||
| `faq` | No | RSS/parser helper | DB/content layer | FAQ/news content | `faq.js` | RSS parsing |
|
||||
| `fast_download` | Yes | admin/user pages, helper file | `lib_remote.php`, DB layer | fastdl config aliases | module pages | web server / FastDL service |
|
||||
| `ftp` | Yes | bundled net2ftp app files, admin wrapper | `lib_remote.php`, DB layer | remote server FTP config | admin and embedded FTP UI | Pure-FTPd / FTP service, net2ftp |
|
||||
| `gamemanager` | Yes | `home_handling_functions.php`, start/stop/restart/log pages | `lib_remote.php`, XML parser, helpers | server homes, last params, runtime status | `get_server_log.php`, `log.php`, `rcon.php` | screen, RCON, query protocols, SteamCMD |
|
||||
| `lgsl_with_img_mod` | No agent by default | own LGSL pages | LGSL | server query presentation | `feed.php`, `image.php` | LGSL |
|
||||
| `litefm` | Yes | file manager pages and helpers | `lib_remote.php`, session helpers | session download state | `fm_dir.php`, `fm_read.php`, `fm_write.php`, `get_file.php` | remote file management |
|
||||
| `lostpwd` | No | own page | DB layer, mail helpers | users | form endpoints | email |
|
||||
| `modulemanager` | No agent | `module_handling.php`, update modules | filesystem, DB layer | installed module metadata | add/delete/update pages | filesystem |
|
||||
| `mysql` | Yes | own DB server management pages | `lib_remote.php`, DB layer | mysql server records, dumps | `get_dump.php` | MySQL server administration |
|
||||
| `news` | No | admin upload/config pages | DB/content libs | news posts | upload/admin pages | file upload |
|
||||
| `rcon` | Yes | standalone RCON page | `lib_remote.php`, XML parser | server home lookup | module page | RCON |
|
||||
| `register` | No agent | registration helper pages | DB layer | users | `register-exec.php` | captcha/email if configured |
|
||||
| `server` | Yes | add/edit/restart/reboot/firewall/view_log pages | `lib_remote.php`, DB layer | `remote_servers`, IP allocation | `mon_stats.php`, `view_log.php` | agent lifecycle, firewall, reboot |
|
||||
| `settings` | No agent by default | `api_hosts.php`, theme/settings pages | DB layer, API helpers | `settings`, authorized-host files | settings pages | Discord webhook config, API host files |
|
||||
| `status` | Yes | `modules/status/include/*` | `lib_remote.php`, config helpers | remote server list | embedded include pages | CPU/RAM/disk/uptime monitoring |
|
||||
| `subusers` | No direct agent | own CRUD pages | DB layer | users, permissions | form endpoints | none |
|
||||
| `support` | No agent | own page | DB layer, `functions.php` | support requests | support form page | Discord webhook |
|
||||
| `teamspeak3` | No generic agent RPC | own TS3 admin lib set | TS3-specific classes, DB layer | TS3 homes/config | TS3 pages | TeamSpeak query/admin |
|
||||
| `tickets` | No agent by default | attachment, rating, settings, count, submit, view pages | DB layer | tickets, attachments, ratings | `notificationCount.php`, `submitTicket.php`, `downloadAttachment.php` | email/notifications if configured |
|
||||
| `TS3Admin` | No generic agent RPC | bundled TS3 admin web app | TS3 admin classes | TS3 runtime/admin data | JS-driven views | TeamSpeak admin interface |
|
||||
| `tshock` | No generic agent RPC | shared TShock helpers | DB layer | Terraria/TShock tokens/config | create token and management pages | TShock REST/API |
|
||||
| `update` | Indirectly through `administration/panel_update.php` and agent `component_update` | `updating.php`, patch manager | filesystem, DB/settings, `lib_remote.php` | update settings, backups, last update files | module pages | Git / Forgejo |
|
||||
| `user_admin` | No direct agent | user/group CRUD pages | DB layer | users, groups, assignments | form endpoints | none |
|
||||
| `user_games` | Yes | provisioning, clone, migrate, custom fields, browser | `lib_remote.php`, XML parser, DB layer | `server_homes`, `user_homes`, IP allocations, configs | `get_size.php`, browser pages | filesystem, provisioning, rsync |
|
||||
| `util` | Yes | addadmin helpers, SteamID tools, network tools | `lib_remote.php`, DB layer | server lookup | helper pages | RCON, Steam ID conversion |
|
||||
|
||||
## Module-To-Module Relationships
|
||||
|
||||
| Source Module | Target Module / File | Why |
|
||||
|---|---|---|
|
||||
| `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 |
|
||||
| `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 |
|
||||
| `update` | `administration/panel_update.php` | actual admin-facing updater implementation |
|
||||
| `settings` | `api_functions.php` | authorized host list UI for external API |
|
||||
| `billing` | `Website/` mirrored runtime | storefront and payment logic is shared between panel module and public site |
|
||||
|
||||
## AJAX And Async Endpoints
|
||||
|
||||
| Endpoint | Owning Module | Purpose |
|
||||
|---|---|---|
|
||||
| `Panel/modules/gamemanager/get_server_log.php` | `gamemanager` | live log refresh |
|
||||
| `Panel/modules/dashboard/updateWidgets.php` | `dashboard` | dashboard widget refresh |
|
||||
| `Panel/modules/tickets/notificationCount.php` | `tickets` | unread/support badge count |
|
||||
| `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 |
|
||||
|
||||
## Major Database Ownership
|
||||
|
||||
This is not a full schema map. It identifies ownership boundaries.
|
||||
|
||||
| Table / Group | Main Owners |
|
||||
|---|---|
|
||||
| `settings` | `settings`, `update`, general bootstrap |
|
||||
| `users`, `user_groups`, `user_homes` | `user_admin`, `subusers`, `register`, auth/session flows |
|
||||
| `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 |
|
||||
| `server_content_manifest`, `server_content_workshop`, `addons` | `addonsmanager` |
|
||||
| billing/order/invoice/coupon tables | `billing`, `Website/` |
|
||||
| ticket/support tables | `tickets`, `support` |
|
||||
| widget / dashboard tables | `dashboard` |
|
||||
|
||||
## External Integration Map
|
||||
|
||||
| Integration | Primary Modules |
|
||||
|---|---|
|
||||
| SteamCMD | `gamemanager`, `addonsmanager`, Workshop flows, agents |
|
||||
| Steam Workshop | `addonsmanager`, legacy `steam_workshop`, agents |
|
||||
| GameQ / LGSL | `gamemanager`, `dashboard`, `dsi`, XML config |
|
||||
| RCON | `gamemanager`, `rcon`, `util`, scheduler-triggered API calls |
|
||||
| Git / Forgejo | `update`, `administration/panel_update.php`, agent `component_update` |
|
||||
| FTP / Pure-FTPd / net2ftp | `ftp`, provisioning |
|
||||
| Discord webhooks | `settings`, `support`, shared `functions.php::discordmsg` |
|
||||
| PayPal / Stripe / manual payments | `billing`, `Website/api/*`, `Website/webhook.php` |
|
||||
| TeamSpeak | `teamspeak3`, `TS3Admin` |
|
||||
| TShock | `tshock` |
|
||||
|
||||
## Search Coverage Used For This Document
|
||||
|
||||
Key searches:
|
||||
|
||||
- `rg -n "new OGPRemoteLibrary|->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' \\)`
|
||||
208
docs/architecture/PANEL_AGENT_COMMANDS.md
Normal file
208
docs/architecture/PANEL_AGENT_COMMANDS.md
Normal file
|
|
@ -0,0 +1,208 @@
|
|||
# Panel-Agent Commands
|
||||
|
||||
## Scope
|
||||
|
||||
This file is the command catalog for the XML-RPC surface between the Panel and the agents.
|
||||
|
||||
Primary files:
|
||||
|
||||
- `Panel/includes/lib_remote.php`
|
||||
- `Agent_Linux/ogp_agent.pl`
|
||||
- `Agent-Windows/ogp_agent.pl`
|
||||
|
||||
Transport:
|
||||
|
||||
- Panel -> agent uses XML-RPC over HTTP to `/RPC2`
|
||||
- Arguments are encrypted by `OGPRemoteLibrary`
|
||||
- Agents validate the encryption marker before executing commands
|
||||
|
||||
## Command Dispatch
|
||||
|
||||
Linux dispatch table:
|
||||
|
||||
- `Agent_Linux/ogp_agent.pl`
|
||||
|
||||
Windows dispatch table:
|
||||
|
||||
- `Agent-Windows/ogp_agent.pl`
|
||||
|
||||
Important parity note:
|
||||
|
||||
- Linux exposes `renice_process`
|
||||
- Linux exposes `lock_additional_files`
|
||||
- Windows does not expose those two commands in its current dispatcher
|
||||
|
||||
## Return Conventions
|
||||
|
||||
Common patterns:
|
||||
|
||||
- `1`: success
|
||||
- `0`: false, offline, or not running depending on command
|
||||
- negative values: error or unreachable state
|
||||
- arrays / hashes: structured payloads for newer commands
|
||||
- base64-encoded text payloads are common for file, shell, and stats responses
|
||||
|
||||
## Lifecycle And Status Commands
|
||||
|
||||
| Agent Command | Purpose | Key Arguments | Returns | Windows | Linux | Panel Callers | Security Notes |
|
||||
|---|---|---|---|---|---|---|---|
|
||||
| `quick_chk` | Lightweight reachability and encryption check | none | `1`, `0`, or error | Yes | Yes | `lib_remote.php::status_chk`, most modules before remote work | Safe probe; no server-side mutation |
|
||||
| `is_screen_running` | Legacy managed-session check | `screen_type`, `home_id` | `1`, `0`, `-1` | Yes | Yes | `gamemanager`, status fallback, legacy monitor code | Session existence only; not a full readiness check |
|
||||
| `server_status` | Structured server state check | `home_id`, `server_ip`, `server_port`, `query_port`, `rcon_port`, `startup_timeout`, `state_hint` | hash with state flags | Yes | Yes | `gamemanager/home_handling_functions.php`, `server_monitor.php` | Preferred source of truth for runtime state |
|
||||
| `universal_start` | Start a game server | `home_id`, `game_home`, `game_binary`, `run_dir`, `startup_cmd`, `server_port`, `server_ip`, `cpu`, `nice`, `preStart`, `envVars`, `game_key`, `console_log` | `1`, `-1`, `-2` | Yes | Yes | `gamemanager/start_server.php`, restart flows, API start | Starts managed `screen` session and game command |
|
||||
| `stop_server` | Stop a running server | `home_id`, `server_ip`, `server_port`, `control_protocol`, `control_password`, `control_type`, `game_home` | `1`, `0`, negative error | Yes | Yes | `gamemanager/stop_server.php`, restart flows, API stop, billing expiry flows | Can issue control-protocol commands and escalation kills |
|
||||
| `restart_server` | Restart a running server | start + stop argument set | `1`, `0`, `-1`, `-2` | Yes | Yes | `gamemanager/restart_server.php`, API restart, scheduler | Depends on both stop and start paths working |
|
||||
| `send_rcon_command` | Send RCON / console command | `home_id`, `server_ip`, `server_port`, `control_protocol`, `control_password`, `control_type`, `command`, `return` | `1`, `-10`, error | Yes | Yes | `gamemanager/rcon.php`, `rcon`, util helpers, API rcon | Admin/customer command surface; must not accept untrusted shell text |
|
||||
| `remote_query` | Query game metadata | `protocol`, `game_type`, `ip`, `c_port`, `q_port`, `s_port` | base64 payload or null/error | Yes | Yes | `gamemanager`, dashboard, DSI | Metadata only; not source of truth for online/offline |
|
||||
| `renice_process` | Adjust process priority | process / nice inputs | success / error | No | Yes | `lib_remote.php::renice_process`, startup tuning | Linux-only; process control |
|
||||
| `cpu_count` | Return CPU/core count | none | integer | Yes | Yes | start flows, provisioning, tuning UIs | Read-only system info |
|
||||
|
||||
## File And Filesystem Commands
|
||||
|
||||
| Agent Command | Purpose | Key Arguments | Returns | Windows | Linux | Panel Callers | Security Notes |
|
||||
|---|---|---|---|---|---|---|---|
|
||||
| `rfile_exists` | Check remote file existence | `path` | `1` / `0` | Yes | Yes | file tools, content helpers | Must remain path-safe |
|
||||
| `readfile` | Read remote file | `path` | status + base64 data | Yes | Yes | `litefm`, `gamemanager`, `editconfigfiles`, `mysql`, `server`, API helpers | Reads customer server files and some agent logs |
|
||||
| `writefile` | Write remote file | `path`, `content` | `1` / error | Yes | Yes | `litefm`, `editconfigfiles`, `gamemanager`, `addonsmanager`, `mysql`, `fast_download`, `server` | High-risk write path; caller must validate target path |
|
||||
| `dirlist` | Directory listing | `path` | array / error | Yes | Yes | `gamemanager/mini_start.php`, older browsers | Read-only |
|
||||
| `dirlistfm` | File-manager-specific directory listing | `path` | array / error | Yes | Yes | `litefm`, `user_games/browser.php` | Read-only |
|
||||
| `get_file_part` | Stream file in chunks | `path`, `offset` | next offset + chunk | Yes | Yes | `litefm/get_file.php` | Download helper for large files |
|
||||
| `secure_path` | Agent path validation helper | `action`, `path` | base64 payload / validation result | Yes | Yes | update/content/security flows | Important for safe agent-side path operations |
|
||||
| `get_chattr` | Read filesystem attributes | `path` | attributes text | Yes | Yes | admin/security tools | Mostly Linux semantics |
|
||||
| `lock_additional_files` | Lock or unlock extra files | `game_home`, `filesToLockUnlock`, `action` | success / error | No | Yes | `lib_remote.php::lock_additional_home_files` | Linux-only file-attribute helper |
|
||||
| `clone_home` | Copy a game home | `source_home`, `dest_home`, `owner` | `1`, `0`, `-1` | Yes | Yes | `user_games/clone_home.php`, provisioning | Long-running filesystem mutation |
|
||||
| `remove_home` | Delete a game home | `game_home_del` | `1`, `0`, `-1` | Yes | Yes | `user_games/del_home.php`, teardown flows | Destructive; must be admin or owner-controlled |
|
||||
| `compress_files` | Build archive from remote files | `files`, `destination`, `archive_name`, `archive_type` | success / error | Yes | Yes | backup/content/fastdl flows | Archive path must stay inside allowed roots |
|
||||
| `uncompress_file` | Extract archive | archive inputs | success / error | Yes | Yes | installers, content tools | Extraction path must be constrained |
|
||||
|
||||
## Download, Install, And Update Commands
|
||||
|
||||
| Agent Command | Purpose | Key Arguments | Returns | Windows | Linux | Panel Callers | Security Notes |
|
||||
|---|---|---|---|---|---|---|---|
|
||||
| `steam_cmd` | Run SteamCMD-based install/update | steam-specific arguments | status code | Yes | Yes | `gamemanager/update_server.php`, API update | Can change server binaries and Steam content |
|
||||
| `fetch_steam_version` | Fetch Steam app version metadata | app arguments | version string / error | Yes | Yes | update pages | Read-only Steam helper |
|
||||
| `installed_steam_version` | Read installed Steam app version | path/app inputs | version string / error | Yes | Yes | update pages | Read-only |
|
||||
| `automatic_steam_update` | Auto-update via SteamCMD | update args | status code | Yes | Yes | scheduler/API update path | Mutation of game install |
|
||||
| `start_file_download` | Begin remote file download | URL and target args | pid / handle / status | Yes | Yes | installers, update/content flows | External network fetch; validate destination |
|
||||
| `is_file_download_in_progress` | Poll active download | download handle | status | Yes | Yes | update/content flows | Read-only |
|
||||
| `start_rsync_install` | Begin rsync-based install/copy | rsync args | status | Yes | Yes | migration/provisioning | Long-running copy action |
|
||||
| `rsync_progress` | Poll rsync copy | rsync handle | progress | Yes | Yes | migration/provisioning | Read-only |
|
||||
| `master_server_update` | Legacy master server update helper | update args | status | Yes | Yes | legacy update flows | Administrative |
|
||||
| `stop_update` | Abort active update | `home_id` | `1` / error | Yes | Yes | update UI, `lib_remote.php::stop_update` | Mutates running install/update |
|
||||
| `component_update` | Update agent code from Git staging | encrypted JSON payload | structured hash | Yes | Yes | `administration/panel_update.php` | Admin-only; must preserve config and hosted server data |
|
||||
| `agent_restart` | Restart the agent service/process | marker arg | `1` / error | Yes | Yes | `server/restart.php` | Admin-only node control |
|
||||
|
||||
## Workshop And Server Content Commands
|
||||
|
||||
| Agent Command | Purpose | Key Arguments | Returns | Windows | Linux | Panel Callers | Security Notes |
|
||||
|---|---|---|---|---|---|---|---|
|
||||
| `steam_workshop` | Legacy direct Workshop installer | `home_id`, `mods_full_path`, `workshop_id`, `mods_list`, regex/config args, auth args, download args | `1`, `-1`, `-2`, `-3`, `-4` | Yes | Yes | legacy `steam_workshop` module and compatibility helpers | High-risk legacy surface; keep compatibility but prefer Server Content Manager |
|
||||
| `get_workshop_mods_info` | Enumerate installed Workshop mods | none / `mods_info` marker | status + mod list | Yes | Yes | Workshop UIs, compatibility views | Read-only |
|
||||
|
||||
Current preferred implementation path:
|
||||
|
||||
- `addonsmanager` stages a manifest and helper script through `writefile`
|
||||
- it executes the helper through `exec`
|
||||
- it uses `steam_workshop` only as legacy compatibility, not as the primary workflow
|
||||
|
||||
## Shell And System Commands
|
||||
|
||||
| Agent Command | Purpose | Key Arguments | Returns | Windows | Linux | Panel Callers | Security Notes |
|
||||
|---|---|---|---|---|---|---|---|
|
||||
| `exec` | Execute a constrained command and return output | `command` | base64 text output | Yes | Yes | status fallback, content helpers, provisioning, misc admin tools | Must never receive raw customer shell input |
|
||||
| `sudo_exec` | Execute privileged command | `command` | base64 text output | Yes | Yes | advanced admin tooling | Highest-risk command; admin-only |
|
||||
| `shell_action` | Structured shell action abstraction | `action`, `arguments` | array or text | Yes | Yes | newer advanced operations | Safer than raw shell when used correctly |
|
||||
| `rebootnow` | Reboot remote host | none | status | Yes | Yes | `server/reboot.php` | Node-level destructive action |
|
||||
| `what_os` | Return agent OS identifier | none | OS string | Yes | Yes | provisioning, workshop script selection, path handling | Read-only |
|
||||
| `discover_ips` | Return agent IP list | marker arg | CSV / array | Yes | Yes | server provisioning | Read-only |
|
||||
| `mon_stats` | Return agent monitoring stats | marker arg | base64 stats text | Yes | Yes | `server/mon_stats.php`, `status` | Read-only system metrics |
|
||||
|
||||
## FTP And Fast Download Commands
|
||||
|
||||
| Agent Command | Purpose | Key Arguments | Returns | Windows | Linux | Panel Callers | Security Notes |
|
||||
|---|---|---|---|---|---|---|---|
|
||||
| `ftp_mgr` | Manage FTP account state | `action`, `login`, `password`, `home_path` | text/status | Yes | Yes | `ftp/ftp_admin.php`, provisioning | Touches service credentials and user state |
|
||||
| `stop_fastdl` | Stop FastDL service | none | status | Yes | Yes | `fast_download` admin UI | Node service control |
|
||||
| `restart_fastdl` | Restart FastDL service | none | status | Yes | Yes | `fast_download` admin UI | Node service control |
|
||||
| `fastdl_status` | Check FastDL status | none | status | Yes | Yes | `fast_download` | Read-only |
|
||||
| `fastdl_get_aliases` | List FastDL aliases | none | alias list | Yes | Yes | `fast_download` | Read-only |
|
||||
| `fastdl_add_alias` | Add FastDL alias | alias args | status | Yes | Yes | `fast_download` | Writes service config |
|
||||
| `fastdl_del_alias` | Delete FastDL alias | alias list | status | Yes | Yes | `fast_download` | Writes service config |
|
||||
| `fastdl_get_info` | Return FastDL config info | none | info payload | Yes | Yes | `fast_download` | Read-only |
|
||||
| `fastdl_create_config` | Build FastDL config | bind/config args | status | Yes | Yes | `fast_download` | Writes service config |
|
||||
|
||||
## Scheduler Commands
|
||||
|
||||
| Agent Command | Purpose | Key Arguments | Returns | Windows | Linux | Panel Callers | Security Notes |
|
||||
|---|---|---|---|---|---|---|---|
|
||||
| `scheduler_add_task` | Add cron entry | `job` | status | Yes | Yes | `cron/cron.php`, `cron/user_cron.php` | Agent executes stored commands locally |
|
||||
| `scheduler_edit_task` | Modify cron entry | `job_id`, `job` | status | Yes | Yes | `cron/cron.php`, token refresh helpers | Same risks as add |
|
||||
| `scheduler_del_task` | Remove cron entry | `job_id` or comma list | status | Yes | Yes | `cron/cron.php`, cleanup helpers | Destructive |
|
||||
| `scheduler_list_tasks` | Return cron table | none | map of job IDs to cron lines | Yes | Yes | `cron/shared_cron_functions.php`, `cron/events.php` | Read-only |
|
||||
|
||||
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`
|
||||
|
||||
## Internal Agent Scheduler Actions
|
||||
|
||||
These are not XML-RPC command names, but they are part of the runtime architecture inside both agents:
|
||||
|
||||
- `scheduler_dispatcher`
|
||||
- `scheduler_server_action`
|
||||
- `scheduler_log_events`
|
||||
- `scheduler_read_tasks`
|
||||
- `scheduler_stop`
|
||||
|
||||
The built-in action names handled by the Panel-generated API URLs are:
|
||||
|
||||
- `start`
|
||||
- `stop`
|
||||
- `restart`
|
||||
- `steam_auto_update`
|
||||
- `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`
|
||||
|
||||
## Panel Wrapper Map
|
||||
|
||||
Primary wrapper file:
|
||||
|
||||
- `Panel/includes/lib_remote.php`
|
||||
|
||||
Notable wrapper methods:
|
||||
|
||||
| Wrapper Method | XML-RPC Command |
|
||||
|---|---|
|
||||
| `status_chk()` | `quick_chk` |
|
||||
| `remote_server_status()` | `server_status` |
|
||||
| `universal_start()` | `universal_start` |
|
||||
| `remote_stop_server()` | `stop_server` |
|
||||
| `remote_restart_server()` | `restart_server` |
|
||||
| `remote_send_rcon_command()` | `send_rcon_command` |
|
||||
| `remote_readfile()` | `readfile` |
|
||||
| `remote_writefile()` | `writefile` |
|
||||
| `remote_query()` | `remote_query` |
|
||||
| `scheduler_add_task()` | `scheduler_add_task` |
|
||||
| `scheduler_edit_task()` | `scheduler_edit_task` |
|
||||
| `scheduler_del_task()` | `scheduler_del_task` |
|
||||
| `scheduler_list_tasks()` | `scheduler_list_tasks` |
|
||||
| `component_update()` | `component_update` |
|
||||
| `steam_workshop()` | `steam_workshop` |
|
||||
|
||||
## Search Coverage Used For This Document
|
||||
|
||||
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/ogp_agent.pl`
|
||||
- `rg -n "public function .*\\(" Panel/includes/lib_remote.php`
|
||||
|
|
@ -2,7 +2,7 @@
|
|||
|
||||
## Status
|
||||
|
||||
Accepted, Phase 1 implementation started
|
||||
Accepted, Phase 1 implementation active
|
||||
|
||||
## Decision
|
||||
|
||||
|
|
@ -36,3 +36,17 @@ Phase 1 implements this decision by routing the user-facing Workshop install flo
|
|||
- Generic content installs under `{SERVER_ROOT}/workshop/{MOD_FOLDER}` by default.
|
||||
- DayZ/Arma-style installs default to `@<workshop_id>` folders and copy `.bikey` files into `keys` when present.
|
||||
- Startup parameter generation remains a later phase.
|
||||
- Game XML uses the canonical `workshop_support` block. The schema validates this block and no longer requires loose top-level Workshop tags.
|
||||
- The Panel helpers read `workshop_support` first, then tolerate older direct tags only as compatibility fallbacks.
|
||||
- Arma 3 Linux and Windows configs declare Workshop app ID `107410` through `workshop_support`.
|
||||
|
||||
## Validation
|
||||
|
||||
Current validation commands:
|
||||
|
||||
```bash
|
||||
php Panel/modules/addonsmanager/tests/workshop_helpers_test.php
|
||||
php Panel/modules/config_games/tests/validate_server_configs.php
|
||||
bash -n Panel/modules/addonsmanager/scripts/workshop/generic_steam_workshop_linux.sh
|
||||
bash -n Panel/modules/addonsmanager/scripts/workshop/generic_steam_workshop_windows_cygwin.sh
|
||||
```
|
||||
|
|
|
|||
|
|
@ -18,14 +18,19 @@ 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/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/`
|
||||
4. `docs/architecture/PANEL_AGENT_COMMANDS.md`
|
||||
5. `docs/architecture/MODULE_DEPENDENCIES.md`
|
||||
6. `docs/architecture/LIBRARY_REFERENCE.md`
|
||||
7. `docs/modules/MODULE_INDEX.md`
|
||||
8. `docs/modules/GAMEMANAGER.md`
|
||||
9. `docs/features/STATUS_SYSTEM.md`
|
||||
10. `docs/features/XML_SYSTEM.md`
|
||||
11. `docs/modules/SCHEDULER.md`
|
||||
12. `docs/features/SCHEDULER_ACTIONS.md`
|
||||
13. `docs/modules/SERVER_CONTENT_MANAGER.md`
|
||||
14. `docs/features/USER_API.md`
|
||||
15. `docs/decisions/`
|
||||
16. `docs/games/`
|
||||
|
||||
## Important Files By Topic
|
||||
|
||||
|
|
|
|||
103
docs/features/SCHEDULER_ACTIONS.md
Normal file
103
docs/features/SCHEDULER_ACTIONS.md
Normal 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
171
docs/features/USER_API.md
Normal 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`
|
||||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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
|
||||
```
|
||||
|
||||
|
|
|
|||
|
|
@ -61,6 +61,29 @@ Current default install paths:
|
|||
- Generic Steam Workshop content: `{SERVER_ROOT}/workshop/{MOD_FOLDER}`
|
||||
- DayZ / Arma strategy content: `{SERVER_ROOT}/{MOD_FOLDER}` for root `@<workshop_id>` folder compatibility
|
||||
|
||||
Game XML fallback should use the canonical `workshop_support` block:
|
||||
|
||||
```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 this block first and only tolerates old direct tags as an internal compatibility fallback.
|
||||
|
||||
SteamCMD requirements:
|
||||
|
||||
- Linux agents need SteamCMD available at the configured profile/template path, `STEAMCMD_PATH`, `/home/gameserver/steamcmd/steamcmd.sh`, or in `PATH`.
|
||||
|
|
@ -99,3 +122,14 @@ This module is the right place for:
|
|||
- install history
|
||||
|
||||
The old `steam_workshop` module should be treated as a deprecated compatibility layer, not the main future path.
|
||||
|
||||
## Validation
|
||||
|
||||
Relevant smoke tests:
|
||||
|
||||
```bash
|
||||
php Panel/modules/addonsmanager/tests/workshop_helpers_test.php
|
||||
php Panel/modules/config_games/tests/validate_server_configs.php
|
||||
```
|
||||
|
||||
`validate_server_configs.php` validates every XML file under `Panel/modules/config_games/server_configs/` against `schema_server_config.xml`.
|
||||
|
|
|
|||
|
|
@ -53,10 +53,33 @@ Game XML definitions, CLI parameter generation, mod definitions, and custom fiel
|
|||
|
||||
## Missing Functionality
|
||||
|
||||
- first-class workshop/content capability declarations
|
||||
- first-class scheduler capability declarations
|
||||
- richer docs metadata
|
||||
|
||||
## Workshop Capability Declarations
|
||||
|
||||
The XML schema now supports a first-class `workshop_support` block for Steam Workshop / Server Content Manager metadata. This is the only canonical XML format for Workshop-enabled game configs.
|
||||
|
||||
Key fields:
|
||||
|
||||
- `enabled`
|
||||
- `provider`
|
||||
- `steam_app_id`
|
||||
- `workshop_app_id`
|
||||
- `download_method`
|
||||
- `install_strategy`
|
||||
- `install_path`
|
||||
- `startup_param_format`
|
||||
- `mod_separator`
|
||||
- `mod_prefix`
|
||||
- `copy_keys`
|
||||
|
||||
Validate changes with:
|
||||
|
||||
```bash
|
||||
php Panel/modules/config_games/tests/validate_server_configs.php
|
||||
```
|
||||
|
||||
## Suggested Future Improvements
|
||||
|
||||
- extend XML capability model
|
||||
|
|
@ -66,4 +89,3 @@ Game XML definitions, CLI parameter generation, mod definitions, and custom fiel
|
|||
## Recommendation
|
||||
|
||||
- Keep / Improve
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue