System check & setup token

Two things stand between a freshly installed Loghound and the internet: a screen that tells you exactly what is wrong with the machine, and a token in a file only its administrator can read.

The first screen the browser installer shows is one row per requirement, with the exact command that fixes anything not passing, written for the user PHP is actually running as on this machine. For example, if the service user cannot read your access logs:

setfacl -m u:loghound:rx /var/log/apache2
setfacl -m u:loghound:r  /var/log/apache2/example_com_access.log

Read that table before continuing. A green check here is the difference between “the daemon is running” and “the daemon is running and indexing something”.

If you are behind open_basedir

The shipped PHP-FPM pool restricts the panel to the application directory and /tmp, plus the three directories this screen depends on:

php_admin_value[open_basedir] = /opt/loghound:/var/log:/etc/apache2:/etc/nginx:/tmp

/var/log is where your access logs are; /etc/apache2 and /etc/nginx are where the CustomLog and access_log directives that name them live, which is how the format is read exactly rather than guessed. If you tightened the pool, or your distribution ships its own, this screen physically cannot see those directories — and the system check says exactly that, rather than reporting a permission problem that does not exist.

Either widen open_basedir for them, or run bin/loghound-setup in a shell, where the restriction does not apply. The permission model has the rest.

Before the installer accepts anything that will be written to the configuration, it asks you to paste a token from a file only this server’s administrator can read:

sudo cat /opt/loghound/var/install-token

The status page itself stays readable without the token, and that is deliberate: you have to be able to see a permission problem in order to go and fix it. Nothing can be saved until it is entered.

There is one exception to being asked for it at all. Pressing the reinstall button inside an authenticated panel session carries that proof into the installer, so you are not sent back to the server for a token; it lasts half an hour, it is used once, and it belongs to that browser alone. Anyone else reaching the installer still has to read the file over a shell.

• It is unreachable once a valid configuration exists.
• Nothing is written until the token — a 0600 file — has been pasted.
• Every state-changing request carries a CSRF token, and no privileged action happens on a GET.
• Steps cannot be reached out of order by guessing a URL; a step whose prerequisites are unmet redirects to the first incomplete one.
• No secret is rendered anywhere — not the API key, the beacon signing key, the address salt or the password, and not into a hidden field, a URL, a job payload, a log line or an error message. Where it matters that one is set, the screen says “stored”.
• Sample log lines are attacker-controlled bytes by definition, are displayed on purpose, and are escaped on the way out. The page’s Content-Security-Policy is script-src 'self' with no inline scripts.
• A hand-typed log path is resolved with realpath() and refused unless it is inside allowed_log_roots; a custom pattern is refused unless it compiles and runs fast.