Skip to main content
emisar

Caddy web server

v0.1.25

Caddy v2 ops via its admin API (default http://127.0.0.1:2019) and CLI. Config dump, upstream health, PKI inventory, config validation, plus reload (live config swap). Set CADDY_ADMIN env var if not on default.

6 allowed by default 4 need approval by default
Pack ID
caddy
Vendor
emisar
OS
linux
Actions
10
Required binaries. Install these on the host before relying on the pack — an action that calls a missing one fails at run time.
caddy curl

Install

emisar pack install fetches this pack, re-validates it, and verifies its content hash against the --hash below — the exact bytes this page was rendered against, so a tampered copy is rejected — before copying it into the runner's packs dir. The command reloads a running daemon itself; no manual restart.

on the runner host 
sudo emisar pack install caddy --hash sha256:279d41883e657e2b1b36551ea0af96daf2d03e4e5e043cae9caeac0facc19aed

Setup

Operates on the local Caddy instance on the runner host — no credentials needed. Inventory/health actions curl the admin API at 127.0.0.1:2019; validate/reload/stop run the caddy binary directly.

Environment

Set these on the runner host, then add each name to execution.inherit_env so the value reaches the action.

  • CADDY_ADMIN default http://127.0.0.1:2019

    Base URL of the Caddy admin API; set only if it does not listen on the default.

  • CADDY_ACCESS_LOG default /var/log/caddy/access.log

    Path to the Caddy access log for access_log_tail.

Host access

Run these commands yourself on the runner host. Emisar shows and copies setup recipes; it never runs them.

Read Caddy's protected log and configuration files. Reload also requires the separately configured admin endpoint to accept the request.

caddy.access_log_tailcaddy.adapt_caddyfilecaddy.validate_configcaddy.reload_config

Add the Emisar service user to caddy

Grant access 
sudo usermod -aG caddy emisar
sudo systemctl restart emisar
Verify access 
id -nG emisar | tr ' ' '\n' | grep -Fx caddy
sudo -u emisar test -r /etc/caddy/Caddyfile

Impact: Every process running as emisar can read files exposed to the caddy group. Reload can replace the live server configuration when the admin endpoint also permits it.

Notes

  • CADDY_ADMIN and CADDY_ACCESS_LOG only reach an action when the runner allowlists them in execution.inherit_env — the action env is scrubbed to PATH/LANG/LC_ALL/TERM by default. Unset, both fall back to their defaults above, so a non-default admin endpoint or log path silently reads the local one instead of yours.

Verify it works

Runs caddy.version, a low-risk read that confirms the pack can reach its target. Run it on the host once the pack is installed; pack install runs it for you.

on the runner host 
sudo emisar pack verify caddy

Install and configure a pack walks through the whole sequence on a host.

Actions 10 total

View on GitHub
  • caddy.access_log_tail exec medium Medium — changes state, easily reversible

    tail caddy access log

    Tail the access log (path configurable via CADDY_ACCESS_LOG env).

    View source on GitHub
  • caddy.adapt_caddyfile exec high High — service-affecting

    caddy adapt --config <file>

    Convert a Caddyfile to JSON config without loading it. The output is the full resulting config — the same content class as `caddy.config_dump` — and can carry secrets (TLS private-key material, basic-auth hashes, upstream credentials, API tokens); adapt errors also quote offending Caddyfile lines back. The runner's redaction is a fail-closed backstop, not a guarantee — it is pattern-bound and can miss a bespoke secret.

    View source on GitHub
  • caddy.config_dump exec high High — service-affecting

    GET /config (current config)

    Dump the currently-loaded Caddy configuration as JSON. This surfaces the full config, which can carry secrets (TLS private-key material, basic-auth hashes, upstream credentials, API tokens). The runner's redaction is a fail-closed backstop, not a guarantee — it is pattern-bound and can miss a bespoke secret whose name and value match no rule.

    View source on GitHub
  • caddy.pki_certs exec low Low — read-only or trivially reversible

    GET /pki/ca/<id>/certificates

    List certificates managed by Caddy's internal PKI.

    View source on GitHub
  • caddy.reload_config exec high High — service-affecting

    caddy reload --config <file>

    Live-swap the running config. No connection drops on success; rejected config keeps the old one running.

    View source on GitHub
  • caddy.reverse_proxy_upstreams exec low Low — read-only or trivially reversible

    GET /reverse_proxy/upstreams

    List all reverse-proxy upstreams with current health.

    View source on GitHub
  • caddy.runtime_metrics exec low Low — read-only or trivially reversible

    GET /metrics (Prometheus exposition)

    Show Caddy's Prometheus-format metrics endpoint.

    View source on GitHub
  • caddy.stop exec high High — service-affecting

    caddy stop

    Stop the running Caddy process via its admin API. All listeners close; in-flight requests drain. Recovery requires starting Caddy again via systemd or `caddy start`. Use as a last resort during incidents.

    View source on GitHub
  • caddy.validate_config exec low Low — read-only or trivially reversible

    caddy validate --config <file>

    Validate a Caddyfile or JSON config without loading it.

    View source on GitHub
  • caddy.version exec low Low — read-only or trivially reversible

    caddy version

    Show Caddy binary version + build info.

    View source on GitHub
← Back to registry
Pack reference  Publish your own