docs(win_client): update README.md with mTLS 1.3, dynamic PKI enrollment, and Inno Setup installer instructions
This commit is contained in:
+48
-44
@@ -1,40 +1,56 @@
|
||||
# LOGAR Windows Edge Forwarder
|
||||
|
||||
Standalone compiled executable distribution for Windows Server and workstation environments.
|
||||
Standalone compiled executable and installer distribution for Windows Server and workstation environments.
|
||||
|
||||
---
|
||||
|
||||
## Overview
|
||||
`Win_Client.exe` is a self-contained, pre-compiled executable that queries the Windows Application Event Log, filters candidate events at the source, encrypts the payload using OpenPGP, and streams records over an authenticated TCP socket to the central LOGAR hub.
|
||||
`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`). No Python installation, pip packages, or GnuPG binaries are required on the host.
|
||||
- **Source-Level Filtering**: Retains events spanning `INFO`, `WARNING`, and `ERROR`. Strips audit success/failure events and debug noise, skipping events older than 24 hours.
|
||||
- **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.
|
||||
- **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.
|
||||
- **End-to-End Encryption**: Encrypts payloads using the server's OpenPGP public key before transmission.
|
||||
|
||||
---
|
||||
|
||||
## 1. Generating & Deploying the Configuration File
|
||||
## 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 to export a client bundle tailored for your environment:
|
||||
|
||||
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 TCP port is `9443`.
|
||||
- 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..."
|
||||
@@ -42,11 +58,10 @@ The generated `client_config.json` contains:
|
||||
```
|
||||
|
||||
> [!NOTE]
|
||||
> A reference example is provided in `client_config.sample.json`. The configuration file contains **no host-specific names or site names** to ensure client anonymity and easy redistribution.
|
||||
> The configuration contains **no host-specific names or site names** to ensure client anonymity and easy redistribution.
|
||||
|
||||
### Step 3: Copy to Edge Node
|
||||
Place `Win_Client.exe` and `client_config.json` in the target directory (recommended: `C:\LOGAR\`):
|
||||
|
||||
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\"
|
||||
@@ -54,14 +69,14 @@ Copy-Item "Win_Client.exe", "client_config.json" -Destination "C:\LOGAR\"
|
||||
|
||||
---
|
||||
|
||||
## 2. Running Manually
|
||||
## 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 |
|
||||
@@ -73,22 +88,24 @@ cd C:\LOGAR
|
||||
|
||||
---
|
||||
|
||||
## 3. Installing as a Background Service / Scheduled Task
|
||||
|
||||
Edge forwarders run as episodic background processes (run, forward unsent candidate records, commit state, and terminate). On Windows, this is natively managed via Windows Task Scheduler running as a background service under `SYSTEM`.
|
||||
|
||||
### Method A: Windows Scheduled Task via PowerShell (Recommended)
|
||||
Open an **Elevated PowerShell (Run as Administrator)** window and execute:
|
||||
## 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
|
||||
# Define action and periodic trigger (every 3 hours indefinitely)
|
||||
$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)
|
||||
|
||||
# Configure task settings (wake on sleep, start when ready, run hidden)
|
||||
$Settings = New-ScheduledTaskSettingsSet -AllowStartIfOnBatteries -DontStopIfGoingOnBatteries -StartWhenAvailable -ExecutionTimeLimit (New-TimeSpan -Minutes 15)
|
||||
|
||||
# Register task running under the local SYSTEM account with highest privileges
|
||||
Register-ScheduledTask -TaskName "LOGAR_Forwarder" `
|
||||
-Action $Action `
|
||||
-Trigger $Trigger `
|
||||
@@ -97,31 +114,18 @@ Register-ScheduledTask -TaskName "LOGAR_Forwarder" `
|
||||
-RunLevel Highest `
|
||||
-Description "LOGAR Windows Edge Log Forwarder Service"
|
||||
|
||||
# Verify task creation and trigger immediate execution
|
||||
Start-ScheduledTask -TaskName "LOGAR_Forwarder"
|
||||
Get-ScheduledTask -TaskName "LOGAR_Forwarder"
|
||||
```
|
||||
|
||||
### Method B: Continuous Windows Service via NSSM
|
||||
If your organizational policy requires a formal Windows Service listed under `services.msc`:
|
||||
|
||||
1. Download [NSSM (Non-Sucking Service Manager)](https://nssm.cc/).
|
||||
2. Install the service using NSSM:
|
||||
```cmd
|
||||
nssm.exe install LOGAR_Forwarder "C:\LOGAR\Win_Client.exe" "--hours 24"
|
||||
nssm.exe set LOGAR_Forwarder AppDirectory "C:\LOGAR"
|
||||
nssm.exe set LOGAR_Forwarder AppRestartDelay 10800000
|
||||
nssm.exe start LOGAR_Forwarder
|
||||
```
|
||||
*(Note: `AppRestartDelay 10800000` pauses 3 hours between execution cycles).*
|
||||
|
||||
---
|
||||
|
||||
## 4. Uninstallation & Removal
|
||||
## 5. Uninstallation
|
||||
|
||||
To remove the scheduled task:
|
||||
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
|
||||
Unregister-ScheduledTask -TaskName "LOGAR_Forwarder" -Confirm:$false
|
||||
.\nssm.exe stop LOGAR_Client
|
||||
.\nssm.exe remove LOGAR_Client confirm
|
||||
Remove-Item -Recurse -Force "C:\LOGAR"
|
||||
```
|
||||
|
||||
Reference in New Issue
Block a user