Directives

Chaque entrée indique la syntaxe, la valeur par défaut lorsque la directive est absente, et les endroits où la directive peut apparaître. L’attestation de version — la ligne Since: qui indiquerait depuis quand une directive existe — n’est pas encore publiée.

📖 Cette page documente un sous-ensemble de départ. Les directives acceptées mais pas encore documentées ici sont tout de même validées par pingclair validate ; une directive que le serveur n’implémente pas est refusée par son nom plutôt qu’acceptée en silence.

encode

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

Compresse les réponses. Les arguments sont listés par ordre de préférence : le premier format accepté par le client est utilisé. Les formats pris en charge sont zstd et gzip.

Demander Brotli est une erreur de compilation plutôt qu’une dégradation silencieuse vers gzip : le proxy n’a pas d’encodeur Brotli en flux, l’option ne peut donc pas être honorée.

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

file_server

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

Sert des fichiers depuis le disque, avec détection du type MIME, requêtes partielles et validation par ETag et Last-Modified. L’argument facultatif définit la racine pour cette seule directive. Lorsqu’il est omis, la racine du site définie par root est utilisée.

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

Ajoute, remplace ou supprime des en-têtes de réponse. Un nom de champ seul définit l’en-tête ; le préfixe + l’ajoute à la suite et le préfixe - le supprime.

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

Configure une destination de journal d’accès. Un log seul active la destination par défaut du site ; log <nom> { ... } configure un journal nommé, et log <nom> sans bloc renvoie à un canal déclaré dans les options globales.

Les options de bloc couvrent la destination et le format (output, format), le sélecteur hostnames, les filtres include et exclude, l’échantillonnage (sampling) et les réglages de rotation des fichiers (mode, dir_mode, roll_*).

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

Les enregistrements sont regroupés en lots avant d’être écrits, et une destination qui ne suit pas le rythme perd des enregistrements et les compte dans pingclair_access_log_dropped_total. Écrire chaque requête dans le journal du système entraîne également le coût du récepteur de ce journal.

reverse_proxy

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

Transmet les requêtes à un ou plusieurs amonts. La politique de répartition de charge par défaut est le tourniquet. Les amonts désignés par un nom d’hôte sont résolus à nouveau à l’intervalle défini par dns_refresh : un backend qui redémarre sur une nouvelle adresse est suivi sans intervention, et une résolution en échec conserve l’adresse précédente dans la rotation.

: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
        }
    }
}

Les contrôles de santé actifs s’exécutent hors du chemin des requêtes : un backend en échec quitte la rotation avant qu’une requête utilisateur ne l’atteigne, et y revient après le nombre configuré de sondes réussies. Un amont backup n’est utilisé que lorsque tous les amonts principaux sont indisponibles.

root

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

Définit la racine du site. file_server peut prendre sa propre racine, mais la définir ici est ce qui permet au serveur de fichiers et aux autres directives manipulant des fichiers de s’accorder sur un emplacement unique.

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

tls

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

Contrôle la façon dont les certificats sont obtenus.

Mode	Comportement
`tls auto`	Obtient des certificats publics via ACME et les renouvelle.
`tls internal`	Émet depuis une autorité de certification locale persistante. La racine est publiée dans `$PINGCLAIR_TLS_STORE/internal/root.crt` et doit être approuvée par les clients.
`tls { cert ...; key ... }`	Utilise les fichiers de certificat et de clé nommés dans le bloc.

La forme en bloc active aussi HTTP/3 avec http3, et prend en charge l’émission DNS-01 avec dns cloudflare <token>, seul fournisseur DNS implémenté. Nommer un autre fournisseur est refusé au démarrage plutôt qu’accepté et ignoré, car DNS-01 est ce qui rend possibles les certificats wildcard.

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

🌍 Global options

Les options globales s’écrivent dans le bloc sans nom, en tête de fichier.

Option	Syntax	Notes
`admin`	`admin <address> [<token>]`	Écouteur de l’Admin API. Sans jeton, seules les connexions de boucle locale sont acceptées.
`auto_https`	`auto_https on \| off \| disable_redirects`	Contrôle HTTPS automatique et la redirection du port 80.
`dns_refresh`	`dns_refresh <duration>`	Intervalle de résolution des amonts désignés par un nom d’hôte. `off` fige les adresses résolues au démarrage.
`email`	`email <address>`	Adresse e-mail du compte ACME utilisée pour l’émission.
`trusted_proxies`	`trusted_proxies <cidr> [<cidr> ...]`	Pairs autorisés à affirmer des en-têtes d’identité client. Un changement exige un redémarrage.

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

🧾Directives