Skip to content

Utilisation de la commande s5cmd

S5cmd est une interface en ligne de commande pour piloter son Amazon S3, ou dans le cadre du Mésocentre, piloter son stockage Ceph via l'API S3. Pour l'installer sur votre poste, récupérez les binaires disponibles ici : https://github.com/peak/s5cmd . Ce logiciel a l'avantage d'être un binaire statique, ne nécessitant aucune dépendance, et n'ayant pas besoin d'un environnement d'exécution particulier (par exemple, pas de python).

Il est déployé par défaut sur toutes les ressources de calcul du mésocentre et accessible via le module s5cmd : 

$ module load s5cmd

Configuration de s5cmd pour le serveur de stockage du Mésocentre

Permissions

Tout d'abord, contactez le support pour demander la création d'un compte. On vous fournira alors vos clés d'accès (MYACCESSKEY et MYSECRETKEY) qui sont spécifiques des projets ouverts.

Vous pouvez indiquer de différentes manières (https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-files.html) à s5cmd d'utiliser ces clés :

  1. Via un fichier ~/.aws/config : 

    [default]
aws_access_key_id = MYACCESSKEY
aws_secret_access_key = MYSECRETKEY

  2. Via des variables d'environnement : 

    $ export AWS_ACCESS_KEY_ID=MYACCESSKEY
$ export AWS_SECRET_ACCESS_KEY=MYSECRETKEY

Vous pouvez ajouter ces variables d'environnement à votre fichier ~/.bashrc.

Attention

Notez que ces variables devront être définies dans vos scripts de jobs, qui ne chargent pas nécessairement ~/.bashrc.

Notez que le [default] représente le nom d'un profil correspondant à un projet. Si vous avez plusieurs projets, vous avez plusieurs paires de clés d'accès à gérer. Dans ce cas le fichier ~/.aws/config est vide et est remplacé par le fichier ~/.aws/credentials qui ressemblera à :

[default]
aws_access_key_id = MYACCESSKEY_for_default
aws_secret_access_key = MYSECRETKEY_for_default

[my_perfect_project]
aws_access_key_id = MYACCESSKEY_for_my_perfect_project
aws_secret_access_key = MYSECRETKEY_for_my_perfect_project
Lors des commandes s5cmd il est nécessaire de spécifier l'option --profile, par exemple :

$ s5cmd --profile=my_perfect_project ls

Accès à l'adresse de stockage S3 du Mésocentre

À chaque invocation de l'outil s5cmd il est nécessaire de spécifier le paramètre --endpoint-url="https://s3.mesocentre.uca.fr" : 

$ s5cmd --endpoint-url="https://s3.mesocentre.uca.fr" ls
Il vous est recommandé d'ajouter cette variable d'environnement dans votre fichier de configuration ~/.bashrc de cette manière:

$ export S3_ENDPOINT_URL=https://s3.mesocentre.uca.fr
Vous n'aurez ainsi plus besoin de stipuler ce endpoint lors de l'utilisation des commandes S3. Si vous avez l'habitude de définir des alias dans votre fichier de configuration ~/.bashrc, cela reste possible. Par exemple:

$ alias sxcmd='s5cmd --endpoint-url="https://s3.mesocentre.uca.fr"'

Commandes usuelles de s5cmd

On vérifie dans un premier temps que l'accès fonctionne : 

$ sxcmd ls
# ou
$ s5cmd ls
On partira ensuite du principe que l'export du endpoint a été fait.

Et on va créer un nouveau bucket (mb) : 

$ s5cmd mb s3://monbucket42
mb s3://monbucket42/

Nom du bucket

Il est important de réfléchir au nom de son bucket :

  • un bucket ne peut pas être renommé ;
  • il est impossible de créer un bucket dont le nom a déjà été pris par un autre utilisateur ;
  • le nom du bucket doit respecter certaines règles.

Règles de nommage d'un bucket

Il convient de nommer un bucket en respectant les règles énoncées ici, en particulier pour pouvoir monter un bucket dans le système de fichiers en utilisant goofys, le nom doit être compatible avec les règles DNS :

  • entre 3 et 63 caractères, et ne peut contenir que des lettres minuscules, des chiffres, des points (.) et des tirets (-) ;
  • les noms ne doivent pas contenir de tiret bas (underscore _) ; le nom Mon_Bucket_De_Donnees n'est pas correct, ni mon_bucket_de_donnees ;
  • les noms ne doivent pas ressembler à une adresse IP (ie 192.168.5.4) ;
  • les noms ne doivent pas commencer par un point ni un tiret (.monbucket) ;
  • les noms ne doivent pas se terminer par un point ni un tiret (monbucket.) ;
  • deux points ne doivent pas être adjacents (mon..bucket) ;
  • les tirets et les points ne doivent pas être adjacents (mon-.bucket).

Que l'on peut lister en faisant (ls) : 

$ s5cmd ls
2024/09/18 12:42:02  s3://monbucket42

Je peux ajouter des fichiers à monbucket42 (cp) : 

$ s5cmd cp mkdocs.yml s3://monbucket42
cp mkdocs.yml s3://monbucket42/mkdocs.yml

Que je vois appraître : 

$ s5cmd ls s3://monbucket42
2023/09/18 13:05:45            118997  mkdocs.yml

Ou je peux aussi ajouter des répertoires (cp) : 

$ s5cmd cp docs s3://monbucket42
cp docs/aubi/biomaj.md s3://monbucket42/docs/aubi/biomaj.md
cp docs/oscar/images.md s3://monbucket42/docs/oscar/images.md
[...]
cp docs/cluster/slurm/overview.md s3://monbucket42/docs/cluster/slurm/overview.md
cp docs/s3/rclone.md s3://monbucket42/docs/s3/rclone.md

Qui apparaît : 

$ s5cmd ls s3://monbucket42
                                  DIR  docs/
2023/09/18 13:05:45            118997  mkdocs.yml

$ sxcmd ls s3://monbucket42/docs/
                                  DIR  aubi/
                                  DIR  cluster/
                                  DIR  formation/
                                  DIR  mesocentre/
                                  DIR  oscar/
                                  DIR  s3/
2023/09/18 13:45:45              3965  index.md

Attention, petite subtilité, si vous voulez envoyer uniquement le contenu d'un répertoire (et pas le répertoire lui-même), pensez à mettre un / après le nom : 

$ s5cmd cp monrepertoire/ s3://monbucket42

Pour connaître la taille de votre bucket (du) : 

$ s5cmd du 's3://monbucket42/*'
32782970 bytes in 89 objects: s3://monbucket42/*

Pour récupérer l'un des fichiers (cp) : 

$ s5cmd cp s3://monbucket42/docs/mesocentre/publis.md .
cp s3://monbucket42/docs/mesocentre/publis.md publis.md

Pour copier un fichier d'un endroit à un autre du bucket, ou de 2 buckets différents (cp) : 

$ s5cmd cp s3://monbucket42/docs/files/20161007-tutoriel-mesocentre.pdf s3://monbucket42/autre_dossier/fichier.pdf

Ou pour déplacer un fichier (mv) : 

$ s5cmd mv s3://monbucket42/autre_dossier/fichier.pdf s3://monbucket42/formation.pdf

Pour supprimer un fichier (rm) : 

$ s5cmd rm s3://monbucket42/formation.pdf

Pour supprimer un bucket, il faut d'abord vider son contenu : 

$ s5cmd rm 's3://monbucket42/*'

Puis on peut supprimer le bucket : 

$ s5cmd rb s3://monbucket42
rb 's3://monbucket42/'

Si vous avez besoin de synchroniser un répertoire local avec un répertoire S3, utilisez la commande sync. Elle utilisera les MD5 des fichiers pour savoir quoi envoyer et quoi mettre à jour sur votre S3 ou en local sur votre disque dur : 

$ s5cmd sync docs s3://monbucket42/docs/

D'une manière générale, l'aide de s5cmd fournit de nombreux exemples : 

$ s5cmd help sync
$ s5cmd cp --help

Vous trouverez par exemple quelques options d'intérêt pour la commande cp :

  • --show-progress : affiche une barre de progression lors de la copie. Utile pour les gros fichiers.
  • --concurrency 8 : effectue les transferts avec 8 threads en parallèle.

Vitesse

Si vous constatez des lenteurs d'accès aux objets stockés sur le S3, vérifiez si la variable d'environnement no_proxy est bien positionnée : 

$ export no_proxy=127.0.0.1,localhost,192.168.53.0/24,s3.mesocentre.uca.fr
Cela permettra aux transferts S3 de s'effectuer sans passer par le proxy web. Éventuellement, dans un second temps, si votre job n'a pas besoin d'accéder à internet, vous pouvez effacer les proxy afin d'améliorer la rapidité des transferts : 
$ unset http_proxy
$ unset https_proxy