133 lines
6.2 KiB
Markdown
133 lines
6.2 KiB
Markdown
# LOGAR Windows Edge Forwarder
|
|
|
|
Standalone compiled executable and installer distribution for Windows Server and workstation environments.
|
|
|
|
---
|
|
|
|
## Overview
|
|
`Win_Client.exe` is a self-contained executable that queries the Windows Application Event Log, filters candidate events at the source, auto-enrolls with the central LOGAR hub to receive signed mTLS certificates, and streams records over mutual TLS 1.3 (**mTLS**) socket connection.
|
|
|
|
### Key Capabilities
|
|
- **Pre-compiled & Dependency-Free**: Ships as a standalone native Windows executable (`Win_Client.exe`) or full installer (`LOGAR-Client-Setup.exe`). No Python installation, pip packages, or GnuPG binaries are required on the host.
|
|
- **Mutual TLS 1.3 (mTLS) Ingestion**: Streams directly over hardware-authenticated TLS 1.3 sockets with hardware/machine-bound client certificates.
|
|
- **Automated Client Enrollment**: On first run with an `enrollment_secret`, the client automatically calls `POST /api/client/enroll` on the hub, saves its certificates into `certs/`, and establishes secure mTLS streaming.
|
|
- **Proactive Expiry Check & Reactive Self-Healing**: Before each run, the client evaluates `client.crt` validity. If within 30 days of expiry, it automatically contacts the hub to renew certificates. If the server Root CA rotates or a TLS handshake error occurs, the client catch-heals by re-enrolling immediately and re-establishing connection without human intervention.
|
|
- **Source-Level Filtering**: Retains events spanning `INFO`, `WARNING`, and `ERROR`. Strips audit events and debug noise, skipping events older than 24 hours.
|
|
- **State Tracking & Deduplication**: Maintains persistent client state in `client_state.json` (tracking event record numbers and timestamp signatures) so every log record is forwarded exactly once without duplicates.
|
|
- **Fail-Safe State Commit**: State is committed only when the server returns a verified `success` response. In the event of a network outage, state remains unchanged and unsent events are retried automatically on the next run.
|
|
|
|
---
|
|
|
|
## 1. Automated Installation via Inno Setup (Recommended)
|
|
|
|
Run the self-contained installer built from `compilation/installer_client.iss`:
|
|
```powershell
|
|
.\LOGAR-Client-Setup.exe
|
|
```
|
|
This installer:
|
|
1. Installs `Win_Client.exe` and bundled `nssm.exe` to `C:\Program Files\LOGAR\`.
|
|
2. Sets up directory permissions in `C:\ProgramData\LOGAR\`.
|
|
3. Registers and starts the `LOGAR_Client` Windows service automatically via NSSM.
|
|
4. Redirects stdout and stderr logs to `C:\ProgramData\LOGAR\client.log` and `client_err.log`.
|
|
|
|
---
|
|
|
|
## 2. Generating & Deploying the Configuration File
|
|
|
|
### Step 1: Generate `client_config.json` on the Server
|
|
Run the following command on your central LOGAR server:
|
|
```bash
|
|
python src/Server.py --create-client-config --server-host <SERVER_IP_OR_DNS> --server-port 9443 --client-out client_config.json
|
|
```
|
|
- Replace `<SERVER_IP_OR_DNS>` with the reachable IP address or FQDN of your central LOGAR server hub.
|
|
- Default mTLS socket port is `9443`; Hermes REST API port is `8443`.
|
|
|
|
### Step 2: Configuration Structure
|
|
The generated `client_config.json` contains:
|
|
```json
|
|
{
|
|
"server_host": "192.168.1.100",
|
|
"server_port": 9443,
|
|
"hermes_host": "192.168.1.100",
|
|
"hermes_port": 8443,
|
|
"enrollment_secret": "a1b2c3d4e5f6...",
|
|
"cert_dir": "certs",
|
|
"server_fingerprint": "375388960531264EA0648EC0D2C4E4ABC6F22AC2",
|
|
"server_public_key": "-----BEGIN PGP PUBLIC KEY BLOCK-----\n...",
|
|
"auth_token": "a1b2c3d4e5f6..."
|
|
}
|
|
```
|
|
|
|
> [!NOTE]
|
|
> The configuration contains **no host-specific names or site names** to ensure client anonymity and easy redistribution.
|
|
|
|
### Step 3: Copy to Edge Node
|
|
Place `client_config.json` next to `Win_Client.exe` (e.g. `C:\Program Files\LOGAR\` or `C:\LOGAR\`):
|
|
```powershell
|
|
New-Item -ItemType Directory -Path "C:\LOGAR" -Force
|
|
Copy-Item "Win_Client.exe", "client_config.json" -Destination "C:\LOGAR\"
|
|
```
|
|
|
|
---
|
|
|
|
## 3. Running Manually
|
|
|
|
Test the forwarder interactively from PowerShell or Command Prompt:
|
|
```powershell
|
|
cd C:\LOGAR
|
|
.\Win_Client.exe --hours 24
|
|
```
|
|
On first run, the client contacts `http://<hermes_host>:<hermes_port>/api/client/enroll`, downloads `ca.crt`, `client.crt`, and `client.key` into `certs/`, and streams logs over mTLS.
|
|
|
|
### Command-Line Arguments
|
|
| Argument | Default | Description |
|
|
| :--- | :--- | :--- |
|
|
| `--config` | `client_config.json` | Path to client configuration file |
|
|
| `--hours` | `24` | Lookback window in hours for event logs |
|
|
| `--state-file` | `client_state.json` | Path to persistent state tracking file |
|
|
| `--no-state` | `False` | Disable state tracking and send all events matching lookback window |
|
|
|
|
---
|
|
|
|
## 4. Manual Service Installation (NSSM or Scheduled Task)
|
|
|
|
### Method A: Windows Service via Bundled NSSM
|
|
```powershell
|
|
# From the compilation directory or with bundled nssm.exe:
|
|
.\nssm.exe install LOGAR_Client "C:\LOGAR\Win_Client.exe" "--hours 24"
|
|
.\nssm.exe set LOGAR_Client AppDirectory "C:\LOGAR"
|
|
.\nssm.exe set LOGAR_Client AppStdout "C:\ProgramData\LOGAR\client.log"
|
|
.\nssm.exe set LOGAR_Client AppStderr "C:\ProgramData\LOGAR\client_err.log"
|
|
.\nssm.exe start LOGAR_Client
|
|
```
|
|
|
|
### Method B: Windows Scheduled Task via PowerShell
|
|
```powershell
|
|
$Action = New-ScheduledTaskAction -Execute "C:\LOGAR\Win_Client.exe" -Argument "--hours 24" -WorkingDirectory "C:\LOGAR"
|
|
$Trigger = New-ScheduledTaskTrigger -Once -At (Get-Date) -RepetitionInterval (New-TimeSpan -Hours 3)
|
|
$Settings = New-ScheduledTaskSettingsSet -AllowStartIfOnBatteries -DontStopIfGoingOnBatteries -StartWhenAvailable -ExecutionTimeLimit (New-TimeSpan -Minutes 15)
|
|
|
|
Register-ScheduledTask -TaskName "LOGAR_Forwarder" `
|
|
-Action $Action `
|
|
-Trigger $Trigger `
|
|
-Settings $Settings `
|
|
-User "NT AUTHORITY\SYSTEM" `
|
|
-RunLevel Highest `
|
|
-Description "LOGAR Windows Edge Log Forwarder Service"
|
|
|
|
Start-ScheduledTask -TaskName "LOGAR_Forwarder"
|
|
```
|
|
|
|
---
|
|
|
|
## 5. Uninstallation
|
|
|
|
If installed via the Inno Setup installer, use **Windows Add/Remove Programs** or run `unins000.exe` in `C:\Program Files\LOGAR\`.
|
|
|
|
If installed manually via NSSM:
|
|
```powershell
|
|
.\nssm.exe stop LOGAR_Client
|
|
.\nssm.exe remove LOGAR_Client confirm
|
|
Remove-Item -Recurse -Force "C:\LOGAR"
|
|
```
|