Panel/docs/agents/WINDOWS_AGENT.md

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:

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.

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.

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.