LOGAR/out/linux_server

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:

./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:

{
  "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:

./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

./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

# 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:

[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

sudo systemctl daemon-reload
sudo systemctl enable --now logar-server.service

Step 4: Verify Status and Inspect Logs

# 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

curl -s http://127.0.0.1:8443/api/hermes/report | jq .

Response Schema:

[
  {
    "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:

# 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