52 lines
1.9 KiB
Markdown
52 lines
1.9 KiB
Markdown
# Linux Agent Activity Events
|
|
|
|
The Linux agent can report meaningful server lifecycle events to the GSP Panel activity log. It does not send routine XML-RPC chatter, file reads, status polls with no state change, or every local agent log line.
|
|
|
|
## Configuration
|
|
|
|
Set these values in `Cfg/Config.pm`:
|
|
|
|
```perl
|
|
agent_event_url => 'https://panel.example.com/agent_event_receiver.php',
|
|
remote_server_id => '1',
|
|
```
|
|
|
|
If `agent_event_url` is empty, the agent attempts to derive it from `web_api_url`. The `key` value must match the Panel remote server encryption key because it is used to sign event payloads.
|
|
|
|
## Authentication
|
|
|
|
Events are JSON POST requests signed with HMAC-SHA256:
|
|
|
|
- `X-GSP-Agent-Id`: Panel `remote_server_id`
|
|
- `X-GSP-Agent-Timestamp`: Unix timestamp
|
|
- `X-GSP-Agent-Signature`: `sha256=` plus HMAC of `timestamp.body`
|
|
|
|
The Panel validates the signature, remote server identity, event type, severity, and `home_id` ownership before writing the activity log.
|
|
|
|
## Offline Queue
|
|
|
|
If the Panel is unavailable, the Linux agent appends events to:
|
|
|
|
```text
|
|
events/pending-events.jsonl
|
|
```
|
|
|
|
The queue is retried after later successful event deliveries and rotates when it exceeds 1 MB. Server start, stop, and restart operations do not wait on Panel event delivery.
|
|
|
|
## Lifecycle Detection
|
|
|
|
The agent uses existing runtime evidence:
|
|
|
|
- screen/session status
|
|
- tracked PID metadata
|
|
- process existence
|
|
- required game/query/RCON port validation
|
|
- short-lived status hints such as `STARTING`, `STOPPING`, and `STOPPED`
|
|
|
|
It does not create or read `SERVER_STOPPED` marker files.
|
|
|
|
## Reported Events
|
|
|
|
The Linux agent reports confirmed start and stop outcomes, unresponsive process states, missing/restored port transitions, unexpected `ONLINE -> OFFLINE` transitions, and scheduled restart sequences when the scheduler invokes restart actions.
|
|
|
|
External kills, including a companion bot terminating a server process, are recorded after status polling observes the validated state change.
|