Exploitation

Exploiter & Superviser


    Flower s’appuie sur la librairie Logback pour la gestion des logs applicatifs.

    Fichiers de log


    Les paramètres suivants peuvent définis dans le fichier flowerdocs.properties approprié :

    Paramètre Description Valeur par défaut
    logging.file Chemin du fichier de log ${flower.docs.config.dir}/flowerdocs-xxx.log
    logging.file.max-size Taille maximum d’un fichier de log à partir de laquelle la rotation est activée 10MB
    logging.file.max-history Nombre maximum de fichiers de log historisés non défini
    logging.level.root Niveau de log par défaut INFO

    Niveaux de log


    Flower et les librairies utilisées poussent des logs de plusieurs niveaux :

    • TRACE : niveau le plus fin d’information permettant d’obtenir des informations facilitant le debug (peut être activé suite à une demande du support)
    • DEBUG : niveau permettant d’obtenir des informations nécessaires au debug (peut être activé suite à une demande du support)
    • INFO : messages donnés à titre d’information
    • WARN : messages d’avertissement
    • ERROR: erreurs interceptées par l’application


    Le niveau de log peut être défini par package Java en ajoutant un paramètre logging.level.<package>=<niveau> comme par exemple :

    logging.level.com.flower.docs.core.tsp=DEBUG
    

    Variables


    Sur une plateforme mutualisée ou tout simplement très utilisée, il peut être nécessaire de contextualiser les logs. Flower met donc à disposition des variables pouvant être affichées dans les messages de log :

    • user : identifiant de l’utilisateur courrant
    • scope : identifiant du scope sur lequel l’utilisateur courrant est authentifié
    • request : identifiant unique de la requête émise (dans le cas d’une requête émise sur la GUI et propagée sur le Core, l’identifiant est conservé)

    Pour utiliser ces variables, il suffit de modifier le paramètre logging.pattern.level de l’appender considéré : %X{variable} comme par exemple :

    logging.pattern.level=%X{request} %X{scope} %X{user} %5p
    


    Flower s’appuie sur le projet Spring Boot Actuator pour fournir des web services REST aidant à monitorer et gérer une stack Flower.

    Endpoints


    Les endpoints disponibles sont exposés sous le path /actuator

    Endpoint Description
    info Informations relatives à l’application (nom et version)
    health Etat de santé de l’application
    env Propriétés de l’application
    caches Gestion des caches utilisés
    httptrace Affiche, par défaut, les 100 dernières requêtes HTTP
    loggers Configuration des logs
    logfile Téléchargement du fichier de log

    Ces endpoints peuvent être désactivés en ajoutant un paramètre tel que :

    management.endpoints.web.exposure.exclude=httptrace,caches,env
    

    Sécurité


    Par défaut, l’ensemble des endpoints décrits requièrent une authentification basic et le rôle SYSTEM_ADMIN pour chaque application exposant ces endpoints.

    La sécurisation de ces endpoints peut être désactivée en ajoutant le paramètre actuator.secured=false.


    L’application Management s’appuie sur Actuator afin de faciliter la supervision d’une stack Flower. Cette application est basée sur le projet libre Spring Boot Admin.

    Features

    Cette application exploite les services REST exposés (cf. Actuator) pour fournir un ensemble de fonctionnalités facilitant la supervision de Flower.

    Parmis la liste des fonctionnalités proposées, vous pourrez trouver entre autre :

    • Vision d’ensemble des différentes instances de la stack Flower
    • Changez les niveaux de log à la volée
    • Consultation des logs applicatifs
    • Purge de cache
    • Consultation des métriques à disposition
    • Visualisation des dernières traces HTTP
    • Notifications
    • ….

    Pour plus d’informations sur les fonctionnalités et leur paramétrage, consultez la documentation.

    Lancement

    java -jar flower-docs-management-<span class="version">2.4.2.5</span>.jar --system.admin.password=<password>
    

    L’application est accessible à l’URL : http://localhost:2111/admin

    Découverte via Eureka

    Les différentes instances pouvant être gérées dans cette application sont découvertes via Eureka. La découverte des applications passe par l’enregistrement de chacune auprès du serveur Eureka (embarqué dans l’application Management).

    Pour cela, il est nécessaire de définir, pour la GUI et le Core, la propriété eureka.client.serviceUrl.defaultZone (par défaut : http://localhost:2111/eureka).


    La GUI et le Core s’enregistre auprès d’Eureka avec les informations à leur disposition afin d’indiquer comment les contacter. Si leur contexte (path) ou leur port ont été personnalisés, il est nécessaire de l’indiquer dans leur fichier de configuration flowerdocs.properties.

    Core

    Information Propriété Valeur par défaut
    Contexte core.context /core
    Port core.port 8081

    GUI

    Information Propriété Valeur par défaut
    Contexte gui.context /gui
    Port gui.port 8080

    Configuration

    Sécurité

    Accès à l’application

    Un compte utilisateur est nécessaire pour pouvoir accéder à cette application. Par défaut, le mot de passe de l’utilisateur user est indiqué dans le fichier de logs. Ce compte peut être personnalisé avec les paramètres spring.security.user.name et spring.security.user.password.

    Accès à Flower

    L’application nécessite l’utilisation d’un compte ayant le rôle SYSTEM_ADMIN afin d’exécuter des requêtes sur les endpoints décrits précédemment (cf. Actuator). Ce compte peut être défini grâce aux paramètres system.admin.username et system.admin.password.


    Sans configuration, seul l’utilisateur système du Core et de la GUI peut être utilisé. Il est possible de définir un utilisateur additionnel tel que :

    internal.realm.users[0].id=metric-admin
    internal.realm.users[0].password=<password>
    internal.realm.users[0].profiles=SYSTEM_ADMIN
    

    Cette configuration est à effectuer côté Core et GUI.


    Les secrets définis dans cette application peuvent être chiffrés comme indiqué ici.

    Notifications Email

    Il est possible de configurer les notitifications de changement de statut des applications Flower (GUI et Core).

    Serveur SMTP

    Pour cela, il est nécessaire de configurer le serveur SMTP à utiliser pour l’envoie d’email :

    spring.mail.host=<host>
    spring.mail.username=<user>
    spring.mail.password=<password>
    spring.mail.properties.mail.smtp.starttls.enable=true
    

    Selon la configuration, il peut être nécessaire de forcer la confiance en l’hôte SMTP :

    spring.mail.properties.mail.smtp.ssl.trust=<host>
    

    Diffusion

    Pour définir à quelles adresses seront envoyer les emails de notification, ajouter le paramètre suivant :

    spring.boot.admin.notify.mail.to=<recipient>
    

    Plusieurs métriques sont mises à disposition afin d’avoir des retours quantitatifs sur l’utilisation de Flower Core.

    Ces métriques sont mises à dispostion à travers :

    • une API REST
    • des MBeans JMX accessibles depuis une JConsole ou JVisualVM (avec le plugin MBean installé)

    Elles sont exposées sur le endpoint /actuator/metrics et comme les autres endpoints Actuator sont soumises à une authentification basic.

    Opérations

    Chaque opération effectuée sur Flower Core peut être mesurée à l’aide des métriques. Pour chaque couple scope / catégorie de composant, une métrique <scope>.<categorie> est exposée (par exemple : gec.document) via le framework Micrometer.

    Exemple : Métrique de dossier pour le scope GEC

    GET core/actuator/metrics/gec.folder
    

    La métrique est exposée à partir du moment où l’opération a été exécutée une première fois.


    Pour chaque métrique d’opération, un tag method est ajouté permettant ainsi de filter par méthode appelée.

    Exemple : Métrique de création de tâche pour le scope GEC

    GET core/actuator/metrics/gec.task?tag=method:create
    

    OperationHandler

    Comme pour les opérations, une métrique est exposée pour les OperationHandler avec le nom <scope>.handlers.<categorie> (par exemple : gec.handlers.document)

    Pour chacune de ces métriques, plusieurs tags sont populés afin de filter les valeurs de la métrique.

    Nom Description
    phase Phase d’exécution de l’opération
    action Action de l’opération
    registration Identifiant de l’abonnement ayant déclenché l’exécution de l’OperationHandler


    Exemple : Métrique d’OperationHandler exécuté après la création de document

    GET core/metrics/gec.handlers.document?tag=phase:AFTER,action:CREATE
    


    Ce type de métrique n’est disponible qu’avec l’utilsiation du connecteur Elasticsearch.

    L’historique des connexions des utilisateurs est maintenu et peut être requêté sur le endpoint /rest/metrics/profiles :

    • par profile (ou équipe) utilisateur
    • par plage de date

    Ces métriques permettent d’obtenir des informations sur les utilisateurs s’étant connecté pour un profile particulier. Pour obtenir ces métriques, il est nécessaire de disposer du rôle ADMIN.

    • /rest/metrics/profiles/{profile} : Liste les connexions pour un profile donné
    • /rest/metrics/profiles/{profile}/count : Compte les connexions pour un profile donné


    Ce endpoint nécessite une authentification qui doit être fournie par un jeton utilisateur :

    • via un paramètre token de l’URL
    • via une en-tête HTTP token
    Paramètre Description
    start Paramètre facultatif permettant d’indiquer le début de la plage de date sur laquelle la mesure doit portée.
    Par défaut, ce paramètre est valorisé à 24 heures avant la fin de la plage de date. timestamp
    end Paramètre facultatif permettant d’indiquer la fin de la plage de date sur laquelle la mesure doit portée.
    Par défaut, ce paramètre est valorisé à l’instant présent. timestamp

    Exemple :

    GET /core/rest/metrics/profiles/ALL_USERS?token=<token>
    

    Navigateurs qualifiés

    Les navigateurs qualifiés sont testés et validés par Arondor pour chaque release du produit. Nous n’excluons pas qu’il puisse y avoir des anomalies sur ces navigateurs qualifiés, cependant le risque est minime et restreint à des cas particuliers ou spécifiques.


    Liste des navigateurs qualifiés :

    • Internet Explorer 11
    • Chrome 73
    • Mozilla FireFox 66


    Arondor s’engage à qualifier la dernière version de ces navigateurs au plus tard 6 mois après leur sortie.

    Navigateurs supportés

    Les navigateurs supportés correspondent à ceux dans lesquels l’application est réputée fonctionnelle. En effet, le rythme de release de certains navigateurs étant très important, Arondor ne peut pleinement qualifier l’ensemble des couples navigateurs/versions à chaque release. Cependant, la très grande majorité des versions intermédiaires des navigateurs permettent une utilisation normale de l’application. La remontée d’anomalies éventuelles sur ces navigateurs est couverte par le support produit standard.


    Liste des navigateurs supportés :

    • Internet Explorer 11
    • Chrome 58+
    • Mozilla FireFox 53+
    • Safari for iOs 11+
    • MS Edge 16+


    Les navigateurs non listés ci-dessus ne sont pas pris en charge dans le cadre du support produit standard. Le support étendu d’une version particulière d’un navigateur peut être envisagée au cas par cas.



    • L’utilisation d’un navigateur WEB conforme au standard HTML 5 et récent est préconisée pour des questions de confort utilisateur, de performance et de rendu visuel.
    • Les anomalies des navigateurs liées au non-respect des standards (HTML, JavaScript …) ne sont pas couvertes par le support produit. Une montée de version des navigateurs concernés est préconisée.

    Apache HTTP Server est un des serveurs WEB les plus utilisés. Il permet facilement d’exposer des URLs via HTTP(s).

    Cette section décrit quelques configurations types à adapter en fonction du contexte.

    Configuration minimale

    <VirtualHost *:80>
    	ServerName www.flowerdocs.com                                                           
    	ServerAlias flowerdocs.com *.flowerdocs.com                                             
    	                                                                                                                                                                                      
    	<Location /gui >                                                         
    	    ProxyPass http://localhost:8080/gui
    	    ProxyPassReverse http://localhost:8080/gui
    	</Location>
    	                                                                                        
    	<Location /flower-docs-arender >
    	    ProxyPass http://localhost:8080/flower-docs-arender
    	    ProxyPassReverse http://localhost:8080/flower-docs-arender
    	</Location>
    	
    	<Location /core >
    	    ProxyPass http://localhost:8081/core
    	    ProxyPassReverse http://localhost:8081/core
    	</Location>
    	                                                                                        
    	ErrorLog ${APACHE_LOG_DIR}/flower-error.log
    	CustomLog ${APACHE_LOG_DIR}/flower-access.log combined
    </VirtualHost>
    

    Ré-écriture

    Dans le cas où le chemin d’accès à Flower change, il est nécessaire de modifier certaines en-têtes HTTP pour la GUI.

    Pour cela, il est nécessaire de rajouter les directives suivantes :

    	<Location /ui >
    	    Header edit Set-Cookie "^(.*; [p|P]ath=)(.*)" "$1/ui"                          
    	    RequestHeader edit X-GWT-Module-Base ^(.*)/gui/(.*)$ $1/ui/$2
        </Location>                  
    

    Load balancing

    Apache HTTP Server permet de mettre en place facilement un load balancing applicatif.

    Dans l’exemple ci-dessous, un équilibrage de type roundrobin est mis en place pour les Core et un avec affinité de session pour les GUI.

    <VirtualHost *:80>
    	Header add Set-Cookie "ROUTEID=.%{BALANCER_WORKER_ROUTE}e; path=/" env=BALANCER_ROUTE_CHANGED
    	
    	<Proxy "balancer://core-cluster">
    	    BalancerMember "http://192.168.1.50:8080/core"
    	    BalancerMember "http://192.168.1.51:8080/core"
    	</Proxy>
    	ProxyPass        "/core" "balancer://core-cluster"
    	ProxyPassReverse "/core" "balancer://core-cluster"
    	
    	
    	<Proxy "balancer://gui-cluster">
    	    BalancerMember "http://192.168.1.52:8080/gui" route=1
    	    BalancerMember "http://192.168.1.53:8080/gui" route=2
    	    ProxySet stickysession=ROUTEID
    	</Proxy>
    	ProxyPass        "/gui" "balancer://gui-cluster"
    	ProxyPassReverse "/gui" "balancer://gui-cluster"
    
    	ErrorLog ${APACHE_LOG_DIR}/flower-cluster-error.log
    	CustomLog ${APACHE_LOG_DIR}/flower-cluster-access.log combined
    </VirtualHost>