docs: streamline admin guide to focus on WebUI management
CI Test Suite / Run Component Tests & Pipeline Verification (push) Successful in 1m19s
CI Test Suite / Run Component Tests & Pipeline Verification (push) Successful in 1m19s
This commit is contained in:
+158
-333
@@ -1,369 +1,194 @@
|
||||
# LOGAR Administrator & Operations Guide
|
||||
### *Complete Operations Manual for Fleet Hub Administration, Database Engines, PKI Licensing & AI Provisioning*
|
||||
# WebUI Administrator Guide
|
||||
|
||||
Welcome to the **LOGAR WebUI Administrator Guide**. This guide provides step-by-step instructions for managing and operating the LOGAR Server Hub through its graphical web console (`:8443/webui`).
|
||||
|
||||
For deep architectural design, cryptographic protocols, X.509 OID schemas, and full REST API specifications, please refer to the dedicated technical wiki pages:
|
||||
* **[Architecture & Design](https://gitea.eibl.tech/me0nline/LOGAR/wiki/Architecture-and-Design)**
|
||||
* **[PKI & Licensing](https://gitea.eibl.tech/me0nline/LOGAR/wiki/PKI-and-Licensing)**
|
||||
* **[State Machines & Lifecycles](https://gitea.eibl.tech/me0nline/LOGAR/wiki/State-Machines-and-Lifecycles)**
|
||||
* **[API Reference](https://gitea.eibl.tech/me0nline/LOGAR/wiki/API-Reference)**
|
||||
|
||||
---
|
||||
|
||||
## Table of Contents
|
||||
|
||||
1. [Executive Summary & System Architecture](#1-executive-summary--system-architecture)
|
||||
2. [Database Storage Engine Management](#2-database-storage-engine-management)
|
||||
- [Local SQLite 3 (WAL Mode)](#local-sqlite-3-wal-mode)
|
||||
- [External PostgreSQL Enterprise Backend](#external-postgresql-enterprise-backend)
|
||||
- [Automated SQLite to PostgreSQL Migration](#automated-sqlite-to-postgresql-migration)
|
||||
3. [Telemetry Ingestion Cache & Buffer Tuning](#3-telemetry-ingestion-cache--buffer-tuning)
|
||||
- [Ingestion Modes: Direct Write vs In-Memory Queue Buffer](#ingestion-modes-direct-write-vs-in-memory-queue-buffer)
|
||||
- [Tuning Parameters & Metrics](#tuning-parameters--metrics)
|
||||
- [Manual Flush & Buffer Monitoring](#manual-flush--buffer-monitoring)
|
||||
4. [Zero-Knowledge OpenPGP Data Encryption at Rest](#4-zero-knowledge-openpgp-data-encryption-at-rest)
|
||||
- [Encryption Mechanism](#encryption-mechanism)
|
||||
- [Transparent Authorized Decryption](#transparent-authorized-decryption)
|
||||
5. [Subordinate CA & Dynamic PKI Licensing](#5-subordinate-ca--dynamic-pki-licensing)
|
||||
- [Hierarchical PKI & Custom X.509 OIDs](#hierarchical-pki--custom-x509-oids)
|
||||
- [Licensed Feature Capabilities (`enterprise_db`)](#licensed-feature-capabilities-enterprise_db)
|
||||
- [Importing `.lic` Activation Packages](#importing-lic-activation-packages)
|
||||
- [Automated mTLS License Renewal](#automated-mtls-license-renewal)
|
||||
6. [Fleet Forwarder Management & Seat Provisioning](#6-fleet-forwarder-management--seat-provisioning)
|
||||
- [Zero-Touch Linux Deployment](#zero-touch-linux-deployment)
|
||||
- [Windows Edge Client Deployment](#windows-edge-client-deployment)
|
||||
- [Seat Lifecycle: Approve, Revoke, Delete](#seat-lifecycle-approve-revoke-delete)
|
||||
7. [Hermes AI Agent Integration](#7-hermes-ai-agent-integration)
|
||||
- [Dedicated Bearer Tokens](#dedicated-bearer-tokens)
|
||||
- [12-Hour Temporal Persistence Anomaly Stream](#12-hour-temporal-persistence-anomaly-stream)
|
||||
8. [Security, Authentication & 2FA](#8-security-authentication--2fa)
|
||||
- [Password Policies & PBKDF2 Hashing](#password-policies--pbkdf2-hashing)
|
||||
- [Time-Based One-Time Password (TOTP 2FA)](#time-based-one-time-password-totp-2fa)
|
||||
- [Sliding Window IP Rate Limiting](#sliding-window-ip-rate-limiting)
|
||||
9. [Configuration Reference & CLI Flags](#9-configuration-reference--cli-flags)
|
||||
10. [REST API Reference](#10-rest-api-reference)
|
||||
11. [Operational Runbook & Troubleshooting](#11-operational-runbook--troubleshooting)
|
||||
1. [Accessing the Web Console & Authentication](#1-accessing-the-web-console--authentication)
|
||||
2. [Dashboard: Live Verified Telemetry](#2-dashboard-live-verified-telemetry)
|
||||
3. [Fleet Seat Management & Client Provisioning](#3-fleet-seat-management--client-provisioning)
|
||||
4. [Sub-CA & Modular Licensing](#4-sub-ca--modular-licensing)
|
||||
5. [Storage Engine & Ingestion Performance](#5-storage-engine--ingestion-performance)
|
||||
6. [Hermes AI Tokens & Integration](#6-hermes-ai-tokens--integration)
|
||||
7. [User Account & 2FA Security](#7-user-account--2fa-security)
|
||||
|
||||
---
|
||||
|
||||
## 1. Executive Summary & System Architecture
|
||||
## 1. Accessing the Web Console & Authentication
|
||||
|
||||
LOGAR is a centralized log aggregation, normalization, and provisioning system designed for enterprise server fleets. It connects heterogeneous edge nodes (Windows and Linux) with a central server hub over **Mutual TLS 1.3 (mTLS)**, normalizing incoming events and presenting structured anomaly intelligence to **Hermes AI**.
|
||||
The LOGAR Server Hub provides an authenticated web management portal accessible from any modern web browser.
|
||||
|
||||
### Core Network Architecture
|
||||
### URL & Port
|
||||
* **Management Console URL**: `http://<SERVER_IP>:8443/webui`
|
||||
* **Protocol**: HTTP (or HTTPS behind an enterprise reverse proxy / load balancer)
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
subgraph MasterAuthority [Master License Authority]
|
||||
ROOT_CA[Master Root CA]
|
||||
AUTH_API[WebSocket Licensing Hub<br/>logar.eibl.tech]
|
||||
end
|
||||
### Default Credentials
|
||||
Upon first launch, LOGAR initializes default administrative credentials:
|
||||
* **Username**: `admin`
|
||||
* **Password**: `admin_logar_2026!`
|
||||
|
||||
subgraph Hub [LOGAR Server Hub]
|
||||
SUB_CA[Subordinate CA & PKI Engine]
|
||||
INGEST_QUEUE[IngestQueueManager<br/>In-Memory RAM Buffer]
|
||||
STORAGE_ROUTER[Storage Engine Router]
|
||||
SQLITE[(Local SQLite 3 WAL)]
|
||||
POSTGRES[(External PostgreSQL Cluster)]
|
||||
TEMP_ENG[12h Temporal Persistence Engine]
|
||||
HERMES_API[Hermes REST & WebUI API<br/>Port 8443]
|
||||
MTLS_SOCKET[mTLS 1.3 Socket Listener<br/>Port 9443]
|
||||
> **Security Recommendation**: Change the default credentials immediately after initial deployment using the **User Settings** menu.
|
||||
|
||||
MTLS_SOCKET --> INGEST_QUEUE
|
||||
INGEST_QUEUE --> STORAGE_ROUTER
|
||||
STORAGE_ROUTER --> SQLITE
|
||||
STORAGE_ROUTER --> POSTGRES
|
||||
STORAGE_ROUTER --> TEMP_ENG
|
||||
TEMP_ENG --> HERMES_API
|
||||
end
|
||||
---
|
||||
|
||||
subgraph EdgeNodes [Fleet Edge Forwarders]
|
||||
WIN_NODE[Windows Forwarder<br/>Win_Client.exe]
|
||||
LIN_NODE[Linux Forwarder<br/>Linux_Client.bin]
|
||||
end
|
||||
## 2. Dashboard: Live Verified Telemetry
|
||||
|
||||
subgraph AI [Hermes AI Analysis Layer]
|
||||
HERMES_AGENT[Hermes AI Agent]
|
||||
end
|
||||
**Tab: 📊 Live Telemetry**
|
||||
|
||||
ROOT_CA -->|Signs Sub-CA Cert| SUB_CA
|
||||
AUTH_API <==>|Live mTLS Renewal| SUB_CA
|
||||
The Live Telemetry view displays real-time anomalous log events aggregated across all enrolled Windows and Linux edge forwarders.
|
||||
|
||||
WIN_NODE ==>|1. Auto-Enrollment / mTLS Ingest| MTLS_SOCKET
|
||||
LIN_NODE ==>|1. Auto-Enrollment / mTLS Ingest| MTLS_SOCKET
|
||||
### Key Controls & Information
|
||||
* **Severity Filter**: Filter events by `ALL`, `CRITICAL`, `ERROR`, or `WARNING`.
|
||||
* **Temporal Tracking**: View occurrence frequency (`Runs: N`), first seen timestamp, and relative last seen time (e.g. `2m ago`).
|
||||
* **Source Attribution**: Inspect originating Hostname, Machine GUID, and Operating System badge (`Windows` / `Linux`).
|
||||
* **Message Payload**: Inspect the raw extracted log message and normalized signature.
|
||||
* **Auto-Refresh**: Live stream updates automatically; displays the latest 50 active anomaly frames.
|
||||
|
||||
HERMES_API ==>|GET /api/hermes/report| HERMES_AGENT
|
||||
---
|
||||
|
||||
## 3. Fleet Seat Management & Client Provisioning
|
||||
|
||||
**Tab: 💻 Client Seats**
|
||||
|
||||
Manage connected edge forwarders (`Win_Client` and `Linux_Client`), enforce cryptographic seat quotas, and export client configuration profiles.
|
||||
|
||||
### Seat Quota Overview
|
||||
* Displays the current seat consumption ratio (e.g., `3 / 25 Seats in Use`).
|
||||
* Unlicensed servers allow local log collection (`0 / 0 Seats`) while blocking remote mTLS forwarders until a license is imported.
|
||||
|
||||
### Managing Enrolled Forwarders
|
||||
The client seat table lists every registered forwarder with its Machine Identifier, Hostname, OS Type, IP Address, First Enrolled date, and Status:
|
||||
* **🟢 Active**: The forwarder has valid mTLS certificates and is actively streaming logs.
|
||||
* **🔴 Revoked**: The forwarder's mTLS certificate has been administratively revoked. Ingestion from this client is rejected.
|
||||
* **Action Buttons**:
|
||||
* **Revoke**: Temporarily revoke a client's seat and deny incoming connections.
|
||||
* **Reactivate / Approve**: Re-enable a previously revoked client seat.
|
||||
* **Delete**: Remove the client record and release the seat back to the available pool.
|
||||
|
||||
### Exporting Client Configuration
|
||||
Click **📥 Download Client Config** to generate and download `client_config.json`.
|
||||
* Contains the server's connection endpoints (`server_host:9443`), Sub-CA public certificate, encryption fingerprint, and enrollment secret.
|
||||
* Distribute this file to edge forwarders during deployment for instant zero-touch auto-enrollment.
|
||||
|
||||
---
|
||||
|
||||
## 4. Sub-CA & Modular Licensing
|
||||
|
||||
**Tab: 📜 Sub-CA & Licensing**
|
||||
|
||||
Manage the server's Subordinate Certificate Authority (Sub-CA), verify hardware host binding, view active licensed capabilities, and apply license updates.
|
||||
|
||||
### Sub-CA Status & Fingerprints
|
||||
* **CA Subject**: The Distinguished Name (DN) of the local Sub-CA.
|
||||
* **Server Encryption Fingerprint**: SHA-256 / OpenPGP fingerprint for encrypted payloads.
|
||||
* **Validity Period**: Issue date and certificate expiration date.
|
||||
* **Assigned Seat Quota**: Maximum authorized forwarder capacity.
|
||||
|
||||
### ✨ Licensed Capabilities & Feature Modules
|
||||
This section displays all authorized feature modules:
|
||||
* **`enterprise_db`**: Multi-engine external database support (PostgreSQL / MySQL / MariaDB), high-throughput ring buffering, and zero-knowledge data encryption at rest.
|
||||
* *Standard Edition*: If running without an enterprise license, standard local SQLite storage remains active.
|
||||
|
||||
### License Management Operations
|
||||
* **Export License Request (`.lic`)**:
|
||||
Click **📤 Export CSR (.lic)** to download the server's hardware-bound certificate signing request. Send this file to your organization's Master License Authority administrator.
|
||||
* **Import Signed Sub-CA Certificate**:
|
||||
Paste the signed PEM certificate received from the Master Authority into the text area and click **📥 Import Signed Certificate**. The server reloads its SSLContext and updates seat quotas in-flight with zero downtime.
|
||||
* **Live WebSocket Sync**:
|
||||
Click **🔄 Sync with License Hub** to trigger immediate real-time synchronization with `logar.eibl.tech`.
|
||||
|
||||
---
|
||||
|
||||
## 5. Storage Engine & Ingestion Performance
|
||||
|
||||
**Tab: 🗄️ Database Engine**
|
||||
|
||||
Configure ingestion buffering, payload encryption at rest, and database backends.
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ 1. INGESTION RING BUFFER & BATCH FLUSHER (Top) │
|
||||
│ • Mode: Direct (Sync) / In-Memory Ring Buffer │
|
||||
│ • Batch Flush Interval (sec) & Batch Size (events) │
|
||||
├─────────────────────────────────────────────────────────────┤
|
||||
│ 2. PAYLOAD ENCRYPTION AT REST (Middle) │
|
||||
│ • Toggle: OpenPGP / RSA-2048 Payload Encryption │
|
||||
├─────────────────────────────────────────────────────────────┤
|
||||
│ 3. STORAGE BACKEND SELECTION (Bottom) │
|
||||
│ • Local SQLite (WAL Mode) │
|
||||
│ • External SQL Server (PostgreSQL / MySQL / MariaDB) │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
### 1. Ingestion Ring Buffer (Top Section)
|
||||
Tune log ingestion throughput to prevent socket I/O bottlenecks during high-volume spikes:
|
||||
* **Cache Mode**:
|
||||
* **Direct (Synchronous)**: Commits incoming log batches immediately to disk. Recommended for small deployments (< 20 nodes).
|
||||
* **In-Memory Ring Buffer**: Places incoming events into an in-memory queue. A background thread flushes events in atomic batches. Recommended for large fleets (> 50 nodes).
|
||||
* **Batch Flush Interval**: Time in seconds between automated queue commits (default: `2.0s`).
|
||||
* **Batch Size**: Maximum events processed per database commit transaction (default: `100`).
|
||||
* *Note: Ingestion buffering is an explicit opt-in setting and is not auto-enabled.*
|
||||
|
||||
## 2. Database Storage Engine Management
|
||||
### 2. Payload Encryption at Rest (Middle Section)
|
||||
* **Encrypt Payloads at Rest**: When enabled, log message payloads (`event_data`) stored in external databases are encrypted using the server's X.509 RSA-2048 / OpenPGP public key.
|
||||
* **Zero-Knowledge Guarantee**: Database administrators or compromised SQL servers cannot read raw logs without the private key resident on the LOGAR Server Hub.
|
||||
* *Note: Encryption at rest is an explicit opt-in setting.*
|
||||
|
||||
LOGAR supports dual storage backends: an embedded **Local SQLite 3 (WAL Mode)** engine and an **External PostgreSQL Database Server** for enterprise clustering.
|
||||
|
||||
### Local SQLite 3 (WAL Mode)
|
||||
- **Status**: Standard Default (Included out of the box, zero configuration required).
|
||||
- **Optimization**: Operates with Write-Ahead Logging (`PRAGMA journal_mode=WAL;`), asynchronous normal synchronization (`PRAGMA synchronous=NORMAL;`), and memory-mapped I/O (`PRAGMA mmap_size=268435456;`).
|
||||
- **File Location**: Configurable via `db_path` in `server_config.json` (defaults to `logar_state.db`).
|
||||
|
||||
### External PostgreSQL Enterprise Backend
|
||||
- **Requirement**: Unlocked via the `enterprise_db` license capability.
|
||||
- **Benefits**: Enables horizontal database scalability, clustering, multi-node replication, and centralized enterprise backup policies.
|
||||
- **Connection Parameters**:
|
||||
- **Host / IP**: Database hostname or IP address.
|
||||
- **Port**: Default `5432`.
|
||||
- **Database**: Target schema/database name (default `logar`).
|
||||
- **Username / Password**: Authentication credentials.
|
||||
- **SSL Mode**: Supports `prefer`, `require`, `verify-ca`, `verify-full`, `disable`, and `allow`.
|
||||
- **Connect Timeout**: Timeout in seconds (default `5`s).
|
||||
- **Connection Pool Size**: Maximum pooled persistent connections (default `10`).
|
||||
|
||||
### Automated SQLite to PostgreSQL Migration
|
||||
Administrators can migrate all historical logs, runs, active issues, seat allocations, users, and tokens from SQLite to PostgreSQL directly in the WebUI (`💾 DB Engine` -> `🚀 Migrate SQLite Data to PostgreSQL`) or via API (`POST /api/db/migrate-to-postgres`):
|
||||
1. Flushes any in-memory telemetry buffers to SQLite.
|
||||
2. Connects to PostgreSQL and verifies/initializes the schema.
|
||||
3. Automatically transfers records table-by-table with validation.
|
||||
4. Returns a detailed count of all migrated records.
|
||||
### 3. Database Backend Selection (Bottom Section)
|
||||
Switch between local file storage and external SQL servers:
|
||||
* **Local SQLite (WAL Mode)**:
|
||||
* Default, zero-configuration embedded database located at `logar_state.db`.
|
||||
* Operates with Write-Ahead Logging (WAL) for high concurrency.
|
||||
* **External SQL Server (PostgreSQL / MySQL / MariaDB)**:
|
||||
* Select your database dialect (**PostgreSQL** or **MySQL / MariaDB**).
|
||||
* Enter **Host**, **Port**, **Database Name**, **Username**, and **Password**.
|
||||
* Click **💾 Save & Apply Storage Configuration**.
|
||||
* The server tests connectivity, initializes required tables and indices, and migrates operational state seamlessly.
|
||||
* *Licensing Note: External SQL backend options require the `enterprise_db` licensed capability. If unlicensed, these controls are visible but gracefully disabled.*
|
||||
|
||||
---
|
||||
|
||||
## 3. Telemetry Ingestion Cache & Buffer Tuning
|
||||
## 6. Hermes AI Tokens & Integration
|
||||
|
||||
### Ingestion Modes: Direct Write vs In-Memory Queue Buffer
|
||||
**Tab: 🤖 Hermes AI**
|
||||
|
||||
| Feature | ⚡ Immediate Direct Write | 🚀 In-Memory Queue Buffer (`enterprise_db`) |
|
||||
| :--- | :--- | :--- |
|
||||
| **Ingress Latency** | Low latency, immediate DB commit | Microsecond ingestion, non-blocking |
|
||||
| **Throughput** | Up to 1,500 events/sec | Up to 50,000+ events/sec |
|
||||
| **Disk I/O** | Continuous write cycles | Atomic batch flushing |
|
||||
| **License** | Standard Community Edition | Enterprise License (`enterprise_db`) |
|
||||
Provision dedicated access tokens for Hermes AI agents to ingest anomalous telemetry.
|
||||
|
||||
### Tuning Parameters & Metrics
|
||||
When **In-Memory Queue Buffer** is enabled, administrators can tune the buffer engine:
|
||||
- **Flush Interval (seconds)**: Maximum elapsed time before buffered anomalies are written to storage (e.g. `2.0`s).
|
||||
- **Batch Size Threshold**: Number of buffered events that triggers an immediate atomic flush (e.g. `100` events).
|
||||
- **Max Buffer Capacity**: Upper ceiling of buffered items in memory (e.g. `50,000` events) to protect system RAM under heavy load.
|
||||
### Managing Access Tokens
|
||||
* **Create Token**: Enter an agent name (e.g. `Hermes-Production-Cluster`) and click **➕ Generate Token**.
|
||||
* **Token Attributes**: View Token Name, Creation Date, Last Used Timestamp, and Status (`Active` / `Revoked`).
|
||||
* **Revoke / Delete**: Instantly revoke access for compromised tokens or permanently delete retired tokens.
|
||||
|
||||
### Manual Flush & Buffer Monitoring
|
||||
- **Live Monitoring**: The KPI card displays live buffer size, total events ingested, total flushed, and average flush latency.
|
||||
- **Manual Trigger**: Click **`🌊 Flush Buffer Now`** or call `POST /api/db/flush-buffer` to force an immediate buffer drain.
|
||||
|
||||
---
|
||||
|
||||
## 4. Zero-Knowledge OpenPGP Data Encryption at Rest
|
||||
|
||||
### Encryption Mechanism
|
||||
When **Data Encryption at Rest** is enabled (`encrypt_at_rest: true`):
|
||||
- All sensitive log payloads, anomaly messages, and raw traces are encrypted with the server's OpenPGP public key before writing to the database table (`active_issues.message`).
|
||||
- Remote database administrators or third-party database hosting providers only see armored OpenPGP ciphertext (`-----BEGIN PGP MESSAGE-----`).
|
||||
|
||||
### Transparent Authorized Decryption
|
||||
- The central LOGAR hub instance holds the private OpenPGP key in protected memory.
|
||||
- When authenticated administrators access the WebUI or when authorized Hermes AI instances query `/api/hermes/report`, the server transparently decrypts records on-the-fly.
|
||||
|
||||
---
|
||||
|
||||
## 5. Subordinate CA & Dynamic PKI Licensing
|
||||
|
||||
LOGAR utilizes a hierarchical Public Key Infrastructure (PKI) for cryptographic client identity and license seat enforcement.
|
||||
|
||||
### Hierarchical PKI & Custom X.509 OIDs
|
||||
The Master Authority (`logar.eibl.tech`) signs the hub's Subordinate CA certificate (`certs/ca.crt`), embedding custom ASN.1 OIDs:
|
||||
- **`1.3.6.1.4.1.58888.1.1` (Seat Quota)**: Encodes the authorized edge client seat capacity (e.g. `25` seats).
|
||||
- **`1.3.6.1.4.1.58888.1.2` (Master Authority URL)**: Identifies the upstream licensing authority.
|
||||
- **`1.3.6.1.4.1.58888.1.3` (Feature Capabilities)**: Comma-delimited list of granted features (e.g. `enterprise_db,ai_heuristics`).
|
||||
|
||||
### Licensed Feature Capabilities (`enterprise_db`)
|
||||
The **📜 Sub-CA & Licensing** tab displays all active licensed features:
|
||||
- **`enterprise_db`**: Authorizes external PostgreSQL database pooling, high-throughput in-memory RAM buffering, and OpenPGP data-at-rest encryption.
|
||||
|
||||
### Importing `.lic` Activation Packages
|
||||
1. In the WebUI, navigate to **📜 Sub-CA & Licensing** and click **`📥 Import License (.lic)`**.
|
||||
2. Select your `.lic` bundle or paste the JSON package.
|
||||
3. The server immediately reloads the PKI trust chain and hot-reloads the active mTLS `SSLContext` without downtime.
|
||||
|
||||
### Automated mTLS License Renewal
|
||||
- Click **`🔄 Sync & Renew via mTLS`** in the WebUI or run:
|
||||
```bash
|
||||
python src/Server.py --sync-license
|
||||
```
|
||||
- The hub connects to `logar.eibl.tech` over mTLS, sends its current seat utilization, and retrieves an updated signed CA certificate.
|
||||
|
||||
---
|
||||
|
||||
## 6. Fleet Forwarder Management & Seat Provisioning
|
||||
|
||||
### Zero-Touch Linux Deployment
|
||||
Run the automated single-line installer on target Linux servers:
|
||||
```bash
|
||||
sudo ./compilation/install_linux_client.sh "http://<HUB_IP>:8443" "<ENROLLMENT_SECRET>"
|
||||
### Connecting Hermes AI
|
||||
Configure Hermes AI agents to query the structured anomaly stream:
|
||||
```http
|
||||
GET http://<SERVER_IP>:8443/api/hermes/report
|
||||
Authorization: Bearer hermes_live_xxxxxxxxxxxxxxxx
|
||||
```
|
||||
- Automatically generates a 2048-bit RSA client keypair.
|
||||
- Enrolls with the hub and receives a signed client certificate.
|
||||
- Deploys and starts the `logar-client.service` systemd unit.
|
||||
|
||||
### Windows Edge Client Deployment
|
||||
1. Download and run `LOGAR-Client-Setup.exe` on the Windows host.
|
||||
2. In the Server WebUI, click **`📥 Export Client Profile`** and download `client_config.json`.
|
||||
3. Place `client_config.json` into `C:\Program Files\LOGAR\client_config.json`.
|
||||
4. The `LOGAR_Client` service automatically boots and connects via mTLS.
|
||||
|
||||
### Seat Lifecycle: Approve, Revoke, Delete
|
||||
In the **💻 Fleet Forwarders** tab:
|
||||
- **Revoke**: Temporarily blocks the node at the TLS handshake level (`ssl.CERT_REQUIRED`).
|
||||
- **Approve**: Re-activates a revoked node and restores telemetry ingestion.
|
||||
- **Remove**: Permanently deletes the client record and immediately frees the leased seat quota.
|
||||
* Or via query parameter: `http://<SERVER_IP>:8443/api/hermes/report?token=hermes_live_xxxxxxxxxxxxxxxx`
|
||||
|
||||
---
|
||||
|
||||
## 7. Hermes AI Agent Integration
|
||||
## 7. User Account & 2FA Security
|
||||
|
||||
### Dedicated Bearer Tokens
|
||||
1. Navigate to **🤖 Hermes AI & Tokens** in the WebUI.
|
||||
2. Enter a descriptive token name (e.g. `Hermes-Autonomous-SecOps`) and click **`Generate Token`**.
|
||||
3. Copy the Bearer token for Hermes agent configuration.
|
||||
**Menu: ⚙️ User Settings**
|
||||
|
||||
### 12-Hour Temporal Persistence Anomaly Stream
|
||||
Hermes queries the real-time anomaly stream:
|
||||
```bash
|
||||
curl -H "Authorization: Bearer hermes_xxxxxxxxxxxx" http://<HUB_IP>:8443/api/hermes/report
|
||||
```
|
||||
### Changing Administrative Credentials
|
||||
1. Click the **Admin Profile** icon in the navigation bar.
|
||||
2. Enter a new Username and Password.
|
||||
3. Click **Update Account**.
|
||||
|
||||
#### JSON Telemetry Format:
|
||||
```json
|
||||
[
|
||||
{
|
||||
"fingerprint": "corp-dc:srv-db-01:postgres_wal_checkpoint_delay",
|
||||
"site": "corp-dc",
|
||||
"server": "srv-db-01",
|
||||
"signature": "postgres_wal_checkpoint_delay",
|
||||
"severity": "WARNING",
|
||||
"message": "WAL checkpoint write duration exceeded 30000ms threshold",
|
||||
"os_type": "linux",
|
||||
"first_seen": "2026-09-30 14:10:00",
|
||||
"last_seen": "2026-09-30 17:42:15",
|
||||
"consecutive_runs": 4,
|
||||
"evaluation_window": "12h",
|
||||
"verified": true,
|
||||
"status": "VERIFIED"
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 8. Security, Authentication & 2FA
|
||||
|
||||
### Password Policies & PBKDF2 Hashing
|
||||
- User passwords are protected using PBKDF2-HMAC-SHA256 with 100,000 iterations and 16-byte random salts.
|
||||
- Change admin credentials via the user avatar menu -> **🔑 Change Password**.
|
||||
|
||||
### Time-Based One-Time Password (TOTP 2FA)
|
||||
- Standard RFC 6238 TOTP with standard 30-second drift windows.
|
||||
- Configure via avatar menu -> **🛡️ Two-Factor Auth (2FA)**.
|
||||
- Compatible with Google Authenticator, Authy, 1Password, and Bitwarden.
|
||||
|
||||
### Sliding Window IP Rate Limiting
|
||||
- **Brute-Force Protection**: Enforces rate limiting on `/login` and `/api/client/enroll`.
|
||||
- Excess failed attempts trigger automatic IP blocking with sliding exponential backoff.
|
||||
|
||||
---
|
||||
|
||||
## 9. Configuration Reference & CLI Flags
|
||||
|
||||
### `server_config.json` Specification
|
||||
|
||||
```json
|
||||
{
|
||||
"server_name": "LOGAR-Cloud-Hub",
|
||||
"tcp_host": "0.0.0.0",
|
||||
"tcp_port": 9443,
|
||||
"hermes_host": "0.0.0.0",
|
||||
"hermes_port": 8443,
|
||||
"admin_user": "admin",
|
||||
"enrollment_secret": "9a7f8e...4b",
|
||||
"max_seats": 25,
|
||||
"license_status": "active",
|
||||
"license_server_url": "https://logar.eibl.tech",
|
||||
"cert_dir": "certs",
|
||||
"tls_enabled": true,
|
||||
"db_path": "logar_state.db",
|
||||
"storage_engine": "sqlite",
|
||||
"cache_mode": "direct",
|
||||
"flush_interval": 2.0,
|
||||
"batch_size": 100,
|
||||
"max_queue": 50000,
|
||||
"encrypt_at_rest": false,
|
||||
"server_fingerprint": "6FF5BE81...",
|
||||
"public_key": "-----BEGIN PGP PUBLIC KEY BLOCK-----\n...",
|
||||
"private_key": "-----BEGIN PGP PRIVATE KEY BLOCK-----\n..."
|
||||
}
|
||||
```
|
||||
|
||||
### CLI Arguments
|
||||
|
||||
| Flag | Description |
|
||||
| :--- | :--- |
|
||||
| `--config <path>` | Path to server configuration JSON file |
|
||||
| `--create-client-config` | Exports a client config bundle and exits |
|
||||
| `--client-out <path>` | Destination path for exported client configuration |
|
||||
| `--server-host <host>` | Embedded target host for exported client configuration |
|
||||
| `--server-port <port>` | Embedded target port for exported client configuration |
|
||||
| `--export-lic <path>` | Exports a `.lic` CSR activation request package |
|
||||
| `--import-lic <path>` | Imports and activates a signed `.lic` license package |
|
||||
| `--sync-license` | Connects to master authority to renew certificate & seats |
|
||||
|
||||
---
|
||||
|
||||
## 10. REST API Reference
|
||||
|
||||
| Method | Endpoint | Auth | Description |
|
||||
| :--- | :--- | :--- | :--- |
|
||||
| `GET` | `/health` | None | Health check, server name, and TLS status |
|
||||
| `POST` | `/api/client/enroll` | Secret | Edge forwarder mTLS enrollment & certificate issuance |
|
||||
| `GET` | `/api/clients` | Admin | List registered forwarders, activity times, and seat quota |
|
||||
| `POST` | `/api/clients/approve` | Admin | Reactivate / approve an enrolled forwarder seat |
|
||||
| `POST` | `/api/clients/revoke` | Admin | Revoke an enrolled forwarder seat |
|
||||
| `POST` | `/api/clients/delete` | Admin | Remove forwarder record and permanently free seat |
|
||||
| `GET` | `/api/hermes/report` | Hermes/Admin | Stream verified anomalies within 12h temporal window |
|
||||
| `POST` | `/api/hermes/tokens/create` | Admin | Generate a named Bearer token for Hermes AI |
|
||||
| `POST` | `/api/hermes/tokens/revoke` | Admin | Revoke an existing Hermes Bearer token |
|
||||
| `GET` | `/api/db/stats` | Admin | Telemetry buffer stats, queue metrics, and storage info |
|
||||
| `POST` | `/api/db/flush-buffer` | Admin | Force immediate drain and write of buffered telemetry |
|
||||
| `POST` | `/api/db/test-connection` | Admin | Test external PostgreSQL connectivity (`enterprise_db`) |
|
||||
| `POST` | `/api/db/switch-backend` | Admin | Switch backend between SQLite and PostgreSQL (`enterprise_db`) |
|
||||
| `POST` | `/api/db/config` | Admin | Persist DB engine, cache mode, and encryption settings |
|
||||
| `POST` | `/api/db/migrate-to-postgres` | Admin | Migrate SQLite tables to PostgreSQL (`enterprise_db`) |
|
||||
| `GET` | `/api/license/status` | Admin | Subordinate CA status, seat quota, and licensed features |
|
||||
| `POST` | `/api/license/import` | Admin | Import `.lic` bundle or signed CA PEM |
|
||||
| `POST` | `/api/license/sync` | Admin | Sync license seats with master authority over mTLS |
|
||||
|
||||
---
|
||||
|
||||
## 11. Operational Runbook & Troubleshooting
|
||||
|
||||
### Diagnostic Checklist
|
||||
|
||||
1. **Verify Hub Service Status**:
|
||||
```bash
|
||||
# Linux
|
||||
sudo systemctl status logar-server.service
|
||||
# Windows PowerShell
|
||||
Get-Service LOGAR_Server
|
||||
```
|
||||
2. **Check Health Endpoint**:
|
||||
```bash
|
||||
curl http://localhost:8443/health
|
||||
```
|
||||
3. **Inspect Active Anomaly Telemetry**:
|
||||
```bash
|
||||
curl -H "Authorization: Bearer <ADMIN_OR_HERMES_TOKEN>" http://localhost:8443/api/hermes/report
|
||||
```
|
||||
4. **Certificate Validity Check**:
|
||||
```bash
|
||||
openssl x509 -in certs/ca.crt -text -noout | grep -A 2 "Validity"
|
||||
```
|
||||
|
||||
### Common Issues & Remediation
|
||||
|
||||
- **Issue: Forwarder rejected with `Connection Refused` or `TLS Handshake Failure`**:
|
||||
- Ensure port `9443` is reachable through host and cloud firewalls.
|
||||
- Verify edge node clock synchronization (NTP) with the server hub.
|
||||
- Confirm the client certificate has not been revoked in the **Fleet Forwarders** tab.
|
||||
- **Issue: `403 Forbidden` on PostgreSQL or Buffering settings**:
|
||||
- The `enterprise_db` feature capability is required. Verify your license in **📜 Sub-CA & Licensing**.
|
||||
- **Issue: Rate limit lock on admin login**:
|
||||
- Wait 60 seconds for the sliding attempt window to expire, or authenticate via an existing active session.
|
||||
### Two-Factor Authentication (TOTP 2FA)
|
||||
Enhance login security with RFC 6238 Time-Based One-Time Passwords:
|
||||
1. Click **🔒 Setup Two-Factor Authentication**.
|
||||
2. Scan the displayed QR Code using your preferred authenticator app (Google Authenticator, Microsoft Authenticator, 1Password, etc.).
|
||||
3. Enter the 6-digit verification code from your authenticator app to confirm activation.
|
||||
4. Subsequent logins will require your password followed by the 6-digit TOTP code.
|
||||
|
||||
+158
-333
@@ -1,369 +1,194 @@
|
||||
# LOGAR Administrator & Operations Guide
|
||||
### *Complete Operations Manual for Fleet Hub Administration, Database Engines, PKI Licensing & AI Provisioning*
|
||||
# WebUI Administrator Guide
|
||||
|
||||
Welcome to the **LOGAR WebUI Administrator Guide**. This guide provides step-by-step instructions for managing and operating the LOGAR Server Hub through its graphical web console (`:8443/webui`).
|
||||
|
||||
For deep architectural design, cryptographic protocols, X.509 OID schemas, and full REST API specifications, please refer to the dedicated technical wiki pages:
|
||||
* **[Architecture & Design](https://gitea.eibl.tech/me0nline/LOGAR/wiki/Architecture-and-Design)**
|
||||
* **[PKI & Licensing](https://gitea.eibl.tech/me0nline/LOGAR/wiki/PKI-and-Licensing)**
|
||||
* **[State Machines & Lifecycles](https://gitea.eibl.tech/me0nline/LOGAR/wiki/State-Machines-and-Lifecycles)**
|
||||
* **[API Reference](https://gitea.eibl.tech/me0nline/LOGAR/wiki/API-Reference)**
|
||||
|
||||
---
|
||||
|
||||
## Table of Contents
|
||||
|
||||
1. [Executive Summary & System Architecture](#1-executive-summary--system-architecture)
|
||||
2. [Database Storage Engine Management](#2-database-storage-engine-management)
|
||||
- [Local SQLite 3 (WAL Mode)](#local-sqlite-3-wal-mode)
|
||||
- [External PostgreSQL Enterprise Backend](#external-postgresql-enterprise-backend)
|
||||
- [Automated SQLite to PostgreSQL Migration](#automated-sqlite-to-postgresql-migration)
|
||||
3. [Telemetry Ingestion Cache & Buffer Tuning](#3-telemetry-ingestion-cache--buffer-tuning)
|
||||
- [Ingestion Modes: Direct Write vs In-Memory Queue Buffer](#ingestion-modes-direct-write-vs-in-memory-queue-buffer)
|
||||
- [Tuning Parameters & Metrics](#tuning-parameters--metrics)
|
||||
- [Manual Flush & Buffer Monitoring](#manual-flush--buffer-monitoring)
|
||||
4. [Zero-Knowledge OpenPGP Data Encryption at Rest](#4-zero-knowledge-openpgp-data-encryption-at-rest)
|
||||
- [Encryption Mechanism](#encryption-mechanism)
|
||||
- [Transparent Authorized Decryption](#transparent-authorized-decryption)
|
||||
5. [Subordinate CA & Dynamic PKI Licensing](#5-subordinate-ca--dynamic-pki-licensing)
|
||||
- [Hierarchical PKI & Custom X.509 OIDs](#hierarchical-pki--custom-x509-oids)
|
||||
- [Licensed Feature Capabilities (`enterprise_db`)](#licensed-feature-capabilities-enterprise_db)
|
||||
- [Importing `.lic` Activation Packages](#importing-lic-activation-packages)
|
||||
- [Automated mTLS License Renewal](#automated-mtls-license-renewal)
|
||||
6. [Fleet Forwarder Management & Seat Provisioning](#6-fleet-forwarder-management--seat-provisioning)
|
||||
- [Zero-Touch Linux Deployment](#zero-touch-linux-deployment)
|
||||
- [Windows Edge Client Deployment](#windows-edge-client-deployment)
|
||||
- [Seat Lifecycle: Approve, Revoke, Delete](#seat-lifecycle-approve-revoke-delete)
|
||||
7. [Hermes AI Agent Integration](#7-hermes-ai-agent-integration)
|
||||
- [Dedicated Bearer Tokens](#dedicated-bearer-tokens)
|
||||
- [12-Hour Temporal Persistence Anomaly Stream](#12-hour-temporal-persistence-anomaly-stream)
|
||||
8. [Security, Authentication & 2FA](#8-security-authentication--2fa)
|
||||
- [Password Policies & PBKDF2 Hashing](#password-policies--pbkdf2-hashing)
|
||||
- [Time-Based One-Time Password (TOTP 2FA)](#time-based-one-time-password-totp-2fa)
|
||||
- [Sliding Window IP Rate Limiting](#sliding-window-ip-rate-limiting)
|
||||
9. [Configuration Reference & CLI Flags](#9-configuration-reference--cli-flags)
|
||||
10. [REST API Reference](#10-rest-api-reference)
|
||||
11. [Operational Runbook & Troubleshooting](#11-operational-runbook--troubleshooting)
|
||||
1. [Accessing the Web Console & Authentication](#1-accessing-the-web-console--authentication)
|
||||
2. [Dashboard: Live Verified Telemetry](#2-dashboard-live-verified-telemetry)
|
||||
3. [Fleet Seat Management & Client Provisioning](#3-fleet-seat-management--client-provisioning)
|
||||
4. [Sub-CA & Modular Licensing](#4-sub-ca--modular-licensing)
|
||||
5. [Storage Engine & Ingestion Performance](#5-storage-engine--ingestion-performance)
|
||||
6. [Hermes AI Tokens & Integration](#6-hermes-ai-tokens--integration)
|
||||
7. [User Account & 2FA Security](#7-user-account--2fa-security)
|
||||
|
||||
---
|
||||
|
||||
## 1. Executive Summary & System Architecture
|
||||
## 1. Accessing the Web Console & Authentication
|
||||
|
||||
LOGAR is a centralized log aggregation, normalization, and provisioning system designed for enterprise server fleets. It connects heterogeneous edge nodes (Windows and Linux) with a central server hub over **Mutual TLS 1.3 (mTLS)**, normalizing incoming events and presenting structured anomaly intelligence to **Hermes AI**.
|
||||
The LOGAR Server Hub provides an authenticated web management portal accessible from any modern web browser.
|
||||
|
||||
### Core Network Architecture
|
||||
### URL & Port
|
||||
* **Management Console URL**: `http://<SERVER_IP>:8443/webui`
|
||||
* **Protocol**: HTTP (or HTTPS behind an enterprise reverse proxy / load balancer)
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
subgraph MasterAuthority [Master License Authority]
|
||||
ROOT_CA[Master Root CA]
|
||||
AUTH_API[WebSocket Licensing Hub<br/>logar.eibl.tech]
|
||||
end
|
||||
### Default Credentials
|
||||
Upon first launch, LOGAR initializes default administrative credentials:
|
||||
* **Username**: `admin`
|
||||
* **Password**: `admin_logar_2026!`
|
||||
|
||||
subgraph Hub [LOGAR Server Hub]
|
||||
SUB_CA[Subordinate CA & PKI Engine]
|
||||
INGEST_QUEUE[IngestQueueManager<br/>In-Memory RAM Buffer]
|
||||
STORAGE_ROUTER[Storage Engine Router]
|
||||
SQLITE[(Local SQLite 3 WAL)]
|
||||
POSTGRES[(External PostgreSQL Cluster)]
|
||||
TEMP_ENG[12h Temporal Persistence Engine]
|
||||
HERMES_API[Hermes REST & WebUI API<br/>Port 8443]
|
||||
MTLS_SOCKET[mTLS 1.3 Socket Listener<br/>Port 9443]
|
||||
> **Security Recommendation**: Change the default credentials immediately after initial deployment using the **User Settings** menu.
|
||||
|
||||
MTLS_SOCKET --> INGEST_QUEUE
|
||||
INGEST_QUEUE --> STORAGE_ROUTER
|
||||
STORAGE_ROUTER --> SQLITE
|
||||
STORAGE_ROUTER --> POSTGRES
|
||||
STORAGE_ROUTER --> TEMP_ENG
|
||||
TEMP_ENG --> HERMES_API
|
||||
end
|
||||
---
|
||||
|
||||
subgraph EdgeNodes [Fleet Edge Forwarders]
|
||||
WIN_NODE[Windows Forwarder<br/>Win_Client.exe]
|
||||
LIN_NODE[Linux Forwarder<br/>Linux_Client.bin]
|
||||
end
|
||||
## 2. Dashboard: Live Verified Telemetry
|
||||
|
||||
subgraph AI [Hermes AI Analysis Layer]
|
||||
HERMES_AGENT[Hermes AI Agent]
|
||||
end
|
||||
**Tab: 📊 Live Telemetry**
|
||||
|
||||
ROOT_CA -->|Signs Sub-CA Cert| SUB_CA
|
||||
AUTH_API <==>|Live mTLS Renewal| SUB_CA
|
||||
The Live Telemetry view displays real-time anomalous log events aggregated across all enrolled Windows and Linux edge forwarders.
|
||||
|
||||
WIN_NODE ==>|1. Auto-Enrollment / mTLS Ingest| MTLS_SOCKET
|
||||
LIN_NODE ==>|1. Auto-Enrollment / mTLS Ingest| MTLS_SOCKET
|
||||
### Key Controls & Information
|
||||
* **Severity Filter**: Filter events by `ALL`, `CRITICAL`, `ERROR`, or `WARNING`.
|
||||
* **Temporal Tracking**: View occurrence frequency (`Runs: N`), first seen timestamp, and relative last seen time (e.g. `2m ago`).
|
||||
* **Source Attribution**: Inspect originating Hostname, Machine GUID, and Operating System badge (`Windows` / `Linux`).
|
||||
* **Message Payload**: Inspect the raw extracted log message and normalized signature.
|
||||
* **Auto-Refresh**: Live stream updates automatically; displays the latest 50 active anomaly frames.
|
||||
|
||||
HERMES_API ==>|GET /api/hermes/report| HERMES_AGENT
|
||||
---
|
||||
|
||||
## 3. Fleet Seat Management & Client Provisioning
|
||||
|
||||
**Tab: 💻 Client Seats**
|
||||
|
||||
Manage connected edge forwarders (`Win_Client` and `Linux_Client`), enforce cryptographic seat quotas, and export client configuration profiles.
|
||||
|
||||
### Seat Quota Overview
|
||||
* Displays the current seat consumption ratio (e.g., `3 / 25 Seats in Use`).
|
||||
* Unlicensed servers allow local log collection (`0 / 0 Seats`) while blocking remote mTLS forwarders until a license is imported.
|
||||
|
||||
### Managing Enrolled Forwarders
|
||||
The client seat table lists every registered forwarder with its Machine Identifier, Hostname, OS Type, IP Address, First Enrolled date, and Status:
|
||||
* **🟢 Active**: The forwarder has valid mTLS certificates and is actively streaming logs.
|
||||
* **🔴 Revoked**: The forwarder's mTLS certificate has been administratively revoked. Ingestion from this client is rejected.
|
||||
* **Action Buttons**:
|
||||
* **Revoke**: Temporarily revoke a client's seat and deny incoming connections.
|
||||
* **Reactivate / Approve**: Re-enable a previously revoked client seat.
|
||||
* **Delete**: Remove the client record and release the seat back to the available pool.
|
||||
|
||||
### Exporting Client Configuration
|
||||
Click **📥 Download Client Config** to generate and download `client_config.json`.
|
||||
* Contains the server's connection endpoints (`server_host:9443`), Sub-CA public certificate, encryption fingerprint, and enrollment secret.
|
||||
* Distribute this file to edge forwarders during deployment for instant zero-touch auto-enrollment.
|
||||
|
||||
---
|
||||
|
||||
## 4. Sub-CA & Modular Licensing
|
||||
|
||||
**Tab: 📜 Sub-CA & Licensing**
|
||||
|
||||
Manage the server's Subordinate Certificate Authority (Sub-CA), verify hardware host binding, view active licensed capabilities, and apply license updates.
|
||||
|
||||
### Sub-CA Status & Fingerprints
|
||||
* **CA Subject**: The Distinguished Name (DN) of the local Sub-CA.
|
||||
* **Server Encryption Fingerprint**: SHA-256 / OpenPGP fingerprint for encrypted payloads.
|
||||
* **Validity Period**: Issue date and certificate expiration date.
|
||||
* **Assigned Seat Quota**: Maximum authorized forwarder capacity.
|
||||
|
||||
### ✨ Licensed Capabilities & Feature Modules
|
||||
This section displays all authorized feature modules:
|
||||
* **`enterprise_db`**: Multi-engine external database support (PostgreSQL / MySQL / MariaDB), high-throughput ring buffering, and zero-knowledge data encryption at rest.
|
||||
* *Standard Edition*: If running without an enterprise license, standard local SQLite storage remains active.
|
||||
|
||||
### License Management Operations
|
||||
* **Export License Request (`.lic`)**:
|
||||
Click **📤 Export CSR (.lic)** to download the server's hardware-bound certificate signing request. Send this file to your organization's Master License Authority administrator.
|
||||
* **Import Signed Sub-CA Certificate**:
|
||||
Paste the signed PEM certificate received from the Master Authority into the text area and click **📥 Import Signed Certificate**. The server reloads its SSLContext and updates seat quotas in-flight with zero downtime.
|
||||
* **Live WebSocket Sync**:
|
||||
Click **🔄 Sync with License Hub** to trigger immediate real-time synchronization with `logar.eibl.tech`.
|
||||
|
||||
---
|
||||
|
||||
## 5. Storage Engine & Ingestion Performance
|
||||
|
||||
**Tab: 🗄️ Database Engine**
|
||||
|
||||
Configure ingestion buffering, payload encryption at rest, and database backends.
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ 1. INGESTION RING BUFFER & BATCH FLUSHER (Top) │
|
||||
│ • Mode: Direct (Sync) / In-Memory Ring Buffer │
|
||||
│ • Batch Flush Interval (sec) & Batch Size (events) │
|
||||
├─────────────────────────────────────────────────────────────┤
|
||||
│ 2. PAYLOAD ENCRYPTION AT REST (Middle) │
|
||||
│ • Toggle: OpenPGP / RSA-2048 Payload Encryption │
|
||||
├─────────────────────────────────────────────────────────────┤
|
||||
│ 3. STORAGE BACKEND SELECTION (Bottom) │
|
||||
│ • Local SQLite (WAL Mode) │
|
||||
│ • External SQL Server (PostgreSQL / MySQL / MariaDB) │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
### 1. Ingestion Ring Buffer (Top Section)
|
||||
Tune log ingestion throughput to prevent socket I/O bottlenecks during high-volume spikes:
|
||||
* **Cache Mode**:
|
||||
* **Direct (Synchronous)**: Commits incoming log batches immediately to disk. Recommended for small deployments (< 20 nodes).
|
||||
* **In-Memory Ring Buffer**: Places incoming events into an in-memory queue. A background thread flushes events in atomic batches. Recommended for large fleets (> 50 nodes).
|
||||
* **Batch Flush Interval**: Time in seconds between automated queue commits (default: `2.0s`).
|
||||
* **Batch Size**: Maximum events processed per database commit transaction (default: `100`).
|
||||
* *Note: Ingestion buffering is an explicit opt-in setting and is not auto-enabled.*
|
||||
|
||||
## 2. Database Storage Engine Management
|
||||
### 2. Payload Encryption at Rest (Middle Section)
|
||||
* **Encrypt Payloads at Rest**: When enabled, log message payloads (`event_data`) stored in external databases are encrypted using the server's X.509 RSA-2048 / OpenPGP public key.
|
||||
* **Zero-Knowledge Guarantee**: Database administrators or compromised SQL servers cannot read raw logs without the private key resident on the LOGAR Server Hub.
|
||||
* *Note: Encryption at rest is an explicit opt-in setting.*
|
||||
|
||||
LOGAR supports dual storage backends: an embedded **Local SQLite 3 (WAL Mode)** engine and an **External PostgreSQL Database Server** for enterprise clustering.
|
||||
|
||||
### Local SQLite 3 (WAL Mode)
|
||||
- **Status**: Standard Default (Included out of the box, zero configuration required).
|
||||
- **Optimization**: Operates with Write-Ahead Logging (`PRAGMA journal_mode=WAL;`), asynchronous normal synchronization (`PRAGMA synchronous=NORMAL;`), and memory-mapped I/O (`PRAGMA mmap_size=268435456;`).
|
||||
- **File Location**: Configurable via `db_path` in `server_config.json` (defaults to `logar_state.db`).
|
||||
|
||||
### External PostgreSQL Enterprise Backend
|
||||
- **Requirement**: Unlocked via the `enterprise_db` license capability.
|
||||
- **Benefits**: Enables horizontal database scalability, clustering, multi-node replication, and centralized enterprise backup policies.
|
||||
- **Connection Parameters**:
|
||||
- **Host / IP**: Database hostname or IP address.
|
||||
- **Port**: Default `5432`.
|
||||
- **Database**: Target schema/database name (default `logar`).
|
||||
- **Username / Password**: Authentication credentials.
|
||||
- **SSL Mode**: Supports `prefer`, `require`, `verify-ca`, `verify-full`, `disable`, and `allow`.
|
||||
- **Connect Timeout**: Timeout in seconds (default `5`s).
|
||||
- **Connection Pool Size**: Maximum pooled persistent connections (default `10`).
|
||||
|
||||
### Automated SQLite to PostgreSQL Migration
|
||||
Administrators can migrate all historical logs, runs, active issues, seat allocations, users, and tokens from SQLite to PostgreSQL directly in the WebUI (`💾 DB Engine` -> `🚀 Migrate SQLite Data to PostgreSQL`) or via API (`POST /api/db/migrate-to-postgres`):
|
||||
1. Flushes any in-memory telemetry buffers to SQLite.
|
||||
2. Connects to PostgreSQL and verifies/initializes the schema.
|
||||
3. Automatically transfers records table-by-table with validation.
|
||||
4. Returns a detailed count of all migrated records.
|
||||
### 3. Database Backend Selection (Bottom Section)
|
||||
Switch between local file storage and external SQL servers:
|
||||
* **Local SQLite (WAL Mode)**:
|
||||
* Default, zero-configuration embedded database located at `logar_state.db`.
|
||||
* Operates with Write-Ahead Logging (WAL) for high concurrency.
|
||||
* **External SQL Server (PostgreSQL / MySQL / MariaDB)**:
|
||||
* Select your database dialect (**PostgreSQL** or **MySQL / MariaDB**).
|
||||
* Enter **Host**, **Port**, **Database Name**, **Username**, and **Password**.
|
||||
* Click **💾 Save & Apply Storage Configuration**.
|
||||
* The server tests connectivity, initializes required tables and indices, and migrates operational state seamlessly.
|
||||
* *Licensing Note: External SQL backend options require the `enterprise_db` licensed capability. If unlicensed, these controls are visible but gracefully disabled.*
|
||||
|
||||
---
|
||||
|
||||
## 3. Telemetry Ingestion Cache & Buffer Tuning
|
||||
## 6. Hermes AI Tokens & Integration
|
||||
|
||||
### Ingestion Modes: Direct Write vs In-Memory Queue Buffer
|
||||
**Tab: 🤖 Hermes AI**
|
||||
|
||||
| Feature | ⚡ Immediate Direct Write | 🚀 In-Memory Queue Buffer (`enterprise_db`) |
|
||||
| :--- | :--- | :--- |
|
||||
| **Ingress Latency** | Low latency, immediate DB commit | Microsecond ingestion, non-blocking |
|
||||
| **Throughput** | Up to 1,500 events/sec | Up to 50,000+ events/sec |
|
||||
| **Disk I/O** | Continuous write cycles | Atomic batch flushing |
|
||||
| **License** | Standard Community Edition | Enterprise License (`enterprise_db`) |
|
||||
Provision dedicated access tokens for Hermes AI agents to ingest anomalous telemetry.
|
||||
|
||||
### Tuning Parameters & Metrics
|
||||
When **In-Memory Queue Buffer** is enabled, administrators can tune the buffer engine:
|
||||
- **Flush Interval (seconds)**: Maximum elapsed time before buffered anomalies are written to storage (e.g. `2.0`s).
|
||||
- **Batch Size Threshold**: Number of buffered events that triggers an immediate atomic flush (e.g. `100` events).
|
||||
- **Max Buffer Capacity**: Upper ceiling of buffered items in memory (e.g. `50,000` events) to protect system RAM under heavy load.
|
||||
### Managing Access Tokens
|
||||
* **Create Token**: Enter an agent name (e.g. `Hermes-Production-Cluster`) and click **➕ Generate Token**.
|
||||
* **Token Attributes**: View Token Name, Creation Date, Last Used Timestamp, and Status (`Active` / `Revoked`).
|
||||
* **Revoke / Delete**: Instantly revoke access for compromised tokens or permanently delete retired tokens.
|
||||
|
||||
### Manual Flush & Buffer Monitoring
|
||||
- **Live Monitoring**: The KPI card displays live buffer size, total events ingested, total flushed, and average flush latency.
|
||||
- **Manual Trigger**: Click **`🌊 Flush Buffer Now`** or call `POST /api/db/flush-buffer` to force an immediate buffer drain.
|
||||
|
||||
---
|
||||
|
||||
## 4. Zero-Knowledge OpenPGP Data Encryption at Rest
|
||||
|
||||
### Encryption Mechanism
|
||||
When **Data Encryption at Rest** is enabled (`encrypt_at_rest: true`):
|
||||
- All sensitive log payloads, anomaly messages, and raw traces are encrypted with the server's OpenPGP public key before writing to the database table (`active_issues.message`).
|
||||
- Remote database administrators or third-party database hosting providers only see armored OpenPGP ciphertext (`-----BEGIN PGP MESSAGE-----`).
|
||||
|
||||
### Transparent Authorized Decryption
|
||||
- The central LOGAR hub instance holds the private OpenPGP key in protected memory.
|
||||
- When authenticated administrators access the WebUI or when authorized Hermes AI instances query `/api/hermes/report`, the server transparently decrypts records on-the-fly.
|
||||
|
||||
---
|
||||
|
||||
## 5. Subordinate CA & Dynamic PKI Licensing
|
||||
|
||||
LOGAR utilizes a hierarchical Public Key Infrastructure (PKI) for cryptographic client identity and license seat enforcement.
|
||||
|
||||
### Hierarchical PKI & Custom X.509 OIDs
|
||||
The Master Authority (`logar.eibl.tech`) signs the hub's Subordinate CA certificate (`certs/ca.crt`), embedding custom ASN.1 OIDs:
|
||||
- **`1.3.6.1.4.1.58888.1.1` (Seat Quota)**: Encodes the authorized edge client seat capacity (e.g. `25` seats).
|
||||
- **`1.3.6.1.4.1.58888.1.2` (Master Authority URL)**: Identifies the upstream licensing authority.
|
||||
- **`1.3.6.1.4.1.58888.1.3` (Feature Capabilities)**: Comma-delimited list of granted features (e.g. `enterprise_db,ai_heuristics`).
|
||||
|
||||
### Licensed Feature Capabilities (`enterprise_db`)
|
||||
The **📜 Sub-CA & Licensing** tab displays all active licensed features:
|
||||
- **`enterprise_db`**: Authorizes external PostgreSQL database pooling, high-throughput in-memory RAM buffering, and OpenPGP data-at-rest encryption.
|
||||
|
||||
### Importing `.lic` Activation Packages
|
||||
1. In the WebUI, navigate to **📜 Sub-CA & Licensing** and click **`📥 Import License (.lic)`**.
|
||||
2. Select your `.lic` bundle or paste the JSON package.
|
||||
3. The server immediately reloads the PKI trust chain and hot-reloads the active mTLS `SSLContext` without downtime.
|
||||
|
||||
### Automated mTLS License Renewal
|
||||
- Click **`🔄 Sync & Renew via mTLS`** in the WebUI or run:
|
||||
```bash
|
||||
python src/Server.py --sync-license
|
||||
```
|
||||
- The hub connects to `logar.eibl.tech` over mTLS, sends its current seat utilization, and retrieves an updated signed CA certificate.
|
||||
|
||||
---
|
||||
|
||||
## 6. Fleet Forwarder Management & Seat Provisioning
|
||||
|
||||
### Zero-Touch Linux Deployment
|
||||
Run the automated single-line installer on target Linux servers:
|
||||
```bash
|
||||
sudo ./compilation/install_linux_client.sh "http://<HUB_IP>:8443" "<ENROLLMENT_SECRET>"
|
||||
### Connecting Hermes AI
|
||||
Configure Hermes AI agents to query the structured anomaly stream:
|
||||
```http
|
||||
GET http://<SERVER_IP>:8443/api/hermes/report
|
||||
Authorization: Bearer hermes_live_xxxxxxxxxxxxxxxx
|
||||
```
|
||||
- Automatically generates a 2048-bit RSA client keypair.
|
||||
- Enrolls with the hub and receives a signed client certificate.
|
||||
- Deploys and starts the `logar-client.service` systemd unit.
|
||||
|
||||
### Windows Edge Client Deployment
|
||||
1. Download and run `LOGAR-Client-Setup.exe` on the Windows host.
|
||||
2. In the Server WebUI, click **`📥 Export Client Profile`** and download `client_config.json`.
|
||||
3. Place `client_config.json` into `C:\Program Files\LOGAR\client_config.json`.
|
||||
4. The `LOGAR_Client` service automatically boots and connects via mTLS.
|
||||
|
||||
### Seat Lifecycle: Approve, Revoke, Delete
|
||||
In the **💻 Fleet Forwarders** tab:
|
||||
- **Revoke**: Temporarily blocks the node at the TLS handshake level (`ssl.CERT_REQUIRED`).
|
||||
- **Approve**: Re-activates a revoked node and restores telemetry ingestion.
|
||||
- **Remove**: Permanently deletes the client record and immediately frees the leased seat quota.
|
||||
* Or via query parameter: `http://<SERVER_IP>:8443/api/hermes/report?token=hermes_live_xxxxxxxxxxxxxxxx`
|
||||
|
||||
---
|
||||
|
||||
## 7. Hermes AI Agent Integration
|
||||
## 7. User Account & 2FA Security
|
||||
|
||||
### Dedicated Bearer Tokens
|
||||
1. Navigate to **🤖 Hermes AI & Tokens** in the WebUI.
|
||||
2. Enter a descriptive token name (e.g. `Hermes-Autonomous-SecOps`) and click **`Generate Token`**.
|
||||
3. Copy the Bearer token for Hermes agent configuration.
|
||||
**Menu: ⚙️ User Settings**
|
||||
|
||||
### 12-Hour Temporal Persistence Anomaly Stream
|
||||
Hermes queries the real-time anomaly stream:
|
||||
```bash
|
||||
curl -H "Authorization: Bearer hermes_xxxxxxxxxxxx" http://<HUB_IP>:8443/api/hermes/report
|
||||
```
|
||||
### Changing Administrative Credentials
|
||||
1. Click the **Admin Profile** icon in the navigation bar.
|
||||
2. Enter a new Username and Password.
|
||||
3. Click **Update Account**.
|
||||
|
||||
#### JSON Telemetry Format:
|
||||
```json
|
||||
[
|
||||
{
|
||||
"fingerprint": "corp-dc:srv-db-01:postgres_wal_checkpoint_delay",
|
||||
"site": "corp-dc",
|
||||
"server": "srv-db-01",
|
||||
"signature": "postgres_wal_checkpoint_delay",
|
||||
"severity": "WARNING",
|
||||
"message": "WAL checkpoint write duration exceeded 30000ms threshold",
|
||||
"os_type": "linux",
|
||||
"first_seen": "2026-09-30 14:10:00",
|
||||
"last_seen": "2026-09-30 17:42:15",
|
||||
"consecutive_runs": 4,
|
||||
"evaluation_window": "12h",
|
||||
"verified": true,
|
||||
"status": "VERIFIED"
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 8. Security, Authentication & 2FA
|
||||
|
||||
### Password Policies & PBKDF2 Hashing
|
||||
- User passwords are protected using PBKDF2-HMAC-SHA256 with 100,000 iterations and 16-byte random salts.
|
||||
- Change admin credentials via the user avatar menu -> **🔑 Change Password**.
|
||||
|
||||
### Time-Based One-Time Password (TOTP 2FA)
|
||||
- Standard RFC 6238 TOTP with standard 30-second drift windows.
|
||||
- Configure via avatar menu -> **🛡️ Two-Factor Auth (2FA)**.
|
||||
- Compatible with Google Authenticator, Authy, 1Password, and Bitwarden.
|
||||
|
||||
### Sliding Window IP Rate Limiting
|
||||
- **Brute-Force Protection**: Enforces rate limiting on `/login` and `/api/client/enroll`.
|
||||
- Excess failed attempts trigger automatic IP blocking with sliding exponential backoff.
|
||||
|
||||
---
|
||||
|
||||
## 9. Configuration Reference & CLI Flags
|
||||
|
||||
### `server_config.json` Specification
|
||||
|
||||
```json
|
||||
{
|
||||
"server_name": "LOGAR-Cloud-Hub",
|
||||
"tcp_host": "0.0.0.0",
|
||||
"tcp_port": 9443,
|
||||
"hermes_host": "0.0.0.0",
|
||||
"hermes_port": 8443,
|
||||
"admin_user": "admin",
|
||||
"enrollment_secret": "9a7f8e...4b",
|
||||
"max_seats": 25,
|
||||
"license_status": "active",
|
||||
"license_server_url": "https://logar.eibl.tech",
|
||||
"cert_dir": "certs",
|
||||
"tls_enabled": true,
|
||||
"db_path": "logar_state.db",
|
||||
"storage_engine": "sqlite",
|
||||
"cache_mode": "direct",
|
||||
"flush_interval": 2.0,
|
||||
"batch_size": 100,
|
||||
"max_queue": 50000,
|
||||
"encrypt_at_rest": false,
|
||||
"server_fingerprint": "6FF5BE81...",
|
||||
"public_key": "-----BEGIN PGP PUBLIC KEY BLOCK-----\n...",
|
||||
"private_key": "-----BEGIN PGP PRIVATE KEY BLOCK-----\n..."
|
||||
}
|
||||
```
|
||||
|
||||
### CLI Arguments
|
||||
|
||||
| Flag | Description |
|
||||
| :--- | :--- |
|
||||
| `--config <path>` | Path to server configuration JSON file |
|
||||
| `--create-client-config` | Exports a client config bundle and exits |
|
||||
| `--client-out <path>` | Destination path for exported client configuration |
|
||||
| `--server-host <host>` | Embedded target host for exported client configuration |
|
||||
| `--server-port <port>` | Embedded target port for exported client configuration |
|
||||
| `--export-lic <path>` | Exports a `.lic` CSR activation request package |
|
||||
| `--import-lic <path>` | Imports and activates a signed `.lic` license package |
|
||||
| `--sync-license` | Connects to master authority to renew certificate & seats |
|
||||
|
||||
---
|
||||
|
||||
## 10. REST API Reference
|
||||
|
||||
| Method | Endpoint | Auth | Description |
|
||||
| :--- | :--- | :--- | :--- |
|
||||
| `GET` | `/health` | None | Health check, server name, and TLS status |
|
||||
| `POST` | `/api/client/enroll` | Secret | Edge forwarder mTLS enrollment & certificate issuance |
|
||||
| `GET` | `/api/clients` | Admin | List registered forwarders, activity times, and seat quota |
|
||||
| `POST` | `/api/clients/approve` | Admin | Reactivate / approve an enrolled forwarder seat |
|
||||
| `POST` | `/api/clients/revoke` | Admin | Revoke an enrolled forwarder seat |
|
||||
| `POST` | `/api/clients/delete` | Admin | Remove forwarder record and permanently free seat |
|
||||
| `GET` | `/api/hermes/report` | Hermes/Admin | Stream verified anomalies within 12h temporal window |
|
||||
| `POST` | `/api/hermes/tokens/create` | Admin | Generate a named Bearer token for Hermes AI |
|
||||
| `POST` | `/api/hermes/tokens/revoke` | Admin | Revoke an existing Hermes Bearer token |
|
||||
| `GET` | `/api/db/stats` | Admin | Telemetry buffer stats, queue metrics, and storage info |
|
||||
| `POST` | `/api/db/flush-buffer` | Admin | Force immediate drain and write of buffered telemetry |
|
||||
| `POST` | `/api/db/test-connection` | Admin | Test external PostgreSQL connectivity (`enterprise_db`) |
|
||||
| `POST` | `/api/db/switch-backend` | Admin | Switch backend between SQLite and PostgreSQL (`enterprise_db`) |
|
||||
| `POST` | `/api/db/config` | Admin | Persist DB engine, cache mode, and encryption settings |
|
||||
| `POST` | `/api/db/migrate-to-postgres` | Admin | Migrate SQLite tables to PostgreSQL (`enterprise_db`) |
|
||||
| `GET` | `/api/license/status` | Admin | Subordinate CA status, seat quota, and licensed features |
|
||||
| `POST` | `/api/license/import` | Admin | Import `.lic` bundle or signed CA PEM |
|
||||
| `POST` | `/api/license/sync` | Admin | Sync license seats with master authority over mTLS |
|
||||
|
||||
---
|
||||
|
||||
## 11. Operational Runbook & Troubleshooting
|
||||
|
||||
### Diagnostic Checklist
|
||||
|
||||
1. **Verify Hub Service Status**:
|
||||
```bash
|
||||
# Linux
|
||||
sudo systemctl status logar-server.service
|
||||
# Windows PowerShell
|
||||
Get-Service LOGAR_Server
|
||||
```
|
||||
2. **Check Health Endpoint**:
|
||||
```bash
|
||||
curl http://localhost:8443/health
|
||||
```
|
||||
3. **Inspect Active Anomaly Telemetry**:
|
||||
```bash
|
||||
curl -H "Authorization: Bearer <ADMIN_OR_HERMES_TOKEN>" http://localhost:8443/api/hermes/report
|
||||
```
|
||||
4. **Certificate Validity Check**:
|
||||
```bash
|
||||
openssl x509 -in certs/ca.crt -text -noout | grep -A 2 "Validity"
|
||||
```
|
||||
|
||||
### Common Issues & Remediation
|
||||
|
||||
- **Issue: Forwarder rejected with `Connection Refused` or `TLS Handshake Failure`**:
|
||||
- Ensure port `9443` is reachable through host and cloud firewalls.
|
||||
- Verify edge node clock synchronization (NTP) with the server hub.
|
||||
- Confirm the client certificate has not been revoked in the **Fleet Forwarders** tab.
|
||||
- **Issue: `403 Forbidden` on PostgreSQL or Buffering settings**:
|
||||
- The `enterprise_db` feature capability is required. Verify your license in **📜 Sub-CA & Licensing**.
|
||||
- **Issue: Rate limit lock on admin login**:
|
||||
- Wait 60 seconds for the sliding attempt window to expire, or authenticate via an existing active session.
|
||||
### Two-Factor Authentication (TOTP 2FA)
|
||||
Enhance login security with RFC 6238 Time-Based One-Time Passwords:
|
||||
1. Click **🔒 Setup Two-Factor Authentication**.
|
||||
2. Scan the displayed QR Code using your preferred authenticator app (Google Authenticator, Microsoft Authenticator, 1Password, etc.).
|
||||
3. Enter the 6-digit verification code from your authenticator app to confirm activation.
|
||||
4. Subsequent logins will require your password followed by the 6-digit TOTP code.
|
||||
|
||||
@@ -0,0 +1,194 @@
|
||||
# WebUI Administrator Guide
|
||||
|
||||
Welcome to the **LOGAR WebUI Administrator Guide**. This guide provides step-by-step instructions for managing and operating the LOGAR Server Hub through its graphical web console (`:8443/webui`).
|
||||
|
||||
For deep architectural design, cryptographic protocols, X.509 OID schemas, and full REST API specifications, please refer to the dedicated technical wiki pages:
|
||||
* **[Architecture & Design](https://gitea.eibl.tech/me0nline/LOGAR/wiki/Architecture-and-Design)**
|
||||
* **[PKI & Licensing](https://gitea.eibl.tech/me0nline/LOGAR/wiki/PKI-and-Licensing)**
|
||||
* **[State Machines & Lifecycles](https://gitea.eibl.tech/me0nline/LOGAR/wiki/State-Machines-and-Lifecycles)**
|
||||
* **[API Reference](https://gitea.eibl.tech/me0nline/LOGAR/wiki/API-Reference)**
|
||||
|
||||
---
|
||||
|
||||
## Table of Contents
|
||||
|
||||
1. [Accessing the Web Console & Authentication](#1-accessing-the-web-console--authentication)
|
||||
2. [Dashboard: Live Verified Telemetry](#2-dashboard-live-verified-telemetry)
|
||||
3. [Fleet Seat Management & Client Provisioning](#3-fleet-seat-management--client-provisioning)
|
||||
4. [Sub-CA & Modular Licensing](#4-sub-ca--modular-licensing)
|
||||
5. [Storage Engine & Ingestion Performance](#5-storage-engine--ingestion-performance)
|
||||
6. [Hermes AI Tokens & Integration](#6-hermes-ai-tokens--integration)
|
||||
7. [User Account & 2FA Security](#7-user-account--2fa-security)
|
||||
|
||||
---
|
||||
|
||||
## 1. Accessing the Web Console & Authentication
|
||||
|
||||
The LOGAR Server Hub provides an authenticated web management portal accessible from any modern web browser.
|
||||
|
||||
### URL & Port
|
||||
* **Management Console URL**: `http://<SERVER_IP>:8443/webui`
|
||||
* **Protocol**: HTTP (or HTTPS behind an enterprise reverse proxy / load balancer)
|
||||
|
||||
### Default Credentials
|
||||
Upon first launch, LOGAR initializes default administrative credentials:
|
||||
* **Username**: `admin`
|
||||
* **Password**: `admin_logar_2026!`
|
||||
|
||||
> **Security Recommendation**: Change the default credentials immediately after initial deployment using the **User Settings** menu.
|
||||
|
||||
---
|
||||
|
||||
## 2. Dashboard: Live Verified Telemetry
|
||||
|
||||
**Tab: 📊 Live Telemetry**
|
||||
|
||||
The Live Telemetry view displays real-time anomalous log events aggregated across all enrolled Windows and Linux edge forwarders.
|
||||
|
||||
### Key Controls & Information
|
||||
* **Severity Filter**: Filter events by `ALL`, `CRITICAL`, `ERROR`, or `WARNING`.
|
||||
* **Temporal Tracking**: View occurrence frequency (`Runs: N`), first seen timestamp, and relative last seen time (e.g. `2m ago`).
|
||||
* **Source Attribution**: Inspect originating Hostname, Machine GUID, and Operating System badge (`Windows` / `Linux`).
|
||||
* **Message Payload**: Inspect the raw extracted log message and normalized signature.
|
||||
* **Auto-Refresh**: Live stream updates automatically; displays the latest 50 active anomaly frames.
|
||||
|
||||
---
|
||||
|
||||
## 3. Fleet Seat Management & Client Provisioning
|
||||
|
||||
**Tab: 💻 Client Seats**
|
||||
|
||||
Manage connected edge forwarders (`Win_Client` and `Linux_Client`), enforce cryptographic seat quotas, and export client configuration profiles.
|
||||
|
||||
### Seat Quota Overview
|
||||
* Displays the current seat consumption ratio (e.g., `3 / 25 Seats in Use`).
|
||||
* Unlicensed servers allow local log collection (`0 / 0 Seats`) while blocking remote mTLS forwarders until a license is imported.
|
||||
|
||||
### Managing Enrolled Forwarders
|
||||
The client seat table lists every registered forwarder with its Machine Identifier, Hostname, OS Type, IP Address, First Enrolled date, and Status:
|
||||
* **🟢 Active**: The forwarder has valid mTLS certificates and is actively streaming logs.
|
||||
* **🔴 Revoked**: The forwarder's mTLS certificate has been administratively revoked. Ingestion from this client is rejected.
|
||||
* **Action Buttons**:
|
||||
* **Revoke**: Temporarily revoke a client's seat and deny incoming connections.
|
||||
* **Reactivate / Approve**: Re-enable a previously revoked client seat.
|
||||
* **Delete**: Remove the client record and release the seat back to the available pool.
|
||||
|
||||
### Exporting Client Configuration
|
||||
Click **📥 Download Client Config** to generate and download `client_config.json`.
|
||||
* Contains the server's connection endpoints (`server_host:9443`), Sub-CA public certificate, encryption fingerprint, and enrollment secret.
|
||||
* Distribute this file to edge forwarders during deployment for instant zero-touch auto-enrollment.
|
||||
|
||||
---
|
||||
|
||||
## 4. Sub-CA & Modular Licensing
|
||||
|
||||
**Tab: 📜 Sub-CA & Licensing**
|
||||
|
||||
Manage the server's Subordinate Certificate Authority (Sub-CA), verify hardware host binding, view active licensed capabilities, and apply license updates.
|
||||
|
||||
### Sub-CA Status & Fingerprints
|
||||
* **CA Subject**: The Distinguished Name (DN) of the local Sub-CA.
|
||||
* **Server Encryption Fingerprint**: SHA-256 / OpenPGP fingerprint for encrypted payloads.
|
||||
* **Validity Period**: Issue date and certificate expiration date.
|
||||
* **Assigned Seat Quota**: Maximum authorized forwarder capacity.
|
||||
|
||||
### ✨ Licensed Capabilities & Feature Modules
|
||||
This section displays all authorized feature modules:
|
||||
* **`enterprise_db`**: Multi-engine external database support (PostgreSQL / MySQL / MariaDB), high-throughput ring buffering, and zero-knowledge data encryption at rest.
|
||||
* *Standard Edition*: If running without an enterprise license, standard local SQLite storage remains active.
|
||||
|
||||
### License Management Operations
|
||||
* **Export License Request (`.lic`)**:
|
||||
Click **📤 Export CSR (.lic)** to download the server's hardware-bound certificate signing request. Send this file to your organization's Master License Authority administrator.
|
||||
* **Import Signed Sub-CA Certificate**:
|
||||
Paste the signed PEM certificate received from the Master Authority into the text area and click **📥 Import Signed Certificate**. The server reloads its SSLContext and updates seat quotas in-flight with zero downtime.
|
||||
* **Live WebSocket Sync**:
|
||||
Click **🔄 Sync with License Hub** to trigger immediate real-time synchronization with `logar.eibl.tech`.
|
||||
|
||||
---
|
||||
|
||||
## 5. Storage Engine & Ingestion Performance
|
||||
|
||||
**Tab: 🗄️ Database Engine**
|
||||
|
||||
Configure ingestion buffering, payload encryption at rest, and database backends.
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ 1. INGESTION RING BUFFER & BATCH FLUSHER (Top) │
|
||||
│ • Mode: Direct (Sync) / In-Memory Ring Buffer │
|
||||
│ • Batch Flush Interval (sec) & Batch Size (events) │
|
||||
├─────────────────────────────────────────────────────────────┤
|
||||
│ 2. PAYLOAD ENCRYPTION AT REST (Middle) │
|
||||
│ • Toggle: OpenPGP / RSA-2048 Payload Encryption │
|
||||
├─────────────────────────────────────────────────────────────┤
|
||||
│ 3. STORAGE BACKEND SELECTION (Bottom) │
|
||||
│ • Local SQLite (WAL Mode) │
|
||||
│ • External SQL Server (PostgreSQL / MySQL / MariaDB) │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
### 1. Ingestion Ring Buffer (Top Section)
|
||||
Tune log ingestion throughput to prevent socket I/O bottlenecks during high-volume spikes:
|
||||
* **Cache Mode**:
|
||||
* **Direct (Synchronous)**: Commits incoming log batches immediately to disk. Recommended for small deployments (< 20 nodes).
|
||||
* **In-Memory Ring Buffer**: Places incoming events into an in-memory queue. A background thread flushes events in atomic batches. Recommended for large fleets (> 50 nodes).
|
||||
* **Batch Flush Interval**: Time in seconds between automated queue commits (default: `2.0s`).
|
||||
* **Batch Size**: Maximum events processed per database commit transaction (default: `100`).
|
||||
* *Note: Ingestion buffering is an explicit opt-in setting and is not auto-enabled.*
|
||||
|
||||
### 2. Payload Encryption at Rest (Middle Section)
|
||||
* **Encrypt Payloads at Rest**: When enabled, log message payloads (`event_data`) stored in external databases are encrypted using the server's X.509 RSA-2048 / OpenPGP public key.
|
||||
* **Zero-Knowledge Guarantee**: Database administrators or compromised SQL servers cannot read raw logs without the private key resident on the LOGAR Server Hub.
|
||||
* *Note: Encryption at rest is an explicit opt-in setting.*
|
||||
|
||||
### 3. Database Backend Selection (Bottom Section)
|
||||
Switch between local file storage and external SQL servers:
|
||||
* **Local SQLite (WAL Mode)**:
|
||||
* Default, zero-configuration embedded database located at `logar_state.db`.
|
||||
* Operates with Write-Ahead Logging (WAL) for high concurrency.
|
||||
* **External SQL Server (PostgreSQL / MySQL / MariaDB)**:
|
||||
* Select your database dialect (**PostgreSQL** or **MySQL / MariaDB**).
|
||||
* Enter **Host**, **Port**, **Database Name**, **Username**, and **Password**.
|
||||
* Click **💾 Save & Apply Storage Configuration**.
|
||||
* The server tests connectivity, initializes required tables and indices, and migrates operational state seamlessly.
|
||||
* *Licensing Note: External SQL backend options require the `enterprise_db` licensed capability. If unlicensed, these controls are visible but gracefully disabled.*
|
||||
|
||||
---
|
||||
|
||||
## 6. Hermes AI Tokens & Integration
|
||||
|
||||
**Tab: 🤖 Hermes AI**
|
||||
|
||||
Provision dedicated access tokens for Hermes AI agents to ingest anomalous telemetry.
|
||||
|
||||
### Managing Access Tokens
|
||||
* **Create Token**: Enter an agent name (e.g. `Hermes-Production-Cluster`) and click **➕ Generate Token**.
|
||||
* **Token Attributes**: View Token Name, Creation Date, Last Used Timestamp, and Status (`Active` / `Revoked`).
|
||||
* **Revoke / Delete**: Instantly revoke access for compromised tokens or permanently delete retired tokens.
|
||||
|
||||
### Connecting Hermes AI
|
||||
Configure Hermes AI agents to query the structured anomaly stream:
|
||||
```http
|
||||
GET http://<SERVER_IP>:8443/api/hermes/report
|
||||
Authorization: Bearer hermes_live_xxxxxxxxxxxxxxxx
|
||||
```
|
||||
* Or via query parameter: `http://<SERVER_IP>:8443/api/hermes/report?token=hermes_live_xxxxxxxxxxxxxxxx`
|
||||
|
||||
---
|
||||
|
||||
## 7. User Account & 2FA Security
|
||||
|
||||
**Menu: ⚙️ User Settings**
|
||||
|
||||
### Changing Administrative Credentials
|
||||
1. Click the **Admin Profile** icon in the navigation bar.
|
||||
2. Enter a new Username and Password.
|
||||
3. Click **Update Account**.
|
||||
|
||||
### Two-Factor Authentication (TOTP 2FA)
|
||||
Enhance login security with RFC 6238 Time-Based One-Time Passwords:
|
||||
1. Click **🔒 Setup Two-Factor Authentication**.
|
||||
2. Scan the displayed QR Code using your preferred authenticator app (Google Authenticator, Microsoft Authenticator, 1Password, etc.).
|
||||
3. Enter the 6-digit verification code from your authenticator app to confirm activation.
|
||||
4. Subsequent logins will require your password followed by the 6-digit TOTP code.
|
||||
Reference in New Issue
Block a user