Historique de la page

 
{panel:bgColor=#F8F7EF}
h1. InstallationConseils et paramétrage de pam_casd'installation d'esup-portail
**
\\
Auteur : Vincent MathieuMATHIEU ([Université Nancy
        2|http://http://www.univ-nancy2.fr])
{panel} 
{toc:style=disc\|indent=20px\|minLevel=1}
  h1. Liens Téléchargementutiles
\\
Ce package est disponible en téléchargement [ici
 * [Document d'installation
        du package esup-portail|InstallPackage2-5Esup.html]
   * [Paramétrage
        du fichier personDirectory.xml|http://sourcesupwww.cru.fr/frs/?group_id=213&release_id=712].
h1. Généralités
\\
pam_cas est un module qui permet à un 'service' UNIX sachantja-sig.org/wiki/display/UPC/PersonDirectory]
   * Paramétrage et utilisation des groupes 
 ** [Paramétrage
      authentifier via pam d'utiliser le mécanisme de SSO du fichier CAS.
 
La version originale a été dévelopée par l'Université de Yale. EllecompositeGroupServices.xml|../gestion_groupes/serviceGroup/composite.html]
   ** [Service de
             est disponible [ici|http://www.yale.edu/tp/cas/cas-client-2.0.11.tar.gz].
 
Des modifications esup-portail ont été apportées afin de le rendregroupe 'local'|../gestion_groupes/serviceGroup/local.html]
   ** [Service de
          paramétrable.
 
Le fonctionnement global du module est le suivant :
 
 * Il reçoit de pam deux informations : le nom d'utilisateur et le    groupes 'LDAP"|../gestion_groupes/serviceGroup/ldap.html]
   ** [Groupes
              PAGS|../gestion_groupes/serviceGroup/pags.html]
   ** [Documentation
     PT (Proxy Ticket) passé comme mot de passe.
  groupes *PAGS Ilsur génèrele ensuite une connexion http(s) directe vers le serveur         CAS, à l'url de validation de PT (en standard, /proxyValidate).
   * Il analyse le retour de cette requête, reçue en xml : validation         du PT, identité de l'utilisateur, hiérarchie de proxies par lesquels         le PT a été obtenu.
   * Il fait un controle du nom de proxy pour des raisons de         sécurité, et s'assure que l'identité de l'utilisateur retournée par le         serveur CAS correspond à celle passée par pam.
   * Il retourne à pam le code PAM_SUCCESS en cas de réussite,         PAM_AUTH_ERR dans le cas contraire.
  h1. Modifications esup
\\
Les modifications apportées par rapport à la version de yale sont     les suivantes :
h2. fichier de configuration
\\
Il n'y a plus de paramètres 'en dur' dans les programmes.
 
La distribution proposée utilise un fichier de paramètres (par       défaut, /etc/pam_cas.conf)wiki uportal|http://www.ja-sig.org/wiki/display/GAP/uPortal+PAGS+documentation]
   

  h1. Généralités
\\
Ce document donne un exemple d'organisation d'une installation     esup-portail qui permet de faciliter la maintenance, et en particulier la     mise à jour de nouvelles versions en limitant les efforts et les     risques.
 
Il ne prétend pas être une bible : chaque installation est à adapter     en fonction de l'environnement cible : mono ou multi-serveurs, politique     de site, ...
 
Les différentes problématiques à prendre en compte sont les     suivantes :
 
h2. Gestion des librairies
\\
uPortal est packagé avec un certain nombre de librairies (fichiers       .jar) nécessaires à son bon fonctionnement ; esup-portail ajoute un       certain nombre de librairies communes à notre environnement.
 
Certains canaux ont également besoin de librairies externes pour       fonctionner ; les canaux 'natifs' uportal (hors les portlets)       s'exécutent dans le contexte d'uPortal ; ils partagent donc les mêmes       librairies.
 
h2. Gestion des connexions http(s)canaux, des fragments
\\
LaAu partiecours de codela consacréevie àdu la connexion http ou https a étéportail, l'administrateur est amené à gérer       son entièrement ré-écrite. Elle s'appuie toujours sur l'API openssl, mais encontenu : ajout / modification de canaux, modifications de       utilisant des fonctions de plus haut niveau qu'auparavant (objet       BIO).
h2. possibilités de debug
\\
Il est possible maintenant de débuguer le module sans avoir àfragments, ...
 
Il faut donc faire en sorte que ces actions soient les plus       pérennes possibles, et qu'un retour en arrière soit possible simplement       en retouchercas lede code, par simple modification d'un paramètre du fichier de       configuration.
 
De nombreuses informations de débugging ont été rajoutées. Lesmodification malheureuse.
 
h2. Mises à jour du 'socle' esup-portail
\\
C'est la mise à jour du package uPortal-w.z-esup.y       (exemple : uPortal-2.5-esup-1). Suivant       messagesl'ampleur dansde la log d'erreurs sont maitenant explicites mise à jour, la procédure va différer.
 
Enfinw, lez binaire {span:class=command}castest{span}
   a été complétement ré   sont les indices de mise à jour d'uPortal, y un sous-indice    écrit afin de pouvoir tester hors module pam la partie communication       avec le serveur CAS.
 
h2. Comportements optionnels
\\
 * L'administrateur peut maintenant choisir entre http ou https           pour la validation des proxy ticket.
   * Il est possible de ne plus contrôler le proxy qui a généré leesup-portail.
 
 * w : c'est une mise à jour majeure. Une procédure spécifique           doit être mise en oeuvre.
   * z : C'est une mise à jour 'intermédiaire'. Elle peut           nécessiter une mise à jour de la base de données, de JVM, ... Une           procédure Proxyspécifique Ticket.
peut être h2nécessaire. Divers
\\
 * Le Makefile* ay été: entièrementC'est réune écrit
mise à jour *mineure Corrige; unce document bugdevrait identifié avec certaines versions de      suffire à couvrir les contraintes redhat
liées à h1.ces Compilationmises duà module
\\
En pré-requis, openssl doit être installé.
 
Sur redhat, le package pam-devel doit également être     installé.
 
 * cd sources
   * cp Makefile.Redhat Makefile (sous redhat, ou autre Makefile en         fonction de l'OS).
   * make (compilation et création du module         pam_cas.so)
   * make test (si vous désirez utiliser le binaire         castest)
  Faire un contrôle du binaire généré : {span:class=command}ldd
    pam_cas.so{span}
  .
 
Si des fichiers d'include ou des librairies manquent, adapter     l'entête du Makefile.
 
Tenter un ./castest sans paramètre : il doit afficher un message     d'erreur du genre :
 
{code}
unable to open config file "/etc/pam_cas.conf"
Error while reading config file. Error 1
cannot open it
{code}

h1. Fichier de configuration
\\
Par défaut, le fichier de configuration est     /etc/pam_cas.conf.
 
Les directives doivent commencer en début de ligne.
 
Les lignes vides sont autorisées.
 
Une ligne 'active' se compose d'une directive, suivie d'espaces     et/ou tabulation, puis d'une valeur.
 
Les directives ne sont pas sensibles à la casse.
 
Les directives de type booléen acceptent les valeurs "on" ou     "off".
 
Les directives sont les suivantes :
 
{span:class=term}host{span}
  
  {quote}
  obligatoire. C'est le nom de host du serveur CAS (ex :           secure.its.yale.edu).    
  {quote}
{span:class=term}port{span}
  
  {quote}
  facultatif. C'est le port TCP pour contacter le serveur CAS en           http ou https. 
Par défaut : *80* si http, ou           *443* si https 
    
  {quote}
{span:class=term}uriValidate{span}
  
  {quote}
  facultatif. C'est l'URI utilisée pour la validation d'un  jour.
  La lecture du [document
    d'installation du package esup-portail|InstallPackage2-5Esup.html] est un préalable à la bonne     compréhension de ce document.
 
h1. Exemple d'installation du 'socle'
\\
Afin de faciliter la compréhension, nous allons prendre un exemple     d'installation 'générique' ; cette installation ne correspond     volontairement pas à un cas réel.
 
Elle est proposée en trame de la documentation. C'est bien un     exemple qui est proposé, pas un modèle à appliquer     systématiquement.
 
h2. Création d'un compte lié au portail
\\
Il est fortement conseillé d'installer un serveur apache en       frontal d'esup-portail, via mod_jk (ou       mod_proxy en apache 2.2).
 
Il n'est donc pas nécessaire que le lancement d'esup-portail (en       fait, le serveur J2EE supportant esup-portail) se fasse sous le compte       root, puisque le port TCP APJ13 peut être supérieur à 1024.
 
Nous supposerons ici qu'un compte esup est       créé.
 
Toutes les actions nécessaires au fonctionnement d'esup-portail (à       l'exception du frontal apache) seront faites sous le compte       'esup'. Tous les chemins file système paramétrés       seront accessibles en écriture à ce compte.
 
h2. Organisation file-système
\\
On va séparer l'environnement de paramétrage/compilation de       l'environnement de production.
 
Dans cet exemple, l'environnement de paramétrage/compilation sera       /home/esup/BUILD, l'environnement de production       /home/esup/PROD.
 
On suppose que le package à installer est uPortal-2.5-esup-1 ; il       est désarchivé dans /home/esup/BUILD/.
 
Voici un extrait du fichier esup.properties       correspondant à l'exemple de ce document :
 
{code}
java_home=/usr/java/jdk1.5
esup.custom=/home/esup/BUILD/Custom
esup.root=/home/esup/BUILD/uPortal-package
esup.distrib=/home/esup/BUILD/uPortal-sources
esup.custom=/home/esup/BUILD/Custom
esup.deploy=/home/esup/PROD/webapps
server.home=/home/esup/PROD/Tomcat
server.temp=/home/esup/PROD/temp
{code}


 
 * /ur/java/jdk1.5 est un lien symbolique         Ticket. 
Par défaut, */proxyValidate* 
  vers la JVM 1.5 courante.
   * /home/esup/BUILD/uPortal-package est un    
  {quote}
{span:class=term}ssl{span}
  
  {quote}
 lien facultatif,symbolique booléen.vers Si _on_, la connexion   le répertoire de décompactage du package, ici        se fera en https, si _off_ en http 
Par défaut, prend la valeur *on* 
 BUILD/uPortal-2.5-esup-1.
   * /home/esup/BUILD/uPortal-sources est un    
  {quote}
{span:class=term}debug{span}
  
  {quote}
 lien facultatif,vers booléen.le Si *on*,répertoire BUILD/uPortal-2.5-esup-1-sources           des(à informationscréer de debug sont envoyées dans le syslog (niveau    avant {span:class=command}ant esup.unzip{span}
  ).
   * /home/esup/PROD/webapps est un lien       _LOG_DEBUG_). 
par défaut, prend lasymbolique valeur *off* 
    
  {quote}
{span:class=term}proxy{span}
  
  {quote}
  facultatif. On y paramètre le nom du proxy CAS qui a obtenu le vers PROD/webapps-2.5-esup-1
   * /home/esup/PROD/Tomcat est un lien           symbolique vers PROD/Tomcat_5-5-9
  On crée également le répertoire          Proxy Ticket. 
Il peut y avoir plusieurs directives/home/esup/BUILD/canaux, qui sera la racine de       désarchivage des différents canaux   _proxy_installés.
 
h2. Personnalisations
\\
SiLes paspersonnalisations depropres directive proxy, pam_cas n'effectue pas ceà l'établissement se trouvent dans       le répertoire /home/esup/BUILD/Custom, lui-même  contrôle. 
ex : _proxy
  subdivisé en sous-répertoires : ROOT,    https://uportal1.its.yale.edu/CasProxyServlet_ 
    
  {quote}
{span:class=term}trusted_ca{span}
  
  {quote}
  facultatif si ssl a la valeur off. 
Contient le nom d'un fichier qui contient un ou plusieurs           certificats au format pem. 
Ce certificat sert à valider la connexion https. 
Si le certificat X509 du serveur CAS est auto-signé, ceTomcat, uPortal.
 
Vous aurez au moins les choses suivantes dans le répertoire       Custom :
 
h3. Custom/uPortal/properties
\\
On devrait y trouver au moins les fichiers suivants :
 * uPortal55.xml : C'est un fichier qui             permet de définir les pools Tomcat de connexion aux différents             bases certificatde doitdonnées.
 être dans le* fichierpersonDirectory.xml : 
Sice lefichier certificatpermet a été signé par une Autorité de      de faire un 'mapping' entre Certification, c'est le certificat de l'AC de plus haut niveau de lades attributs LDAP (ou issus d'une             base SQL) avec des chaineattributs deuPortal. cetificationVoir qui[ce
 doit être dans le fichier. 
    
  {quote}

Voici un exemple de [fichier de  document|http://www.ja-sig.org/wiki/display/UPC/PersonDirectory] sur le wiki uportal.
    configuration|pam_cas.conf].
 
h1. Utilisation du module
\\
On va prendre pour exemple l'intégration pour le serveur imap
 * Recopier le module pam_cas.so dans* groups/PAGSGroupStoreConfig.xml :             définition des groupes dynamiques uPortal. Voir [ce
            /lib/security/. 
ajuster le propriétaire et les droits 

   * Adapter le fichier /etc/pam.d/imap (voirdocument|http://www.ja-sig.org/wiki/display/GAP/uPortal+PAGS+documentation] sur le wiki uportal.
   * chanpub/XXXXX.xml : les fichiers de             publication exemple ci-après)
   * Arrêter - Relancer le démon utilisateur (dans le cas dedes différents canaux. Même s'il est possible de             déclarer / modifier cyrus-imap, c'est le démon saslauthd). 
En fait, cette dernière étape n'est à priori pasdynamiquement dans uPortal les canaux, nous             préconisons de le faire nécessaire.par 

la publication h2.de Paramètresces du module
\\
 * *-s* : paramètre obligatoire.fichiers de             description (utilisés par Contientla l'URL du service tier. Cette URL doit être identique àcommande {span:class=command}ant
            uportal.pubchan{span}
  ), ceci afin de les cellerejouer que le proxy CAS a passé au serveur CAS lors de la demandeultérieur.
 du  * al/xx-fragments.xml : les fragments     PT.
   * *-f* : paramètre facultatif. poussés pour cette instance d'esup-portail.
  h3. Custom/uPortal/lib
\\
Comme indiqué dans C'estun lepragraphe nomsuivant, duce fichierrépertoire de paramètres (par défaut,     contiendra les librairies    /etc/pam_cas.conf).
  h2. Exemple de fichier /etc/pam.d/imap(fichiers .jar) nécessiare à l'exécution de         certains canaux.
h3. Custom/uPortal/webpages
\\
CeCa fichiercontenir supposeles queéventuels imapskins tentede l'authentification CAS, puis       LDAP, puis UNIX
 
{code}
   auth sufficient /lib/security/pam_cas.so -simap://imap.univ.fr -f/etc/pam_cas.conf
   auth sufficient /lib/security/pam_ldap.so
   auth required /lib/security/pam_pwdb.so shadow nullok
   account required /lib/security/pam_pwdb.so shadow nullok
{code}

A remarquer qu'on peut mettre pam_cas sans craintes de surcharge établissement.
h2. Première installation du portail
\\
On utilise la procédure 'normale' :
 * {span:class=command}ant -buildfile
          /home/esup/BUILD/uPortal-package/build.xml
          esup.unzip{span}
  
   * {span:class=command}ant -buildfile
          /home/esup/BUILD/uPortal-package/build.xml
      du serveur imap : il ne fait de requêtes auprès du serveur CAS que si le esup.init{span}
  
   * {span:class=command}ant -buildfile
           mot de passe reçu ressemble à un PT ou un ST.
 
h1. En cas de problème
\\
h2. logs 'normaux'
\\
Des logs sont produits en cas d'erreur, aux niveaux/home/esup/BUILD/uPortal-package/build.xml
          esup.deploy{span}
  
   * {span:class=command}ant -buildfile
          /home/esup/BUILD/uPortal-package/build.xml
       _LOG_NOTICE_ et _LOG_ERR_
 
Des logs de debug sont générés si {span:class=command}debug=on{span}
   dans       le fichier de configuration. Ils sont alors produits au niveau       _LOG_DEBUG_.
 
h2. castest
\\
C'est un utilitaire fourni dans le 'package' pam_cas. Il permet de       générer des requêtes de validation de ticket auprès du serveur CAS. Il       utilise les mêmes librairies que le module pam_cas, et utilise également       le fichier de config.
 
Il est vivement conseillé de l'utiliser avant la mise en service       du module pam_cas ; cela permet de debuguer la configuration.
 
Il affiche sa configuration, puis tente de valider le ticket. Il       affiche alors les messages que sort pam_cas en mode debug, plus d'autres       informations.
 
Il supporte les arguments suivants (tous facultatifs) :
 
 * le service CAS. Par défaut,           _https://foo.fr_
   * un ticket (ST ou PT) à valider. Par défaut, PT-1-xxx
   * le nom du fichier de configuration. Par défaut,           /etc/pam_cas.conf
  Donc, pour l'utiliser, préparez déja votre fichier de       configuration.
 
exemple d'utilisation :
 
{code}
$PAM_CAS_SOURCES/castest <service> <ticket> <fichier_de_configuration>
{code}

Il est possible de le lancer sans paramètres. Avec un fichier de       configuration correctement paramétré, la sortie est la suivante :
 
{code}
---------------------------------------------------------------
                    Parameters from test :
host = auth.univ-nancy2.fr
port = 443
uri = /proxyValidate
ssl = on
trusted_ca = /Cert/ac-racine.pem
debug = localtest
proxy = https://imp.univ.fr/cas/casProxy.php
proxy = https://ent.univ.fr/CasProxyServlet
service = https://foo.fr
ticket = PT-1-xxx
---------------------------------------------------------------
authentication failure
<cas:serviceResponse xmlns:cas='http://www.yale.edu/tp/cas'>
  <cas:authenticationFailure code='INVALID_TICKET'>
    ticket 'PT-1-xxx' not recognized
  </cas:authenticationFailure>
</cas:serviceResponse>
---------------------------------------------------------------
invalid ticket : bad CAS ticket
{code}

On a donc validé les paramètres de communication avec le serveur       CAS très simplement.
 
Si problème, s'assurer avec wget que la machine qui supporte       pam_cas arrive bien à communiquer avec le serveur CAS. Par exemple       :
 
{code}
wget --ca-certificate=/Cert/ac-racine.pem -O /tmp/cas.log "https://auth.univ.fr:443/proxyValidate?ticket=PT-1-xxx&service=https://foo.fr"
{code}

Le contenu du fichier /tmp/cas.log contient       la réponse du serveur CAS ; il devrait être :
 
{code}
<cas:serviceResponse xmlns:cas='http://www.yale.edu/tp/cas'>
  <cas:authenticationFailure code='INVALID_TICKET'>
    ticket 'PT-1-xxx' not recognized
  </cas:authenticationFailure>
</cas:serviceResponse>
{code}

*Rem* : si on ne veut pas valider       le certificat du serveur https lors du wget, il suffit de remplacer       --ca-certificate=/Cert/ac-racine.pem par       --no-check-certificate ; un warning sera néammoins       affiché lors du wget.
 
h2. testImap.php
\\
Cet [utilitaire|../imap/CyrusImap-cas.html#CASIMAP] permet de       tester le fonctionnement d'un serveur IMAP CAS-ifié.
h1. Cache des tickets
\\
pam_cas permet de valider un ticket (PT ou ST) présenté comme un     simple mot de passe.
 
Pour des raisons de performance, il est souvent nécessaire de     "cacher" ce ticket afin de pouvoir le rejouer plusieurs fois.
 
[Ce document |../imap/CyrusImap-cas.html]décrit     l'exemple d'imap. Imap est utilisé par les webmail (cassifiés), l'ent     (cassifié) et les clients de messagerie (non cassifié).
 
Les Webmails ont la particularité de générer de nombreuses     connexions imap, au moins une par chargement de page.
 
Il serait très couteux que le webmail redemande un nouveau ticket     pour chaque ouverture de connexion IMAP ; un cache doit donc être installé     côté serveur, et le code du client webmail doit être modifié afin de gérer     au mieux ce mécanisme de cache.
 
h2. mécanismes de cache
\\
Deux mécanismes de cache coté serveur sont connus,       cyrus-saslauthd et pam_ccreds ; il       existe aussi la solution imapproxy.
h3. cyrus - saslauthd
\\
C'est un démon qui est livré avec la distribution         cyrus-imap.
 
cyrus-imap peut être paramétré pour authentifier les connexions         (imap, pop, ...) à l'aide de ce démon, via une socket unix.
 
saslauthd peut être paramétré pour authentifier à l'aide de pam.         Il est alors possible d'utiliser pam_cas pour cassifier saslauthd,         donc cyrus-imap.
 
Et il est possible de paramétrer saslauthd pour qu'il implémente         un cache de mot de passe (donc, éventuellement, de tickets).
 
Un intérêt essentiel de saslauthd est le fait qu'il est capable         de conserver en cache plusieurs mots de passe pour un utilisateur ;         ceci permet d'optimiser le mécanisme lorsque des sources différentes         (ent, webmail, client lourd) génèrent en parralèle des requêtes IMAP,         avec chacune un mot de pase différent.
 
h3. pam_ccreds
\\
C'est un module pam qui permet de cacher les mots de         passe.
 
Il est développé par [PADL
        Software|http://www.padl.com/].
 
Des patchs ont été proposés par Nicolas Bouillis fin de         l'adapter au cache de ticket, et à apporter des fonctionnalités         supplémentaires.
 
Une [documentation
        de mise en oeuvre|https://portail.cevif.univ-paris13.fr/wiki/Pam_ccreds] est proposée par Damien Mascré (IUT         Villetaneuse - Paris 13).
 
Voir également un [échange
        de mails|http://listes.esup-portail.org/sympa/arc/esup-devel/2006-04/msg00019.html] à ce sujet sur la liste esup-devel.
 
Pour les personnes qui ne sont pas abonnées à cette liste,         [ce mail est également
        disponible|pam_ccreds-mail.txt], ainsi que le [document attaché|pam_ccreds-3-patchs.zip]         (patchs).
 
h3. imapproxy
\\
C'est une solution utilisée par certains établissements, qui         semble donner satisfaction.
 
Voir les documents suivants :
 
 * [http://shib.kuleuven.be/docs/horde3-cas/proxyCAS.pdf|http://shib.kuleuven.be/docs/horde3-cas/proxyCAS.pdf]
   * [http://shib.kuleuven.be/docs/horde3-cas/|http://shib.kuleuven.be/docs/horde3-cas/]
   * [http://wiki.horde.org/CASAuthHowTo|http://wiki.horde.org/CASAuthHowTo]
   esup.db.init{span}
  
  h1. Installation des canaux
\\
Comme indiqué prédédemment, un répertoire dédié aux canaux a été     créé.
 
Chaque canal à la norme esup contient à sa racine un fichier     {span:class=command}build.properties{span}
  , qui contient au moins les trois     propriétés tomcat.home,     uportal.home, deploy.home ; voici     comment les valuer dans notre exemple :
 
{code}
#Repertoire d'installation de Tomcat
tomcat.home  = /home/esup/PROD/Tomcat

#Repertoire d'installation d'uPortal
uportal.home = /home/esup/BUILD/uPortal-sources

#Repertoire de deploiement
deploy.home  = /home/esup/PROD/webapps/uPortal
{code}

A la racine du répertoire     /home/esup/BUILD/canaux, un script shell est créé,     afin de pouvoir compiler/déployer facilement l'ensemble des canaux, et de     pouvoir rejouer cette installation (le terme déploiement ici ne comprend     pas la déclaration des canaux dans la base esup-portail, mais la     compilation et la recopie des classes java et des fichiers annexes aux     canaux dans l'environnement de production).
 
Voici ce script :
 
{code}
#!/bin/sh

UPORTAL_CHANNEL_DIR=/home/esup/BUILD/canaux

CHANNELS="esup-utils-mag-2.10-RC-3 connectors-1.06-RC-1 CAnnuaire-3.0-RC-4 CActu-1.0-Rc-2 .... "

for channel in $CHANNELS
do
  if [ -d  $UPORTAL_CHANNEL_DIR/$channel ]; then
      /home/uportal/ant.sh -buildfile $UPORTAL_CHANNEL_DIR/$channel/build.xml clean > /dev/null 2>&1   
      echo -n "Deploy $channel : "

      /home/uportal/ant.sh -buildfile $UPORTAL_CHANNEL_DIR/$channel/build.xml deploy | grep BUILD 
  else
     echo -n "###### $channel pas trouve #####"
  fi
done
{code}

Une attention particulière doit être apportée aux libraires     (fichiers .jar) nécessaires à certains canaux. Ces librairies se trouvent     habituellement dans le sous-répertoire lib de la racine de désarchivage du     canal.
 
Ces librairies doivent être ajoutées en final dans le répertoire de     librairies d'esup-portail :     PROD/webapps/uPortal/WEB-INF/lib.
 
Il est déconseillé de les ajouter directement dans ce répertoire ;     nous conseillons de les ajouter dans     BUILD/Custom/uPortal/lib, puis de lancer ensuite un     {span:class=command}ant esup.init{span}
   puis {span:class=command}ant
    esup.deploy{span}
  .
 
Ceci permet de suivre plus facilement les librairies liées aux     canaux. En particulier, avant de recopier une nouvelle librairie dans ce     répertoire, il faut s'assurer qu'un autre librairie de même nom n'y est     pas présente, afin d'éviter les conflits.
 
{info}
Si une libraire plus récente doit être installée (exemple :       mylib.2.2 en remplacement de mylib.2.1), il faut éviter que les 2       librairies se retrouvent en final dans l'environnement de production       esup-portal.
 
Pour celà, il faut supprimer dans les différents environnements       l'ancienne librairie :
 
- BUILD/Custom/uPortal/lib/mylib.2.1
 
- BUILD/uPortal-sources/lib/mylib.2.1
 
-       PROD/webapps/uPortal/WEB-INF/lib/mylib.2.1
 
{info}
h1. Installation d'une nouvelle version du package
\\
Ce paragraphe décrit l'installation une version mineure, qui     n'impacte pas la base esup-portail.
 
Grace aux différents liens symboliques utilisés, on s'assure d'un     retour en arrière facile.
 
On suppose ici qu'on installe la version     uPortal-2.5-esup-2.
 
h2. Liens symboliques
\\
On déporte les différents liens symboliques vers les nouveaux       répertoires :
 * /home/esup/BUILD/uPortal-package vers           BUILD/uPortal-2.5-esup-2.
   * /home/esup/BUILD/uPortal-sources vers           BUILD/uPortal-2.5-esup-2-sources
   * /home/esup/PROD/webapps vers           PROD/webapps-2.5-esup-2
  h2. désarchivage du package
\\
Dans /home/esup/BUILD, donc vers       BUILD/uPortal-2.5-esup-2
h2. Personnalisations
\\
D'une manière générale, commencer par lire le fichier       CHANGELOG de la nouvelle version du package.
 
Les modifications qui sont fortement susceptibles de nécessiter       des modifications de paramètres sont préfixés de 5 étoiles       "_*****_".
 
h3. esup.properties
\\
{span:class=command}cp BUILD/uPortal-2.5-esup-1/esup.properties
        BUILD/uPortal-2.5-esup-2/{span}
  
 
Vérifier que les paramètres sont toujours corrects. Voir         CHANGELOG. Si modification nécessaire, penser à         sauvegarder l'ancien fichier.
 
h3. Custom/uPortal
\\
Vérifier que les fichiers que vous avez personnalisés n'ont pas         été modifiés par cette nouvelle version. Si nécessaire, les adapter         (sauvegarde préalable).
h2. Installation
\\
Comme l'installation originale, sans l'installation de la base       : * {span:class=command}ant -buildfile
            /home/esup/BUILD/uPortal-package/build.xml
            esup.init{span}
  
   * {span:class=command}ant -buildfile
            /home/esup/BUILD/uPortal-package/build.xml
            esup.deploy{span}
  
  
 
Puis, nouveau déploiement des canaux :
 
{span:class=command}/home/esup/BUILD/canaux/deploy.sh{span}
  {note}
Il est possible de simplifier la procédure, et de recopier           PROD/webapps-2.5-esup-1 vers           PROD/webapps-2.5-esup-2 ; dans ce cas, le           nouveau déploiement des canaux n'est pas nécessaire.
{note}

 
h2. Si problème
\\
Il est possible de revenir en arrière très rapidement, en       remodifiant les 3 liens symboliques liés à la version du package       esup-portail.
h1. Cas du load-balancing
\\
De nombreux sites utilisent un load-balancer pour répartir la charge     des requêtes sur plusieurs serveurs esup-portail.
 
Nous exposons ici une méthode qui permet de maintenir les différents     serveurs synchrones.
 
On suppose que l'adresse publique d'accès au portail est     http://ent.univ.fr, et que 3 serveurs réels dont     installés : ent1.univ.fr,     ent2.univ.fr, ent3.univ.fr.
 
h2. Paramétrage
\\
Dans le fichier esup.properties, le paramètre       esup.multiservers doir être valué à       true.
 
Si vous désirez regrouper les logs (et/ou les stats) des       différents instances de portail dans un seul fichier, il est facile de       modifier le fichier de propriétés       Logger.properties.
 
Voici un extrait permettant ceci :
 
{code}
syslog_host=syslog.univ.fr

log4j.appender.R=org.apache.log4j.net.SyslogAppender
log4j.appender.R.SyslogHost=${syslog_host}
log4j.appender.R.Facility=LOCAL5
{code}

h2. Principe
\\
Le principe est d'utiliser un serveur comme maître ; c'est sur ce       serveur (ici, ent1) que l'on fera les différents       paramétrages, compilations, déploiements, ...
 
Ensuite, il suffit de déployer l'environnement de production vers       les serveurs 'esclaves'. En pratique, ceci peut se faire chaque nuit,       depuis un script exécuté sur les esclaves, qui réalise les opérations       suivantes :
 
 * arrêt du portail
   * {span:class=command}rsync{span}
   du répertoire           /home/esup/PROD
   * adaptation des quelques fichiers liés au serveur réel : 
 ** Logger.properties
   ** portal.properties                 (logicalname)
   ** web.xml (call back CAS)
   ** ...
   

   * relance du portail
  h1. Arrêt - Relance du portail
\\
D'une manière générale, il est préconisé de faire un redémarrage du     portail à intervalle régulier, toutes les nuits par exemple.