.. _configuration:

######################
Configuration initiale
######################


Une fois Waarp Manager installé, la procédure suivante doit être suivie
pour initialiser la configuration et permettre son utilisation.




Création de la base de données
==============================

Waarp Manager utilise une base de données PostgreSQL 9.4 minimum.

.. note::

   Pour installer un serveur de PostgreSQL sur le même serveur que Waarp
   Manager, se référer à la `documentation de PostgreSQL`_.

Sur le serveurs de base de données, créez une base et un utilisateur
dédiée à Waarp Manager. Ceci peut se faire avec les requêtes SQL suivantes :

.. todo:: mettre les commandes compactes
.. code-block:: plpgsql

   -- Pensez à changer le mot de passe de l'utilisateur waarp !
   CREATE USER waarp;
   ALTER USER waarp WITH ENCRYPTED PASSWORD 'password';
   CREATE DATABASE "waarp_manager";
   ALTER DATABASE "waarp_manager" OWNER TO waarp;

Une fois la base de données créée, éditez le fichier de configuration
``waarp-manager.ini`` et renseignez les informations de connexion à la
base de données. Si Waarp Manager a été installé en utilisant des
packages (dépôts ou unitaires), ce fichier se trouve dans le dossier
``/etc/waarp-manager`` ; sinon, il se trouve dans le dossier ``etc``
de l'archive extraite.

Les options de configuration concernées sont dans la section ``[db]``
du fichier :

.. code-block:: ini

   [db]

   ; The host to connect to
   Host = localhost

   ; The port to bind to
   Port = 5432

   ; The user to sign in as
   User = waarp

   ; The user's password
   Password = password

   ; The name of the database to use
   Name = waarp_manager

   ; Whether or not to use SSL
   ; Ssl = false



Initialisation de la base de données
====================================

Le script de génération de la structure de la base de données et des
données initiales est généré avec la commande ``waarp-manager db dump``.

Vous pouvez soit le stocker dans un fichier pour l'exécuter directement :

.. code-block:: bash

   # Avec les packages :
   waarp-manager db dump -c /etc/waarp-anager/waarp-manager.ini > waarp-manager.sql
   psql -W --user waarp --host localhost --port 5432 waarp_manager < waarp-manager.sql
   
   # Avec les archives portables :
   ./bin/waarp-manager db dump -c etc/waarp-manager.ini > waarp-manager.sql
   psql -W --user waarp --host localhost --port 5432 waarp_manager < waarp-manager.sql

ou l'exécuter directement dans une base :

.. code-block:: bash

   # Changez le serveur, le nom d'utilisateur et le port si ceux-ci
   # ne correspondent pas

   # Avec les packages :
   waarp-manager db dump -c /etc/waarp-manager/waarp-manager.ini | psql -W --user waarp --host localhost --port 5432 waarp_manager

   # Avec les archives portables :
   ./bin/waarp-manager db dump -c etc/waarp-manager.ini | psql -W --user waarp --host localhost --port 5432 waarp_manager

.. warning::

   L'utilisateur configuré dans Waarp Manager doit avoir le droit d'utiliser
   les tables de la base de données. Pour ça, il faut :

   1. Soit initialiser la base avec l'utilisateur configuré pour Waarp Manager
   2. Soit donner explicitement le droit à l'utilisateur de Waarp Manager
      d'utiliser la base :
      
      .. code-block:: sql

         GRANT ALL PRIVILEGES ON ALL TABLES IN SCHEMA public TO [USERNAME];


La dernière étape consiste à appliquer les dernières migrations à la base de
données pour qu'elle soit à jour :

.. code-block:: sh

   # Avec les packages :
   waarp-manager db migrate up -c /etc/waarp-manager/waarp-manager.ini
   
   # Avec les archives portables :
   ./bin/waarp-manager db migrate up -c etc/waarp-manager.ini

.. versionadded:: 1.0
   Lors de la création de la base de données un site ainsi qu'un partenaire
   Waarp R66 seront automatiquement créé afin de pouvoir utiliser le client r66
   interne sans configuration suplémentaire


Client r66 interne
==================

.. versionadded:: 1.0
   Avec les versions précédentes de Manager, il était nécessaire d'installer un
   client R66 externe. Veuillez vous référer à la documentation de votre version
   le cas échéant.

Pour déployer la configuration vers les serveurs Waarp R66, Waarp Manager
utilise un client R66 interne.

Les options de configurations sont dans la section `[r66]` du fichier:

.. code-block:: ini

   [r66]
   ; The DES key to use when encrypting passwords
   DesKey = {{path/to/waarp/encryptionkey}}

    ; The directory where generated conf archives must be written
    OutDir = {{path/to/waarp/out/directory}}
 
    ; The command to use to deploy the configuration to the server
    R66Cmd = waarp-r66client
 
    ; The template to use to deploy the configuration to the server
    DiffusionRule = déploiement_config
 
    ; The name of the Waarp R66 client that Waarp Manager uses
    ClientName = wm-client
 
    ; The path to the file containing the key to sign REST requests
    RestSigningKey = {{path/to/waarp/restsigningkey}}
 
    ; The path to the file containing the certification chain of Waarp R66 Servers (PEM format)
    RootCA = {{path/to/waarp/certificationchain}}
 
    ; The period to wait for answers for REST requests
    RestTimeout = 3s
 
    ; The delay between two queries to update a server's transfer history
    HistoryRefresh = 5m
 
Toutes ces options permettent de paramétrer et mettre en oeuvre les interactions
entre Waarp Manager et les serveurs Waarp R66 qu'il pilote.

Il y a deux types d'interactions : 

1. L'envoi de la configuration (règles et authentification) aux moniteurs
2. La récupération des historiques de transfert des serveurs

Dans le premier cas, Waarp Manager génère, pour chaque serveur R66, les
fichiers XML contenant les règles de transfert et les doonnées
d'authentification des partenaires nécessaire à la mise en oeuvre des flux
définis. Ces fichiers sont ensuite transférés vers les serveurs via R66.

Pour ce faire, Waarp Manager a besoin d'utiliser un client R66 configuré sur
son serveur. L'identifiant (``name``) de ce client doit être renseigné dans
l'option ``ClientName``. Les fichiers générés (ceux qui doivent être transférés)
sont déposés dans le dossier indiqué dans l'option ``OutDir``. En général, il
faut renseigner dans cette option le dossier d'envoi (``out``) du client R66
associé. Le programme utilisé pour lancer les transferts avec le client R66
associé doit être renseigné dans l'option ``R66Cmd``. Pour une installation faite
avec les RPM, ``waarp-r66client`` suffit (le script est dans le ``PATH`` système --
``/usr/bin``).

Pour envoyer les fichiers, il utilise un flux qui doit être défini dans Waarp
Manager (du client associé à Waarp Manager vers le serveur à mettre à jour)
avec le modèle de flux défini dans l'option ``DiffusionRule``.
Enfin, les mots de passe des partenaires R66 transmis dans les fichiers XML
sont chiffrés (ils le sont aussi dans les bases des de données des
partenaires R66) en utilisant la clef DES renseignée dans l'option ``DesKey``
(cette clef doit aussi être utilisée par tous les moniteurs R66).

Pour le deuxième cas, la consultation des historiques, Waarp Manager utilise
l'interface REST des serveurs R66. Pour plus de sécurité, les requêtes sont
signées cryptographiquement (en utilisant l'algorithme HMAC-SHA256). 
La clef utilisée pour cette signature est indiquée dans l'option
``RestSigningKey``. 
Enfin, l'interface REST des serveurs est consultée en HTTPS. L'option ``RootCA``
permet de renseigner, de manière optionnelle, une chaîne de certification au
format PEM pour valider la connection HTTPS.


Client r66 interne
==================

.. versionadded:: 1.0.0

Pour les version de Waarp Manager supérieur ou égale à la version 1.0.0, un
client r66 interne est utilisé pour envoyer la configuration aux serveurs r66.

Les options de configurations sont dans la section [r66] du fichier:

.. code-block:: ini

   [r66]
   ; The DES key to use when encrypting passwords
   DesKey = {{path/to/waarp/encryptionkey}}
 
   ; The template to use to deploy the configuration to the server
   DiffusionRule = déploiement_config

   ; The name of the Waarp R66 client that Waarp Manager uses
   ; Might be changed by manager to avoid conflicts
   ClientName = wm-client

   ; The path to the file containing the key to sign REST requests
   RestSigningKey = {{path/to/waarp/restsigningkey}}

   ; The path to the file containing the certification chain of Waarp R66 Servers (PEM format)
   RootCA = {{path/to/waarp/certificationchain}}

   ; The period to wait for answers for REST requests
   RestTimeout = 3s

   ; The delay between two queries to update a server's transfer history
   HistoryRefresh = 5m

Toutes ces options permettent de paramétrer et mettre en oeuvre les interactions
entre Waarp Manager et les serveurs Waarp R66 qu'il pilote.

Il y a deux types d'interactions :

1. L'envoi de la configuration (règles et authentification) aux moniteurs
2. La récupération des historiques de transfert des serveurs

Dans le premier cas, Waarp Manager génère, pour chaque serveur R66, les
fichiers XML contenant les règles de transfert et les données d'authentification
des partenaires nécessaire à la mise en oeuvre des flux définis. Ces fichiers
sont ensuite transférés vers les serveurs via R66.

Pour ce faire, Waarp Manager utilise son client r66 interne. L'identifiant
(``hostid``) de ce client peut être renseigné dans l'option ``ClientName`` pour
garder une rétrocompatibilité avec les ancienne versions, mais il est préférable
de laisser Waarp Manager le gérer lui-même pour éviter d'éventuel conflicts. Les
fichers générés (ceux qui doivent être transférés) sont gardé en mémoire et
transférés directement par le client r66 interne.

Pour envoyer les fichiers, il utilise un flux qui doit être défini dans Waarp
Manager (du client interne vers le serveur à mettre à jour) avec le modèle de
flux défini dans l'option ``DiffusionRule``.
Enfin, les mots de passe des partenaires R66 transmis dans les fichiers XML
sont chiffrés (ils le sont aussi dans les bases des de données des
partenaires R66) en utilisant la clef DES renseignée dans l'option ``DesKey``
(cette clef doit aussi être utilisée par tous les moniteurs R66).

Pour le deuxième cas, la consultation des historiques, Waarp Manager utilise
l'interface REST des serveurs R66. Pour plus de sécurité, les requêtes sont
signées cryptographiquement (en utilisant l'algorithme HMAC-SHA256).
La clef utilisée pour cette signature est indiquée dans l'option
``RestSigningKey``.
Enfin, l'interface REST des serveurs est consultée en HTTPS. L'option ``RootCA``
permet de renseigner, de manière optionnelle, une chaîne de certification au
format PEM pour valider la connection HTTPS.

.. note::

   Lors de la migration depuis un version antérieure à la 1.0, le client r66
   interne utilisera le client r66 deja renseigné dans la base de données.

.. note::

   Lors de l'initialisation de la base de données, un site et un partenaire
   seront automatiquement créé pour pouvoir utiliser le client r66 interne
   sans configuration supplémentaire. Le site sera nommé ``"system"``
   et le partenaire ``"wm_client"``. Ils sont utilisés par le system il est donc
   déconseillé de les supprimer ou de les modifier.


Communication avec les serveurs Waarp R66
=========================================

Pour récupérer l'historique des serveurs Waarp R66, Waarp Manager
utilise l'interface REST de ceux-ci.

Si, pour les serveurs, la signature des requêtes est activée, le chemin
vers le fichier contenant la clef de signature doit être indiquée dans
le paramètre ``RestSigningKey`` du fichier de configuration de Waarp
Manager.

De même, si l'interface  REST des serveurs R66 est protégée par un
certificat signée par un tiers dont les certificats racine ne sont pas
installés sur le système, le fichier contenant la chaîne de
certification doit être indiquée dans le paramètre ``RootCA`` du fichier
de configuration.



.. _documentation de PostgreSQL: http://www.postgresql.org/download/


