209 lines
7.5 KiB
Markdown
209 lines
7.5 KiB
Markdown
# 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`).
|
|
- **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`).
|
|
|
|
---
|
|
|
|
## 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 warning persistence |
|
|
| `min_persistence_runs` | `4` | Number of distinct runs required to promote warnings 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
|
|
```
|