diff --git a/out/linux_client/README.md b/out/linux_client/README.md index 09cfed3..25005dd 100644 --- a/out/linux_client/README.md +++ b/out/linux_client/README.md @@ -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://:8443" "" +``` +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-port 9443 --client-out client_config.json ``` - - Replace `` 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://:/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 ```