=========
Amazon S3
=========

Waarp Transfer permet d'utiliser un bucket S3 à la place du disque dur local.

Configuration
-------------

Pour utiliser une instance cloud, celle-ci doit d'abord être créée et configurée.
Pour créer une instance cloud S3, le type renseigné doit être ``s3`` ou ``aws``.

Authentification
^^^^^^^^^^^^^^^^

Pour se connecter à une instance S3, Waarp Transfer a besoin d'identifiants.
Ces identifiants peuvent être fournis de 2 manières différentes :

- Soit en les renseignant directement à la création de l'instance cloud, auquel cas :

  - Le paramètre *key* doit contenir la clé d'accès
  - Le paramètre *secret* doit contenir la clé secrète
- Soit en les renseignant dans des variables d'environnement. Les variables
  suivantes doivent être renseignées :

  - :envvar:`AWS_ACCESS_KEY_ID` pour la clé d'accès AWS
  - :envvar:`AWS_SECRET_ACCESS_KEY` pour la clé secrète associée à la clé d'accès

Options
^^^^^^^

Les options de configuration suivantes sont disponibles pour S3 :

* **bucket**: *REQUIS* - Le nom du bucket dans lequel le fichier sera déposé.
* **env_auth**: Booléen, mettre à ``true`` pour activer l'authentification via
  variables d'environnement décrite ci-dessus.
* **region**: La région du serveur S3. Peut également être renseigné via la
  variable d'environnement :envvar:`AWS_REGION`.
* **endpoint**: L'adresse du serveur S3 (si celle-ci est différente de l'adresse
  par défaut ``amazonaws.com``). Peut également être renseigné via la
  variable d'environnement :envvar:`AWS_ENDPOINT_URL`.

Exemple
-------

Prenons le cas de figure suivant :

- fichier: ``doc/waarp-transfer.pdf``
- bucket: ``archive``
- point de terminaison: ``s3.eu-west-3.amazonaws.com``
- région: ``eu-west-3`` (Paris)
- clé d'accès: ``toto``
- clé d'accès secrète: ``sesame``

Dans un premier temps, l'instance cloud doit être définie. Dans cet exemple, nous
lui donnerons le nom "ex-s3".

La commande de création pour cette instance cloud est donc :

.. code-block:: shell

   waarp-transfer cloud add -n "ex-s3" -t "s3" -k "toto" -s "sesame" -o "bucket:archive" -o "region:eu-west-3" -o "endpoint:s3.eu-west-3.amazonaws.com"

Par la suite, lors de mon transfert, le chemin du fichier devra donc ressembler à :

| ex-s3:doc/waarp-transfer.pdf