Panel/docs/architecture/PANEL_AGENT_COMMANDS.md

Panel-Agent Commands

Workspace reference: GSP-WORKSPACE.md

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/OGP64/OGP/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/OGP64/OGP/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 generated per-job script through writefile
• the generated script creates a temporary SteamCMD runscript and runs steamcmd +runscript
• it executes the generated job script through exec
• it records per-server items and policies in Panel database tables
• it uses steam_workshop only as legacy compatibility, not as the primary workflow
• no new Workshop-specific business logic should be added to agents for the current design

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
• workshop_update
• workshop_update_and_restart
• workshop_download_only
• workshop_install_pending_on_restart

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/OGP64/OGP/ogp_agent.pl
• rg -n "public function .*\\(" Panel/includes/lib_remote.php