From 98a227a23408337c31be1af26100608dedb9d7a6 Mon Sep 17 00:00:00 2001 From: Maximilian Eibl Date: Fri, 4 Sep 2026 16:04:20 +0200 Subject: [PATCH] Add Linux server deployment guide and sample configuration to out/linux_server --- out/linux_server/README.md | 208 +++++++++++++++++++++ out/linux_server/server_config.sample.json | 14 ++ 2 files changed, 222 insertions(+) create mode 100644 out/linux_server/README.md create mode 100644 out/linux_server/server_config.sample.json diff --git a/out/linux_server/README.md b/out/linux_server/README.md new file mode 100644 index 0000000..93abae3 --- /dev/null +++ b/out/linux_server/README.md @@ -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-port 9443 --client-out client_config.json +``` + +- Replace `` 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 +``` diff --git a/out/linux_server/server_config.sample.json b/out/linux_server/server_config.sample.json new file mode 100644 index 0000000..00880d5 --- /dev/null +++ b/out/linux_server/server_config.sample.json @@ -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" +}