# Configuration doctor

> Source: https://ferron.sh/docs/configuration/fundamentals/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.

```bash
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:

```text
$ 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:

```bash
ferron doctor -c ferron.conf --json
```

```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

Best-practice violations use the `"Best practice violation"` diagnostic kind. They are advisory: the server can start with these patterns, but they may indicate security risks or operational issues.

## See also

- [Configuration validation](https://ferron.sh/docs/configuration/fundamentals/validation.md)
- [Configuration formatting](https://ferron.sh/docs/configuration/fundamentals/formatting.md): `ferron-fmt` for formatting `.conf` files
- [Syntax and file structure](https://ferron.sh/docs/configuration/fundamentals/syntax.md)
- [Security and TLS](https://ferron.sh/docs/configuration/security/tls.md)