me0nline/LOGAR
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 4 Wiki Activity

docs(linux_client): update README.md with mTLS 1.3, dynamic PKI enrollment, and systemd installer script instructions

Browse Source
This commit is contained in:
me0nline
2026-09-04 22:39:09 +02:00
parent b24108a788
commit 4a446a2e73
1 changed files with 45 additions and 58 deletions
Download Patch File Download Diff File Expand all files Collapse all files
out/linux_client/README.md
+45 -58
View File
@@ -1,40 +1,56 @@
# LOGAR Linux Edge Forwarder
Standalone compiled binary distribution for Linux edge servers running systemd.
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, encrypts the payload using OpenPGP, and streams candidate events over an authenticated TCP socket to the central LOGAR hub.
`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 executable binary (`Linux_Client.bin`). No Python environment, pip packages, or GnuPG binaries are required on the host.
- **Source-Level Filtering**: Retains events spanning `INFO`, `WARNING`, and `ERROR` (`journalctl -p info`). Drops debug noise (priority 7) and skips events older than 24 hours.
- **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.
- **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.
- **End-to-End Encryption**: Encrypts payloads using the server's OpenPGP public key before transmission.
---
## 1. Generating & Deploying the Configuration File
## 1. Automated Installation via Script (Recommended)
Run the automated installer script:
```bash
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 to export a client bundle tailored for your environment:
Run the following command on your central LOGAR server:
```bash
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 TCP port is `9443`.
- Default mTLS socket port is `9443`; Hermes REST API port is `8443`.
### Step 2: Configuration Structure
The generated `client_config.json` contains:
```json
{
"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..."
@@ -42,11 +58,10 @@ The generated `client_config.json` contains:
```
> [!NOTE]
> A reference example is provided in `client_config.sample.json`. The configuration file contains **no host-specific names or site names** to ensure client anonymity and easy redistribution.
> 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 (recommended: `/opt/logar/`):
Place `Linux_Client.bin` and `client_config.json` into the target directory (e.g. `/opt/logar/`):
```bash
sudo mkdir -p /opt/logar
sudo cp Linux_Client.bin client_config.json /opt/logar/
@@ -55,14 +70,14 @@ sudo chmod +x /opt/logar/Linux_Client.bin
---
## 2. Running Manually
## 3. Running Manually
Test the forwarder interactively:
```bash
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 |
@@ -74,13 +89,10 @@ cd /opt/logar
---
## 3. Installing as a Systemd Service & Timer (Recommended)
Running `Linux_Client.bin` via a systemd timer ensures reliable periodic execution, automatic restart, and native log integration with `journalctl`.
## 4. Manual Systemd Service & Timer Setup
### Step 1: Create the Systemd Service Unit
Create `/etc/systemd/system/logar-forwarder.service`:
Create `/etc/systemd/system/logar-client.service`:
```ini
[Unit]
Description=LOGAR Edge Log Forwarder
@@ -88,9 +100,11 @@ After=network-online.target
Wants=network-online.target
[Service]
Type=oneshot
Type=simple
WorkingDirectory=/opt/logar
ExecStart=/opt/logar/Linux_Client.bin --hours 24
Restart=always
RestartSec=5s
User=root
StandardOutput=journal
StandardError=journal
@@ -99,51 +113,24 @@ StandardError=journal
WantedBy=multi-user.target
```
### Step 2: Create the Systemd Timer Unit
Create `/etc/systemd/system/logar-forwarder.timer` to execute the forwarder every 3 hours (with a 5-minute initial delay upon boot):
```ini
[Unit]
Description=Run LOGAR Edge Forwarder periodically
Requires=logar-forwarder.service
[Timer]
OnBootSec=5min
OnUnitActiveSec=3h
Persistent=true
[Install]
WantedBy=timers.target
```
### Step 3: Enable and Start the Timer
### Step 2: Enable and Start the Service
```bash
sudo systemctl daemon-reload
sudo systemctl enable --now logar-forwarder.timer
sudo systemctl enable --now logar-client.service
```
### Step 4: Verify Timer & Service Status
### Step 3: Check Logs
```bash
# Check timer schedule
sudo systemctl list-timers --all | grep logar
# Trigger an immediate manual execution
sudo systemctl start logar-forwarder.service
# View execution logs
sudo journalctl -u logar-forwarder.service -n 50
sudo journalctl -u logar-client.service -n 50 -f
```
---
## 4. Alternative: Cron Job Deployment
If systemd timers are not preferred, configure a periodic cron job running every 3 hours:
## 5. Uninstallation & Removal
```bash
# Open root crontab
sudo crontab -e
# Add the following entry:
0 */3 * * * cd /opt/logar && ./Linux_Client.bin --hours 24 >> /var/log/logar_forwarder.log 2>&1
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
```