Docs

Configuration directives

The ferron directives command prints every configuration directive that the loaded modules register as a JSON document. It does not validate a configuration file, it only reflects the directive schema known to the running binary.

ferron directives
Tip

Pipe the output to a JSON processor (for example, jq) for filtering, or save it to a file for reference.

Output structure⁠#

The JSON output is an object whose keys are directive sections: logical groupings of related directives. Each section maps to a list of directive definitions:

{
  "section_name": [
    {
      "name": "directive_name",
      "usage": "directive_name <arg>",
      "description": "What the directive does.",
      "applicable_protocols": ["http"],
      "global_only": false,
      "subblock_link": null
    }
  ]
}

Directive fields⁠#

FieldTypeDescription
namestringThe directive name as it appears in the configuration file.
usagestringA usage hint showing the expected argument shape. <arg> indicates a required value, [bool] an optional boolean flag, and { ... } a block with sub-directives.
descriptionstringA short human-readable description that states the directive’s purpose.
applicable_protocolsstring[] | nullThe protocols this directive can appear in (for example ["http"]). null means the directive is valid globally or in all protocol contexts.
global_onlyboolIf true, the directive can only appear at the top level of the configuration file (outside any host block).
subblock_linkstring | nullWhen non-null, the directive has child directives registered under this subblock name. Ferron groups the child directives under a separate section with the same name.

Sections⁠#

Sections group directives that belong to the same logical area. For example, http_proxy contains reverse-proxy directives, while http_proxy_upstream contains per-upstream-server directives. Ferron prefixes section names with custom_ for module-contributed directives, or leaves them as default for core directives.

Example⁠#

ferron directives | jq '.default'
[
  {
    "name": "runtime",
    "usage": "runtime { ... }",
    "description": "This directive specifies global runtime settings.",
    "applicable_protocols": null,
    "global_only": true,
    "subblock_link": "custom_global_runtime"
  },
  ...
]
Note

The directive list depends on which modules the binary compiles in. A minimal custom build may expose fewer directives than the default binary.

See also⁠#