Configuration

Farrier is configured with plain files in its data directory and a few environment variables. There is no configuration in the database, so a deployment is reproducible from a directory and a secret.

Data directory

Set with --data or FARRIER_DATA. Defaults to ./farrier-data, or ./farrier-demo for farrier demo.

farrier-data/
├── farrier.db                     # SQLite: endpoints, observations, renewals, events
├── master.key                   # Fernet key sealing private keys (unless FARRIER_MASTER_KEY is set)
├── issuers.json                 # which CAs to use (optional)
├── settings.json                # planner tuning (optional)
├── acme-account-<hash>.key      # one ACME account key per directory URL
├── local-ca/                    # built-in private CA (ca.key, ca.pem)
└── packs/<renewal-id>/          # manual change packs, deleted once verified

Issuers: issuers.json

Maps issuer names to CAs. Endpoints choose one with their issuer field. If an endpoint names an issuer that doesn't exist, default is used. Without the file, Farrier uses only the built-in private CA:

{ "default": { "type": "local_ca" } }

Any string value can be a secret reference (env:NAME or file:/path).

Let's Encrypt

{
  "default": { "type": "local_ca" },
  "le": {
    "type": "acme",
    "directory_url": "https://acme-v02.api.letsencrypt.org/directory",
    "email": "pki@example.com",
    "dns_hook": "/opt/farrier/hooks/route53.sh",
    "propagation_seconds": 60
  }
}

Commercial CA with External Account Binding

DigiCert, Sectigo, Entrust and others expose ACME with EAB credentials:

{
  "digicert": {
    "type": "acme",
    "directory_url": "https://acme.digicert.com/v2/acme/directory/",
    "eab_kid": "env:DIGICERT_EAB_KID",
    "eab_hmac_key": "env:DIGICERT_EAB_HMAC",
    "dns_hook": "/opt/farrier/hooks/infoblox.sh"
  }
}

acme options

Only the DNS-01 challenge is supported, by design: the device never needs to be reachable from the CA.

local_ca options

The private CA follows the public lifetime schedule by default, so you can rehearse the 47-day world today. Use it for labs and internal-only names; clients must trust local-ca/ca.pem.

DNS-01 hook contract

dns_hook is run through the shell once per challenge, with these environment variables:

present must add a TXT value, not replace the record: a certificate for example.com and *.example.com needs two values on the same name. cleanup removes only the given value. A non-zero exit fails the issuance attempt, which is retried on the next tick. Each call has a 300-second timeout.

Example for BIND or any RFC 2136 server (examples/dns-hook-nsupdate.sh):

#!/bin/sh
set -eu
SERVER="${NSUPDATE_SERVER:-ns1.example.com}"
KEY="${NSUPDATE_KEY:-/etc/farrier/tsig.key}"
case "$FARRIER_DNS_ACTION" in
  present) OP="update add $FARRIER_DNS_NAME. 60 IN TXT \"$FARRIER_DNS_VALUE\"" ;;
  cleanup) OP="update delete $FARRIER_DNS_NAME. IN TXT \"$FARRIER_DNS_VALUE\"" ;;
  *) echo "unknown action $FARRIER_DNS_ACTION" >&2; exit 2 ;;
esac
printf 'server %s\n%s\nsend\n' "$SERVER" "$OP" | nsupdate -k "$KEY"

Write equivalents for Route 53, Infoblox or Azure DNS with their CLIs.

Planner settings: settings.json

All keys are optional; missing keys use these defaults.

{
  "horizon_days": 14,
  "manual_daily_cap": 25,
  "auto_daily_cap": 1000,
  "verify_max_attempts": 6,
  "verify_retry_seconds": 2.0,
  "issue_max_attempts": 5,
  "safety_days": 2,
  "scan_timeout": 5.0,
  "crypto_scan_hours": 24,
  "ssh_scan_hours": 24,
  "ssh_collect_hours": 24,
  "export_key_retention_hours": 24
}

See Concepts for how these interact.

Notifications

Add notifiers to settings.json to hear about renewals in Slack, Microsoft Teams or any webhook:

{
  "dashboard_url": "https://farrier.example.internal/dashboard",
  "notifiers": [
    { "type": "slack", "url": "env:FARRIER_SECRET_SLACK_WEBHOOK" },
    { "type": "teams", "url": "file:/run/secrets/farrier/teams-webhook", "events": ["failed", "rolled_back"] },
    { "type": "webhook", "url": "https://hooks.example.internal/farrier",
      "headers": { "Authorization": "env:FARRIER_SECRET_HOOK_TOKEN" },
      "events": ["done", "failed", "rolled_back", "awaiting_manual"] }
  ]
}

• events defaults to failed, rolled_back and awaiting_manual (event-bus channels eventbridge, pubsub and eventgrid: issued, awaiting_manual, done, failed, rolled_back and cancelled; see Events). Others: planned, issued, verifying, done, superseded, cancelled.
• webhook posts JSON: event, endpoint, host, port, connector, owner, renewal_id, error, ticket, new_not_after, at, dashboard_url. slack and teams post a one-paragraph text message.
• URLs and header values go through the secret guardrails, are resolved at send time and are never logged. Delivery runs in the background with a 5 second timeout; a failure is written to the event log and never blocks a renewal.
• Check the setup with POST /api/notifiers/test.

Inventory: farrier import

Declare endpoints and their connectors in a JSON array and import them. Importing is an upsert by name, and each connector config is validated first.

[
  {
    "name": "vpn-fgt",
    "host": "vpn.example.com",
    "port": 443,
    "issuer": "le",
    "connector": "fortigate",
    "connector_config": {
      "url": "https://fgt-mgmt.example.com",
      "api_token": "env:FGT_TOKEN",
      "bind": "sslvpn"
    },
    "window": { "days": ["sat"], "start": "02:00", "hours": 4 },
    "owner": "network"
  }
]

examples/inventory.json has a complete example covering F5, FortiGate, PAN-OS, a Java keystore and a manual ASA with a ServiceNow ticket.

Environment variables

The web dashboard has its own variables; see Self-hosting.

CLI

Global option: --data PATH.

Target syntax

Used by farrier scan and the Discovery screen. Items are separated by spaces or commas.

Hostnames, ports and ranges are validated, and malformed targets are rejected rather than scanned. A single range may not exceed 65,536 addresses, and the API accepts at most 4,096 targets per request.