7. Doctor, diag and support

This guide describes Lawliet 1.5.13.s (the current release). Screens, commands and procedures may change in later versions; the usage guide is updated with each release. Check the version your server runs under Settings > Platform or with ./lawliet version, and see the Releases page for what changed.

Three tools find out what is wrong and package it for the vendor without exposing secrets: ./lawliet doctor, ./lawliet diag, and the console's Download diagnostics.

You need
`doctor`, `diag`	Root (or `sudo`) on the server. No four-eyes
Console diagnostics	Permission Manage settings

7.1 doctor#

Report only#

sudo ./lawliet doctor

Changes nothing on the server. It prints, in order:

The TLS warning, if encryption is off.
Bundled images: each image of this bundle, OK when loaded.
TLS certificate (HTTPS mode): coverage of every address.
Findings: each problem, with either safe fix: <what --fix would do> or to fix: <the command to run>.
A support file lawliet-support-<time>.txt (mode 600) in the installation directory: host and Docker versions, the deployment settings, /health, container states, the schema revision, the .env keys with every value except a short safe list replaced by its length, disk use, and the last lines of the backend, frontend and nginx logs. No secrets, no database rows.

When nothing is wrong it says Nothing found: services, images, certificate, TRUSTED_HOSTS, clock, disk, licence, backups and leftovers checked.

The findings#

Finding	Severity	`--fix` does	Or run
`<service> is not running`	FAIL	Starts it and waits up to 2 minutes
`<service> is <state>` (unhealthy)	FAIL	Restarts it and waits
`Bundled images not loaded: ...`	FAIL	Loads them, each checked against its checksum
`Encryption is off`	FAIL	-	`sudo ./lawliet tls on`
`The certificate does not cover <address>` or `expires within 30 days` (self-signed)	FAIL	Runs `tls repair`; with enrolled agents it lists them and asks you itself
The same, CA-issued	FAIL	-	Ask your CA for a certificate that names every address, then `sudo ./lawliet tls`
`TRUSTED_HOSTS does not list <address>`	!	Adds it to `.env` and recreates the backend
`This server's clock is not synchronised (NTP)`	!	-	`sudo timedatectl set-ntp true`, then `timedatectl timesync-status`
`Low disk space on <mount>` (under 5 GB free or 90% used)	FAIL	-	Free space; `docker system df` shows what Docker holds; move old backups off the server
`No valid licence is active`	FAIL	-	`./lawliet licence`, send the fingerprint, then `./lawliet licence <key>`
`The licence expires in N day(s)` (30 or fewer)	!	-	Ask your vendor for a renewal, then `./lawliet licence <key>`
`No database backup in ./backups` or `The newest database backup is more than 7 days old`	!	-	`./lawliet backup`, then copy it off the server
`N old TLS-switch snapshot(s) ... still hold a copy of .env and of the private key`	!	Removes those beyond the newest 5 or older than 30 days (the newest is always kept)
`N TLS-switch snapshot(s) from before 1.5.12.s in ./backups`	!	Removes them (none is ever restored)
`N offline agent package file(s) ... are expired or left from a build that stopped`	!	Removes them

Apply the safe fixes#


Risk	Low. A safe fix never touches the database, volumes, secrets, keys, the licence or backups. It starts or restarts a service, loads images, runs the `tls repair` flow, adds addresses to `TRUSTED_HOSTS`, or deletes old snapshots and expired packages
Rollback	A removed snapshot or package cannot be brought back (neither is needed). A `TRUSTED_HOSTS` change: edit `.env` and run `sudo ./lawliet start`

Run:
```
sudo ./lawliet doctor --fix
```
For each finding with a safe fix it shows the problem and Will <what it does>, then asks Apply this fix? (y/N). Answer per fix. --fix --yes answers yes to all of doctor's own questions (it does not answer the tls repair question about enrolled agents).
Needs you (no safe automatic fix) lists the rest with the command to run.
Checking again runs every check once more and prints Fixed: ... or Still open: ... for each.

Every applied fix is written to the audit trail as doctor_fix, with who ran it. If the backend does not answer, it is written to doctor-fix.log in the installation directory instead, and the command says so.

7.2 diag#

The file to send to the vendor from an air-gapped site, instead of screenshots.

sudo ./lawliet diag                        # last 1000 log lines per service
sudo ./lawliet diag --since 24h            # logs of the last 24 hours (30m, 7d, or a timestamp)
sudo ./lawliet diag --output /media/usb    # write there (a directory or a file name)
sudo ./lawliet diag --lines 5000           # more lines per service
sudo ./lawliet diag --keep-emails          # keep e-mail addresses (removed by default)

What you see: one OK line per part collected, then OK Wrote <dir>/lawliet-diag-<host>-<UTC time>.tar.gz (mode 600).

What is in it#

File	Contents
`MANIFEST.txt`	Every file, its size, and how many redactions of each kind were made
`bundle.txt`	Bundle version, `VERSION.json` (build id), deployment settings (no secrets)
`env.redacted`	`.env` with every value not on a short safe list replaced by `[redacted]`
`containers.txt`	Docker and Compose versions, container states, health, restart counts
`logs/<service>.log`	The last lines (or `--since`) of each service's log, redacted
`backend-errors.txt`	Recent backend errors and tracebacks, redacted
`health.txt`	`/health`, `/health/ready`, licence status (never the key)
`tls.txt`	Certificate subject, issuer, names, dates, SHA-256 fingerprint (never the private key); `TRUSTED_HOSTS`, `CORS_ORIGINS`
`system.txt`	OS, CPU, memory, disk, time in UTC and local, NTP state
`database.txt`	Schema revision; agents by status, platform and version; agent clock offsets; the last 20 failed remote-deployment hosts with reasons

Never included: the database, the TLS private key, the licence key, any .env secret.

What is removed#

Every secret value from .env wherever it appears (also URL-encoded), tokens (JWTs, ldt_, lwk_, lec_, bearer tokens), passwords inside URLs, private keys, licence strings, secret headers and password=/token=/secret= values, and e-mail addresses unless --keep-emails.

The self-check#

Before writing, diag opens the archive it built and searches every file for each secret value from .env and for any private key. If one is found it refuses: nothing is written, and it names the setting that would have leaked (never its value) and the file. Report that to the vendor without the file.

If it fails#

Message	Cause and fix
`--since takes 30m, 24h, 7d or a timestamp`	Fix the value
`Refused to write the diagnostics: the redaction self-check found a secret value in it`	Nothing was written. Tell support, without the file
`Could not build the diagnostics archive`	No `python3` on the host and the backend is not running. Start the backend or install `python3`

A host without Docker Compose still gets an archive that says so.

7.3 Diagnostics from the console#

For someone without shell access to the server.

Go to Settings > Platform, panel Platform updates, section Diagnostics for support.
Press Download diagnostics.

What you see: Diagnostics archive downloaded. Send it to support with your ticket. The archive holds the version and build id, the effective configuration with every value reduced to a length and a hash, row counts per table, migration state, worker health and the end of the application log. Collected logs, findings and incidents are not included.

If it fails: The diagnostics archive could not be built. The backend log will say why. Ask someone with server access to run sudo ./lawliet diag.

7.4 Health endpoints for monitoring#

Endpoint	Answers	Use
`/health`	`"status": "healthy"`, version, build, whether TLS is on	Is the process up
`/health/ready`	`"status": "ready"` when the database and Redis answer, 503 `not_ready` otherwise. Also reports the licence state and expiry and the certificate status, without failing on them	Readiness alarm
`/health/tasks`	Background loops (scan worker, schedules, drift, retention) are running	Background work alarm
`/metrics`	Prometheus metrics. In HTTPS mode served only to loopback and private address ranges	Trending. Set `METRICS_TOKEN` in `.env` and send `Authorization: Bearer <token>`

curl -fsk https://<address>/health/ready

7.5 Contacting support#

Email [email protected] for help. Report security vulnerabilities only as described on the security disclosure page.

Send:

The build id from sudo ./lawliet status (a version number is not specific enough).
The diag archive (sudo ./lawliet diag --since 24h), or the console's diagnostics archive.
What you did, what you expected, what happened, and when (with time zone).
The exact message, copied as text.

Do not send .env, .keys files, backups, the private key or the licence key.