Services web (Manuel de référence de GNU Guix)

11.10.20 Services web

Le module (gnu services web) fournit le serveur Apache HTTP, le serveur web nginx et aussi un démon fastcgi.

Serveur Apache HTTP

Variable :httpd-service-type

Type de service pour le serveur Apache HTTP (httpd). La valeur de ce type de service est un enregistrement httpd-configuration.

Un exemple de configuration simple est donné ci-dessous.

(service httpd-service-type
         (httpd-configuration
           (config
             (httpd-config-file
               (server-name "www.example.com")
               (document-root "/srv/http/www.example.com")))))

D’autres services peuvent aussi étendre httpd-service-type pour être ajouté à la configuration.

(simple-service 'www.example.com-server httpd-service-type
                (list
                  (httpd-virtualhost
                    "*:80"
                    (list (string-join '("ServerName www.example.com"
                                         "DocumentRoot /srv/http/www.example.com")
                                       "\n")))))

Les détails des types d’enregistrement httpd-configuration, httpd-module, httpd-config-file et httpd-virtualhost sont donnés plus bas.

Type de données :httpd-configuration

Ce type de données représente la configuration du service httpd.

package (par défaut : httpd): Le paquet httpd à utiliser.
pid-file (par défaut : "/var/run/httpd"): Le fichier de pid utilisé par le service shepherd.
config (par défaut : (httpd-config-file)): Le fichier de configuration à utiliser avec le service httpd. La valeur par défaut est un enregistrement httpd-config-file mais cela peut aussi être un G-expression qui génère un fichier, par exemple un plain-file. Un fichier en dehors du dépôt peut aussi être spécifié avec une chaîne de caractères.

Type de données :httpd-module

Ce type de données représente un module pour le service httpd.

name: Le nom du module.
file: Le fichier pour le module. Cela peut être relatif au paquet httpd utilisé, l’emplacement absolu d’un fichier ou une G-expression pour un fichier dans le dépôt, par exemple (file-append mod-wsgi "/modules/mod_wsgi.so").

Variable :%default-httpd-modules: Une liste par défaut des objets httpd-module.

Type de données :httpd-config-file

Ce type de données représente un fichier de configuration pour le service httpd.

modules (par défaut : %default-httpd-modules)

Les modules à charger. Les modules supplémentaires peuvent être ajoutés ici ou chargés par des configuration supplémentaires.

Par exemple, pour gérer les requêtes pour des fichiers PHP, vous pouvez utiliser le module mod_proxy_fcgi d’Apache avec php-fpm-service-type :

(service httpd-service-type
         (httpd-configuration
          (config
           (httpd-config-file
            (modules (cons*
                      (httpd-module
                       (name "proxy_module")
                       (file "modules/mod_proxy.so"))
                      (httpd-module
                       (name "proxy_fcgi_module")
                       (file "modules/mod_proxy_fcgi.so"))
                      %default-httpd-modules))
            (extra-config (list "\
<FilesMatch \\.php$>
    SetHandler \"proxy:unix:/var/run/php-fpm.sock|fcgi://localhost/\"
</FilesMatch>"))))))
(service php-fpm-service-type
         (php-fpm-configuration
          (socket "/var/run/php-fpm.sock")
          (socket-group "httpd")))

server-root (par défaut : httpd)

Le ServerRoot dans le fichier de configuration, par défaut le paquet httpd. Les directives comme Include et LoadModule sont prises relativement à la racine du serveur.

server-name (par défaut : #f)

Le ServerName dans le fichier de configuration, utilisé pour spécifier le schéma de requête, le nom d’hôte et le port que le serveur utilise pour s’identifier.

Cela n’a pas besoin d’être dans la configuration du serveur, et peut être spécifié dans les hôtes virtuels. La valeur par défaut est #f pour ne pas spécifier de ServerName.

document-root (par défaut : "/srv/http")

Le DocumentRoot depuis lequel les fichiers seront servis.

listen (par défaut : '("80"))

La liste des valeurs pour les directives Listen dans le fichier de configuration. La valeur devrait être une liste de chaînes, où chacune spécifie le port sur lequel écouter et éventuellement une adresse IP et un protocole à utiliser.

pid-file (par défaut : "/var/run/httpd")

Le PidFile à utiliser. Cela devrait correspondre à pid-file indiqué dans httpd-configuration pour que le service Shepherd soit correctement configuré.

error-log (par défaut : "/var/log/httpd/error_log")

Le ErrorLog où le serveur écrit les journaux d’erreurs.

user (par défaut : "httpd")

Le User en tant que lequel le serveur répondra aux requêtes.

group (par défaut : "httpd")

Le Group que le serveur utilisera pour répondre aux requêtes.

extra-config (par défaut : (list "TypesConfig etc/httpd/mime.types"))

Une liste plate de chaînes et de G-expressions qui seront ajoutées à la fin du fichier de configuration.

N’importe quelle valeur avec laquelle le service est étendu sera ajouté à cette liste.

Type de données :httpd-virtualhost

Ce type de données représente la configuration d’un hôte virtuel pour le service httpd.

Ils devraient être ajoutés à extra-config dans httpd-service.

(simple-service 'www.example.com-server httpd-service-type
                (list
                  (httpd-virtualhost
                    "*:80"
                    (list (string-join '("ServerName www.example.com"
                                          "DocumentRoot /srv/http/www.example.com")
                                       "\n")))))

addresses-and-ports: L’adresse et le port pour la directive VirtualHost.
contents: Le contenu de la directive VirtualHost, cela devrait être une liste de chaîne et de G-expressions.

NGINX

Variable :nginx-service-type

Type de service pour le serveur web NGinx. La valeur de ce service est un enregistrement <nginx-configuration>.

Un exemple de configuration simple est donné ci-dessous.

(service nginx-service-type
         (nginx-configuration
           (server-blocks
             (list (nginx-server-configuration
                     (server-name '("www.example.com"))
                     (root "/srv/http/www.example.com"))))))

En plus d’ajouter des blocs de serveurs dans la configuration du service directement, ce service peut être étendu par d’autres services pour ajouter des blocs de serveurs, comme dans cet exemple :

(simple-service 'my-extra-server nginx-service-type
                (list (nginx-server-configuration
                        (root "/srv/http/extra-website")
                        (try-files (list "$uri" "$uri/index.html")))))

Au démarrage, nginx n’a pas encore lu son fichier de configuration, donc il utilise les fichiers par défaut pour les messages d’erreur. S’il échoue à charger sa configuration, c’est là où les messages seront enregistrés. Après la lecture du fichier de configuration, le fichier de journal d’erreur par défaut change en fonction de celle-ci. Dans notre cas, les messages d’erreur au démarrage se trouvent dans /var/run/nginx/logs/error.log et après la configuration dans /var/log/nginx/error.log. Ce second emplacement peut être modifié avec l’option de configuration log-directory.

Type de données :nginx-configuration

Ce type de données représente la configuration de NGinx. Certaines configurations peuvent se faire ici et d’autres fournissent des types d’enregistrement ou éventuellement, on peut fournir un fichier de configuration.

nginx (par défaut : nginx)

Le paquet nginx à utiliser.

rshepherd-equirement (par défaut : '())

C’est une liste de symboles nommant les services du Shepherd dont les services nginx dépendent.

C’est utile si vous voulez que nginx démarre après qu’un serveur web en arrière-plan ou qu’un service de journalisation comme Anonip a été démarré.

log-directory (par défaut : "/var/log/nginx")

Le répertoire dans lequel NGinx écrira ses fichiers journaux.

log-level (default: 'error) (type: symbol)

Logging level, which can be any of the following values: 'debug, 'info, 'notice, 'warn, 'error, 'crit, 'alert, or 'emerg.

run-directory (par défaut : "/var/run/nginx")

Le répertoire dans lequel NGinx créera un fichier de pid et écrira des fichiers temporaires.

server-blocks (par défaut : '())

Une liste de blocs serveur à créer dans le fichier de configuration généré, dont les éléments sont de type <nginx-server-configuration>.

L’exemple suivant paramètre NGinx pour servir www.example.com depuis le répertoire /srv/http/www.example.com sans utiliser HTTPS.

(service nginx-service-type
         (nginx-configuration
           (server-blocks
             (list (nginx-server-configuration
                     (server-name '("www.example.com"))
                     (root "/srv/http/www.example.com"))))))

upstream-blocks (par défaut : '())

Une liste de blocs amont à créer dans le fichier de configuration généré, dont les éléments sont de type <nginx-upstream-configuration>.

Configurer les serveurs amont à travers les upstream-blocks peut être utile en combinaison avec locations dans les enregistrements <nginx-server-configuration>. L’exemple suivant crée une configuration de serveur avec une configuration « location » qui sera mandataire pour une configuration amont, qui gérera les requêtes avec deux serveurs.

(service
  nginx-service-type
  (nginx-configuration
    (server-blocks
      (list (nginx-server-configuration
              (server-name '("www.example.com"))
              (root "/srv/http/www.example.com")
              (locations
                (list
                  (nginx-location-configuration
                  (uri "/path1")
                  (body '("proxy_pass http://server-proxy;"))))))))
    (upstream-blocks
      (list (nginx-upstream-configuration
              (name "server-proxy")
              (servers (list "server1.example.com"
                             "server2.example.com")))))))

file (par défaut : #f)

Si un fichier de configuration file est fourni, il sera utilisé au lieu de générer un fichier de configuration à partir des log-directory, run-directory, server-blocks et upstream-blocks fournis. Pour un bon fonctionnement, ces arguments devraient correspondre à ce qui se trouve dans file pour s’assurer que les répertoires sont créé lorsque le service est activé.

Cela peut être utile si vous avez déjà un fichier de configuration existant ou s’il n’est pas possible de faire ce dont vous avez besoin avec les autres parties de l’enregistrement nginx-configuration.

server-names-hash-bucket-size (par défaut : #f)

Taille du seau pour les tables de hashage des noms de serveurs, par dauft #f pour utilise la taille des lignes de cache du processeur.

server-names-hash-bucket-max-size (par défaut : #f)

Taille maximum des seaux pour les tables de hashage des serveurs de noms.

modules (par défaut : '())

Liste de modules dynamiques de nginx à charger. Cela devrait être une liste de noms de fichiers de modules chargeables, comme dans cet exemple :

(modules
 (list
  (file-append nginx-accept-language-module "\
/etc/nginx/modules/ngx_http_accept_language_module.so")
  (file-append nginx-lua-module "\
/etc/nginx/modules/ngx_http_lua_module.so")))

lua-package-path (par défaut : '())

Liste des paquets lua à charger. Cela devrait être une liste de noms de paquets de modules lua chargeables, comme dans cet exemple :

(lua-package-path (list lua-resty-core
                        lua-resty-lrucache
                        lua-resty-signal
                        lua-tablepool
                        lua-resty-shell))

lua-package-cpath (par défaut : '())

Liste de paquets lua C à charger. cela devrait être une liste de noms de paquets de modules lua C, comme dans cet exemple :

(lua-package-cpath (list lua-resty-signal))

global-directives (par défaut : '((events . ())))

Liste d’association des directives globales pour le plus haut niveau de la configuration de nginx. Les valeurs peuvent elles-mêmes être des listes d’association.

(global-directives
 `((worker_processes . 16)
   (pcre_jit . on)
   (events . ((worker_connections . 1024)))))

extra-content (par défaut : "")

Additional content to be appended to the http block. Can either be a value that can be lowered into a string or a list of such values. In the former case, it is inserted directly. In the latter, it is prefixed with indentation and suffixed with a newline. Nested lists are flattened into one line.

(extra-content "include /etc/nginx/custom-config.conf;")
(extra-content `("include /etc/nginx/custom-config.conf;"
                 ("include " ,%custom-config.conf ";")))

Type de données :nginx-server-configuration

Type de données représentant la configuration d’un bloc serveur de nginx. Ce type a les paramètres suivants :

listen (par défaut : '("80" "443 ssl"))

Chaque directive listen indique l’adresse et le port pour le protocole IP ou le chemin d’un socket UNIX-domain sur lequel le serveur acceptera les connexions. On peut spécifier l’adresse et le port, ou juste l’adresse ou juste le port. Une adresse peut aussi être un nom d’hôte, par exemple :

'("127.0.0.1:8000" "127.0.0.1" "8000" "*:8000" "localhost:8000")

server-name (par défaut : (list 'default))

Une liste de noms de serveurs que ce serveur représente. 'default représente le serveur par défaut pour les connexions qui ne correspondent à aucun autre serveur.

root (par défaut : "/srv/http")

Racine du site web que sert nginx.

locations (par défaut : '())

Une liste d’enregistrements nginx-location-configuration ou nginx-named-location-configuration à utiliser dans ce bloc serveur.

index (par défaut : (list "index.html"))

Fichiers d’index à chercher lorsque les clients demandent un répertoire. S’il ne peut pas être trouvé, Nginx enverra la liste des fichiers dans le répertoire.

try-files (par défaut : '())

Une liste de fichiers dont l’existence doit être vérifiée dans l’ordre spécifié. nginx utilisera le premier fichier trouvé pour satisfaire la requête.

ssl-certificate (par défaut : #f)

Où trouver les certificats pour les connexions sécurisées. Indiquez #f si vous n’avez pas de certificats et que vous ne voulez pas utiliser HTTPS.

ssl-certificate-key (par défaut : #f)

Où trouver la clef privée pour les connexions sécurisées. Indiquez #f si vous n’avez pas de clef et que vous ne voulez pas utiliser HTTPS.

server-tokens? (par défaut : #f)

Indique si le serveur devrait ajouter sa configuration dans les réponses.

raw-content (par défaut : '())

A list of strings or file-like objects to be appended to the server block. Each item is prefixed with indentation and suffixed with a new line. Nested lists are flattened.

Type de données :nginx-upstream-configuration

Type de données représentant la configuration d’un bloc upstream nginx. Ce type a les paramètres suivants :

name: Nome de ces groupe de serveurs.
serveurs: Spécifie les adresses des serveurs dans le groupe. L’adresse peut être spécifié avec une adresse IP (p. ex. ‘127.0.0.1’), un nom de domaine (p. ex. ‘backend1.example.com’) ou un chemin vers un socket UNIX avec le préfixe ‘unix:’. Pour les adresse utilisant une adresse IP ou un nom de domaine, le port par défaut est 80 et un port différent peut être spécifié explicitement.
extra-content: Une chaine ou une liste de chaines à ajouter au bloc amont.

Type de données :nginx-location-configuration

Type de données représentant la configuration d’un bloc location nginx. Ce type a les paramètres suivants :

uri

URI qui correspond à ce bloc.

body

Body of the location block, specified as a list of strings or file-like objects. Each item is prefixed with indentation and suffixed with a new line. Nested lists are flattened.

For example, to pass requests to a upstream server group defined using an nginx-upstream-configuration block, the following directive would be specified in the body ‘(list "proxy_pass http://upstream-name;")’.

Type de données :nginx-named-location-configuration

Type de données représentant la configuration d’un bloc location nginx nommé. Les blocs location nommés sont utilisé les redirections de requêtes et pas pour le traitement des requêtes normales. Ce type a les paramètres suivants :

name: Nom pour identifier ce bloc location.
body: Voir nginx-location-configuration body, comme le corps d’un bloc location nommé peut être utilisé de la même manière que nginx-location-configuration body. Une restriction est que le corps d’un bloc location nommé ne peut pas contenir de bloc location.

Cache Varnish

Varnish est un serveur de cache rapide qui se trouve entre les applications web et les utilisateurs. Il sert de serveur mandataire pour les requêtes des clients et met les URL accédées en cache pour que plusieurs requêtes à la même ressource ne crée qu’une requête au moteur.

Variable :varnish-service-type: Type de service pour le démon Varnish.

Type de données :varnish-configuration

Type de données représentant la configuration du service varnish. Ce type a les paramètres suivants :

package (par défaut : varnish)

Le paquet Varnish à utiliser.

name (par défaut : "default")

Un nom pour cet instance de Varnish. Varnish va créer un répertoire dans /var/varnish/ avec ce nom et gardera des fichiers temporaires à cet endroit. Si le nom commence par une barre oblique, il est interprété comme un nom de répertoire absolu.

Passez l’argument -n aux autres programmes Varnish pour vous connecter à l’instance nommée, p. ex. varnishncsa -n default.

backend (par défaut : "localhost:8080")

Le moteur à utiliser. Cette option n’a pas d’effet si vcl est vrai.

vcl (par défaut : #f)

Le programme VCL (Varnish Configuration Language) à lancer. Si la valeur est #f, Varnsh servira de mandataire pour backend avec la configuration par défaut. Sinon, ce doit être un objet simili-fichier avec une syntaxe VCL valide.

Par exemple, pour créer un miroir de www.gnu.org avec VCL vous pouvez faire quelque chose comme cela :

(define %gnu-mirror
  (plain-file "gnu.vcl"
              "vcl 4.1;
backend gnu { .host = \"www.gnu.org\"; }"))

(operating-system
  ;; …
  (services (cons (service varnish-service-type
                           (varnish-configuration
                            (listen '(":80"))
                            (vcl %gnu-mirror)))
                  %base-services)))

On peut inspecter la configuration d’une instance Varnish actuellement lancée en utilisant le programme varnishadm.

Consultez le guide utilisateur de varnish et le livre varnish pour une documentation complète sur Varnish et son langage de configuration.

listen (par défaut : '("localhost:80"))

Liste des adresses sur lesquelles écoute Varnish.

storage (par défaut : '("malloc,128m"))

Liste de moteurs de stockage qui seront disponibles en VCL.

parameters (par défaut : '())

Liste des paramètres à l’exécution de la forme '(("parameter" . "value")).

extra-options (par défaut : '())

Arguments supplémentaires à passer au processus varnishd.

Whoogle Search

Whoogle Search is a self-hosted, ad-free, privacy-respecting meta search engine that collects and displays Google search results. By default, you can configure it by adding this line to the services field of your operating system declaration:

(service whoogle-service-type)

As a result, Whoogle Search runs as local Web server, which you can access by opening ‘http://localhost:5000’ in your browser. The configuration reference is given below.

Variable :whoogle-service-type: Service type for Whoogle Search. Its value must be a whoogle-configuration record—see below.

Data Type :whoogle-configuration

Data type representing Whoogle Search service configuration.

package (default: whoogle-search): The Whoogle Search package to use.
host (par défaut : "127.0.0.1"): The host address to run Whoogle on.
port (par défaut : 5000): The port where Whoogle will be exposed.
environment-variables (par défaut : '()): A list of strings with the environment variables to configure Whoogle. You can consult its environment variables template for the list of available options.

Patchwork

Patchwork est un système de suivi de correctifs. Il peut récupérer des correctifs envoyés à une liste de diffusion, et les afficher sur une interface web.

Variable :patchwork-service-type: Type de service pour Patchwork.

L’exemple suivant est un exemple de service Patchwork minimal, pour le domaine patchwork.example.com.

(service patchwork-service-type
         (patchwork-configuration
          (domain "patchwork.example.com")
          (settings-module
           (patchwork-settings-module
            (allowed-hosts (list domain))
            (default-from-email "patchwork@patchwork.example.com")))
          (getmail-retriever-config
           (getmail-retriever-configuration
            (type "SimpleIMAPSSLRetriever")
            (server "imap.example.com")
            (port 993)
            (username "patchwork")
            (password-command
             (list (file-append coreutils "/bin/cat")
                   "/etc/getmail-patchwork-imap-password"))
            (extra-parameters
            '((mailboxes . ("Patches"))))))))

Il y a trois enregistrements pour configurer le service Patchwork. Le <patchwork-configuration> correspond à la configuration de Patchwork dans le service HTTPD.

Le champ settings-module dans l’enregistrement <patchwork-configuration> peut être rempli avec l’enregistrement <patchwork-settings-modules>, qui décrit un module de paramètres généré dans le dépôt de Guix.

Pour le champ database-configuration dans <patchwork-settings-module>, il faut utiliser un <patchwork-dataase-configuration>.

Type de données :patchwork-configuration

Type de données représentant la configuration du service Patchwork. Ce type a les paramètres suivants :

patchwork (par défaut : patchwork): Le paquet Patchwork à utiliser.
domain: Le domaine à utiliser pour Patchwork, utilisé comme hôte virtuel dans le service HTTPD.
settings-module: Le module de paramètres à utiliser pour Patchwork. En tant qu’application Django, Patchwork est configuré avec un module Python contenant les paramètres. Il peut s’agir d’une instance de l’enregistrement <patchwork-settings-module>, de n’importe quel enregistrement qui représente les paramètres dans le dépôt, ou un répertoire en dehors du dépôt.
static-path (par défaut : "/static/"): Le chemin dans lequel le service HTTPD devrait servir les fichiers statiques.
getmail-retriever-config: La valeur d’enregistrement getmail-retriever-configuration à utiliser avec Patchwork. getmail sera configuré avec cette valeur, les messages seront livrés à Patchwork.

Type de données :patchwork-settings-module

Type de données représentant le module de paramètres de Patchwork. Certains de ces paramètres sont liés à Patchwork, mais d’autres sont liés à Django, le cadriciel web utilisé par Patchwork, ou la bibliothèque Django Rest Framework. Ce type a les paramètres suivants :

database-configuration (par défaut : (patchwork-database-configuration))

Les paramètres de connexion à la base de données à utiliser pour Patchwork. Voir le type d’enregistrement <patchwork-database-configuration> pour plus d’information.

secret-key-file (par défaut : "/etc/patchwork/django-secret-key")

Patchwork, en tant qu’application web Django, utilise une clé secrète pour signer des valeurs avec de la cryptographie. Ce fichier devrait contenir une valeur unique imprévisible.

Si ce fichier n’existe pas, il sera créé avec une valeur aléatoire par le service patchwork-setup.

Ce paramètre est lié à Django.

allowed-hosts

Une liste des hôtes valides pour ce service Patchwork. Cela doit au minimum inclure le domaine spécifié dans l’enregistrement <patchwork-configuration>.

C’est un paramètre pour Django.

default-from-email

L’adresse de courriel sur laquelle Patchwork devrait envoyer les courriels par défaut.

C’est un paramètre de Patchwork.

static-url (par défaut : #f)

L’URL à utiliser pour servir les ressources statiques. Cela peut être un bout d’URL ou une URL complète, mais doit finir par /.

Si la valeur par défaut est utilisée, la valeur static-path de <patchwork-configuration> sera utilisée.

C’est un paramètre pour Django.

admins (par défaut : '())

Adresses de courriel auxquelles envoyer le détails des erreurs s’il y en a. Chaque valeur de la liste contient deux éléments, le nom et l’adresse de courriel.

C’est un paramètre pour Django.

debug? (par défaut : #f)

Indique s’il faut lancer Patchwork en mode de débogage. Si la valeur est #t, les messages d’erreur détaillés seront affichés.

C’est un paramètre pour Django.

enable-rest-api? (par défaut : #t)

Indique s’il faut activer l’API REST de Patchwork.

C’est un paramètre de Patchwork.

enable-xmlrpc? (par défaut : #t)

Indique s’il faut active l’API RPC en XML.

C’est un paramètre de Patchwork.

force-https-links? (par défaut : #t)

Indique s’il faut utiliser des liens HTTPS sur les pages de Patchwork.

C’est un paramètre de Patchwork.

extra-settings (par défaut : "")

Code supplémentaire à placer à la fin du module de paramètres de Patchwork.

Type de données :patchwork-database-configuration

Type de données représentant la configuration de la base de données de Patchwork.

engine (par défaut : "django.db.backends.postgresql_psycopg2"): Le moteur de base de données à utiliser.
name (par défaut : "patchwork"): Le nom de la base de données à utiliser.
user (par défaut : "httpd"): L’utilisateur à utiliser pour se connecter à la base de données.
password (par défaut : ""): Le mot de passe à utiliser lors de la connexion à la base de données.
host (par défaut : ""): L’hôte sur lequel se connecter à la base de données.
port (par défaut : ""): Le port sur lequel se connecter à la base de données.

Mumi

Mumi is a Web interface to the Debbugs bug tracker, by default for the GNU instance. Mumi is a Web server, but it also fetches and indexes mail retrieved from Debbugs.

Variable :mumi-service-type: Le type de service pour Mumi.

Type de données :mumi-configuration

Type de données représentant la configuration du service Mumi. Ce type a les champs suivants :

mumi (par défaut : mumi): Le paquet Mumi à utiliser.
mailer? (par défaut : #true): Indique s’il faut activer le composant d’envoie de courriels.
mumi-configuration-sender: L’adresse de courriel utilisée comme expéditeur pour les commentaires.
mumi-configuration-smtp: Une URI pour configurer les paramètres SMTP pour Mailutils. Cela peut être quelque chose comme sendmail:///path/to/bin/msmtp ou toute autre URI prise en charge par Mailutils. Voir SMTP Mailboxes dans GNU Mailutils.

FastCGI

FastCGI est une interface entre le frontal et le moteur d’un service web. C’est un dispositif quelque peu désuet ; les nouveaux services devraient généralement juste parler HTTP entre le frontal et le moteur. Cependant il y a un certain nombre de services de moteurs comme PHP ou l’accès aux dépôts Git optimisé en HTTP qui utilisent FastCGI, donc nous le supportons dans Guix.

Pour utiliser FastCGI, vous configurez le serveur web frontal (p. ex. nginx) pour envoyer un sous-ensemble de ses requêtes au moteur fastcgi, qui écoute sur un socket UNIX ou TCP local. Il y a un programme fcgiwrap intermédiaire qui se trouve entre le processus du moteur et le serveur web. Le frontal indique quel moteur lancer, en passant cette information au processus fcgiwrap.

Variable :fcgiwrap-service-type: Un type de service pour le mandataire FastCGI fcgiwrap.

Type de données :fcgiwrap-configuration

Type de données représentant la configuration du service fcgiwrap. Ce type a les paramètres suivants :

package (par défaut : fcgiwrap)

Le paquet fcgiwrap à utiliser.

socket (par défaut : tcp:127.0.0.1:9000)

Le socket sur lequel le processus fcgiwrap écoute, en tant que chaîne de caractères. Les valeurs valides de socket sont unix:/path/to/unix/socket, tcp:dot.ted.qu.ad:port et tcp6:[ipv6_addr]:port.

user (par défaut : fcgiwrap)

group (par défaut : fcgiwrap)

Les noms de l’utilisateur et du groupe, en tant que chaînes de caractères, sous lesquels lancer le processus fcgiwrap. Le service fastcgi s’assurera que si l’utilisateur demande les noms d’utilisateurs et de groupes fcgiwrap l’utilisateur et le groupe correspondant seront présents sur le système.

Il est possible de configurer un service web soutenu par FastCGI pour passer les informations d’authentification HTTP depuis le frontal jusqu’au moteur, et de permettre à fcgiwrap dans lancer le processus de moteur avec l’utilisateur local correspondant. Pour activer cette fonctionnalité sur le moteur, lancez fcgiwrap en tant qu’utilisateur et groupe root. Remarquez que cette fonctionnalité doit aussi être configurée sur le frontal.

PHP-FPM

PHP-FPM (FastCGI Process Manager) est une implémentation FastCGI de PHP alternative avec quelques fonctionnalités supplémentaires utiles pour les sites de toutes tailles.

Ces fonctionnalités comprennent :

La création de processus adaptative
Des statistiques de base (comme le mod_status d’Apache)
La gestion des processus avancée avec arrêt et démarrage sans heurts
La possibilité de démarrer des processus de travail avec différents uid/gid/chroot/environnement et différents php.ini (à la place de safe_mode)
L’enregistrement des journaux sur stdout et stderr
Le redémarrage d’urgence dans le cas de la destruction accidentelle du cache des opcodes
Le support des téléversements accélérés
Le support de « showlog »
Des améliorations à FastCGI, comme fastcgi_finish_request() - une fonction spéciale pour terminer la requête et nettoyer toutes les données tout en continuant à faire d’autres choses qui prennent du temps (conversion vidéo, gestion des stats, etc.).

… et bien plus.

Variable :php-fpm-service-type: Un type de service pour php-fpm.

Type de données :php-fpm-configuration

Type de données pour la configuration du service php-fpm.

php (par défaut : php)

Le paquet php à utiliser.

socket (par défaut : (string-append "/var/run/php" (version-major (package-version php)) "-fpm.sock"))

L’adresse sur laquelle accepter les requêtes FastCGI. Les syntaxes valides sont :

"ip.add.re.ss:port": Écoute sur un socket TCP sur l’adresse spécifiée sur un port spécifié.
"port": Écoute sur un socket TCP sur toutes les adresse sur un port spécifique.
"/path/to/unix/socket": Écoute sur un socket unix.

user (par défaut : php-fpm)

Utilisateur à qui appartiendra le processus de travail de php.

group (par défaut : php-fpm)

Groupe du processus de travail.

socket-user (par défaut : php-fpm)

Utilisateur qui peut parler au socket php-fpm.

socket-group (par défaut : nginx)

Groupe qui peut parler au socket php-fpm.

pid-file (par défaut : (string-append "/var/run/php" (version-major (package-version php)) "-fpm.pid"))

Le pid de php-fpm est écrit dans ce fichier une fois que le service a démarré.

log-file (par défaut : (string-append "/var/log/php" (version-major (package-version php)) "-fpm.log"))

Fichier de journal pour le processus maître de php-fpm.

process-manager (par défaut : (php-fpm-dynamic-process-manager-configuration))

Configuration détaillée pour le gestionnaire de processus de php-fpm. Il doit s’agir soit de :

<php-fpm-dynamic-process-manager-configuration>
<php-fpm-static-process-manager-configuration> ou
<php-fpm-on-demand-process-manager-configuration>

display-errors (par défaut : #f)

Détermine si les erreurs et les avertissements php doivent être envoyés aux clients et affichés dans leur navigateur. Cela est utile pour un développement php local, mais un risque pour la sécurité pour les sites publics, comme les messages d’erreur peuvent révéler des mots de passes et des données personnelles.

timezone (par défaut : #f)

Spécifie le paramètre php_admin_value[date.timezone].

workers-logfile (par défaut : (string-append "/var/log/php" (version-major (package-version php)) "-fpm.www.log"))

Ce fichier enregistrera la sortie stderr des processus de travail de php. On peut indiquer #f pour désactiver la journalisation.

file (par défaut : #f)

Une version alternative de la configuration complète. Vous pouvez utiliser la fonction mixed-text-file ou un chemin de fichier absolu.

php-ini-file (par défaut : #f)

Une version alternative de la configuration de php par défaut. Il peut s’agir de n’importe quel objet « simili-fichier » (voir file-like objects). Vous pouvez utiliser la fonction mixed-text-file ou un chemin de fichier absolu.

Pour le développement local il est utile d’indiquer un long délai d’attente et une limite mémoire plus importante pour les processus php créés. Cela se fait avec les bouts de configuration systèmes suivants :

(define %local-php-ini
  (plain-file "php.ini"
              "memory_limit = 2G
max_execution_time = 1800"))

(operating-system
  ;; …
  (services (cons (service php-fpm-service-type
                           (php-fpm-configuration
                            (php-ini-file %local-php-ini)))
                  %base-services)))

Consultez les principales directives de php.ini pour une documentation complète sur les directives php.ini possibles.

Type de données :php-fpm-dynamic-process-manager-configuration

Type de données pour le gestionnaire de processus dynamic de php-fpm. Avec le gestionnaire de processus dynamic, des processus de travail de secours sont gardés en fonction des limites configurées.

max-children (par défaut : 5): Nombre maximum de processus de travail.
start-servers (par défaut : 2): Nombre de processus de travail au démarrage.
min-spare-servers (par défaut : 1): Nombre de processus de travail de secours minimum qui doivent rester à disposition.
max-spare-servers (par défaut : 3): Nombre maximum de processus de travail de secours qui peuvent rester à disposition.

Type de données :php-fpm-static-process-manager-configuration

Type de données pour le gestionnaire de processus static de php-fpm. Avec le gestionnaire de processus static, un nombre constant de processus de travail est créé.

max-children (par défaut : 5): Nombre maximum de processus de travail.

Type de données :php-fpm-on-demand-process-manager-configuration

Type de données pour le gestionnaire de processus on-demand de php-fpm. Avec le gestionnaire de processus on-demand, les processus de travail ne sont créés que lorsque les requêtes arrivent.

max-children (par défaut : 5): Nombre maximum de processus de travail.
process-idle-timeout (par défaut : 10): La durée en secondes après laquelle un processus sans requête sera tué.

Procédure :nginx-php-location [#:nginx-package nginx] [socket (string-append "/var/run/php" (version-major (package-version php)) "-fpm.sock")]: Une fonction d’aide pour ajouter rapidement php à un nginx-server-configuration.

Une configuration simple de services pour php ressemble à ceci :

(services (cons* (service dhcp-client-service-type)
                 (service php-fpm-service-type)
                 (service nginx-service-type
                          (nginx-server-configuration
                           (server-name '("example.com"))
                           (root "/srv/http/")
                           (locations
                            (list (nginx-php-location)))
                           (listen '("80"))
                           (ssl-certificate #f)
                           (ssl-certificate-key #f)))
                 %base-services))

Le générateur d’avatar de chat est un simple service pour démontrer l’utilisation de php-fpm dans Nginx. Il permet de générer des avatars de chats à partir d’une graine, par exemple le hash de l’adresse de courriel d’un utilisateur.

Procédure :cat-avatar-generator-service [#:cache-dir "/var/cache/cat-avatar-generator"] [#:package cat-avatar-generator] [#:configuration (nginx-server-configuration)]: Renvoie un nginx-server-configuration qui hérite de configuration. Il étend la configuration nginx pour ajouter un bloc de serveur qui sert package, une version de cat-avatar-generator. Pendant l’exécution, cat-avatar-generator pourra utiliser cache-dir comme répertoire de cache.

Une configuration simple de cat-avatar-generator ressemble à ceci :

(services (cons* (cat-avatar-generator-service
                  #:configuration
                  (nginx-server-configuration
                    (server-name '("example.com"))))
                 ...
                 %base-services))

Hpcguix-web

Le programme hpcguix-web est une interface web personnalisable pour naviguer dans les paquets Guix, initialement conçue pour les utilisateurs des grappes de calcul de haute performance (HPC).

Variable :hpcguix-web-service-type: Le type de service pour hpcguix-web.

Type de données :hpcguix-web-configuration

Type de données pour la configuration du service hpcguix-web.

specs (par défaut : #f)

Soit #f, soit une gexp (voir G-Expressions) qui spécifie la configuration du service hpcguix-web en tant qu’enregistrement hpcguix-web-configuration. Les principaux champs de ce type d’enregistrement sont :

title-prefix (par défaut : "hpcguix | "): Le préfixe du titre des pages.
guix-command (par défaut : "guix"): La commande guix à utiliser dans les exemples qui apparaissent sur les pages HTML.
package-filter-proc (par défaut : (const #t)): Une procédure qui spécifie comment filtrer les paquets qui seront affichés.
package-page-extension-proc (par défaut : (const '())): Paquet d’extensions pour hpcguix-web.
menu (par défaut : '()): Entrée supplémentaire dans la page menu.
channels (par défaut : %default-channels): Liste des canaux depuis lesquels la liste des paquets est construite (voir Canaux).
package-list-expiration (par défaut : (* 12 3600)): Le temps d’expiration, en secondes, après lequel la liste des paquets est reconstruite depuis les dernières instance des canaux donnés.

Voir le dépôt hpcguix-web pour un exemple complet.

package (par défaut : hpcguix-web)

Le paquet hpcguix-web à utiliser.

address (par défaut : "127.0.0.1")

L’adresse IP sur laquelle écouter.

port (par défaut : 5000)

Le numéro de port sur lequel écouter.

Une déclaration de service hpcguix-web typique ressemble à cela :

(service hpcguix-web-service-type
         (hpcguix-web-configuration
          (specs
           #~(hpcweb-configuration
              (title-prefix "Guix-HPC - ")
              (menu '(("/about" "ABOUT")))))))

Remarque : Le service hpcguix-web met régulièrement à jour la liste des paquets qu’il publie en récupérant les canaux depuis Git. Pour cela, il doit accéder aux certificats X.509 pour qu’il puisse authentifier les serveurs Git quand il communique en HTTPS, et il suppose que /etc/ssl/certs contient ces certificats.

A certificate package, nss-certs, is provided by default as part of %base-packages. Certificats X.509, for more information on X.509 certificates.

gmnisrv

Le programme gmnisrv est un serveur simple pour le protocole Gemini.

Variable :gmnisrv-service-type

C’est le type du service gmnisrv, dont la valeur devrait être un objet gmnisrv-configuration comme dans cet exemple :

(service gmnisrv-service-type
         (gmnisrv-configuration
           (config-file (local-file "./my-gmnisrv.ini"))))

Type de données :gmnisrv-configuration

Type données qui représente la configuration de gmnisrv.

package (par défaut : gmnisrv): Objet de paquet du serveur gmnisrv.
config-file (par défaut : %default-gmnisrv-config-file): Objet simili-fichier du fichier de configuration de gmnisrv à utiliser. La configuration par défaut écoute sur le port 1965 et sert les fichiers de /srv/gemini. Les certificats sont stockés dans /var/lib/gemini/certs. Pour plus d’informations, lancez man gmnisrv et man gmnisrv.ini.

Agate

Le programme Agate (page GitHub sur HTTPS) est un serveur simple pour le protocole Gemini écrit en Rust.

Variable :agate-service-type

C’est le type du service agate, dont la valeur devrait être un objet agate-service-type comme dans cet exemple :

(service agate-service-type
	 (agate-configuration
	   (content "/srv/gemini")
	   (certificates "/srv/gemini-certs")))

The example above represents the minimal tweaking necessary to get Agate up and running. Specifying the path to the certificate and key directory is always necessary, as the Gemini protocol requires TLS by default.

If the specified certificates path is writable by Agate, and contains no valid pre-generated key and certificate, Agate will try to generate them on the first start. In this case you should pass at least one hostname using the hostnames option. If the specified directory is read-only, key and certificate should be pre-generated by the user.

To obtain a certificate and a key in DER format, you could, for example, use OpenSSL, running commands similar to the following example:

openssl genpkey -out key.der -outform DER -algorithm RSA \
    -pkeyopt rsa_keygen_bits:4096
openssl req -x509 -key key.der -outform DER -days 3650 -out cert.der \
    -subj "/CN=example.com"

Of course, you’ll have to replace example.com with your own domain name, and then point the Agate configuration towards the path of the directory with the generated key and certificate using the certificates option.

Type de données :agate-configuration

Type de données représentant la configuration d’Agate.

package (par défaut : agate): Objet de paquet du serveur Agate.
content (par défaut : "/srv/gemini"): Le répertoire à partir duquel Agate servira ses fichiers.
certificates (default: "/srv/gemini-certs"): Root of the certificate directory. Must be filled in with a value from the user.
addresses (default: '("[::]:1965" "0.0.0.0:1965")): Une liste des adresses sur lesquelles écouter.
hostnames (default: '()): Virtual hosts for the Gemini server. If multiple values are specified, corresponding directory names should be present in the content directory. Optional.
languages (default: #f): Codes de langues RFC 4646 pour les documents text/gemini. Facultatif.
only-tls13? (default: #f): Set to #t to disable support for TLSv1.2.
serve-secret? (par défaut : #f): Indiquez #t pour servir des fichiers secrets (des fichiers et répertoires commençant par un point).
central-configuration? (default: #f): Set to #t to look for the .meta configuration file in the content root directory and will ignore .meta files in other directories
ed25519? (default: #f): Set to #t to generate keys using the Ed25519 signature algorithm instead of the default ECDSA.
skip-port-check? (default: #f): Set to #t to skip URL port check even when a hostname is specified.
log-ip? (par défaut : #t): Indique si l’adresse IP de sortie doit être journalisée.
user (par défaut : "agate"): Propriétaire du processus agate.
group (par défaut : "agate"): Groupe du propriétaire du processus agate.
log-file (par défaut : "/var/log/agate.log"): Le fichier qui devrait contenir la sortie de journal d’Agate.