Doc update

- add deprecation od fbcheck to the doc - formatting - move some content in appropriate sections
waarp · Apr 22, 2020 · 92c640c · 92c640c
1 parent fde410e
commit 92c640c
Show file tree

Hide file tree

Showing 5 changed files with 159 additions and 61 deletions.
diff --git a/doc/waarp-r66/source/cli/raw.rst b/doc/waarp-r66/source/cli/raw.rst
@@ -12,12 +12,148 @@ Tous les appels sont de la forme :
 
 .. code-block:: sh
 
-   java -cp "path/to/waarp/jars" [classname] [class arguments]
+   java -cp "path/to/waarp/jars" [options jvm] [classname] [class arguments]
 
 Le détail des classes pouvant être exécutées et de leurs arguments est décrit
 ci-dessous.
 
 
+Options additionnelles pour Waarp via la JVM
+============================================
+
+.. index:: -Dopenr66.locale
+
+``-Dopenr66.locale=en|fr``
+   (défaut = en)
+
+   Permet choisir entre l'anglais ou le français pour le langage de l'interface
+
+
+.. index:: -Dopenr66.ishostproxyfied
+
+``-Dopenr66.ishostproxyfied=1|0``
+   (défaut = 0)
+
+   Indique que ce serveur est derrière un proxy (comme R66Proxy ou un matériel
+   équivalent) afin d'empêcher le contrôle des adresses IP de s'appliquer
+   (puisque celle-ci sera celle du Proxy)
+
+
+.. index:: -Dopenr66.startup.warning
+
+``-Dopenr66.startup.warning=1|0``
+   (défaut = 1)
+
+   Indique si les messages de démarrage doivent être inscrits dans les logs avec
+   le niveau warning (``1``) ou info (``0``).
+
+
+.. index:: -Dopenr66.startup.checkdb
+
+``-Dopenr66.startup.checkdb=1|0``
+   .. deprecated:: 3.1.0
+
+      Utiliser ``-Dopenr66.autoUpgrade`` à la place
+
+
+.. index:: -Dopenr66.startup.autoUpgrade
+
+``-Dopenr66.startup.autoUpgrade=0|1``
+   (défaut = 0)
+
+   .. versionadded:: 3.1.0
+
+   Active la mise-à-jour automatique de la base de données au lancement du
+   programme
+
+
+.. index:: -Dopenr66.chroot.checked
+
+``-Dopenr66.chroot.checked=1|0``
+   (défaut = 1)
+
+   Active le mode chroot pour les connexions clientes.
+
+   Par exemple, tenter de récupérer un fichier (RECV) depuis un partenaire
+   distant en spécifiant un chemin complet peut être autorisé, même si il est en
+   dehors du répertoire "OUT", sauf si checked=1. Si checked=1, alors tous les
+   fichiers reçus doivent spécifier un chemin inclu dans "OUT", sans remonter
+   au-delà.
+
+
+.. index:: -Dopenr66.blacklist.badauthent
+
+``-Dopenr66.blacklist.badauthent=1|0``
+   (défaut = 1)
+
+   Active le banissement temporaire des partenaires distants en cas d'erreur
+   d'authentification. Cette option permet de prévenir les attaques de type
+   DDOS.
+
+   Si ``-Dopenr66.ishostproxyfied=1``, alors il est obligatoirement faux. En
+   effet, dans ce cas, si un des partenaires a un problème d'authentification,
+   alors tous les partenaires proxifiés via le même proxy seront bannis puisque
+   visibles depuis la même adresse IP.
+
+
+.. index:: -Dopenr66.filename.maxlength
+
+``-Dopenr66.filename.maxlength=n``
+   (défaut = 255)
+
+   Définit la longueur maximale autorisée pour les nom de fichiers reçus (nom
+   temporaire et nom final). Ceci n'empêche pas de changer le nom du fichier
+   après et #ORIGINALFILENAME# contient toujours le nom complet d'origine du
+   fichier, non tronqué.
+
+
+.. index:: -Dopenr66.trace.stats
+
+``-Dopenr66.trace.stats=n``
+   (défaut = 0)
+
+   pour mettre en debug certaines traces spécifiques sur des données toutes les
+   ``n`` secondes. 0 signifie absence de trace.
+
+
+.. index:: -Dopenr66.cache.limit
+
+.. index:: -Dopenr66.cache.timelimit
+
+``-Dopenr66.cache.limit=n`` et ``-Dopenr66.cache.timelimit=m``
+   (défaut n = 20000, m=180000)
+
+   .. versionchanged:: 3.2.0
+      Le cache a été supprimé, ces options sont ignorées
+
+   pour mettre en cache les informations de transfert avec
+
+   - ``n`` est le nombre maximum de tâches à conserver dans un cache LRU (Last
+     Recent Used). La valeur minimale est 100
+   - ``m`` est le temps maximum en millisecondes avant qu'un élément créé,
+     utilisé ou modifié soit évincé du cache. La valeur minimale est 1000 ms
+     (1s). Une valeur trop grande peut provoquer des consommations mémoires trop
+     importante.
+
+
+.. index:: -Dopenr66.usespaceseparator
+
+``-Dopenr66.usespaceseparator=0|1``
+   (défaut = 0)
+
+   Autorise Waarp à utiliser l'espace comme séparateur mais induit des risques
+   de bugs.
+
+
+.. index:: -Dopenr66.executebeforetransferred
+
+``-Dopenr66.executebeforetransferred=0|1``
+   (défaut = 1)
+
+   Autorise Waarp à exécuter les Error-Tasks si une erreur intervient pendant
+   les "pré-task", avant le transfert effectif
+
+
 ``org.waarp.client.Message``
 ============================
 

diff --git a/doc/waarp-r66/source/conf.py b/doc/waarp-r66/source/conf.py
@@ -62,7 +62,7 @@
 # The short X.Y version.
 version = '3.3.1'
 # The full version, including alpha/beta/rc tags.
-release = '3.3.1-1'
+release = '3.3.1-2'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.

diff --git a/doc/waarp-r66/source/configuration-details/client.rst b/doc/waarp-r66/source/configuration-details/client.rst
@@ -150,7 +150,8 @@ dbdriver          String  N               Type de base de données utilisé. Son
 dbserver          String  N               Chaîne de connexion JDBC à la base de données. Consulter le manuel du pilote JDBC utilisé pour la syntaxe exacte.
 dbuser            String  N               Utilisateur de la base de données
 dbpasswd          String  N               Mot de passe de l'utilisateur de la base de données.
-dbcheck           boolean N    True       Vérifie que le modèle de données est à jour au démarrage, et effectue la mise à jour le cas échéant
+autoUpgrade       boolean N    True       Vérifie que le modèle de données est à jour au démarrage, et effectue la mise à jour le cas échéant
+dbcheck           boolean N    True       *(déprécié)* Utiliser ``autoUpgrade`` à la place
 ================= ======= ==== ========== =============
 
 
@@ -199,6 +200,6 @@ Exemple complet
            <dbserver>jdbc:postgresql://localhost:5432/waarp_r66</dbserver>
            <dbuser>username</dbuser>
            <dbpasswd>password</dbpasswd>
-           <dbcheck>false</dbcheck>
+           <autoUpgrade>false</autoUpgrade>
      </db>
    </config>
diff --git a/doc/waarp-r66/source/configuration-details/server.rst b/doc/waarp-r66/source/configuration-details/server.rst
@@ -195,7 +195,8 @@ dbdriver          String  N               Type de base de données utilisé. Son
 dbserver          String  N               Chaîne de connexion JDBC à la base de données. Consulter le manuel du pilote JDBC utilisé pour la syntaxe exacte.
 dbuser            String  N               Utilisateur de la base de données
 dbpasswd          String  N               Mot de passe de l'utilisateur de la base de données.
-dbcheck           boolean N    True       Vérifie que le modèle de données est à jour au démarrage, et effectue la mise à jour le cas échéant
+autoUpgrade       boolean N    True       Vérifie que le modèle de données est à jour au démarrage, et effectue la mise à jour le cas échéant
+dbcheck           boolean N    True       *(déprécié)* Utiliser ``autoUpgrade`` à la place
 ================= ======= ==== ========== =============
 
 
@@ -319,68 +320,29 @@ aliasid           string  O               liste de noms alias équiavelents, sé
 Section ``ExtraOptions``
 ------------------------
 
-Extra XML Option:
+Mise à jour automatique de la base de données
+"""""""""""""""""""""""""""""""""""""""""""""
 
-- Mise à jour automatique de la base en fonction de la version de Waarp
+Par défaut, le champ ``<root><version>version</version></root>`` du fichier de
+configuration XML est géré par Waarp pour vérifier la configuration de la base
+de données et sa version par rapport à celle du programme, afin de permettre une
+mise à jour automatique.
 
-Par défaut, le champ ``<root><version>version</version></root>`` du fichier de configuration XML
-est géré par Waarp pour vérifier la configuration de la base de données et sa version par rapport à celle
-du programme, afin de permettre une mise à jour automatique.
+Cette mise à jour automatique peut être empêchée par l'option
+``<db><autoUpgrade>False</autoUpgrade>...</db>`` ou grâce à la propriété Java
+``-Dopenr66.startup.dbcheck=0``.
 
-Cette mise à jour automatique peut être empêchée par l'option ``<db>dbcheck>False</dbcheck>...</db>`` ou
-grâce à la propriété Java ``-Dopenr66.startup.dbcheck=0``.
 
-- Partage d'une même base entre plusieurs moniteurs Waarp
+Partage d'une même base entre plusieurs moniteurs Waarp
+"""""""""""""""""""""""""""""""""""""""""""""""""""""""
 
 Dans le cas où une base est partagée entre plusieurs moniteurs R66, afin d'être capable de voir tous les
 transferts dans la console web d'administration, vous pouvez indiquer une option spéciale dans "Autres
 informations" avec l'identifiant qui sera utilisé pour se connecter à cette interface Web.
-    ``<root>...<seeallid>id1,id2,...,idn</seeallid></root>``
-
-- Options additionnelles pour Waarp via la JVM :
-
-  - ``-Dopenr66.locale=en|fr`` pour choisir entre l'anglais ou le français pour le langage de l'interface (
-  (défaut = en)
-  - ``-Dopenr66.ishostproxyfied=1|0``  pour indiquer que ce serveur est derrière un proxy (comme R66Proxy
-  ou un matériel équivalent) afin d'empêcher le contrôle des adresses IP de s'appliquer (puisque celle-ci
-  sera celle du Proxy) (défaut = 0)
-  - ``-Dopenr66.startup.warning=1|0`` pour décider si les Warning du démarrage seront affichées ou non
-  (défaut = 1)
-  - ``-Dopenr66.startup.checkdb=1|0`` pour choisir s'il y a un test entre le niveau de la configuration de la
-  base de données
-  et la version du serveur lors du démarrage (défaut = 0)
-   - ``-Dopenr66.startup.autoUpgrade=0|1`` (défaut 0) Si les versions de la base et du moniteur diffèrent,
-   autorise la mise à jour automatique de la base de données.
-  - ``-Dopenr66.chroot.checked=1|0`` pour choisir si toutes les règles doivent respecter le contrat "choroot"
-  Par exemple, tenter de récupérer un fichier (RECV) depuis un partenaire distant en spécifiant un chemin
-  complet peut être autorisé, même si il est en dehors du répertoire "OUT", sauf si checked=1. Si
-  checked=1, alors tous les fichiers reçus doivent spécifier un chemin incluant "OUT", sans remonter
-  au-delà.  (défaut = 1)
-  - ``-Dopenr66.blacklist.badauthent=1|0`` pour choisir si un serveur qui a une mauvaise identification
-  doit être immédiatement "black listé" (il n'est plus autorisé pour un temps) pour prévenir des attaques
-  DDOS. Si ``-Dopenr66.ishostproxyfied=1``, alors il est obligatoirement faux. En effet, dans ce cas, si un
-   des partenaires a un problème d'authentification, alors tous les partenaires proxifiés via le même
-   proxy seront bannis puisque visibles depuis la même adresse IP. (défaut = 1)
-  - ``-Dopenr66.filename.maxlength=n`` pour choisir la longueur maximum autorisée pour le nom du fichier
-   (défaut = 255) quand on reçoit un fichier (nom temporaire et nom final). Ceci n'empêche pas de changer
-   le nom du fichier après et #ORIGINALFILENAME# contient toujours le nom complet d'origine du fichier, non
-    tronqué.
-  - ``-Dopenr66.trace.stats=n`` pour mettre en debug certaines traces spécifiques sur des données toutes
-  les n secondes. 0 signifie absence de trace. (défaut n=0)
-  - ``-Dopenr66.cache.limit=n`` et ``-Dopenr66.cache.timelimit=m`` pour mettre en cache les informations de
-   transfert avec
-      - n est le nombre maximum de tâches à conserver dans un cache LRU (Last Recent Used). La valeur
-      minimale est 100
-      - m est le temps maximum en millisecondes avant qu'un élément créé, utilisé ou modifié soit évincé du
-       cache. La valeur minimale est 1000 ms (1s). Une valeur trop grande peut provoquer des consommations
-       mémoires trop importante.
-    (défaut n=20000, m=180000 - 180s -)
-    **A noter: Cette option n'est plus valide à compter de la version 3.2.0 qui ne tient plus un cache LRU
-    actif**
-   - ``-Dopenr66.usespaceseparator=0|1`` (défaut 0) Autorise Waarp à utiliser l'espace comme séparateur
-   mais induit des risques de bugs.
-   - ``-Dopenr66.executebeforetransferred=0|1`` (défaut 1) Autorise Waarp à exécuter les Error-Tasks si une
-    erreur intervient pendant les "pré-task", avant le transfert effectif
+
+.. code-block:: xml
+
+   <root>...<seeallid>id1,id2,...,idn</seeallid></root>
 
 
 .. _server-xml-example:
@@ -479,6 +441,6 @@ Exemple complet
            <dbserver>jdbc:postgresql://localhost:5432/waarp_r66</dbserver>
            <dbuser>username</dbuser>
            <dbpasswd>password</dbpasswd>
-           <dbcheck>false</dbcheck>
+           <autoUpgrade>false</autoUpgrade>
        </db>
    </config>
diff --git a/doc/waarp-r66/source/usage/filewatcher.rst b/doc/waarp-r66/source/usage/filewatcher.rst
@@ -223,7 +223,6 @@ balises suivantes :
 
 
 ``<ignoreAlreadyUsed>``
-
    Si positionné à vrai, tout fichier déjà traité et non effacé, même s'il est
    modifié, sera ignoré et ne sera donc pas renvoyé pour éviter tout risque de
    collisions quant au contenu transféré. Normalement, cette option devrait être