Command reference

Five commands, plus the installer. The installer links the five into place, so they are on the path as shown; run them as the service user when a path is given explicitly. This page is the one place every option is listed.

Normally run by systemd. Reading its status is a read-only client of the running daemon, so it is safe at any time.

loghound-tail [options]

  --status [--human]   report lag, rate and parse errors from the running daemon
  --once               poll every source once and exit
  --dry-run            parse and count, never write to Solr
  --from-start         a newly seen log file is read from byte 0 (default: from EOF)
  --config=PATH        alternate config file
  --verbose, -v        log every batch
  --help, -h

Run every sixty seconds by a timer. Takes -v or --verbose. Running it by hand is useful after changing a weight, to see the next batch scored under it:

sudo -u loghound php /opt/loghound/bin/loghound-score --verbose

It closes sessions idle past the timeout, publishes the open ones whose aggregate has advanced, merges the beacon rows, computes the fingerprint clusters, runs the ruleset, writes the session documents and rebuilds the daily rollup over settled sessions only.

loghound-retention            delete
loghound-retention --dry-run  report what would be deleted, delete nothing

It runs daily from a timer and does three passes: the age rule, the disk rule, and a clean-up of the local state database. Retention & disk explains each. Exit codes: 0 success, including “nothing to do”; 1 a configuration error; 2 a runtime failure.

On a shared index pair it detects the sharing and deletes only its own documents; if it cannot name its own documents it refuses to run rather than guessing, because an installation with a ninety-day policy must not be able to delete a neighbour’s year.

Run this after every upgrade. It is one read per index and it changes nothing without --apply.

loghound-schema                 compare, change nothing (the default)
loghound-schema --check         the same, spelled out
loghound-schema --apply         upload this release's configsets where they are missing
                                fields, then re-check
loghound-schema --force         upload them even where the fields already match, and reload
                                (implies --apply)
loghound-schema --quiet         print only what is wrong, and the verdict
loghound-schema --help

--force is for a release that changed the index configuration without changing a field: --apply would report everything up to date and upload nothing. It still refuses to push to an index whose live schema could not be read. Set LOGHOUND_CONFIG to run against a configuration file somewhere else.

if loghound-schema --check; then deploy; else echo "run --apply first"; fi

The verdict is also written to a file the panel reads, so running this on the shell updates the Index schema block on the Solr connection card in Settings. Like the retention command, it refuses to run under a web server: --apply reconfigures and reloads a live index, and an unauthenticated route to that is not something to leave lying around. The API key is never printed, by this command or by anything it calls.

loghound-setup [options]

  --detect-only         find the access logs, print what would be asked, change nothing
  --beacon-doc          print the beacon reference (snippet, every option, what is stored,
                        the two CSP directives) and stop
  --base-url=URL        the address --beacon-doc builds its snippet from, when the
                        configuration has no base_url yet
  --reset               set up again on this machine and KEEP your data (see below)
  --non-interactive     answer every prompt from the environment or the offered default
  --interactive         prompt even when stdin does not look like a terminal
  --config=PATH         write somewhere other than config/loghound.php
  --no-color            plain output
  -h, --help

Every prompt defaults to what is stored now, so pressing Enter through it changes nothing. --non-interactive switches on by itself when stdin is not a terminal, because a wizard that blocks forever on a closed stdin is the worst possible failure inside an automated deploy.

The full list of environment variables is on Unattended installs, and --help prints it too.

Runs setup again on this machine without deleting any data. It is narrower than the panel’s Start over, which deletes both indexes.

sudo -u loghound php /opt/loghound/bin/loghound-setup --reset

• Kept: both Opensolr indexes and every document in them, your access log files, the Opensolr account details (email, API key, region), the beacon signing key and the address salt.
• Removed: the sign-in (username, password, two-factor), and every browser that stayed signed in is signed out.
• Forgotten: the log sources and the index names. Setup offers the same pair back to you, so you can land on the history you started with.
• Deleted: the local state database (the reader’s position in each log, open visits, beacon reports not yet merged, lookup caches) and the saved detection report. Each log is then read from its end, so the gap is not filled in.

It lists all of this and asks before doing anything; the answer defaults to no, and an unattended run needs LOGHOUND_CONFIRM_RESET=yes. The service and timers keep running on the old configuration until you restart them. To delete the data as well, use Settings › Start over, or the uninstaller to take Loghound off the machine.

Not on the path; run it from the checkout. It is the one that needs root.

sudo ./install/install.sh [options]

  --dry-run             print every action and change nothing. Do this first.
  --upgrade             refresh code in place; config and var/ untouched
  --uninstall           reverse everything, prompting before deleting any data
  --prefix DIR          install root (default /opt/loghound)
  --user NAME           system user to run as (default loghound)
  --hostname FQDN       the panel's hostname
  --webserver           apache | nginx | none
  --tls-mode            existing | certbot | selfsigned | none
  --tls-cert PATH       with --tls-mode existing
  --tls-key PATH        with --tls-mode existing
  --skip-setup          prepare the machine and stop; configure in the browser
  --skip-tests          do not run the test suite
  --non-interactive     answer every prompt from the environment or defaults
  --yes, -y             assume yes for confirmations (still refuses to overwrite files)
  -h, --help

Every option also has an environment variable; Unattended installs lists them. install/uninstall.sh is a thin wrapper around --uninstall, the same code path under an obvious name. See Uninstalling.

Not part of an installation, and it refuses to overwrite a real configuration because that file holds the API key and the beacon signing secret:

php tools/panel-preview.php        # writes a throwaway config, prints a password
php -S 127.0.0.1:8099 -t public

That is demo mode, and every page in it carries a banner saying the numbers are fabricated.