Installing the LiteSOC Server Agent

The LiteSOC Agent is a lightweight, open-source Go binary that runs on your servers. It tails system authentication logs in real-time, parses SSH events, and forwards structured security events to LiteSOC. It also sends heartbeats so you can monitor server health from your dashboard.

What the Agent Does

Real-time SSH log parsing — detects auth.login_failed, auth.login_success, and auth.logout events from OpenSSH logs
Heartbeat monitoring — sends a health check every 60 seconds with hostname, OS, CPU, and RAM metrics
Zero dependencies — single static binary, no interpreter or runtime needed
Log rotation safe — handles logrotate via inotify/kqueue with no missed events

Prerequisites

Linux (Debian, Ubuntu, RHEL, Fedora, CentOS, Amazon Linux, Alpine) or macOS
curl and tar installed
A LiteSOC API key from Settings → API Keys
systemd (optional, for service management)

One-Line Install (Recommended)

Run this command on your server:

curl -sSL https://litesoc.io/install.sh | LITESOC_KEY=lsoc_live_your_key bash

The installer will:

Detect your OS and architecture
Download the pre-built binary from GitHub Releases
Write the config file to /etc/litesoc/config.yaml
Store your API key securely in /etc/litesoc/agent.env (mode 0600)
Install and enable a systemd service

You can also copy the install command directly from your Infrastructure Dashboard — it pre-fills your API key and project ID.

Configuration

The config file lives at /etc/litesoc/config.yaml:

api_endpoint: https://api.litesoc.io
heartbeat_interval: 60   # seconds
log_watchers:
  - path: /var/log/auth.log    # Debian/Ubuntu
    type: sshd
  # - path: /var/log/secure    # RHEL/Fedora/CentOS
  #   type: sshd

Field	Default	Description
`api_endpoint`	`https://api.litesoc.io`	LiteSOC ingestion URL
`heartbeat_interval`	`60`	Heartbeat frequency in seconds
`log_watchers[].path`	—	Absolute path to the log file
`log_watchers[].type`	—	Parser type (currently `sshd`)

Security: The API key is never stored in the config file — it is read from the LITESOC_KEY environment variable.

Supported Architectures

OS	Architectures
Linux	`amd64`, `arm64`, `arm`
macOS	`amd64` (Intel), `arm64` (Apple Silicon)

Events Emitted

Event	Trigger	Data
`auth.login_failed`	Failed password or invalid user	actor, source IP, port, reason
`auth.login_success`	Accepted password/publickey	actor, source IP, port
`auth.logout`	Disconnected from	actor, source IP, port

Managing the Service

# Check status
sudo systemctl status litesoc-agent

# View logs
sudo journalctl -u litesoc-agent -f

# Restart after config change
sudo systemctl restart litesoc-agent

Building from Source

git clone https://github.com/litesoc/litesoc-agent.git
cd litesoc-agent
make build        # → bin/litesoc-agent
make build-all    # cross-compile all targets

Run manually:

export LITESOC_KEY=lsoc_live_your_key
./bin/litesoc-agent /etc/litesoc/config.yaml

Verifying the Installation

After installing, check your Infrastructure Dashboard at litesoc.io/dashboard/infrastructure. Your server should appear within 60 seconds with a green "Online" badge.

Next Steps

Need help? Contact our support team or check our API documentation.