From cfc633c398fd68d9178e6d4a928c4957c5027082 Mon Sep 17 00:00:00 2001 From: max Date: Fri, 4 Sep 2026 22:39:48 +0200 Subject: [PATCH] docs(linux_server): update README.md with mTLS 1.3, dynamic PKI licensing, and systemd installer script instructions --- out/linux_server/README.md | 206 +++++++++++-------------------------- 1 file changed, 60 insertions(+), 146 deletions(-) diff --git a/out/linux_server/README.md b/out/linux_server/README.md index 6b29350..f6daac0 100644 --- a/out/linux_server/README.md +++ b/out/linux_server/README.md @@ -1,31 +1,45 @@ # LOGAR Linux Server Hub -Standalone compiled executable binary distribution for Linux server environments (`Server.bin`). +Standalone compiled binary and automated systemd service 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. +`Server.bin` is a self-contained, pre-compiled Linux ELF executable that operates as the central coordination, log analysis, dynamic PKI, and reporting 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`). -- **Warning Persistence & Immediate Error Routing**: High-severity `ERROR`, `CRITICAL`, and `FATAL` events are promoted to `VERIFIED` immediately on their first occurrence. Operational `WARNING` and `INFO` events are evaluated against an episodic threshold, requiring persistence across at least 4 distinct client transmission cycles within a sliding 12-hour evaluation window before promotion from transient noise to `VERIFIED`. -- **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`). +- **Mutual TLS 1.3 (mTLS) Ingestion (Port 9443)**: Enforces mutual TLS 1.3 authentication for all incoming edge connections. Validates client certificates against an internal Root CA and verifies active licensing in SQLite. +- **Dynamic PKI & License Accounting**: Built-in Root CA generates server TLS certificates with SANs and dynamically signs client certificates via `POST /api/client/enroll` while enforcing seat limits (`max_seats`). +- **Warning Persistence & Immediate Error Routing**: High-severity `ERROR`, `CRITICAL`, and `FATAL` events are promoted to `VERIFIED` immediately on their first occurrence. Operational `WARNING` and `INFO` events require persistence across at least 4 distinct client transmission cycles within a rolling 12-hour evaluation window. +- **Embedded Hermes Reporting & Management API (Port 8443)**: Integrated REST API exposing `/api/hermes/report`, `/api/clients`, and `/api/client/enroll`. +- **State Database**: Stores issue lifecycle records, client telemetry, and licensing quotas in a local SQLite database (`logar_state.db`). --- -## 1. Initializing & Generating Server Configuration +## 1. Automated Installation via Script (Recommended) + +Deploy using the automated installer: +```bash +sudo ./compilation/install_linux_server.sh +``` +This script: +1. Installs the server binary to `/opt/logar-server/Server`. +2. Creates `/etc/logar` and `/var/log/logar`. +3. Deploys, enables, and starts the systemd service unit `/etc/systemd/system/logar-server.service` with `LimitNOFILE=65536`. + +--- + +## 2. 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). +1. An internal Root CA (`certs/ca.crt` and `certs/ca.key`). +2. A server TLS certificate (`certs/server.crt` and `certs/server.key`) with SANs. +3. An OpenPGP RSA-2048 keypair (`private_key` and `public_key`). +4. Cryptographically random authentication tokens and enrollment secrets. +5. Default network socket coordinates (mTLS 9443, Hermes API 8443). Run `Server.bin` once to initialize: ```bash @@ -37,11 +51,20 @@ Output: [+] Successfully generated new server config and OpenPGP keypair. [+] Server Encryption Fingerprint: 375388960531264EA0648EC0D2C4E4ABC6F22AC2 [+] Saved to: server_config.json +============================================================ + LOGAR Server Hub: LOGAR-Cloud-Hub + Transport Security: mTLS (TLS 1.3) + License Quota: 10 Active Seats + Server Encryption Fingerprint: 375388960531264EA0648EC0D2C4E4ABC6F22AC2 + Evaluation Window: 12 hours | 4-Run Rule: Warnings | Immediate Pass: Errors +============================================================ +[*] LOGAR mTLS TLSv1.3 Socket Server listening on 0.0.0.0:9443 +[*] Hermes Reporting API available at http://0.0.0.0:8443/api/hermes/report +[*] Client Enrollment API available at http://0.0.0.0:8443/api/client/enroll ``` ### Step 2: Configuration Fields Reference The generated `server_config.json` contains: - ```json { "server_name": "LOGAR-Linux-Hub", @@ -50,6 +73,10 @@ The generated `server_config.json` contains: "hermes_host": "0.0.0.0", "hermes_port": 8443, "auth_token": "a1b2c3d4e5f67890abcdef1234567890...", + "enrollment_secret": "e1f2a3b4c5d6...", + "max_seats": 10, + "cert_dir": "certs", + "tls_enabled": true, "db_path": "logar_state.db", "evaluation_window_hours": 12, "min_persistence_runs": 4, @@ -59,150 +86,37 @@ The generated `server_config.json` contains: } ``` -| 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 warning persistence | -| `min_persistence_runs` | `4` | Number of distinct runs required to promote warnings to `VERIFIED` | +--- + +## 3. Exporting Client Configurations + +Generate a client configuration bundle to deploy onto Windows or Linux forwarders: +```bash +./Server.bin --create-client-config --server-host 192.168.1.100 --server-port 9443 --client-out client_config.json +``` +The output file contains the server coordinates, enrollment secret, and fingerprint, ready for client deployment. --- -## 2. Generating Client Configuration Bundles +## 4. Manual Systemd Service Management -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: +Check service status: ```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 +Inspect live service logs: +```bash +sudo journalctl -u logar-server.service -f -n 50 ``` --- -## 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: +## 5. Uninstallation & Removal ```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 +sudo systemctl disable --now logar-server.service +sudo rm -f /etc/systemd/system/logar-server.service +sudo systemctl daemon-reload +sudo rm -rf /opt/logar-server /etc/logar /var/log/logar ```