API

Caddy は、REST API を使用して HTTP でアクセスできる管理エンドポイントを通じて設定されます。Caddy の設定でこのエンドポイントを設定できます。

デフォルトアドレス: `localhost:2019`

デフォルトアドレスは、`CADDY_ADMIN` 環境変数を設定することで変更できます。インストール方法によっては、異なる値が設定される場合があります。Caddy の設定ファイル内のアドレスは、常にデフォルトよりも優先されます。

変更後、最新の構成はディスクに保存されます（無効化されていない限り）。`caddy run --resume` を使用して、再起動後に最後の動作していた構成を再開できます。これにより、停電時などにおける構成の永続性が保証されます。

API を使い始めるには、API チュートリアルを試してみてください。時間がない場合は、API クイックスタートガイドもあります。

POST /load アクティブな設定を設定または置き換えます
POST /stop アクティブな設定を停止し、プロセスを終了します
GET /config/[path] 指定されたパスにある設定をエクスポートします
POST /config/[path] オブジェクトを設定または置き換えます。配列に追加します。
PUT /config/[path] 新しいオブジェクトを作成します。配列に挿入します。
PATCH /config/[path] 既存のオブジェクトまたは配列要素を置き換えます。
DELETE /config/[path] 指定されたパスにある値を削除します。
JSON で `@id` を使用 設定構造内を簡単に移動できます
同時設定変更 同期されていない設定変更時の衝突を回避します
POST /adapt 実行せずに設定を JSON に変換します
GET /pki/ca/<id> 特定の PKI アプリ CA に関する情報を返します
GET /pki/ca/<id>/certificates 特定の PKI アプリ CA の証明書チェーンを返します
GET /reverse_proxy/upstreams 設定されたプロキシアップストリームの現在の状態を返します

POST /load

Caddy の設定を設定し、以前の設定を上書きします。リロードが完了するか失敗するまでブロックします。設定変更は軽量で効率的であり、ダウンタイムは発生しません。新しい設定が何らかの理由で失敗した場合、古い設定がダウンタイムなしで元に戻されます。

このエンドポイントは、設定アダプターを使用して異なる設定形式をサポートしています。リクエストの `Content-Type` ヘッダーは、リクエスト本文で使用される設定形式を示します。通常、これは Caddy のネイティブ設定形式を表す `application/json` である必要があります。別の設定形式を使用するには、適切な `Content-Type` を指定します。スラッシュ `/` の後の値は、使用する設定アダプターの名前です。たとえば、Caddyfile を送信する場合は `text/caddyfile` のような値を使用し、JSON 5 を使用する場合は `application/json5` のような値を使用します。

新しい設定が現在の設定と同じ場合、リロードは実行されません。リロードを強制するには、リクエストヘッダーに `Cache-Control: must-revalidate` を設定します。

例

新しいアクティブな設定を設定する

curl "https://:2019/load" \
	-H "Content-Type: application/json" \
	-d @caddy.json

注: curl の `-d` フラグは改行を削除するため、設定形式が改行に依存する場合（例：Caddyfile）、代わりに `--data-binary` を使用してください。

curl "https://:2019/load" \
	-H "Content-Type: text/caddyfile" \
	--data-binary @Caddyfile

POST /stop

サーバーを正常にシャットダウンし、プロセスを終了します。プロセスを終了せずに実行中の設定のみを停止するには、DELETE /config/ を使用します。

例

プロセスを停止する

curl -X POST "https://:2019/stop"

GET /config/[path]

指定されたパスにある Caddy の現在の設定をエクスポートします。JSON 本文を返します。

例

設定全体をエクスポートして整形する

curl "https://:2019/config/" | jq
{
	"apps": {
		"http": {
			"servers": {
				"myserver": {
					"listen": [
						":443"
					],
					"routes": [
						{
							"match": [
								{
									"host": [
										"example.com"
									]
								}
							],
							"handle": [
								{
									"handler": "file_server"
								}
							]
						}
					]
				}
			}
		}
	}
}

リスナーアドレスのみをエクスポートする

curl "https://:2019/config/apps/http/servers/myserver/listen"
[":443"]

POST /config/[path]

指定されたパスにある Caddy の設定をリクエストの JSON 本文に変更します。宛先値が配列の場合、POST は追加します。オブジェクトの場合、作成または置き換えます。

特別なケースとして、多くのアイテムを配列に追加できます。

パスが `/...` で終わる場合
`/...` の前のパスの要素が配列を参照する場合
ペイロードが配列である場合

この場合、ペイロードの配列内の要素が展開され、それぞれが宛先配列に追加されます。Go の用語では、これは次のと同じ効果があります。

baseSlice = append(baseSlice, newElems...)

例

リスナーアドレスを追加する

curl \
	-H "Content-Type: application/json" \
	-d '":8080"' \
	"https://:2019/config/apps/http/servers/myserver/listen"

複数のリスナーアドレスを追加する

curl \
	-H "Content-Type: application/json" \
	-d '[":8080", ":5133"]' \
	"https://:2019/config/apps/http/servers/myserver/listen/..."

PUT /config/[path]

指定されたパスにある Caddy の設定をリクエストの JSON 本文に変更します。宛先値が配列内の位置（インデックス）の場合、PUT は挿入します。オブジェクトの場合、厳密に新しい値を作成します。

例

最初のスロットにリスナーアドレスを追加する

curl -X PUT \
	-H "Content-Type: application/json" \
	-d '":8080"' \
	"https://:2019/config/apps/http/servers/myserver/listen/0"

PATCH /config/[path]

指定されたパスにある Caddy の設定をリクエストの JSON 本文に変更します。PATCH は、既存の値または配列要素を厳密に置き換えます。

例

リスナーアドレスを置き換える

curl -X PATCH \
	-H "Content-Type: application/json" \
	-d '[":8081", ":8082"]' \
	"https://:2019/config/apps/http/servers/myserver/listen"

DELETE /config/[path]

指定されたパスにある Caddy の設定を削除します。DELETE はターゲット値を削除します。

例

現在の設定全体をアンロードするが、プロセスを実行したままにする

curl -X DELETE "https://:2019/config/"

HTTP サーバーの1つだけを停止する

curl -X DELETE "https://:2019/config/apps/http/servers/myserver"

JSON で `@id` を使用

JSON ドキュメントに ID を埋め込んで、JSON のそれらの部分に簡単に直接アクセスできます。

オブジェクトに `"@id"` というフィールドを追加し、一意の名前を付けるだけです。たとえば、頻繁にアクセスする必要があるリバースプロキシハンドラーがあったとします。

{
	"@id": "my_proxy",
	"handler": "reverse_proxy"
}

使用する際は、対応する `/config/` エンドポイントと同じように `/id/` API エンドポイントにリクエストを送信しますが、パス全体は使用しません。ID はリクエストを構成のそのスコープに直接入力します。

たとえば、ID を使用せずにリバースプロキシのアップストリームにアクセスする場合は、パスは次のようになります。

/config/apps/http/servers/myserver/routes/1/handle/0/upstreams

しかし、ID を使用すると、パスは次のようになります。

/id/my_proxy/upstreams

これは、手動で覚えたり書いたりする方がはるかに簡単です。

同時設定変更

Caddy の設定 API は、個々のリクエストに対してACID 保証を提供しますが、複数のリクエストを含む変更は、適切に同期されていない場合、衝突またはデータ損失が発生する可能性があります。

たとえば、2 つのクライアントが同時に `GET /config/foo` を実行し、そのスコープ（設定パス）内で編集を行い、次に同時に `POST|PUT|PATCH|DELETE /config/foo/...` を呼び出して変更を適用すると、衝突が発生する可能性があります。いずれかが他方を上書きするか、2 番目が準備されたものとは異なるバージョンの設定に適用されたため、設定が意図しない状態になる可能性があります。これは、変更が互いを認識していないためです。

Caddy の API は、複数のリクエストにまたがるトランザクションをサポートしておらず、HTTP はステートレスプロトコルです。ただし、`Etag` トレーラーと `If-Match` ヘッダーを使用して、一種の楽観的同時実行制御として、すべての変更の衝突を検出して防止できます。これは、同期せずに Caddy の `/config/...` エンドポイントを同時に使用している可能性がある場合に役立ちます。`GET /config/...` リクエストへのすべてのレスポンスには、`Etag` という HTTP トレーラーが含まれており、パスと、そのスコープの内容のハッシュが含まれています（例：`Etag: "/config/apps/http/servers 65760b8e"`）。変更リクエストで `If-Match` ヘッダーを、以前の `GET` リクエストの Etag トレーラーに設定するだけです。

この基本アルゴリズムは次のとおりです。

設定内の任意のスコープ `S` に対して `GET` リクエストを実行します。レスポンスの `Etag` トレーラーを保持します。
返された設定に必要な変更を加えます。
スコープ `S` 内で `POST|PUT|PATCH|DELETE` リクエストを実行し、`If-Match` ヘッダーを最近の `Etag` 値に設定します。
レスポンスが HTTP 412（条件付き失敗）の場合、ステップ 1 から繰り返すか、試行が多すぎる場合は諦めます。

このアルゴリズムにより、明示的な同期なしで、Caddy の設定に対する複数の重複する変更を安全に実行できます。これは、設定の異なる部分への同時変更は再試行を必要としないように設計されています。設定の同じスコープと重複する変更のみが衝突を引き起こし、再試行が必要になる可能性があります。

POST /adapt

設定をロードまたは実行せずに Caddy JSON に変換します。成功すると、結果の JSON ドキュメントがレスポンス本文で返されます。

`Content-Type` ヘッダーは、/load と同じ方法で設定形式を指定するために使用されます。たとえば、Caddyfile を変換するには、`Content-Type: text/caddyfile` を設定します。

このエンドポイントは、関連する設定アダプターがCaddyビルドにプラグインされている限り、任意の設定形式に対応します。

例

CaddyfileをJSONに変換する

curl "https://:2019/adapt" \
	-H "Content-Type: text/caddyfile" \
	--data-binary @Caddyfile

GET /pki/ca/<id>

特定のPKIアプリ CAに関する情報を、そのIDで返します。要求されたCA IDがデフォルト（local）の場合、まだプロビジョニングされていない場合はCAがプロビジョニングされます。他のCA IDは、以前にプロビジョニングされていない場合はエラーを返します。

curl "https://:2019/pki/ca/local" | jq
{
	"id": "local",
	"name": "Caddy Local Authority",
	"root_common_name": "Caddy Local Authority - 2022 ECC Root",
	"intermediate_common_name": "Caddy Local Authority - ECC Intermediate",
	"root_certificate": "-----BEGIN CERTIFICATE-----\nMIIB ... gRw==\n-----END CERTIFICATE-----\n",
	"intermediate_certificate": "-----BEGIN CERTIFICATE-----\nMIIB ... FzQ==\n-----END CERTIFICATE-----\n"
}

GET /pki/ca/<id>/certificates

特定のPKIアプリ CAの証明書チェーンを、そのIDで返します。要求されたCA IDがデフォルト（local）の場合、まだプロビジョニングされていない場合はCAがプロビジョニングされます。他のCA IDは、以前にプロビジョニングされていない場合はエラーを返します。

このエンドポイントは、caddy trustコマンドによって内部的に使用され、CAのルート証明書をシステムの信頼ストアにインストールすることを許可します。

curl "https://:2019/pki/ca/local/certificates"
-----BEGIN CERTIFICATE-----
MIIByDCCAW2gAwIBAgIQViS12trTXBS/nyxy7Zg9JDAKBggqhkjOPQQDAjAwMS4w
...
By75JkP6C14OfU733oElfDUMa5ctbMY53rWFzQ==
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
MIIBpDCCAUmgAwIBAgIQTS5a+3LUKNxC6qN3ZDR8bDAKBggqhkjOPQQDAjAwMS4w
...
9M9t0FwCIQCAlUr4ZlFzHE/3K6dARYKusR1ck4A3MtucSSyar6lgRw==
-----END CERTIFICATE-----

GET /reverse_proxy/upstreams

設定されたリバースプロキシアップストリーム（バックエンド）の現在の状態をJSONドキュメントとして返します。

curl "https://:2019/reverse_proxy/upstreams" | jq
[
	{"address": "10.0.1.1:80", "num_requests": 4, "fails": 2},
	{"address": "10.0.1.2:80", "num_requests": 5, "fails": 4},
	{"address": "10.0.1.3:80", "num_requests": 3, "fails": 3}
]

JSON配列の各エントリは、グローバルアップストリームプールに格納されている設定済みのアップストリームです。

addressは、アップストリームのダイヤルアドレスです。
num_requestsは、現在アップストリームによって処理されているアクティブなリクエストの数です。
failsは、パッシブヘルスチェックで設定されているように、記憶されている失敗したリクエストの現在の数です。

バックエンドの可用性を判断することが目的である場合、使用しているハンドラー設定に対してアップストリームの関連プロパティを相互に確認する必要があります。たとえば、プロキシにパッシブヘルスチェックを有効にしている場合は、アップストリームが利用可能と見なされるかどうかを判断するために、failsとnum_requestsの値も考慮する必要があります。つまり、failsの数がプロキシに対して設定された最大失敗数（つまり、max_fails）未満であり、num_requestsがプロキシごとに設定された最大リクエスト数（つまり、unhealthy_request_count全体、または個々のアップストリームのmax_requests）以下であることを確認する必要があります。