Panel/docs/agents/LINUX_AGENT.md

Linux Agent

Role

Agent_Linux/ogp_agent.pl is the Linux execution agent for GSP. It is responsible for:

• starting and stopping game servers
• managing screen sessions
• reading logs
• running update/install tasks
• handling scheduler jobs
• performing query checks and status checks

Important Files

• Agent_Linux/ogp_agent.pl
• Agent_Linux/startups/
• Agent_Linux/includes/
• Agent_Linux/php-query/
• Agent_Linux/Cfg/
• Agent_Linux/Schedule/
• Agent_Linux/steamcmd/
• Agent_Linux/systemd/

Startup Logic

The Linux agent creates a managed screen session per server.

Key flow in ogp_agent.pl:

• universal_start_without_decrypt
• create_screen_cmd
• create_screen_cmd_loop
• replace_OGP_Env_Vars

The agent builds the startup command from:

• the game XML template
• server parameters
• mod data
• control password
• path variables

The session name follows the OGP naming convention, for example:

OGP_HOME_000000123

Status Logic

Relevant functions:

• is_screen_running_without_decrypt
• get_screen_pid_without_decrypt
• server_status_without_decrypt
• verify_server_stopped_without_decrypt

The status implementation should check:

• screen/session existence
• PID or child process information when available
• whether the game port is listening
• whether query metadata can be fetched

Marker files such as SERVER_STOPPED should not be treated as the final source of truth.

Logging

Relevant function:

• get_log

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.

Scheduler

Linux scheduler functions live in ogp_agent.pl:

• scheduler_dispatcher
• scheduler_server_action
• scheduler_log_events
• scheduler_add_task
• scheduler_del_task
• scheduler_edit_task
• scheduler_read_tasks
• scheduler_stop
• scheduler_list_tasks

The scheduler is agent-driven. Panel pages create or edit jobs, but the agent executes them.

Configuration Files

Useful configuration and runtime areas:

• Agent_Linux/Cfg/
• Agent_Linux/startups/
• Agent_Linux/steamcmd/
• Agent_Linux/systemd/

The agent also maintains screen logs and helper scripts inside its runtime area.

Linux-Specific Notes

• The Linux agent uses screen and sudo_exec_without_decrypt.
• It can resolve server ownership and screen users via helper functions such as find_user_by_screen_id.
• It must remain portable across distro variants, so avoid assuming one exact init system or one exact binary path.
• For Windows-targeted games running under Linux, Wine-related path conversion appears in startup path handling.