132 lines
4.4 KiB
Markdown
132 lines
4.4 KiB
Markdown
# 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:
|
|
|
|
```text
|
|
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.
|
|
|
|
If the configured game port is listening but the managed screen/session is missing, the agent reports `ONLINE` with a warning in `last_error`. This mirrors the Windows agent and prevents a live game process from showing false offline/unknown solely because session tracking failed.
|
|
|
|
## Optional Resource Stats Database
|
|
|
|
Resource stats database submission uses Perl `DBI`, but `DBI` is optional for normal agent startup. The agent lazy-loads `DBI` only when resource stats are actually submitted. Missing `DBI.pm` should disable database stats submission with a readable log message, not abort the agent at startup.
|
|
|
|
## 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.
|
|
|
|
## Remote Git Self-Update
|
|
|
|
The Linux agent exposes the admin-only `component_update` XML-RPC method. The Panel update page uses this to queue a Git-based Linux agent update.
|
|
|
|
Flow:
|
|
|
|
1. Panel sends an encrypted payload containing repo URL, branch, source folder, optional Git path, optional backup path, and optional admin post-update command.
|
|
2. Agent validates the payload.
|
|
3. Agent writes `gsp_component_update_<timestamp>.sh` under the agent run directory.
|
|
4. The updater script runs detached in `screen`.
|
|
5. The script clones the configured branch into staging.
|
|
6. It copies only the configured Linux agent source folder, usually `Agent_Linux`.
|
|
7. It preserves `Cfg/`, `ServerFiles/`, `Schedule/`, logs, screen logs, `steamcmd/`, `startups/`, temporary folders, backups, and PID files.
|
|
8. It validates the updated `ogp_agent.pl` with `perl -c`.
|
|
9. It restarts `ogp_agent.service` through `systemd` if available, otherwise uses the existing `screen` startup fallback.
|
|
|
|
The agent returns `queued` immediately with the log path `gsp_component_update.log`. A queued response means the updater launched; check the log for final success/failure.
|
|
|
|
## 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.
|