Gentoo Logo

Documentation Apache pour les développeurs

Table des matières :

1.  À propos de ce document

Ce document détaille les nouvelles eclass, ce que nous avons changé depuis le précédent modèle d'Apache, et la façon dont les ebuilds ont besoin d'être modifiés pour tenir compte des avantages de nos nouvelles eclass. Si vous êtes un utilisateur à la recherche d'informations pour la mise à jour d'Apache, veuillez plutôt consulter le documentation de la mise à jour d'Apache.

2.  Ce qui a changé

Vue d'ensemble

Nous avons fait beaucoup de changements concernant la procédure d'installation et d'utilisation d'Apache et de ses modules sous Gentoo. Cela facilite les tâches de maintenance et permet de suivre de près les versions en amont. Voici nos changements :

  • Correction de nombreux bogues
  • Changement des chemins d'installation et de configuration
  • Création des eclass depend.apache et apache-module
  • Fusion des fichiers apache.conf et commonapache.conf en un seul fichier très similaire à la version de base
  • Dédoublement de apr et apr-utils en-dehors du paquet principal d'Apache pour ceux qui ne nécessitent plus Apache
  • Mise à jour et estampillage d'une version pour presque chaque module
  • Mise à disposition d'un plus grand nombre de MPM
  • Ajout du support de lingerd
  • Fixation du support des longs fichiers
  • Et bien plus encore, je suis sûr que j'en oublie...

Localisation des chemins d'Apache

Afin de suivre de plus près l'installation d'Apache en amont et celle des autres distributions, les chemins suivant ont changé :

Apache 2.x

Utilisation Ancien chemin Nouveau chemin
Racine du serveur /etc/apache2/ /usr/lib/apache2/
Répertoire de configuration /etc/apache2/conf/ /etc/apache2/
Configuration /etc/apache2/conf/apache2.conf /etc/apache2/httpd.conf
Configuration /etc/apache2/conf/commonapache2.conf /etc/apache2/httpd.conf
Configuration des hôtes virtuels /etc/apache2/conf/vhosts/ /etc/apache2/vhosts.d/
Configuration des modules /etc/apache2/conf/modules.d/ /etc/apache2/modules.d/
Modules binaires /usr/lib/apache2-extramodules/ /usr/lib/apache2/modules/

Note : La configuration inclut désormais automatiquement les fichiers modules.d/*.conf et vhosts.d/*.conf par défaut. Cependant, la directive dans le fichier httpd.conf énumère ce qui précède de la même façon que conf/modules.d/*.conf et conf/vhosts.d/*.conf. Cela est dû au fait qu'Apache lit la configuration en utilisant le répertoire /usr/lib/apache{|2} qui contient un lien symbolique conf -> /etc/apache{|2}.

Important : Si vous êtes développeur et que vous mettez à jour un ebuild pour utiliser les changements que nous avons faits, veuillez ne pas compliquer les chemins cités précédemment dans votre ebuild. Regardez plutôt la documentation des eclass pour les variables appropriées que vous pouvez utiliser.

3.  Mise à jour d'un ebuild

Avec nos nouveaux changements, pratiquement chaque ebuild qui dépend d'Apache doit être modifié. L'équipe d'Apache a déjà pris compte d'une grande majorité de ces paquets, car ils en sont responsables. Mais il en reste plusieurs qui appartiennent à d'autres mainteneurs et qui ont besoin d'être mis à jour.

Ce chapitre a pour but de guider un développeur à travers la mise à jour d'un ebuild pour utiliser les nouvelles eclass, en s'appuyant sur un de nos paquets les plus complexes, www-apache/mod_ldap_userdir par exemple.

Note : Si votre paquet actuellement n'est pas un module mais qu'il a juste besoin de connaître les chemins qu'utilise Apache, faites simplement un inherit depend.apache et utilisez les variables qui sont mises à votre disposition dans les eclass. Consultez pour cela la documentation du depend.apache des eclass.

Vue d'ensemble des changements nécessaires

  • Une nouvelle révision sera nécessaire tant que les versions modifiées pour les nouvelles eclass ne sont pas rétro-compatibles avec les anciennes versions d'Apache.
  • Assurez-vous d'avoir mis votre KEYWORDS en instable et (si les paquets d'Apache sont encore masqués) ajoutez-les au fichier package.mask.
  • Remplacez chaque DEPEND d'Apache par need_apache1 (pour les modules de Apache-1*), par need_apache2 (pour les modules d'Apache-2*), ou par need_apache (pour les modules qui peuvent dépendre d'Apache-1* ou d'Apache-2* — selon les variables USE indiquées).
  • Retirez n'importe quel code spécifique qui modifie le SLOT ou DEPEND avec des « bidouilles » telles que has_version.
  • Vérifiez que le src_compile par défaut dans l'eclass est fonctionnel. Si ce n'est pas le cas, réglez APXS1_ARGS et/ou APXS2_ARGS pour compiler les autres fichiers requis.
  • Généralement toutes les fonctions peuvent être retirées de l'ebuild.
  • Modifiez le fichier de configuration des modules afin d'utiliser les directives IfDefine pour charger et configurer le module.
  • Ajoutez les fichiers de documentation dans DOCFILES.
  • Spécifiez les fichiers de configuration que src_install devra installer : APACHE1_MOD_CONF, APACHE2_MOD_CONF.
  • Spécifiez le IfDefine que le module utilise dans son fichier de configuration, pkg_postinst peut vous donner des informations utiles pour activer le module : APACHE1_MOD_DEFINE, APACHE2_MOD_DEFINE.
  • N'oubliez pas de le tester — suivez les instructions de mise à jour de ce document si vous ne l'avez pas déjà fait.

Ebuilds globaux

Exemple de code 3.1 : Diff entre mod_ldap_userdir-1.4.1 et mod_ldap_userdir-1.4.1-r1 (edité)

+inherit apache-module
+
-IUSE="apache2 ssl"
+IUSE="ssl"

 DESCRIPTION="Apache module that enables ~/public_html from an LDAP directory."
 HOMEPAGE="http://horde.net/~jwm/software/mod_ldap_userdir/"
-KEYWORDS="x86 ppc"
+KEYWORDS="~x86 ~ppc"

 SRC_URI="http://horde.net/~jwm/software/mod_ldap_userdir/${P}.tar.gz"

-DEPEND="=net-www/apache-1*
-       apache2? ( =net-www/apache-2* )
-       ssl? ( dev-libs/openssl )
-       net-nds/openldap"
+DEPEND="ssl? ( dev-libs/openssl )
+       net-nds/openldap"

 LICENSE="GPL-1"
 SLOT="0"
+
+DOCFILES="DIRECTIVES README user-ldif posixAccount-objectclass"
+APACHE1_MOD_CONF="${PVR}/47_mod_ldap_userdir"
+APACHE2_MOD_CONF="${PVR}/47_mod_ldap_userdir"
+APACHE1_MOD_DEFINE="LDAPuserdir"
+APACHE2_MOD_DEFINE="LDAPuserdir"
+
+need_apache

Nous commençons avec inherit apache-module qui hérite également depend.apache. depend.apache définit les localisations qu'utilise Apache et, plus important, définit trois DEPEND : APACHE1_DEPEND pour les paquets qui ont besoin d'Apache-1*, APACHE2_DEPEND pour les paquets qui ont besoin d'Apache-2*, et APACHE_DEPEND pour les paquets qui peuvent avoir besoin soit d'Apache-1* soit d'Apache-2* et qui laissent à la variable USE apache2 le soin de déterminer cela.

Note : Pour le moment, nous ne supportons pas l'installation des deux versions d'Apache simultanément (bien que cela soit possible), car il n'est pas possible ensuite d'installer une seule version d'un module pour les deux versions d'Apache. Les modules devront juste utiliser un SLOT autre que 0 s'ils ont des lignes multiples de version et que chacun supporte une version différente d'Apache. (i.e. mod_layout-3.2.1-r1 possède un SLOT="1" et mod_layout-4.0.1a-r1 un SLOT="2".)

apache-module s'occupe d'une lourde tâche pour les paquets de module en définissant des valeurs convenables par défaut pour pkg_setup, src_compile, src_install et pkg_postinst.

Comme depend.apache ajoute apache2 à IUSE si nécessaire, vous ne devez plus le définir explicitement dans l'IUSE des ebuilds. Vous devrez cependant le laisser défini si vous employez cette variable USE dans votre ebuild quelque part.

depend.apache s'exécute en ajoutant le DEPEND Apache correct à votre DEPEND (si vous appelez l'une des fonctions de need_apache{|1|2}), ainsi vous pouvez retirer le traitement du DEPEND Apache de votre ebuild.

DOCFILES est utilisé par src_install dans apache-modules pour installer toutes les documentations. src_install détecte automatiquement les fichiers html et les autres fichiers, et utilise dodoc ou dohtml pour les installer à leur bonne place.

APACHE1_MOD_CONF et APACHE2_MOD_CONF définissent le fichier de configuration à installer pour le module. Ceci est utilisé pendant le src_install, ainsi ils peuvent être liés à ce que vous avez défini pour APXS1_S ou APXS2_S (par défaut à ${S}/src si c'est un répertoire, ou juste ${S}).

APACHE1_MOD_DEFINE et APACHE2_MOD_DEFINE indiquent aux eclass de quelle directive <IfDefine MODULENAME> le module se sert. Il est utilisé pour afficher à l'utilisateur des commandes sur la façon d'activer le module.

src_compile

src_compile peut être nécessaire si le module requiert des étapes spéciales que l'eclass ne peut traiter. Ce serait un cas assez exceptionnel. Dans la plupart des cas, en passant juste en revue le fichier Makefile et en ajoutant les éléments à APXS1_ARGS ou APXS2_ARGS, cela devrait être suffisant.

Exemple de code 3.2 : Diff entre mod_ldap_userdir-1.4.1 et mod_ldap_userdir-1.4.1-r1 (édité)

-src_compile() {
-   local myconf
-   if use apache2; then
-       myconf="${myconf} --with-apxs2=/usr/sbin/apxs2"
-   else
-       myconf="${myconf} --with-apxs=/usr/sbin/apxs"
-   fi
-
-   use ssl && myconf="${myconf} -with-tls"
-
-   myconf="${myconf} --with-activate"
-   ./configure ${myconf} || die "Configure failed"
-   make clean
-   make || die "Make failed"
-}

+src_compile() {
+   local myargs="-lldap -llber -c ${PN}.c"
+   use ssl && myargs="${myargs} -D TLS=1"
+
+   APXS2_ARGS="${myargs}"
+   APXS1_ARGS="${myargs}"
+
+   apache-module_src_compile
+
+}

Note : En général, si APXS1_ARGS ou APXS2_ARGS ont besoin d'être distincts, ils sont définis dans l'espace global. mod_ldap_userdir est différent à cet égard, parce que l'état de la variable USE ssl affecte ces variables et il est plus efficace de placer uniquement ces valeurs dans src_compile plutôt que de faire une vérification de la USE à chaque fois que vous invoquerez cet ebuild.

src_install

Dans la plupart des cas, src_install ne sera pas nécessaire. Il y a des exceptions quand d'autres répertoires ont besoin d'être installés ou quand les droits de fichiers doivent être changés.

Exemple de code 3.3 : Diff entre mod_ldap_userdir-1.4.1 et mod_ldap_userdir-1.4.1-r1 (édité)

-src_install() {
-   if use apache2; then
-       exeinto /usr/lib/apache2-extramodules
-       doexe mod_ldap_userdir.so
-   else
-       exeinto /usr/lib/apache-extramodules
-       doexe mod_ldap_userdir.so
-   fi
-   dodoc DIRECTIVES README user-ldif posixAccount-objectclass
-}
+src_install() {
+   apache-module_src_install
+   if [ "${APACHE_VERSION}" == "2" ]; then
+       fperms 600 ${APACHE2_MODULES_CONFDIR}/$(basename ${APACHE2_MOD_CONF})
+   else
+       fperms 600 ${APACHE1_MODULES_CONFDIR}/$(basename ${APACHE1_MOD_CONF})
+   fi
+}

Comme vous pouvez le voir, dans mod_ldap_userdir nous avions en fait ajouté quelques corrections qui n'étaient pas présentes dans la révision précédente — l'ajout d'un fichier de configuration et le réglage des permissions appropriées dessus. Mais nous permettons encore la présentation de apache-module en appelant apache-module_src_install à l'intérieur de notre src_install. Dans la plupart des cas, src_install ne sera pas nécessaire du tout.

src_install traite complètement l'installation du module, la configuration des fichiers et la documentation aux endroits corrects.

Autres fonctions

Dans la plupart des cas, il ne devrait y avoir ni pkg_postinst ni pkg_config pendant que les eclass manipulent des instructions d'affichage à l'utilisateur à propos de l'activation d'un module et de l'emplacement du fichier de configuration. Si des instructions additionnelles d'installation sont nécessaires, alors un pkg_postinst peut être ajouté, mais il devrait alors exécuter apache1_pkg_postinst ou apache2_pkg_postinst à l'intérieur de lui-même.

Exemple de code 3.4 : Diff entre mod_ldap_userdir-1.4.1 et mod_ldap_userdir-1.4.1-r1 (édité)

-pkg_postinst() {
-   if use apache2; then
-       elog "Adjust /etc/apache2/conf/modules.d/47_mod_ldap_userdir.conf to match your setup and"
-       elog "add '-D LDAPuserdir' to your APACHE2_OPTS in /etc/conf.d/apache2"
-       elog "To configure the package run \"ebuild /var/db/pkg/net-www/${PF}/${PF}.ebuild config\""
-   fi
-}
-
-pkg_config() {
-   /usr/sbin/apacheaddmod \
-       ${ROOT}/etc/apache/conf/apache.conf \
-       extramodules/mod_ldap_userdir.so mod_ldap_userdir.c ldap_userdir_module \
-       define=LDAPuserdir addconf=conf/addon-modules/47_mod_ldap_userdir.conf
-}

Avec la nouvelle configration par défaut d'Apache, nous n'avons plus besoin d'obliger l'utilisateur à modifier son fichier httpd.conf pour activer le module. Tous les fichiers *.conf du répertoire modules.d sont inclus automatiquement. Chaque fichier présent devra être complètement compris dans un bloc <IfDefine MODULENAME>, de telle sorte que les directives dans ce fichier ne soient utilisées que si les utilisateurs ajoutent un "-D MODULENAME" à leur fichier /etc/conf.d/apache{|2}.

Fichier de configuration

La plupart des fichiers de configuration n'auront besoin que de peu de changements. Voici le principal à surveiller pour être sûr qu'il utilise le chemin correct au chargement du module :

Exemple de code 3.5 : Directive LoadModule

(Ancienne directive :)
LoadModule ldap_userdir_module extramodules/mod_ldap_userdir.so

(Nouvelle directive :)
LoadModule ldap_userdir_module modules/mod_ldap_userdir.so

Ainsi, chaque fichier de configuration de module a besoin d'être compris dans un bloc <IfDefine MODULENAME>. Si vous ne faites pas cela, alors Apache chargera le module par défaut, ce que nous ne voulons pas — le chargement du module doit être contrôlé par l'utilisateur, en utilisant le fichier /etc/conf.d/apache{|2}.

Exemple de code 3.6 : Exemple de .conf

<IfDefine LDAPuserdir>
  <IfModule !mod_ldap_userdir.c>
    # Load the module:
    LoadModule ldap_userdir_module modules/mod_ldap_userdir.so
  </IfModule>
</IfDefine>

<IfModule mod_ldap_userdir.c>
# Mettez une bonne configuration par défaut ici :

    LDAPUserDir             public_html
    LDAPUserDirDNInfo       cn=root,dc=yourcompany,dc=com yourpassword
    LDAPUserDirBaseDN       ou=People,dc=yourcompany,dc=com

</IfModule>

Note : Certains modules peuvent vouloir ajouter des extensions qui sont vérifiées dans le DirectoryIndex. Nous avons modifié Apache afin d'avoir une nouvelle directive de configuration, AddDirectoryIndex, qui ne s'occupe que de cela. Utilisez-le exactement comme DirectoryIndex - il travaille de la même manière à l'exception près qu'il ne remplace pas le DirectoryIndex, il s'ajoute à lui. Il y a également un RemoveDirectoryIndex si cela est nécessaire pour une raison quelconque.

4.  Eclass apache-module

Description

L'eclass apache-module fournit des fonctions convenables par défaut pour la compilation des modules Apache. Puisque la plupart des modules sont compilés exactement de la même manière, ceci permet aux ebuilds de modules d'être extrêmement simples.

Fonctions

Fonction Description
apache_cd_dir Retourne le chemin correct du répertoire temporaire de construction.
apache_mod_file Retourne le chemin du module construit à installer.
apache_doc_magic Prend un seul argument optionnel. Si celui-ci est mentionné, la fonction retourne tous les fichiers *.html de ${DOCFILES}, autrement il retourne tous les fichiers non-*.html.
apache1_src_compile Appelle ${APXS1} avec les arguments de ${APXS1_ARGS}. Si un module requiert une installation différente de construction que celle-ci, utilisez ${APXS1} dans votre propre src_compile quotidien.
apache1_src_install Cette fonction installe le module et configure les fichiers dans le répertoire d'Apache. Elle gère l'installation des modules, leur configuration, les exécutables relatifs et la documentation.
apache1_pkg_postinst Affiche les messages de configuration standard.
apache2_pkg_setup Si APACHE2_SAFE_MPMS est paramétré, cette fonction vérifie les MPM installés et affiche une erreur s'il n'y a aucun MPM sûr installé.
apache2_src_compile Appelle ${APXS2} avec les arguments de ${APXS2_ARGS}. Si un module requiert une installation différente de construction que celle-ci, utilisez ${APXS2} dans votre propre src_compile quotidien.
apache2_src_install Cette fonction installe le module et configure les fichiers dans le répertoire d'Apache. Elle gère l'installation des modules, leur configuration, les exécutables relatifs et la documentation.
apache-module_pkg_setup
apache-module_src_compile
apache-module_src_install
apache-module_pkg_postinst
Ce sont des fonctions englobantes des fonctions apache1_* or apache2_*. Elles détectent automatiquement la version d'Apache avec lesquelles elles sont construites.

Variables

Variable Défaut Description
APACHE1_MOD_CONF
APACHE2_MOD_CONF
Non L'emplacement dans ${FILESDIR} de la configuration des modules, sans l'extention .conf.
APACHE1_MOD_DEFINE
APACHE2_MOD_DEFINE
Non Nom du « define » dans la configuration des modules. Utilisé en affichant un message à l'utilisateur pour l'ajouter à son /etc/conf.d/apache{|2}.
APACHE1_EXECFILES
APACHE2_EXECFILES
Non Fichiers exécutables additionnels qui devront être installés.
APACHE1_MOD_FILE
APACHE2_MOD_FILE
${PN}.so
.libs/${PN}.so
Les modules que src_install installe.
APACHE2_SAFE_MPMS Non Une liste des MPM qui fonctionnent avec ce module. Si ce n'est pas renseigné, alors aucune vérification des MPM ne sera faite. S'il y a des MPM peu sûrs d'installés l'utilisateur est averti. S'il n'y pas de MPM installés, le module refuse de s'installer.
APXS1_S
APXS2_S
Non Les chemins vers les répertoires de construction temporaires. Retourné par apache_cd_dir si renseigné, sinon il retourne ${S}/src (si c'est un répertoire) ou ${S} sinon.
APXS1_ARGS
APXS2_ARGS
-c ${PN}.c Arguments à passer à l'outil apxs.
DOCFILES Non La documentation à installer. Tous les fichiers qui finissent par .html sont installés en utilisant dohtml, les autres sont installés en utilisant dodoc.

5.  Eclass depend.apache

Description

L'eclass depend.apache règle les localisations par défaut des différents chemins d'Apache et gère les paramètres des dépendances sur Apache. En général, cette eclass ne devrait pas être utilisée par les modules. Elle devrait seulement être employée pour les programmes qui doivent dépendre d'Apache mais qui ne sont pas des modules. (Les modules devraient employer l'eclass apache-module.)

Fonctions

Fonction Description
need_apache1 Cette fonction renseigne correctement l'information sur les dépendances pour les paquets qui ne supportent que Apache-1.x. Les paquets qui nécessitent Apache-1.x devront appeler need_apache1 dans la portée globale pour placer correctement les dépendances.
need_apache2 Cette fonction renseigne correctement l'information sur les dépendances pour les paquets qui ne supportent que Apache-2.x. Les paquets qui nécessitent Apache-2.x devront appeler need_apache2 dans la portée globale pour placer correctement les dépendances.
need_apache Cette fonction renseigne correctement l'information sur les dépendances basées sur les variables USE actuellement réglées. Les paquets qui peuvent utiliser les deux versions d'Apache devront appeler need_apache dans la portée globale pour placer correctement les dépendances.

Variables

Variable Défaut Description
APACHE_VERSION 1 Paramétré par need_apache, need_apache1, need_apache2. Stocke la version d'apache que nous allons construire.
APXS1
APXS2
/usr/sbin/apxs
/usr/sbin/apxs2
Chemin vers l'outil apxs
APACHECTL1
APACHECTL2
/usr/sbin/apachectl
/usr/sbin/apache2ctl
Chemin vers l'outil apachectl
APACHE1_BASEDIR
APACHE2_BASEDIR
/usr/lib/apache
/usr/lib/apache2
Le chemin dans lequel le serveur tourne.
APACHE1_CONFDIR
APACHE2_CONFDIR
/etc/apache
/etc/apache2
Localisation du fichier de configuration httpd.conf
APACHE1_MODULES_CONFDIR
APACHE2_MODULES_CONFDIR
${APACHE1_CONFDIR}/modules.d
${APACHE2_CONFDIR}/modules.d
Emplacement où les modules devront installer leur configuration. Tous les fichiers *.conf dans ce répertoire sont inclus au lancement.
APACHE1_VHOSTDIR
APACHE2_VHOSTDIR
${APACHE1_CONFDIR}/vhosts.d
${APACHE2_CONFDIR}/vhosts.d
Emplacement où les configurations des hôtes virtuels devront être gardés. Tous les fichiers *.conf dans ce répertoire sont inclus au lancement.
APACHE1_MODULESDIR
APACHE2_MODULESDIR
${APACHE1_BASEDIR}/modules
${APACHE2_BASEDIR}/modules
Emplacement où les modules binaires devront être installés.

Note : Toutes les variables devront être considérées en lecture seule et ne devront pas être modifiées dans l'ebuild. Cela pourrait produire des résultats imprévisibles.



Imprimer

Dernière mise à jour le 30 juillet 2007

Résumé : Ce document fournit des détails au sujet des nouvelles eclass disponibles pour les développeurs des paquets relatifs à Apache.

Michael Stewart
Auteur

Marion Agé
Traducteur

Donate to support our development efforts.

Copyright 2001-2014 Gentoo Foundation, Inc. Questions, Comments? Contact us.