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).
• 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:

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

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