GSP/Panel
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Agent update

Browse source
This commit is contained in:
Frank Harris 2026-06-06 11:41:17 -05:00
parent c195c0930b
commit cc5f7bb90c
16 changed files with 474 additions and 85 deletions
Download patch file Download diff file Expand all files Collapse all files

7
docs/agents/LINUX_AGENT.md
View file

@ -65,6 +65,12 @@ The status implementation should check:
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:
@ -106,4 +112,3 @@ The agent also maintains screen logs and helper scripts inside its runtime area.
- 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.

39
docs/agents/WINDOWS_AGENT.md
View file

@ -43,6 +43,42 @@ The session naming scheme also follows the OGP convention:
OGP_HOME_000000123
```
### Windows Startup Launcher
Relevant files:
- `Agent-Windows/Install/agent_start.bat`
- `Agent-Windows/Install/agent_start_cygwin.sh`
- `/OGP/Cfg/bash_prefs.cfg` on an installed node
The batch launcher must not assume that `bash` is in the Windows `PATH`. It explicitly checks:
- the Cygwin root beside the launcher
- `C:\cygwin64\bin\bash.exe`
- `C:\cygwin\bin\bash.exe`
The Cygwin-side helper performs the shell work:
1. enter `/OGP`
2. normalize CRLF to LF for `.pl`, `.pm`, `.sh`, and `.cfg` files under `/OGP`
3. source `/OGP/Cfg/bash_prefs.cfg`
4. optionally update only `Agent-Windows/ogp_agent.pl` from Forgejo when `agent_auto_update=1`
5. backup the current `/OGP/ogp_agent.pl`
6. validate the updated agent with `perl -c`
7. restore the backup if validation fails
8. launch `/OGP/ogp_agent.pl`
Default optional update source:
- repo: `http://forge.runlevelsystems.com/dev/GSP.git`
- branch: `Panel-unstable`
- source file: `Agent-Windows/ogp_agent.pl`
- target file: `/OGP/ogp_agent.pl`
Auto-update failure is non-fatal. Missing `git`, clone failure, missing source file, or failed validation should warn and continue with the current installed agent.
The Windows agent file does not use `DBI` at startup. If a Windows node reports `Can't locate DBI.pm` at line 48, it is a strong signal that a Linux agent file was copied onto the Windows node.
## Status Logic
Relevant functions:
@ -61,6 +97,8 @@ The status model should check:
The old `SERVER_STOPPED` file should not be the source of truth.
If the game port is listening but the managed screen session is not found, the agent reports `ONLINE` with a warning. This protects customers from false offline/unknown states when a process survives a screen/session mismatch or an older agent cannot report the session correctly.
## Logging
Relevant function:
@ -91,4 +129,3 @@ The Windows scheduler implementation should remain aligned with the Linux schedu
- Batch wrappers are often needed for Windows executables.
- Process cleanup must avoid killing unrelated processes that happen to share an executable name.
- The agent should continue to use `screen` where it already does so, to stay aligned with Linux behavior.

23
docs/architecture/API_REFERENCE.md
View file

@ -42,6 +42,7 @@ Panel module
| `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. |
@ -76,6 +77,25 @@ Return values differ by method, but common patterns are:
- `UNRESPONSIVE`
- `UNKNOWN`
The Panel Game Monitor has a defensive fallback path while the structured status system is still being hardened:
```text
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
@ -117,7 +137,7 @@ Panel log page
Agent
-> read screen log or console log
Panel
-> refresh textarea via AJAX
-> refresh dedicated preformatted log panel via AJAX
```
## Error Handling Notes
@ -126,4 +146,3 @@ Panel
- 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.

10
docs/features/LOGGING_SYSTEM.md
View file

@ -34,11 +34,17 @@ Important references:
## Log Viewer Layout
`Panel/modules/gamemanager/log.php` keeps the AJAX refresh behavior and renders the log in a large textarea:
`Panel/modules/gamemanager/log.php` and `Panel/modules/gamemanager/view_server_log.php` keep the AJAX refresh behavior and render the log in a large dedicated `<pre>` block:
- desktop height around `55vh`
- element: `#live-server-log.gsp-live-log-panel`
- desktop minimum height around `500px`, with `55vh` viewport height
- mobile height around `45vh`
- monospace font
- preserved line breaks
- vertical scrolling inside the log panel
- long-line overflow remains usable without shrinking the panel to one line
- AJAX refresh updates `textContent` only; it does not reload the whole page
The live viewer intentionally avoids `<textarea>` and the generic `.log` class, because inherited theme styles can make the output appear like a one-line input.
If a future route shows a one-line log again, inspect the actual rendered element first. The fix should be applied to the route that emits the element, not as a broad theme override.

19
docs/features/STATUS_SYSTEM.md
View file

@ -29,6 +29,23 @@ Panel display mapping:
LGSL/GameQ query failure is not enough to mark a server offline. Query success may add player/map/hostname metadata, but query failure should only show a small unavailable note when the agent says the server is otherwise active.
Current repaired Panel flow:
1. `Panel/modules/gamemanager/server_monitor.php` calls `get_agent_server_status`.
2. `get_agent_server_status` first asks for structured `remote_server_status` data when available.
3. If the structured response is missing or ambiguous, the Panel uses existing agent calls to check `is_screen_running`.
4. The Panel also asks the agent to test the configured game port with `ss` or `netstat`.
5. A confirmed managed session, process flag, or listening game port is enough to display `ONLINE`.
6. `UNKNOWN` is reserved for an unavailable or inconclusive agent status check.
The port fallback is deliberately cross-platform:
- Linux normally uses `ss -lntu`, then `netstat`.
- Cygwin/Windows normally uses `netstat -an`.
- The Panel-side fallback parses complete command output instead of assuming the listening address is always in the same column.
Agent behavior now treats a listening game port as `ONLINE` even if the managed screen/session cannot be found. The UI may still show the warning from `last_error`, but it must not show a false red/offline or gray/unknown state when the game port proves the server is running.
## Recommended State Model
| State | Meaning |
@ -50,6 +67,8 @@ The agent should check, in this order:
4. optional query/RCON port listening
5. optional query metadata
The Panel fallback does not replace a full agent-owned status model. It exists so existing running servers do not show false unknown/offline when the structured status RPC is missing, partial, or query metadata fails.
## Known Problems To Remember
- LGSL/GameQ may fail for supported games, blocked ports, or slow startups.

21
docs/modules/GAMEMANAGER.md
View file

@ -50,6 +50,8 @@ The current flow now points toward agent-truth status reporting via:
- `remote_server_status`
- `get_agent_server_status` in `home_handling_functions.php`
- `server_status_without_decrypt` in both agents
- fallback `is_screen_running` checks when structured status is unavailable or ambiguous
- fallback agent-side `ss`/`netstat` port listening checks through `exec`
Useful state labels:
@ -62,6 +64,21 @@ Useful state labels:
Query checks should remain optional metadata only.
Current Panel fallback behavior:
1. Try the structured `remote_server_status` response.
2. Check the managed screen/session with `is_screen_running`.
3. Check whether the configured game port is listening from the agent host using `ss` or `netstat`.
4. Treat a confirmed session, process, or game port as `ONLINE`.
5. Treat query failure as missing metadata only, not as offline or unknown.
6. Show `UNKNOWN` only when the Panel cannot complete a reliable agent status check.
Repair note:
- `Panel/modules/gamemanager/home_handling_functions.php` contains the status fallback.
- The port fallback intentionally parses full `ss`/`netstat` output instead of relying on one fixed field, because Cygwin and Linux output differ.
- The Windows and Linux agents report `ONLINE` when the configured game port is listening even if the managed screen/session is missing, with a warning in `last_error`.
## Game Monitor Display Rules
`Panel/modules/gamemanager/server_monitor.php` should display state from the agent status response, not from LGSL/GameQ query success alone.
@ -85,7 +102,9 @@ Relevant files:
The log view should be treated as live, AJAX-updated output rather than a full page reload workflow.
`log.php` now renders the live log as a large monospace textarea with viewport-based height, preserved line breaks, vertical scrolling, and mobile sizing.
`log.php` and `view_server_log.php` now render the live log as a dedicated `<pre id="live-server-log" class="gsp-live-log-panel">` block. They intentionally do not use the generic `log` class or a `textarea`, because theme styles can collapse textarea/log elements into one-line controls.
The live panel uses viewport-based height, preserved line breaks, vertical scrolling, long-line overflow handling, and mobile sizing.
## What This Module Depends On

8
docs/modules/UPDATE.md
View file

@ -36,6 +36,12 @@ Defaults:
- Panel Path: `/var/www/html/GSP/Panel`
- Backup Before Update: enabled
Important implementation note:
- `gsp_update_settings()` and `gsp_validate_update_settings()` are defined at top level in `Panel/modules/administration/panel_update.php`.
- These helpers must not be nested inside another function. A previous bad edit placed `gsp_update_settings()` inside `gsp_get_git_commit()`, which caused a fatal error when the update page called the helper before `gsp_get_git_commit()` had ever executed.
- If the update page throws `Call to undefined function gsp_update_settings()`, first verify the deployed `Panel/modules/administration/panel_update.php` matches the repository version and that this helper exists near the top of the file before `gsp_panel_update_section()` is called.
## Update Flow
1. Save or submit repository settings.
@ -52,7 +58,7 @@ Defaults:
Apache and SSL checks are diagnostics only. Missing SSL certificates do not block Panel updates.
The old repeated SSL vhost disable buttons are not part of the primary update page. Apache path repair remains available under Advanced Diagnostics.
The old repeated SSL vhost disable buttons are not part of the primary update page. Apache path repair remains available under Advanced Diagnostics, and SSL issues are shown as concise diagnostic warnings.
## Remaining Issues