Skip to end of metadata
Go to start of metadata

Installations préalables

Agimus-NG utilise Elasticsearch, Logstash. Pour en savoir plus sur l'installation, consulter la page Installations requises sur le serveur Agimus-NG ou cliquez sur le bouton ci-dessous.

approve ÉTAPE PRÉALABLE : Installation ELK

 

Cette documentation donne des exemples de configuration qui permettent d'enrichir les logs applicatifs grâce aux attributs LDAP suivants :

'eduPersonPrimaryAffiliation', 'supannEntiteAffectationPrincipale', 'supannEtuCursusAnnee', 'supannEtuSecteurDisciplinaire'

Vous êtes bien entendu libre de le modifier/remplacer/supprimer. Il suffit d'effectuer la modification dans chacun des fichiers de paramétrage décrit ci-dessous.

Afin de faciliter ces modifications, un script a été créé pour vous permettre de mettre facilement à jour les fichiers type fournis sur notre espace github

Mise en place Agimus-NG

Pour mettre en place Agimus-NG, il faut :

  • récupérer les sources du projet sur github
  • paramétrer et lancer le déploiement

Pour cela utiliser les commandes suivantes. Nous allons récupérer les sources dans /opt mais vous pouvez le faire où vous le souhaitez en adaptant les chemins.

agimus@agimus-ng:~# cd /opt
# récupération des sources depuis github
agimus@agimus-ng:/opt/# git clone https://github.com/EsupPortail/agimus-ng.git
agimus@agimus-ng:/opt/# cd agimus-ng
agimus@agimus-ng:/opt/agimus-ng/# ls
experimentation  kibana  LICENSE  logstash  README.md  scripts
agimus@agimus-ng:/opt/agimus-ng/# python scripts/deploy_univ.py eduPersonPrimaryAffiliation supannEntiteAffectationPrincipale supannEtuCursusAnnee supannEtuSecteurDisciplinaire
The modified files are avalaible in the build directory: /home/colson18/Projets/GitHub/agimus-ng/build
agimus@agimus-ng:/opt/agimus-ng/# ls
build  experimentation  kibana  LICENSE  logstash  README.md  scripts
agimus@agimus-ng:/opt/agimus-ng/# ls build/
logstash  scripts
agimus@agimus-ng:/opt/agimus-ng/# 

Les fichiers paramétrables contiennent maintenant les attributs ldap que vous souhaitez suivre.

Il vous faut encore paramétrer le script de traitement quotidien scripts/daily_batch.sh en haut de fichier pour adapter les chemins à votre système.

Il faut notamment indiquer les chemins des fichiers de log à traiter (reportez-vous à l'étape suivante).

Rapatriement des logs

Pour lancer le traitement, il faut préalablement rapatrier les logs à traiter sur le serveur Agimus-NG

 

approve ÉTAPE SUIVANTE : Rapatrier les logs à traiter

Script quotidien

Vos données de log vont être enrichies et enregitrées dans elasticsearch grâce au script de traitement quotidien daily_batch.sh

Vous avez commencé à le paramétrer à l'étape précédente. Chaque traitement est indiqué dans les commentaires du fichier de script. Modifiez le suivant les besoins de votre établissement pour supprimer/ajouter les blocs correspondants aux traitements souhaités.

Nous allons voir et tester ci-dessous les premiers traitements fournis par défaut dans le fichier.

Traitement du LDAP

Les informations qui vont enrichir les logs sont extraites quotidiennement du ldap et intégrer à Elasticsearch. A cette étape, vous devriez avoir déjà tester le fonctionnement de la récupération des informations ldap grâce à logstash.

 

Le script de traitement quotidien daily_batch.sh contient les commandes ci-dessous pour :

  • supprimer des données de l'index ldap dans elasticsearch

  • récupérer des nouvelles données du ldap

  • enregistrer des statistiques ldap dans l'index ldap-stat

 

POUR TESTER

curl -XDELETE 'http://localhost:9200/ldap/' # A ne pas faire la première fois
logstash -f build/logstash/logstash-ldap.conf 
python build/scripts/ldap-agg.py

Ces commandes vont générer dans votre elasticsearch :

  • un index ldap, contenant l'ensemble de vos fiches avec les attributs traités
  • un index ldap-stat qui comptabilisent les différentes valeurs ainsi que leur nombre d’occurrence pour chacun des attributs traités

 

Cette ligne de commande utilise les fichiers suivants (pensez à remplacer "__VOS_ATTRIBUTS__" par vos propres valeurs si vous n'avez pas déjà exécuté le script deploy_univ.py) :

Pour aller plus loin

Cas des valeurs d'attributs contenant des tirets ou des espaces

Les attributs que vous allez traiter pour en avoir la synthèse seront traités comme des champs texte par Elasticsearch et seront donc découpés en mots grâce à des séparateurs tels que l'espace ou le tiret.

Prenons l'exemple de l'attribut supannEntiteAffectationPrincipale contenant "Service du personnel". Une agrégation sur supannEntiteAffectationPrincipale renverra un décompte pour "service" et un pour "personnel" au lieu d'un décompte pour "Service du personnel".

Si les attributs traités ont des valeurs contenant des caractères de séparation, il vaut mieux utiliser les valeurs brutes contenues dans le champ spécial nommé nom_attribut.raw, soit dans notre exemple supannEntiteAffectationPrincipale.raw. Ce champ spécial est créé automatiquement lors de l'alimentation d'un attribut de type texte depuis logstash.

Pour éviter de voir apparaître le suffixe ".raw" au moment du rendu, vous pouvez modifier légèrement le code.

Voici un exemple de modification pour les attributs par défaut :

Modification du script ldap-agg.py pour utiliser attribut.raw
--- ldap-agg.py    2015-05-12 11:30:14.955868724 +0200
+++ ldap-agg-raw.py    2015-05-12 11:32:17.691864154 +0200
@@ -25,7 +25,7 @@
     },
     "aggs": {}
 }
-ldapAttrs = ['eduPersonPrimaryAffiliation', 'supannEntiteAffectationPrincipale', 'supannEtuCursusAnnee', 'supannEtuSecteurDisciplinaire']
+ldapAttrs = ['eduPersonPrimaryAffiliation.raw', 'supannEntiteAffectationPrincipale.raw', 'supannEtuCursusAnnee.raw', 'supannEtuSecteurDisciplinaire.raw']
 
 for attr in ldapAttrs:
     bodysearch["aggs"][attr] = {"terms": {"field": attr, "size": 200}}
@@ -33,7 +33,7 @@
 res = es.search(index="ldap", body=bodysearch)
 
 for attr in ldapAttrs:
-    print attr
+    print attr[0:-4]
     for f in res["aggregations"][attr]["buckets"]:
-        es.index(index="ldap-stat", doc_type="ldap-stat", body={"attribut": attr,
+        es.index(index="ldap-stat", doc_type="ldap-stat", body={"attribut": attr[0:-4],
                  "value": f["key"], "count": f["doc_count"], "timestamp": date_object})

Traitement du fichier trace.log issu du serveur CAS

Le contenu du fichier trace.log est enregistré dans elasticsearch dans l'index trace qui sera interrogé lors du traitement des logs afin de faire le lien entre un log et l'utilisateur l'ayant généré.

POUR TESTER

Il faut lancer la commande suivante pour traiter le fichier trace.log rapatrié dans le répertoire /data/in/date_du_jour

logstash -f logstash/logstash-trace.conf < /data/in/$date/trace.log

Cette commande va générer dans votre elasticsearch un index trace, contenant l'ensemble des associations login<->trace

 

 

Cette commande utilise le fichier suivant (pensez à remplacer "__VOS_ATTRIBUTS__" par vos propres valeurs si vous n'avez pas déjà exécuté le script deploy_univ.py) :

 

Traitement des logs Esup-Portail

Choisissez le fichier de configuration qui correspond à la version de portail que vous utilisez (logstash-esup3.conf pour un portail v3 ou logstash-esup4.conf pour un portail v4) et renommer le en logstash-esup.conf.

Vous pouvez tester l'action de traitement qui est faite dans le script quotidien :

Il faut lancer la commande suivante pour traiter les logs esup rapatriés dans le répertoire /data/in/date_du_jour

cat /data/in/$date/access-ent.log | logstash -f build/logstash/logstash-esup.conf

Cette commande va générer dans votre elasticsearch un index logstash-YYYY.MM.DD contenant les logs pertinents concernant votre ENT. Ces documents (chaque document est une ligne de log) contiendront les informations supplémentaires issues de votre ldap.

 

Cette commande utilise un des fichiers suivants suivant votre version d'ENT Esup-Portail (pensez à remplacer "__VOS_ATTRIBUTS_HASHES__" par vos propres valeurs si vous n'avez pas déjà exécuté le script deploy_univ.py) :

 

Traitement des logs lighttpd (ex de Moodle)

Il faut lancer la commande suivante pour traiter les logs moodle rapatriés dans le répertoire /data/in/date_du_jour

cat /data/in/$date/moodle-access.log | logstash -f build/logstash/logstash-lighttpd.conf

 

 

Cette commande utilise le fichier suivant (pensez à remplacer "__VOS_ATTRIBUTS_HASHES__" par vos propres valeurs si vous n'avez pas déjà exécuté le script deploy_univ.py) :

 

Traitement des logs apache (ex de Moodle)

Il faut lancer la commande suivante pour traiter les logs moodle rapatriés dans le répertoire /data/in/date_du_jour

logstash/bin/logstash -f logstash/logstash-moodle.conf < /data/in/$date/moodle-access.log

 

 

Cette commande utilise le fichier suivant (pensez à remplacer "__VOS_ATTRIBUTS_HASHES__" par vos propres valeurs si vous n'avez pas déjà exécuté le script deploy_univ.py) :

 

Traitement quotidien dans la crontab

Afin d'alimenter ElasticSearch quotidiennement, il faut lancer le script daily_batch.sh chaque jour, une fois les logs de la veille rapatriés. Pour cela, ajouter l'appel au script dans la crontab de l'utilisateur exécutant le traitement.

10 0 * * * /opt/agimus-ng/scripts/daily_batch.sh | logger -t AGIMUS

 

 

approve ÉTAPE SUIVANTE : Visualisation des résultats

 

  • No labels