Le reste de la ligne après le signe # est un commentaire.
Le fichier de configuration est constitué de directives avec leurs paramètres.
Voici quelques exemples de directives simples.
... user nobody; error_log logs/error.log notice; worker_processes 1; ...
Un bloc de directives qui peut avoir d'autres directives entre accolades s'appelle un contexte (exemples: events, http, server et location).
Quelques blocs de directives de premier niveau, appelées contextes, regroupent les directives qui s'appliquent à différents types de trafic :
Les directives placées en dehors de tout contexte sont considérées comme étant dans le contexte principal.
Les événements et les directives http sont dans le contexte principal, le server dans http et location dans server.
La configuration suivante illustre l'utilisation des contextes :
user nobody; # une directive dans le contexte "principal" events { # configuration du traitement de la connexion } http { # Configuration spécifique à HTTP et affectant tous les serveurs virtuels server { # configuration du serveur HTTP virtuel 1 location /one { # configuration pour le traitement des URI commençant par '/ one' } location /two { # configuration pour le traitement des URI commençant par '/two' } } server { # configuration du serveur HTTP virtuel 2 } } stream { # Configuration spécifique à TCP / UDP et affectant tous les serveurs virtuels server { # configuration du serveur TCP virtuel 1 } }
Dans une ligne, ce qui suit un # est un commentaire.
On peut utiliser des variables, dont le nom commence par le caractère $ (dollar).
Des variables sont prédéfinies, et vous pouvez définir des variables personnalisées à l'aide des directives set, map et geo.
Par exemple,
Un bloc location peut contenir d'autres directives location.
Une directive location a deux types de paramètres :
Dans l'exemple suivant, le paramètre pathname correspond aux requêtes qui commencent par /some/path/, comme /some/path/document.html, mais pas à /my-site/some/path car /some/path n'est pas au début de cet URI :
location /some/path/ { ... }
Une expression régulière est précédée :
L'exemple suivant correspond aux URI qui incluent la chaîne .html ou .htm à n'importe quelle position.
location ~ \.html? { ... }
Un contexte location peut contenir des directives qui définissent la façon de résoudre une requête : servir un fichier statique ou transmettre la requête à un serveur proxy.
Dans l'exemple suivant, les demandes qui correspondent au premier contexte location sont des fichiers servis depuis le répertoire /data et les requêtes correspondant au second sont transmises au serveur proxy qui héberge le contenu du domaine www.example.com.
server { location /images/ { root /data; } location / { proxy_pass http://www.example.com; } }
La directive root spécifie le chemin du système de fichiers où rechercher les fichiers statiques à servir.
L'URI de la demande associée à l'emplacement est ajoutée au chemin pour obtenir le nom complet du fichier statique à servir.
Dans l'exemple ci-dessus, en réponse à une demande de /images/example.png, NGginx fournit le fichier /data/images/example.png.
La directive proxy_pass transmet la requête au serveur proxy accédé avec l'URL configurée.
La réponse du serveur proxy est ensuite renvoyée au client.
Dans l'exemple ci-dessus, toutes les demandes avec des URI qui ne commencent pas par /images/ sont transmises au serveur proxy.
Un contexte fils (contenu dans un autre contexte, son parent) hérite des paramètres des directives du parent.
Si une directive apparaît dans plusieurs contextes, le paramètre hérité du parent est remplacé par la directive du contexte enfant.
Par exemple, la directive proxy_set_header.
Certains URI de site Web exigent le retour immédiat d'une réponse avec une erreur spécifique ou un code de redirection, par exemple lorsqu'une page a été déplacée temporairement ou définitivement.
La méthode la plus simple consiste à utiliser la directive return. Par exemple :
location /wrong/url {
return 404;
}
Le premier paramètre de retour est un code de réponse.
Le deuxième paramètre facultatif peut être l'URL d'une redirection (pour les codes 301, 302, 303 et 307) ou le texte à renvoyer dans le corps de la réponse. Par exemple :
location /permanently/moved/url {
return 301 http://www.example.com/moved/here;
}
La directive return peut être incluse dans les contextes location et server.
la directive rewrite permet de modifier une URI de requête plusieurs fois lors du traitement. Elle a un paramètre facultatif et deux paramètres obligatoires :
Par exemple :
location /users/ { rewrite ^/users/(.*)$ /show?user=$1 break; }
Comme le montre cet exemple, le deuxième paramètre users capture en faisant correspondre les expressions régulières.
Vous pouvez inclure plusieurs directives rewrite dans les contextes server et location.
Nginx exécute les directives une par une dans l'ordre où elles apparaissent.
Les directives rewrite dans un contexte server sont exécutées une fois lorsque ce contexte est sélectionné.
Une fois que Nginx a traité un ensemble d'instructions de réécriture, il sélectionne un contexte d'emplacement en fonction du nouvel URI.
Si l'emplacement sélectionné contient des directives de réécriture, elles sont exécutées à tour de rôle.
Si l'URI correspond à l'un de ceux-ci, une recherche du nouvel emplacement démarre après le traitement de toutes les directives de réécriture définies.
L'exemple suivant montre les directives de réécriture en combinaison avec une directive return.
server { ... rewrite ^(/download/.*)/media/(.*)\..*$ $1/mp3/$2.mp3 last; rewrite ^(/download/.*)/audio/(.*)\..*$ $1/mp3/$2.ra last; return 403; ... }
Cet exemple de configuration distingue deux ensembles d'URI.
Les URI tels que /download/some/media/file sont remplacés par /download/some/mp3/file.mp3.
En raison de l'indicateur last, les directives suivantes (la seconde réécriture et la directive return) sont ignorées mais Nginx continue à traiter la demande, qui a maintenant un URI différent.
De même, les URI tels que /download/some/audio/file sont remplacés par /download/some/mp3/file.ra.
Si un URI ne correspond à aucune directive rewrite, Nginx renvoie le code d'erreur 403 au client.
Deux paramètres interrompent le traitement des directives de réécriture:
La directive sub_filter permet de réécrire ou modifier le contenu d'une réponse HTTP, en substituant une chaîne à une autre.
Elle permet des changements plus complexes, avec des variables et des chaînes de substitution.
Par exemple, pour modifier les liens absolus qui renvoient à un autre serveur que le proxy :
location / {
sub_filter /blog/ /blog-staging/;
sub_filter_once off;
}
Voici un autre exemple qui modifie http: en http_s_: et remplace l'adresse localhost par le nom d'hôte dans le champ d'en-tête de la requête.
La directive sub_filter_once demande à Nginx d'appliquer successivement les directives sub_filter dans un emplacement:
location / {
sub_filter 'href="http://127.0.0.1:8080/' 'href="https://$host/';
sub_filter 'img src="http://127.0.0.1:8080/' 'img src="https://$host/';
sub_filter_once on;
}
La partie de la réponse déjà modifiée par sub_filter ne sera pas remplacée à nouveau si une autre correspondance sub_filter se produit.