doc changes and reference folder
This commit is contained in:
parent
11691a5876
commit
82cbc206eb
33 changed files with 1514 additions and 2855 deletions
|
|
@ -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`
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue