ディレクティブ

各項目は構文、指定がない場合の既定値、書ける場所を示します。バージョン表記（どのバージョンで導入されたかを示す Since: 行）はまだ公開していません。

📖 本ページは出発点となる一部を扱います。ここに未記載でも、受理されるディレクティブは pingclair validate が検証します。サーバーが実装していないディレクティブは、黙って受理されるのではなく名前を挙げて拒否されます。

encode

Syntax:   encode <format> [<format> ...]
Default:  no compression
Context:  site block

レスポンスを圧縮します。引数は優先順に並べ、クライアントが受理する最初の形式を使います。対応する形式は zstd と gzip です。

Brotli を指定すると、gzip への暗黙の降格ではなくコンパイルエラーになります。プロキシにストリーミングの Brotli エンコーダーがなく、そのオプションを満たせないためです。

example.com {
    encode zstd gzip
    file_server ./public
}

file_server

Syntax:   file_server [<root>]
Default:  disabled
Context:  site block

ディスクからファイルを配信します。MIME タイプの判定、レンジリクエスト、ETag と Last-Modified による検証に対応します。引数を指定するとこのディレクティブ自身のルートになり、省略すると root で設定したサイトルートを使います。

localhost:8080 {
    file_server ./public
}

Syntax:   header [<matcher>] <field> <value>
          header [<matcher>] {
              <field> <value>      # set
              +<field> <value>     # append
              -<field>             # remove
              set <field> <value>  # set, spelled explicitly
          }
Default:  none
Context:  site block

レスポンスヘッダーを追加、置換、削除します。フィールド名だけを書くと設定、+ を前置すると追加、- を前置すると削除です。

example.com {
    header {
        X-Frame-Options "DENY"
        X-Content-Type-Options "nosniff"
        Strict-Transport-Security "max-age=31536000; includeSubDomains"
        -X-Powered-By
    }
}

log

Syntax:   log [<name>] { <options> }
Default:  no access sink
Context:  site block, global options

アクセスログの出力先を設定します。単独の log はそのサイトの既定出力を有効にし、log <name> { ... } は名前付きロガーを設定します。ブロックを伴わない log <name> は、global options で宣言したチャネルを参照します。

ブロックのオプションには出力先と形式（output、format）、hostnames セレクター、include と exclude の絞り込み、sampling、そしてファイルローテーション（mode、dir_mode、roll_*）があります。

example.com {
    log {
        output file /var/log/pingclair/access.log
    }
}

レコードは書き出し前にまとめて蓄積されます。追いつけない出力先はレコードを破棄し、pingclair_access_log_dropped_total に数えます。すべてのリクエストをシステムジャーナルへ書く場合、ジャーナル受信側の処理コストも負担します。

reverse_proxy

Syntax:   reverse_proxy [<matcher>] <upstream> [<upstream> ...]
          reverse_proxy [<matcher>] { ... }
Default:  none
Context:  site block

リクエストを 1 つ以上の上流へ転送します。既定の負荷分散ポリシーはラウンドロビンです。ホスト名の上流は dns_refresh の間隔で再解決されるため、新しいアドレスで再起動したバックエンドにも操作なしで追従します。解決に失敗した場合は、直前のアドレスをローテーションに残します。

:80 :8080 {
    reverse_proxy {
        lb_policy least_conn
        to 10.0.0.1:8080 {
            weight 3
        }
        to 10.0.0.2:8080
        to 10.0.0.3:8080 {
            backup
        }
        health_check {
            path /health
            interval 5s
            timeout 2s
            status 200 204
            consecutive_failure 3
            consecutive_success 2
        }
    }
}

アクティブヘルスチェックは帯域外で実行されるため、失敗したバックエンドは利用者のリクエストが届く前にローテーションから外れ、設定した回数の成功後に復帰します。backup の上流は、すべての主要な上流が利用できない場合にだけ使われます。

root

Syntax:   root [<matcher>] <path>
Default:  none
Context:  site block

サイトルートを設定します。file_server は独自のルートを持てますが、ここで設定すると、ファイルを扱う他のディレクティブとファイルサーバーが同じ場所を指せます。

example.com {
    root * /srv/public
    file_server
}

tls

Syntax:   tls <mode>
          tls { <options> }
Default:  automatic HTTPS for public names
Context:  site block

証明書の取得方法を制御します。

モード	挙動
`tls auto`	ACME で公開証明書を取得し、自動で更新します。
`tls internal`	常駐するローカル認証局から発行します。ルート証明書は `$PINGCLAIR_TLS_STORE/internal/root.crt` にあり、クライアントが信頼する必要があります。
`tls { cert ...; key ... }`	ブロックで指定した証明書と鍵のファイルを使います。

ブロック形式では http3 で HTTP/3 を有効にでき、dns cloudflare <token> による DNS-01 発行にも対応します。実装されている DNS プロバイダーはこれだけです。他のプロバイダー名は、受理して無視するのではなく起動時に拒否されます。DNS-01 はワイルドカード証明書を成立させる前提だからです。

example.com {
    tls {
        cert /etc/pingclair/certs/example.com.pem
        key /etc/pingclair/certs/example.com.key
        http3
    }
    reverse_proxy localhost:3000
}

🌍 Global options

Global options はファイル先頭の名前のないブロックに書きます。

オプション	構文	内容
`admin`	`admin <address> [<token>]`	Admin API のリスナー。token がない場合はループバック接続だけを受理します。
`auto_https`	`auto_https on \| off \| disable_redirects`	自動 HTTPS と 80 番ポートへのリダイレクトを制御します。
`dns_refresh`	`dns_refresh <duration>`	ホスト名上流の再解決間隔。`off` は起動時に解決したアドレスに固定します。
`email`	`email <address>`	ACME 発行に使うアカウントのメールアドレス。
`trusted_proxies`	`trusted_proxies <cidr> [<cidr> ...]`	クライアント識別ヘッダーを主張できる対端。変更には再起動が必要です。

{
    email admin@example.com
    admin 127.0.0.1:2019
    dns_refresh 30s
}

🧾ディレクティブ