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