Loghound Documentation

Loghound is an open-source, MIT-licensed traffic analyser for Apache, nginx and Caddy access logs. You run it on your own machine; it keeps what it learns in two Opensolr indexes it provisions for you. This is the complete documentation for it.

New here? Two pages and you will know whether you want it.

What Loghound is says what it does and, just as importantly, what it refuses to do. The three-plane model is the idea the whole product is built on.

01 · The shortest path to a working install

Check the requirements. PHP 8.1 with five extensions, systemd, read access to your logs, and a free Opensolr account.
Run the installer — from a shell, or prepare the machine and finish in a browser.
Let it provision the two indexes, or join a pair your account already holds.
Confirm the log source and its format, and consider the recommended LogFormat.
Add the beacon to your site. Without it, two of the three planes still work, but neither of the reasons this product exists is at full strength.

02 · Every page in this documentation

Start here

Documentation home	You are here.
What Loghound is	The two reasons it exists, and the things it deliberately does not do.
The three-plane model	Transport, behaviour and execution, and why correlating them is the whole idea.
Requirements	What the machine and the Opensolr account have to provide before you start.

Installing

Install from a shell	What install.sh does, in order, and what it will never do.
Where it installs, and modes	The prefix, the file modes, and the one mistake that breaks the panel.
Install from a browser	The three screens, and why a long step runs as a resumable job.
System check & setup token	The system check, and the file only a server administrator can read.
Unattended installs	Answering every prompt from the environment, for Ansible or CI.
Upgrading	Refreshing the code without touching the configuration or the state.

Your Opensolr indexes

Why an account is required	Why there is no bring-your-own-Solr path, and what that costs you.
Provisioning the two indexes	Creating both indexes, pushing the configsets, and the generated names.
Joining a pair you have	Six sites into two indexes, told apart by the hostname on every record.
The plan index limit	How the allowance is read, and what happens if the second create is refused.

Reading your logs

Log sources & detection	Finding the files, reading the format, and confirming the mapping.
The recommended LogFormat	The copy-paste block, and exactly what each extra header buys you.
How far back it can see	Loghound only ever sees as far back as your own log rotation.

The beacon

Installing the beacon	One script tag, and how to check your server is compressing it.
Every option it reads	Every attribute, global and function b.js reads, with defaults.
Identity & signed-in	Attaching who the visitor is, with real WordPress and Drupal code.
Search terms	The one place Loghound stores something a person typed.
A site on another server	Measuring a site on another machine, and what the allowlist does not protect.
Content-Security-Policy	Two directives, and the one people forget.
The four time numbers	Why the industry number is often fifteen times the true one.

Detection

The fingerprint cluster	The signal the product is built around, and its honest limitation.
The signal codes	Every code the beacon can emit, and what each one is worth.
The scoring rules	All seventeen rules with their weights and what they actually test.
Tuning the weights	How to change a weight, and how not to tune towards a number you expected.
False positives	Every category of real human who may be scored as a bot.
Evasion	Written for somebody who wants to defeat it, because that is the useful way.

The panel

How the panel works	Nothing blocks, every card fails alone, and every number states its population.
Overview	Who was here, and how long they actually stayed.
Bot forensics	Why each verdict was reached, as a facet you can click.
Fingerprint clusters	One header signature, many addresses. The hero view.
Networks	ASN, netname and geography, and what to rate-limit.
Session explorer	Search every session and drill into one visit request by request.
Performance	Latency percentiles by path, and the status heatmap.
Virtual hosts	Every site on the machine, side by side, from one installation.
Filters & facets	The URL is the state, and a filtered dimension keeps listing its values.

Your search indexes

Index analytics	What your Opensolr search indexes are being asked, and how well they answer.
Query analysis	Query shapes, and the ones that find nothing every time they run.
Who is querying	Search traffic cross-referenced with web traffic. The view that needs both.
Storage & bandwidth	How much history your plan holds, and the one limit that really bites.

Configuration

Settings, card by card	Every card on the settings page and what each control changes.
Signing in & two-factor	Two modes, the lockout, staying signed in, and two-factor.
Privacy	Field by field, what is stored, what leaves the machine, and the three IP modes.
Retention & disk	A time policy and a size policy, doing different jobs.
Starting over	Resetting the machine without deleting a single document.

Operations

Running it	The daemon, the two timers, and the status document it keeps about itself.
Troubleshooting	The failures that actually happen, and the command that diagnoses each.
Command reference	Every command and every option it takes.
Uninstalling	The teardown order, what it asks first, and what it leaves behind.

Reference

Identifiers & labels	Every stored identifier and the label the panel shows for it.
The Solr schema	Both Solr cores field by field, and what each one costs.
Security model	Threat model, controls by surface, hardening, and the known limits.

03 · Beyond this documentation

github.com/phpcip/loghound — the source, the issue tracker and the releases. The repository also carries SPEC.md, which is the binding technical specification the software is written against.
opensolr.com/loghound — the product overview, if you are still deciding.
The Opensolr platform documentation — for the account, the control panel and the indexes themselves, which Loghound sits on top of.
Security problems go by email with LOGHOUND SECURITY in the subject line, never into a public issue. The security model has the address and what to expect.