# Windows Agent ## Role `Agent-Windows/ogp_agent.pl` is the Windows/Cygwin execution agent for GSP. It mirrors the Linux agent as closely as practical, while using Windows-compatible paths, processes, and wrappers. ## Important Files - `Agent-Windows/ogp_agent.pl` - `Agent-Windows/php-query/` - `Agent-Windows/ArmaBE/` - `Agent-Windows/Cfg/` - `Agent-Windows/Install/` - `Agent-Windows/ServerFiles/` - `Agent-Windows/Schedule/` ## Cygwin Requirements The Windows agent assumes a Cygwin-style environment that can provide: - `screen` - Perl - shell utilities such as `ps`, `grep`, `cut`, `awk`, `sed` - `cygpath` - a usable `bash` The goal is to keep the Windows agent behavior close to the Linux agent so the Panel does not need separate semantics for basic lifecycle operations. ## Startup Logic Relevant functions: - `universal_start_without_decrypt` - `create_screen_cmd` - `create_screen_cmd_loop` - `replace_OGP_Env_Vars` The Windows agent also uses `screen` sessions for managed server execution. Depending on the game and binary type, it may wrap commands in `cmd /Q /C start` or run a batch file wrapper. The session naming scheme also follows the OGP convention: ```text 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: - `is_screen_running_without_decrypt` - `get_screen_pid_without_decrypt` - `server_status_without_decrypt` - `verify_server_stopped_without_decrypt` The status model should check: - screen/session existence - process/PID information when available - game port listening - optional query metadata 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: - `get_log` Windows/Cygwin logs come from screen logs and/or local copies. Log retrieval should remain compatible with the Panel's AJAX log view. ## Workshop / Server Content The primary Workshop workflow is owned by the Panel `addonsmanager`, not the legacy `steam_workshop` RPC. For Windows/Cygwin servers the Panel: 1. writes `gsp_server_content/workshop_manifest.json` under the server home 2. stages `generic_steam_workshop_windows_cygwin.sh` under `gsp_server_content/scripts/workshop/` 3. invokes the staged script through the authenticated `exec` RPC The staged script uses Python and SteamCMD, validates numeric Workshop IDs, keeps writes under the server home, logs to `gsp_server_content/workshop_install_windows.log`, and supports DayZ/Arma-style `@mod` folders plus `.bikey` copying. The older `steam_workshop` XML-RPC method remains for legacy compatibility only and should not be treated as the primary customer workflow. ## Scheduler Relevant functions: - `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 Windows scheduler implementation should remain aligned with the Linux scheduler implementation so the Panel can treat both the same way. ## Remote Git Self-Update The Windows agent exposes the same admin-only `component_update` XML-RPC method as the Linux agent. In this repository the Windows agent is explicitly Cygwin-based, so the first implementation uses a Cygwin-compatible detached shell updater rather than a separate native PowerShell service wrapper. Flow: 1. Panel sends an encrypted payload containing repo URL, branch, Windows agent source folder, optional Git path, optional backup path, and optional admin post-update command. 2. Agent validates the request and writes `gsp_component_update_.sh` under the current agent run directory, usually `/OGP`. 3. The updater runs detached in `screen`. 4. The updater clones the configured branch into staging. 5. It copies only the configured Windows agent source folder, usually `Agent-Windows`. 6. It preserves `Cfg/`, `ServerFiles/`, `Schedule/`, logs, screen logs, `steamcmd/`, `startups/`, temporary folders, backups, and PID files. 7. It validates `ogp_agent.pl` with `perl -c`. 8. It restarts the agent using the existing Cygwin/screen fallback. The immediate response is `queued` with the agent-side log path `gsp_component_update.log`. ## Windows-Specific Notes - Path conversion between Cygwin and native Windows paths matters during startup. - 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.