Sommaire |
---|
Info |
---|
Si vous utilisez actuellement la version 2 d'Agimus-NG, vous pouvez utiliser la page Migration des données issues de la v2 vers la v7 pour vous aider à migrer vos données |
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.
Button Hyperlink | ||||||||
---|---|---|---|---|---|---|---|---|
|
...
Info |
---|
Cette documentation donne des exemples de configuration qui permettent d'enrichir les logs applicatifs grâce aux attributs LDAP suivants :
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.
Bloc de code |
---|
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.
...
- les fichiers suivants (vous pouvez paramétrer au fur et à mesure de vos besoins) :
- copie du fichier config-sample.py en config.py. Utilisé dans les traitements python
- daily_batch.sh à lancer quotidien par cron pour effectuer les traitements
- check_plugin_ldap.sh changer l'adresse de contact pour être prévenu en cas de mise à jour de logstash
- traitements spécifiques à certains logs : scripts/moodle/*.py, scripts/traitement-ez*.sh, scripts/cron_stats_nc.sh, scripts/rocketchat-stats.sh
- Configurations logstash appelant le ldap ou des bases externes
- Copie du fichier frontal/config/config-sample.php en config.php pour le paramétrage du frontal
- Rapatrier les logs à traiter en vous aidant de la documentation ci-dessous
- Traiter ces logs grâce aux configurations logstash fournies que vous pourrez adapter
- Créer vos graphiques dans kibana pour visualiser les données générées
Rapatriement des logs
Pour lancer le traitement, il faut préalablement rapatrier les logs à traiter sur le serveur Agimus-NG
...
Button Hyperlink | ||||||||
---|---|---|---|---|---|---|---|---|
|
Script quotidien
Vos données de log vont être enrichies et enregitrées enregistrées dans elasticsearch grâce au script de traitement quotidien daily_batch.sh
...
Nous allons voir et tester ci-dessous les premiers quelques traitements fournis par défaut dans le fichier.
Remarque | |||||||
---|---|---|---|---|---|---|---|
Le fichier daily_batch.sh utilise une variable CONF_PATH qui est par défaut égale à $BUILD_HOME"/logstash/". Si vous lancez des traitements en dehors de ce batch, définissez préalablement la valeur de CONF_PATH :
Vous pouvez également remplacer la valeur par défaut (/tmp) dans les fichiers de configuration du répertoire logstash :
|
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 vérifié le bon fonctionnement de la récupération des informations ldap grâce à logstashavec logstash en utilisant le fichier test-logstash.conf.
Le script de traitement quotidien daily_batch.sh contient les commandes ci-dessous pour :
...
Astuce | ||
---|---|---|
| ||
Ces commandes vont générer dans votre elasticsearch :
|
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) :
Info | ||||||
---|---|---|---|---|---|---|
| ||||||
Cas Nom desvaleurs d'attributs contenant des tirets ou des espacesLes 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 : Bloc de code | | |||||
|
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é.
Astuce | ||
---|---|---|
| ||
Il faut lancer la commande suivante pour traiter le fichier trace.log rapatrié dans le répertoire /data/in/date_du_jour
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
...
Traitement des logs issus du CAS
Vous pouvez tester l'action de traitement qui est faite dans le script quotidien :
Astuce | ||
---|---|---|
Il faut lancer la commande suivante pour traiter les logs esup rapatriés dans le répertoire /data/in/date_du_jour
Cette commande va générer dans votre elasticsearch un index logstashag-casrequest-YYYY.MM .DD contenant les logs pertinents concernant votre ENTcontenant les appels à votre CAS. 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
Bloc de code |
---|
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
Bloc de code |
---|
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) :
Autres traitements
Il existe plusieurs autres exemples dans le fichier de traitement quotidien ainsi que des exemples de configuration dans le dossier logstash. Inspirez-vous en et n'hésitez pas à poser vos questions sur la liste de diffusion esup-utilisateurs
Points d'attention
Certains traitements ont des pré-requis. Vérifiez les points suivants si vous rencontrez des soucis lors de l'import de vos données :
- Avez-vous paramétré correctement la variable d'environnement CONF_PATH ? (cf la remarque de la section script_quotidien)
- Avez-vous généré ou créé les fichiers de mappings nécessaires à l'enrichissement des données ? Principalement utilisés par moodle, il vous faudra, au choix :
- lancer les enrichissements du dossier gen_mappings pour générer les fichiers ou
désactiver l'enrichissement en commentant tout le bloc translate {…} de votre fichier de traitement
...
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.
...