diff --git a/doc/README.md b/doc/README.md index df35eca..59fc5bd 100644 --- a/doc/README.md +++ b/doc/README.md @@ -19,6 +19,7 @@ ### Utilisation +- [(FR) - Le cas du "virtual hosting"](./fr/tutorials/virtual-hosting.md) - [(FR) - Ajouter un layer de type "file d'attente"](./fr/tutorials/add-queue-layer.md) - [(FR) - Ajouter une authentification OpenID Connect](./fr/tutorials/add-oidc-authn-layer.md) - [(FR) - Amorçage d'un serveur Bouncer via la configuration](./fr/tutorials/bootstrapping.md) diff --git a/doc/fr/tutorials/virtual-hosting.md b/doc/fr/tutorials/virtual-hosting.md new file mode 100644 index 0000000..add3041 --- /dev/null +++ b/doc/fr/tutorials/virtual-hosting.md @@ -0,0 +1,129 @@ +# Le cas du "virtual hosting" + +De nombreux serveurs HTTP utilisent le mécanisme du ["virtual hosting"](https://en.wikipedia.org/wiki/Virtual_hosting) afin d'héberger plusieurs sites/applications différentes sur un même serveur, se basant alors sur l'entête HTTP `Host` pour effectuer le routage. + +## Exemple + +Pour exemple, avec le site [example.net](https://example.net) il est facile de tester ce type de comportement. Ainsi, en exécutant une requête HTTP avec `curl`: + +```shell +curl -I https://example.net +``` + +On obtient le résultat suivant: + +``` +HTTP/2 200 +accept-ranges: bytes +age: 568237 +cache-control: max-age=604800 +content-type: text/html; charset=UTF-8 +date: Thu, 27 Jun 2024 08:32:46 GMT +etag: "3147526947" +expires: Thu, 04 Jul 2024 08:32:46 GMT +last-modified: Thu, 17 Oct 2019 07:18:26 GMT +server: ECAcc (bsb/2789) +x-cache: HIT +content-length: 1256 +``` + +Ce résultat indique que le serveur a correctement orienté notre requête (code HTTP `200`) et qu'il nous a renvoyé la réponse attendue. + +Si maintenant on modifie l'entête `Host` de notre requête pour la remplacer par une valeur arbitraire: + +```shell +curl -I -H 'Host: localhost:8080' https://example.net +``` + +On obtient alors le résultat: + +``` +HTTP/2 404 +content-type: text/html +date: Thu, 27 Jun 2024 08:38:04 GMT +server: ECAcc (bsb/2789) +content-length: 345 +``` + +Le serveur nous répond avec un code HTTP `404`, indiquant qu'il n'a pas trouvé la page demandée. + +> **Note** +> Le code HTTP retourné par le serveur peut varier en fonction des implémentations. Parfois la requête sera orientée vers la page par défaut, parfois vous recevrez un code d'erreur HTTP comme `404`, `421`, etc. + +## Avec Bouncer + +Ce mécanisme peut parfois poser problème avec Bouncer car par défaut celui ci n'effectue pas de réécriture de l'entête `Host`. Pour exemple: + +1. Créez puis activez un nouveau proxy pointant vers https://example.net + + ```shell + bouncer admin proxy create --proxy-name example --proxy-to https://example.net + bouncer admin proxy update --proxy-name example --proxy-enabled=true + ``` + +2. Avec `curl`, faites une requête sur votre nouveau proxy: + + ```shell + curl -I http://localhost:8080 + ``` + + La réponse devrait ressembler à: + + ``` + HTTP/1.1 404 Not Found + Content-Length: 345 + Content-Type: text/html + Date: Thu, 27 Jun 2024 08:49:05 GMT + Server: ECAcc (bsb/2789) + ``` + + On retrouve bien notre code HTTP `404` tel que vu plus haut. En effet, vu que l'on accède au proxy Bouncer avec `http://localhost:8080` alors le serveur distant recevra l'entête `Host: localhost:8080`. + +### Comment corriger la situation ? + +Le layer [`rewriter`](../references/layers/rewriter.md) a été implémenté notamment pour répondre à ce type de cas. Voyons comment l'utiliser: + +1. Créez puis activez un nouveau layer pour votre proxy `example`: + + ```bash + # Création du layer + bouncer admin layer create --proxy-name example --layer-name host-rewrite --layer-type rewriter + + # Mise à jour et activation du layer + bouncer admin layer update \ + --proxy-name example \ + --layer-name host-rewrite \ + --layer-options '{ "rules": { "request": ["set_host(\"example.net\")"] } }' \ + --layer-enabled=true + ``` + + > **Les règles** + > + > Le layer `rewriter` permet la modification des requêtes/réponses via un moteur de règles. + > + > [Voir la page du layer pour plus d'informations](../references/layers/rewriter.md) sur la syntaxe ainsi que sur l'API à disposition des règles. + +2. Testez maintenant à nouveau un appel vers votre proxy: + + ```shell + curl -I http://localhost:8080 + ``` + + La réponse devrait ressembler à: + + ``` + HTTP/1.1 200 OK + Accept-Ranges: bytes + Age: 569980 + Cache-Control: max-age=604800 + Content-Length: 1256 + Content-Type: text/html; charset=UTF-8 + Date: Thu, 27 Jun 2024 09:01:49 GMT + Etag: "3147526947" + Expires: Thu, 04 Jul 2024 09:01:49 GMT + Last-Modified: Thu, 17 Oct 2019 07:18:26 GMT + Server: ECAcc (bsb/2789) + X-Cache: HIT + ``` + + Cette fois ci, le serveur distant a bien identifié la cible de notre requête.