Two commands, and the second one is not optional.
sudo ./install/install.sh --upgrade php ./bin/loghound-schema # then this, every time
The first refreshes the code and never touches config/loghound.php or anything under var/. The second brings your live indexes’ schemas up to date, and the next section is why leaving it out loses data silently.
Your two indexes keep running the configset that was uploaded when they were created. A release that adds a field therefore ships code that writes a field the live schema does not declare — and the only dynamic field in either schema maps everything unrecognised to a type that indexes and stores nothing.
Nothing raises an error: not the ingest daemon, not the platform, not the panel. The first symptom is a facet that is permanently empty, months later, and the values that were dropped are not recoverable. That silence is deliberate on the ingest side — the alternative is one unknown field killing an entire batch and stalling the tailer — which is exactly why the check is a separate command you are told to run.
bin/loghound-schema reads the schema each index is actually running, compares it field by field against the configsets in this checkout, and names what is missing:
$ php bin/loghound-schema Loghound schema check installation : /opt/loghound release : 187edea2d4fb8de4 hits loghound_9f3c17ab_hits BEHIND 3 missing: planes_s, search_terms_ss, install_s sessions loghound_9f3c17ab_sessions CURRENT 106 fields, all present Out of date. Fix it with: php /opt/loghound/bin/loghound-schema --apply
--apply uploads this release’s configsets — schema first, then the solrconfig, then a core reload, the same call and the same order the installer uses. It is additive: it adds the missing fields and does not touch a document already in the index.
| Exit code | Meaning |
|---|---|
0 | Up to date — both live schemas declare every field this release writes |
1 | Unusable configuration, an unknown flag, or no indexes provisioned yet |
2 | Failed — a schema could not be read, or an upload was rejected |
3 | Out of date — an index is missing a field (check mode only) |
Which makes it something a deployment script can gate on:
php bin/loghound-schema || php bin/loghound-schema --apply
- A field your index has that this release does not write is not an error and is never “fixed”. That is a newer schema, or a field a later release dropped, and it costs nothing.
- A schema that could not be read is never reported as matching. The command says so and exits 2, and
--applyrefuses to push to that index — a push replaces the whole configset, so pushing blind over a schema that might be newer would delete the fields that newer release writes. That would be the same silent data loss the tool exists to stop, caused by the tool. - The verdict is written to a file the panel reads, so running the command on the shell updates the Index schema block in the Solr card.
install.sh --upgradenames the command as it finishes. - It refuses to run under a web server, for the same reason the retention command does.
Which is a supported and, on some boxes, the preferred layout. The upgrade is then a fast-forward pull in place:
git fetch --prune origin
git merge --ff-only @{upstream}git reset --hard or git clean
Both would delete config/loghound.php, which is untracked and holds your API key, and var/state.db, which holds the tailer’s read position in every log file. If the checkout has diverged and cannot fast-forward, the upgrade stops and tells you, leaving everything exactly as it was. Local modifications to tracked files are reported but never discarded.
If the prefix is not a checkout, it is a plain file copy instead. The installer says which one it is doing.
- The beacon cache buster.
b.jsis served with a longCache-Control, so the only thing that reaches a returning visitor after an upgrade is a new URL. The panel’s settings page builds the snippet with the beacon file’s own modification time in the?v=slot, so there is nothing to remember; if you hand-wrote the tag instead, bump the number yourself. - Panel assets look after themselves. Every asset URL in the panel carries
?v=taken from the file’s modification time, so an upgrade reaches a browser that cached the old file with nothing to bump. - A changed
LogFormatis a different upgrade. If you take the opportunity to log more headers, re-runbin/loghound-setupso it picks up the new format — otherwise parse errors climb and the bad-line sample fills up. - An older index pair may be missing fields this version writes. That is checked before anything is written and is covered under joining a pair; adding fields only ever adds, and never alters a document already in the index.
php /opt/loghound/bin/loghound-schema loghound-tail --status --human systemctl status loghound-tail.service --no-pager
If the daemon is running but nothing new is indexed, troubleshooting walks through it. Note that a daemon started before an upgrade keeps the configuration it started with; a reload onto a half-finished configuration is refused and logged, which is what makes it safe to leave running while you change things.