Update README.md to document out/linux_server and out/win_server deployment packages

Add Windows server deployment guide and sample configuration to out/win_server
Add Linux server deployment guide and sample configuration to out/linux_server
2026-09-04 16:05:04 +02:00 · 2026-09-04 16:04:51 +02:00 · 2026-09-04 16:04:20 +02:00
5 changed files with 486 additions and 7 deletions
@@ -195,13 +195,19 @@ LOGAR/
 ├── README.md                       # Comprehensive documentation
 ├── RELEASE_NOTES.md                # Release history and changelog
 ├── server_config.sample.json       # Central server sample configuration
-└── out/                            # Edge forwarder deployment packages
+└── out/                            # Standalone deployment documentation & sample configs
-    ├── win_client/
+    ├── linux_server/
-    │   ├── client_config.sample.json # Reference client configuration
+    │   ├── README.md               # Linux systemd service installation & hub guide
-    │   └── README.md               # Windows service installation & configuration guide
+    │   └── server_config.sample.json # Reference server configuration
-    └── linux_client/
+    ├── win_server/
-        ├── client_config.sample.json # Reference client configuration
+    │   ├── README.md               # Windows service (NSSM/Task Scheduler) installation guide
-        └── README.md               # Linux service installation & configuration guide
+    │   └── server_config.sample.json # Reference server configuration
    ├── linux_client/
    │   ├── README.md               # Linux service & timer installation guide
    │   └── client_config.sample.json # Reference client configuration
    └── win_client/
        ├── README.md               # Windows service installation & configuration guide
        └── client_config.sample.json # Reference client configuration
 ```
 ---
@@ -0,0 +1,208 @@
 # LOGAR Linux Server Hub
 Standalone compiled executable binary distribution for Linux server environments (`Server.bin`).
 ---
 ## Overview
 `Server.bin` is a self-contained, pre-compiled Linux ELF executable that operates as the central coordination and log analysis hub of the LOGAR telemetry architecture.
 ### Key Architecture & Capabilities
 - **Pre-compiled & Dependency-Free**: Ships as a standalone native Linux ELF binary (`Server.bin`). No Python runtime, pip dependencies, or GnuPG binaries are required on the host system.
 - **Authenticated TCP Ingestion Socket (Port 9443)**: Accepts framed OpenPGP encrypted log batches streamed by edge forwarders (`Linux_Client.bin` and `Win_Client.exe`).
 - **4-Run Temporal Persistence Rule**: Ingested candidate error signatures are evaluated against an episodic threshold. An anomaly must occur across at least 4 distinct client transmission cycles within a sliding 12-hour evaluation window before promotion from transient noise to a `VERIFIED` anomaly.
 - **Embedded Hermes Reporting API (Port 8443)**: Integrated REST API exposing `/api/hermes/report` for external scrapers, SIEM collectors, and alerting dashboards.
 - **Pure-Python OpenPGP Cryptography**: Zero dependency on external `gpg` binaries. Automatically generates RSA-2048 encryption keys and SHA-256 fingerprints on first launch.
 - **State Database**: Tracks anomaly lifecycles, run counters, and machine telemetry in a local SQLite state database (`logar_state.db`).
 ---
 ## 1. Initializing & Generating Server Configuration
 ### Step 1: Automatic First-Run Generation
 When launched without an existing `server_config.json`, `Server.bin` automatically generates:
 1. A fresh OpenPGP RSA-2048 encryption keypair (`private_key` and `public_key`).
 2. A SHA-256 public encryption fingerprint (`server_fingerprint`).
 3. A cryptographically random secret authentication token (`auth_token`).
 4. Default network socket coordinates (TCP 9443, Hermes API 8443).
 Run `Server.bin` once to initialize:
 ```bash
 ./Server.bin
 ```
 Output:
 ```
 [!] Config 'server_config.json' not found. Initializing first-run configuration...
 [+] Successfully generated new server config and OpenPGP keypair.
 [+] Server Encryption Fingerprint: 375388960531264EA0648EC0D2C4E4ABC6F22AC2
 [+] Saved to: server_config.json
 ```
 ### Step 2: Configuration Fields Reference
 The generated `server_config.json` contains:
 ```json
 {
  "server_name": "LOGAR-Linux-Hub",
  "tcp_host": "0.0.0.0",
  "tcp_port": 9443,
  "hermes_host": "0.0.0.0",
  "hermes_port": 8443,
  "auth_token": "a1b2c3d4e5f67890abcdef1234567890...",
  "db_path": "logar_state.db",
  "evaluation_window_hours": 12,
  "min_persistence_runs": 4,
  "server_fingerprint": "375388960531264EA0648EC0D2C4E4ABC6F22AC2",
  "public_key": "-----BEGIN PGP PUBLIC KEY BLOCK-----\n...",
  "private_key": "-----BEGIN PGP PRIVATE KEY BLOCK-----\n..."
 }
 ```
 | Parameter | Default | Description |
 | :--- | :--- | :--- |
 | `server_name` | `"LOGAR-Linux-Hub"` | Human-readable identifier for this hub instance |
 | `tcp_host` | `"0.0.0.0"` | Network interface to bind for edge client TCP ingestion |
 | `tcp_port` | `9443` | TCP port for incoming edge log batches |
 | `hermes_host` | `"0.0.0.0"` | Network interface to bind for Hermes HTTP API |
 | `hermes_port` | `8443` | HTTP port for the Hermes reporting endpoint |
 | `auth_token` | *(auto-generated)* | Pre-shared secret required in edge client envelopes |
 | `db_path` | `"logar_state.db"` | Path to persistent SQLite issue database |
 | `evaluation_window_hours` | `12` | Sliding temporal window for 4-run rule persistence |
 | `min_persistence_runs` | `4` | Number of distinct runs required to promote to `VERIFIED` |
 ---
 ## 2. Generating Client Configuration Bundles
 Edge forwarders (`Linux_Client.bin` and `Win_Client.exe`) require a minimal, anonymous configuration bundle containing socket coordinates, the authentication token, and the server's public key (without sensitive server names or private keys).
 Run the following command on the server:
 ```bash
 ./Server.bin --create-client-config --server-host <SERVER_PUBLIC_OR_INTERNAL_IP> --server-port 9443 --client-out client_config.json
 ```
 - Replace `<SERVER_PUBLIC_OR_INTERNAL_IP>` with the reachable IP or FQDN of your LOGAR server.
 - The output `client_config.json` can be distributed directly to Linux and Windows edge forwarder nodes.
 ---
 ## 3. Running Interactively
 ```bash
 ./Server.bin --config /path/to/server_config.json
 ```
 ### Command-Line Arguments
 | Argument | Description |
 | :--- | :--- |
 | `--config` | Path to server configuration JSON file (default: `server_config.json`) |
 | `--create-client-config` | Exports an anonymous client configuration bundle and exits |
 | `--server-host` | Hostname/IP to embed in the exported client configuration |
 | `--server-port` | Port to embed in the exported client configuration (default: `9443`) |
 | `--client-out` | Destination path for exported client configuration (default: `client_config.json`) |
 ---
 ## 4. Installing as a Systemd Service (Recommended)
 Running `Server.bin` as a native systemd background service ensures continuous execution, automatic restart upon reboot or crash, and centralized log management via `journalctl`.
 ### Step 1: Create Deployment Directory and User
 ```bash
 # Create dedicated system group and user
 sudo useradd --system --no-create-home --shell /usr/sbin/nologin logar
 # Prepare deployment folder
 sudo mkdir -p /opt/logar-server
 sudo cp Server.bin server_config.json /opt/logar-server/
 sudo chmod +x /opt/logar-server/Server.bin
 sudo chown -R logar:logar /opt/logar-server
 ```
 ### Step 2: Create Systemd Service File
 Create `/etc/systemd/system/logar-server.service`:
 ```ini
 [Unit]
 Description=LOGAR Central Server Hub Service
 After=network-online.target
 Wants=network-online.target
 [Service]
 Type=simple
 User=logar
 Group=logar
 WorkingDirectory=/opt/logar-server
 ExecStart=/opt/logar-server/Server.bin --config /opt/logar-server/server_config.json
 Restart=always
 RestartSec=5
 LimitNOFILE=65536
 StandardOutput=journal
 StandardError=journal
 [Install]
 WantedBy=multi-user.target
 ```
 ### Step 3: Enable and Start Service
 ```bash
 sudo systemctl daemon-reload
 sudo systemctl enable --now logar-server.service
 ```
 ### Step 4: Verify Status and Inspect Logs
 ```bash
 # Check service status
 sudo systemctl status logar-server.service
 # Stream live server logs
 sudo journalctl -u logar-server.service -f
 ```
 ---
 ## 5. Hermes Reporting API & Integration
 The server embeds a high-performance HTTP service on port `8443` providing real-time intelligence on promoted anomalies:
 ### Fetching Promoted Anomalies
 ```bash
 curl -s http://127.0.0.1:8443/api/hermes/report | jq .
 ```
 ### Response Schema:
 ```json
 [
  {
    "fingerprint": "prod-web-01.corp.internal:Out_Of_Memory",
    "server": "prod-web-01.corp.internal",
    "signature": "Out_Of_Memory",
    "consecutive_runs": 4,
    "first_seen": "2026-09-04T08:00:00Z",
    "last_seen": "2026-09-04T14:30:00Z",
    "status": "VERIFIED",
    "verified": true,
    "os_type": "linux",
    "sample_message": "kernel: Out of memory: Kill process 1824"
  }
 ]
 ```
 ---
 ## 6. Firewall Configuration
 Ensure the following inbound ports are open on your host firewall:
 ```bash
 # UFW (Ubuntu / Debian)
 sudo ufw allow 9443/tcp comment "LOGAR TCP Log Ingestion"
 sudo ufw allow 8443/tcp comment "LOGAR Hermes Reporting API"
 sudo ufw reload
 # Firewalld (RHEL / CentOS / Rocky / Alma)
 sudo firewall-cmd --permanent --add-port=9443/tcp
 sudo firewall-cmd --permanent --add-port=8443/tcp
 sudo firewall-cmd --reload
 ```
@@ -0,0 +1,14 @@
 {
  "server_name": "LOGAR-Linux-Hub",
  "tcp_host": "0.0.0.0",
  "tcp_port": 9443,
  "hermes_host": "0.0.0.0",
  "hermes_port": 8443,
  "auth_token": "replace_with_secure_random_hex_token",
  "db_path": "logar_state.db",
  "evaluation_window_hours": 12,
  "min_persistence_runs": 4,
  "server_fingerprint": "AUTO_GENERATED_ON_FIRST_RUN",
  "public_key": "AUTO_GENERATED_ON_FIRST_RUN",
  "private_key": "AUTO_GENERATED_ON_FIRST_RUN"
 }
@@ -0,0 +1,237 @@
 # LOGAR Windows Server Hub
 Standalone compiled executable distribution for Windows Server environments (`Server.exe`).
 ---
 ## Overview
 `Server.exe` is a self-contained, pre-compiled native Windows PE executable that serves as the central log aggregation, temporal persistence analyzer, and reporting hub of the LOGAR infrastructure.
 ### Key Architecture & Capabilities
 - **Pre-compiled & Dependency-Free**: Ships as a standalone Windows executable (`Server.exe`). No Python installation, pip packages, or GnuPG binaries are required on Windows Server.
 - **Authenticated TCP Ingestion Socket (Port 9443)**: Ingests framed OpenPGP encrypted log batches streamed from edge forwarder nodes (`Win_Client.exe` and `Linux_Client.bin`).
 - **4-Run Temporal Persistence Rule**: Filters transient noise by requiring an issue signature to recur across at least 4 episodic transmission cycles within a rolling 12-hour evaluation window before promotion to `VERIFIED`.
 - **Embedded Hermes Reporting API (Port 8443)**: Integrated REST API exposing `/api/hermes/report` for external dashboards, monitoring agents, and scrapers.
 - **Pure-Python OpenPGP Cryptography**: Automatically generates RSA-2048 encryption keys and a SHA-256 fingerprint on first launch without external dependencies.
 - **State Database**: Stores issue lifecycle records, run counters, and machine telemetry in a local SQLite database (`logar_state.db`).
 ---
 ## 1. Initializing & Generating Server Configuration
 ### Step 1: Automatic First-Run Generation
 When launched without an existing `server_config.json`, `Server.exe` automatically initializes:
 1. An OpenPGP RSA-2048 encryption keypair (`private_key` and `public_key`).
 2. A SHA-256 public encryption fingerprint (`server_fingerprint`).
 3. A cryptographically random secret authentication token (`auth_token`).
 4. Default network socket coordinates (TCP 9443, Hermes API 8443).
 Open PowerShell and run:
 ```powershell
 .\Server.exe
 ```
 Output:
 ```
 [!] Config 'server_config.json' not found. Initializing first-run configuration...
 [+] Successfully generated new server config and OpenPGP keypair.
 [+] Server Encryption Fingerprint: 375388960531264EA0648EC0D2C4E4ABC6F22AC2
 [+] Saved to: server_config.json
 ```
 ### Step 2: Configuration Fields Reference
 The generated `server_config.json` contains:
 ```json
 {
  "server_name": "LOGAR-Windows-Hub",
  "tcp_host": "0.0.0.0",
  "tcp_port": 9443,
  "hermes_host": "0.0.0.0",
  "hermes_port": 8443,
  "auth_token": "a1b2c3d4e5f67890abcdef1234567890...",
  "db_path": "logar_state.db",
  "evaluation_window_hours": 12,
  "min_persistence_runs": 4,
  "server_fingerprint": "375388960531264EA0648EC0D2C4E4ABC6F22AC2",
  "public_key": "-----BEGIN PGP PUBLIC KEY BLOCK-----\n...",
  "private_key": "-----BEGIN PGP PRIVATE KEY BLOCK-----\n..."
 }
 ```
 | Parameter | Default | Description |
 | :--- | :--- | :--- |
 | `server_name` | `"LOGAR-Windows-Hub"` | Identifier for this hub instance |
 | `tcp_host` | `"0.0.0.0"` | Network interface to bind for incoming client socket traffic |
 | `tcp_port` | `9443` | TCP port for incoming edge log batches |
 | `hermes_host` | `"0.0.0.0"` | Network interface to bind for Hermes HTTP API |
 | `hermes_port` | `8443` | HTTP port for the Hermes reporting endpoint |
 | `auth_token` | *(auto-generated)* | Pre-shared authentication secret required in client envelopes |
 | `db_path` | `"logar_state.db"` | Path to persistent SQLite issue database |
 | `evaluation_window_hours` | `12` | Rolling evaluation window in hours for 4-run rule |
 | `min_persistence_runs` | `4` | Consecutive runs required to promote an issue to `VERIFIED` |
 ---
 ## 2. Generating Client Configuration Bundles
 Edge forwarders (`Win_Client.exe` and `Linux_Client.bin`) require an anonymous client configuration bundle that includes the server socket target, authentication token, and encryption public key, without exposing sensitive server names or private keys.
 Run the following command on the server:
 ```powershell
 .\Server.exe --create-client-config --server-host <SERVER_IP_OR_FQDN> --server-port 9443 --client-out client_config.json
 ```
 - Replace `<SERVER_IP_OR_FQDN>` with the reachable IP or DNS name of your LOGAR server.
 - Distribute `client_config.json` to client forwarder nodes along with `Win_Client.exe` or `Linux_Client.bin`.
 ---
 ## 3. Running Interactively
 ```powershell
 .\Server.exe --config C:\LOGAR-Server\server_config.json
 ```
 ### Command-Line Arguments
 | Argument | Description |
 | :--- | :--- |
 | `--config` | Path to server configuration JSON file (default: `server_config.json`) |
 | `--create-client-config` | Exports an anonymous client configuration bundle and exits |
 | `--server-host` | Hostname/IP to embed in the exported client configuration |
 | `--server-port` | Port to embed in the exported client configuration (default: `9443`) |
 | `--client-out` | Destination path for exported client configuration (default: `client_config.json`) |
 ---
 ## 4. Installing as a Continuous Windows Service
 Because `Server.exe` acts as a continuous server hub (listening for TCP connections and HTTP API queries), it should run persistently in the background.
 ### Method A: Native Windows Service via NSSM (Recommended)
 [NSSM (Non-Sucking Service Manager)](https://nssm.cc/) is the industry standard for wrapping standalone executables into formal Windows services managed by `services.msc`.
 1. Place `Server.exe` and `server_config.json` in `C:\LOGAR-Server\`.
 2. Open **Elevated PowerShell (Run as Administrator)**:
   ```powershell
   # Create deployment folder
   New-Item -ItemType Directory -Path "C:\LOGAR-Server" -Force
   Copy-Item "Server.exe", "server_config.json" -Destination "C:\LOGAR-Server\"
   # Install Windows Service via NSSM
   nssm.exe install LOGAR_Server "C:\LOGAR-Server\Server.exe" "--config C:\LOGAR-Server\server_config.json"
   nssm.exe set LOGAR_Server AppDirectory "C:\LOGAR-Server"
   nssm.exe set LOGAR_Server Description "LOGAR Central Aggregation Hub Service"
   nssm.exe set LOGAR_Server Start SERVICE_AUTO_START
   nssm.exe set LOGAR_Server AppStdout "C:\LOGAR-Server\server_out.log"
   nssm.exe set LOGAR_Server AppStderr "C:\LOGAR-Server\server_err.log"
   # Start the service
   nssm.exe start LOGAR_Server
   ```
 3. Verify status in PowerShell:
   ```powershell
   Get-Service -Name "LOGAR_Server"
   ```
 ### Method B: Windows Task Scheduler (Startup Daemon)
 If third-party service wrappers are restricted by organizational policy, configure a Task Scheduler job triggered at boot under the `SYSTEM` account:
 ```powershell
 # Action: Launch Server.exe
 $Action = New-ScheduledTaskAction -Execute "C:\LOGAR-Server\Server.exe" `
                                  -Argument "--config C:\LOGAR-Server\server_config.json" `
                                  -WorkingDirectory "C:\LOGAR-Server"
 # Trigger: At system startup
 $Trigger = New-ScheduledTaskTrigger -AtStartup
 # Settings: Restart on failure, no execution time limit
 $Settings = New-ScheduledTaskSettingsSet -AllowStartIfOnBatteries `
                                       -DontStopIfGoingOnBatteries `
                                       -StartWhenAvailable `
                                       -RestartCount 3 `
                                       -RestartInterval (New-TimeSpan -Minutes 1) `
                                       -ExecutionTimeLimit ([TimeSpan]::Zero)
 # Register task under SYSTEM with highest privileges
 Register-ScheduledTask -TaskName "LOGAR_Server_Daemon" `
                       -Action $Action `
                       -Trigger $Trigger `
                       -Settings $Settings `
                       -User "NT AUTHORITY\SYSTEM" `
                       -RunLevel Highest `
                       -Description "LOGAR Central Hub Daemon"
 # Start the task immediately
 Start-ScheduledTask -TaskName "LOGAR_Server_Daemon"
 Get-ScheduledTask -TaskName "LOGAR_Server_Daemon"
 ```
 ---
 ## 5. Hermes Reporting API & Health Checks
 Test the embedded Hermes REST endpoint locally using PowerShell:
 ```powershell
 $report = Invoke-RestMethod -Uri "http://127.0.0.1:8443/api/hermes/report" -Method GET
 $report | Format-Table fingerprint, status, consecutive_runs, first_seen, last_seen
 ```
 ### Response Format:
 ```json
 [
  {
    "fingerprint": "win-dc-01.corp.internal:DiskCorruptionDetected",
    "server": "win-dc-01.corp.internal",
    "signature": "DiskCorruptionDetected",
    "consecutive_runs": 4,
    "first_seen": "2026-09-04T08:15:00Z",
    "last_seen": "2026-09-04T15:00:00Z",
    "status": "VERIFIED",
    "verified": true,
    "os_type": "windows",
    "sample_message": "An error was detected on device \\Device\\Harddisk0\\DR0 during a paging operation."
  }
 ]
 ```
 ---
 ## 6. Windows Defender Firewall Configuration
 Open the necessary inbound firewall ports to allow incoming edge forwarder socket streams and HTTP API queries:
 ```powershell
 # Allow TCP 9443 for edge log forwarding
 New-NetFirewallRule -DisplayName "LOGAR TCP Log Ingestion" `
                    -Direction Inbound `
                    -LocalPort 9443 `
                    -Protocol TCP `
                    -Action Allow
 # Allow TCP 8443 for Hermes Reporting REST API
 New-NetFirewallRule -DisplayName "LOGAR Hermes Reporting API" `
                    -Direction Inbound `
                    -LocalPort 8443 `
                    -Protocol TCP `
                    -Action Allow
 ```
 ---
 ## 7. Uninstallation & Removal
 To remove the server service:
 ```powershell
 # If installed via NSSM:
 nssm.exe stop LOGAR_Server
 nssm.exe remove LOGAR_Server confirm
 # If installed via Task Scheduler:
 Unregister-ScheduledTask -TaskName "LOGAR_Server_Daemon" -Confirm:$false
 # Clean files
 Remove-Item -Recurse -Force "C:\LOGAR-Server"
 ```
@@ -0,0 +1,14 @@
 {
  "server_name": "LOGAR-Windows-Hub",
  "tcp_host": "0.0.0.0",
  "tcp_port": 9443,
  "hermes_host": "0.0.0.0",
  "hermes_port": 8443,
  "auth_token": "replace_with_secure_random_hex_token",
  "db_path": "logar_state.db",
  "evaluation_window_hours": 12,
  "min_persistence_runs": 4,
  "server_fingerprint": "AUTO_GENERATED_ON_FIRST_RUN",
  "public_key": "AUTO_GENERATED_ON_FIRST_RUN",
  "private_key": "AUTO_GENERATED_ON_FIRST_RUN"
 }
Author	SHA1	Message	Date
me0nline	f871344da4	Update README.md to document out/linux_server and out/win_server deployment packages CI Test Suite / Run Component Tests & Pipeline Verification (push) Successful in 1m33s Details	2026-09-04 16:05:04 +02:00
me0nline	e1dbe32063	Add Windows server deployment guide and sample configuration to out/win_server	2026-09-04 16:04:51 +02:00
me0nline	98a227a234	Add Linux server deployment guide and sample configuration to out/linux_server	2026-09-04 16:04:20 +02:00