##################
Gestion des règles
##################

La commande de gestion des :term:`règles<règle>` de  transfert est ``rule``.
Cette commande doit ensuite être suivie d'une action. La liste complète des
actions est disponible :any:`ici <reference-cli-client-rules>`.

.. _user-add-rule:

Ajouter une règle
=================

Pour créer une règle, la commande est ``add``. Les options de commande
suivantes doivent être fournies:

- ``-n``: le nom de la règle
- ``-c``: un commentaire sur la règle (optionnel)
- ``-d``: la direction de transfert des fichiers, ``SEND`` ou ``RECEIVE``
- ``-p``: le chemin utilisé pour identifier la règle lorsque le protocole ne le
  permet pas
- ``-i``: le chemin de destination des fichiers (optionnel)
- ``-o``: le chemin source des fichiers (optionnel)
- ``-r``: une tâche pré-transfert, peut être répété pour ajouter plusieurs tâches
- ``-s``: une tâche post-transfert, peut être répété pour ajouter plusieurs tâches
- ``-e``: une tâche d'erreur, peut être répété pour ajouter plusieurs tâches

Les tâches doivent être données en format JSON. Voir :any:`reference-tasks`
pour plus de détails sur le format des tâches.

.. note::
   L'ordre dans lequel les tâches (pré/post/erreur) seront exécutés est le même
   que l'ordre dans lequel les tâches ont été spécifiées dans la commande de
   création.

**Exemple**

L'exemple suivant ajoute une règle de réception nommée ``rebond archive``,
identifiée par le chemin ``/rebond``. Cette règle possède 2 traitements
post-transfert. Le premier crée une copie du fichier reçu dans le dossier
``/archive``, le deuxième programme un transfert du fichier reçu vers le
partenaire ``sshd``.

.. code-block:: shell

   waarp-transfer -a 'https://admin@127.0.0.1:8080' rule add \
      -n 'rebond archive' \
      -d 'RECEIVE' \
      -p '/rebond' \
      -s '{"type":"COPY","args":{"path": "/archive"}}' \
      -s '{"type":"TRANSFER","args":{"file":"#TRUEFULLPATH#","to":"sshd","as":"toto","rule":"send"}}'


Modifier une règle
==================

Pour modifier une règle existante, la commande est ``rule update``. Cette
commande doit être suivie du nom de la règle à modifier. Les options de
commandes sont identiques à la commande ``add``. Il est possible d'omettre une
ou plusieurs options pour faire une mise à jour partielle.

.. warning::
   Il est impossible de faire une mise à jour partielle d'une chaine de
   traitements. Par conséquent, si vous souhaitez modifier une des chaines de
   traitement (pre/post/erreur), la chaine en question doit impérativement être
   rentrée en intégralité (y compris les tâches déjà rentrées précédemment).

**Exemple**

.. code-block:: shell

   waarp-transfer -a 'https://admin@127.0.0.1:8080' rule update 'rebond archive' \
      -p '/rebond' \
      -i '/rebond/in'


Consulter les règles
====================

Pour lister les règles connues de Waarp Transfer, la commande est ``rule list``.
Les options de commande permettent de filtrer les résultats selon divers
critères, pour plus de détails, voir la :any:`documentation
<reference-cli-client-rules-list>` de la commande ``list``.

**Exemple**

.. code-block:: shell

   waarp-transfer -a 'https://admin@127.0.0.1:8080' rule list

Pour consulter une règle en particulier, la commande est ``get`` suivie du nom
de la règle.

**Exemple**

.. code-block:: shell

   waarp-transfer -a 'https://admin@127.0.0.1:8080' rule get 'rebond archive'


Supprimer une règle
===================

Pour supprimer une règle, la commande est ``rule delete``, suivie ensuite du nom
de la règle à supprimer.

**Exemple**

.. code-block:: shell

   waarp-transfer -a 'https://admin@127.0.0.1:8080' rule delete 'rebond archive'


Restreindre une règle
=====================

Par défaut, après ajout d'une règle, tous les serveurs, partenaires et comptes
(locaux et distants) peuvent utiliser cette règle. Il est cependant possible de
restreindre l'utilisation d'une règle pour que seuls certains puissent
l'utiliser.

Chaque règle dispose d'une liste d'autorisations, contenant la liste des
différents agents autorisés à utiliser la règle en question. Si cette liste est
vide, alors la règle est utilisable par tous.

.. note::

   Pour qu'un transfert puisse s'exécuter, il est nécessaire qu'au moins un des
   deux agents impliqués (serveur + compte local ou partenaire + compte distant
   suivant le sens de la connexion) soit présent sur la liste d'autorisation de
   la règle.

   Cela signifie donc qu'ajouter un serveur à la liste d'autorisation d'une
   règle ajoute également *de facto* tous les comptes locaux rattachés à ce
   serveur. Idem pour les partenaires et les comptes distants.


Pour ajouter un agent à la liste d'autorisation d'une règle, les commandes
sont :

* ``server 'NOM' authorize 'RÈGLE'`` pour ajouter un serveur
* ``partner 'NOM' authorize 'RÈGLE'`` pour ajouter un partenaire
* ``account local 'LOGIN' authorize 'RÈGLE'`` pour ajouter un serveur
* ``account remote 'LOGIN' authorize 'RÈGLE'`` pour ajouter un serveur

Par exemple, la commande suivante autorise le serveur ``r66`` à utiliser
de la règle ``send`` :

.. code-block:: shell

   waarp-transfer -a 'https://admin@127.0.0.1:8080' server 'r66' authorize 'send'

Retirer à un agent le droit d'utiliser une règle se fait de manière similaire,
la commande ``authorize`` doit juste être remplacée par la commande ``revoke``.

Par exemple, pour retirer au serveur ``r66`` le droit d'utiliser la règle
``send``, la commande est :

.. code-block:: shell

   waarp-transfer -a 'https://admin@127.0.0.1:8080' server 'r66' revoke 'send'


Alternativement, il est possible d'effacer intégralement les restrictions
d'usage d'une règle via la commande ``rule allow`` suivie du nom de la règle.

Par exemple, la commande suivante supprime les autorisations pour la règle 'send',
rendant, de fait, la règle utilisable par tous :

.. code-block:: shell

   waarp-transfer -a 'https://admin@127.0.0.1:8080' rule allow 'send'
