me0nline/LOGAR
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 4 Wiki Activity

docs(linux_server): update README.md with mTLS 1.3, dynamic PKI licensing, and systemd installer script instructions
CI Test Suite / Run Component Tests & Pipeline Verification (push) Successful in 2m3s
Details

Browse Source
This commit is contained in:
me0nline
2026-09-04 22:39:48 +02:00
parent d61e343fbe
commit cfc633c398
1 changed files with 60 additions and 146 deletions
Download Patch File Download Diff File Expand all files Collapse all files
out/linux_server/README.md
+60 -146
View File
@@ -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_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
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
```