Configuration doctor

This page documents the ferron doctor command, which extends configuration validation with best-practice checks for security, reliability, and operational hygiene.

The doctor command⁠#

The doctor command runs the same structural validation as ferron validate. It also checks for configuration patterns that are technically valid but deviate from recommended practices.

ferron doctor -c ferron.conf

If the configuration is valid and contains no best-practice violations, the command exits with code 0. If it finds violations, it still exits with code 0 (they are advisory, not errors). If it finds structural errors, it exits with code 1.

Note

Best-practice violations are advisory and do not prevent the server from starting. Treat the findings as opinionated guidance, not absolute truth.
The ferron validate command suppresses doctor diagnostics. Use ferron doctor to see them.

Tip

Some checks are contextual and only fire when the doctor detects specific directive combinations. The doctor cannot detect all security-relevant patterns at configuration time. Runtime monitoring and network controls remain important. For the full list of detected best-practice violations, see the respective documentation pages in the “Configuration” category.

Log output⁠#

By default, Ferron prints diagnostics as log messages:

$ ferron doctor -c ferron.conf
[2026-05-30 07:18:34.372 INFO] Best practice violation (block 'http example.com' in file 'ferron.conf' at line 5, column 5): `directory_listing` exposes generated indexes for directories without index files; enable it only for intentionally public file listings

JSON output⁠#

Use the --json (or -j) flag for machine-readable output:

ferron doctor -c ferron.conf --json

{
  "valid": true,
  "diagnostics": [
    {
      "kind": "Best practice violation",
      "message": "`directory_listing` exposes generated indexes for directories without index files; enable it only for intentionally public file listings",
      "span": { "line": 5, "column": 5, "file": "ferron.conf" },
      "scope": "http example.com"
    }
  ]
}

Note

The JSON output format is stable and suitable for programmatic consumption by tools and CI pipelines.

How it differs from validate⁠#

Feature	`ferron validate`	`ferron doctor`
Unknown directives	Reported	Reported
Invalid configuration	Reported (errors)	Reported (errors)
Best practice violations	Suppressed	Reported (advisory)

The validate command strips BestPracticeViolation diagnostics from its output. The doctor command retains them. All other behavior is identical. The same validators run in the same order.

Diagnostic kind⁠#