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