LOGAR/out/linux_client/README.md

LOGAR Linux Edge Forwarder

Standalone compiled binary and automated systemd service distribution for Linux edge servers.

---

Overview

Linux_Client.bin is a self-contained, pre-compiled executable that queries systemd-journald via journalctl, filters logs directly at the source, auto-enrolls with the central LOGAR hub, and streams candidate events over mutual TLS 1.3 (mTLS) to the central hub.

Key Capabilities

• Pre-compiled & Dependency-Free: Ships as a standalone native binary (Linux_Client.bin). No Python environment, pip packages, or GnuPG binaries are required on the host.
• Mutual TLS 1.3 (mTLS) Ingestion: Streams directly over hardware-authenticated TLS 1.3 sockets with machine-bound client certificates.
• Automated Client Enrollment: On first run with an enrollment_secret, the client automatically calls POST /api/client/enroll on the hub, saves its certificates into /etc/logar/certs/, and establishes secure mTLS streaming.
• Proactive Expiry Check & Reactive Self-Healing: Before each run, the client evaluates client.crt validity. If within 30 days of expiry, it automatically contacts the hub to renew certificates. If the server Root CA rotates or a TLS handshake error occurs, the client catch-heals by re-enrolling immediately and re-establishing connection without human intervention.
• Source-Level Filtering: Retains events spanning INFO, WARNING, and ERROR (journalctl -p warning). Drops debug noise and skips events older than 24 hours.
• State Tracking & Deduplication: Maintains persistent client state in client_state.json (tracking systemd journalctl cursors and microsecond timestamps) so every log record is forwarded exactly once without duplicates.
• Fail-Safe State Commit: State is committed only when the server returns a verified success response. In the event of a network outage, state remains unchanged and unsent events are retried automatically on the next run.

---

1. Automated Installation via Script (Recommended)

Run the automated installer script:

sudo ./compilation/install_linux_client.sh "http://<HUB_HOST>:8443" "<ENROLLMENT_SECRET>"

This script:

1. Installs the binary to /opt/logar-client/Linux_Client.
2. Creates /etc/logar/certs with strict permissions.
3. Automatically queries /etc/machine-id and enrolls with the hub via curl.
4. Deploys, enables, and starts the systemd service unit /etc/systemd/system/logar-client.service.

---

2. Generating & Deploying the Configuration File

Step 1: Generate client_config.json on the Server

Run the following command on your central LOGAR server:

python src/Server.py --create-client-config --server-host <SERVER_IP_OR_DNS> --server-port 9443 --client-out client_config.json

• Replace <SERVER_IP_OR_DNS> with the reachable IP address or FQDN of your central LOGAR server hub.
• Default mTLS socket port is 9443; Hermes REST API port is 8443.

Step 2: Configuration Structure

The generated client_config.json contains:

{
  "server_host": "192.168.1.100",
  "server_port": 9443,
  "hermes_host": "192.168.1.100",
  "hermes_port": 8443,
  "enrollment_secret": "a1b2c3d4e5f6...",
  "cert_dir": "certs",
  "server_fingerprint": "375388960531264EA0648EC0D2C4E4ABC6F22AC2",
  "server_public_key": "-----BEGIN PGP PUBLIC KEY BLOCK-----\n...",
  "auth_token": "a1b2c3d4e5f6..."
}

Note

The configuration contains no host-specific names or site names to ensure client anonymity and easy redistribution.

Step 3: Copy to Edge Node

Place Linux_Client.bin and client_config.json into the target directory (e.g. /opt/logar/):

sudo mkdir -p /opt/logar
sudo cp Linux_Client.bin client_config.json /opt/logar/
sudo chmod +x /opt/logar/Linux_Client.bin

---

3. Running Manually

Test the forwarder interactively:

cd /opt/logar
./Linux_Client.bin --hours 24

On first run, the client contacts http://<hermes_host>:<hermes_port>/api/client/enroll, downloads ca.crt, client.crt, and client.key into certs/, and streams logs over mTLS.

Command-Line Arguments

Argument	Default	Description
--config	client_config.json	Path to client configuration file
--hours	24	Lookback window in hours for journal logs
--state-file	client_state.json	Path to persistent state file
--no-state	False	Disable state tracking and send all events matching lookback window

---

4. Manual Systemd Service & Timer Setup

Step 1: Create the Systemd Service Unit

Create /etc/systemd/system/logar-client.service:

[Unit]
Description=LOGAR Edge Log Forwarder
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
WorkingDirectory=/opt/logar
ExecStart=/opt/logar/Linux_Client.bin --hours 24
Restart=always
RestartSec=5s
User=root
StandardOutput=journal
StandardError=journal

[Install]
WantedBy=multi-user.target

Step 2: Enable and Start the Service

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

Step 3: Check Logs

sudo journalctl -u logar-client.service -n 50 -f

---

5. Uninstallation & Removal

sudo systemctl disable --now logar-client.service
sudo rm -f /etc/systemd/system/logar-client.service
sudo systemctl daemon-reload
sudo rm -rf /opt/logar-client /opt/logar /etc/logar