Panel/docs/architecture/API_REFERENCE.md

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

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.
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.
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

The Panel Game Monitor has a defensive fallback path while the structured status system is still being hardened:

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

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.

Current compatibility behavior:

• 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.

Sequence Diagrams

Start

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

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

Panel log page
  -> get_log
Agent
  -> read screen log or console log
Panel
  -> refresh dedicated preformatted log panel 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.