Aller au contenu

Avec le client cnrgh-dl

Présentation

L'authentification à double facteur (2FA) requise pour accéder au portail de téléchargement empêche l'utilisation de clients de téléchargement en ligne de commande classiques tels que wget ou curl car ils ne supportent pas ce type d'authentification.

Pour cette raison, le CNRGH met à votre disposition cnrgh-dl, un client de téléchargement adapté à ce nouveau système d'authentification.

Prérequis

cnrgh-dl nécessite au minimum Python 3.9 pour fonctionner.

Installation

Installation sous Linux

L'installation de cnrgh-dl avec pipx est recommandée.

pipx est un outil qui permet l'installation de paquets Python dans des environnements virtuels isolés. Cela permet d'éviter les conflits de dépendances, qui peuvent survenir lorsque plusieurs paquets sont installés dans un environnement virtuel commun comme avec pip.

Pour installer pipx sur votre machine, référez-vous aux instructions d'installation détaillées dans la documentation officielle.

Sous Linux, si vous n'êtes pas administrateur sur votre machine, n'exécutez pas la commande sudo pipx ensurepath --global. Cette commande optionnelle permet d'installer pipx pour tous les utilisateurs de la machine.

La page de documentation comporte un tableau listant la version la plus récente du paquet pipx téléchargeable depuis les dépôts officiels de différentes distributions Linux.

  • Si votre distribution dispose de la dernière version du paquet pipx (case colorée en vert), alors il est recommandé de l'installer avec le gestionnaire de paquets officiel de votre distribution (ex : apt sur Ubuntu),

  • Si ce n'est pas le cas, référez-vous à la section qui détaille l'installation de pipx avec pip.

Par exemple, au 24/07/2024, le tableau indique que le dépôt officiel d'Ubuntu 22.04 propose la version obsolète 1.0.0, alors que la dernière version disponible de pipx est la 1.6.0. Utiliser une version ancienne de pipx peut poser problème lors de l'installation de paquets Python.

Une fois pipx installé sur votre machine, installez cnrgh-dl avec la commande suivante :

pipx install cnrgh-dl

L'installation de cnrgh-dl avec pip nécessite la création d'un environnement virtuel dédié. Cela permet d'isoler les dépendances de cnrgh-dl des autres paquets installés sur votre système, ce qui limite les risques de conflit de dépendances.

Créez un environnement virtuel dédié à cnrgh-dl avec les commandes suivantes :

python -m venv cnrgh_dl_venv # Création d'un environnement virtuel dédié.
source cnrgh_dl_venv/bin/activate # Activation de l'environnement virtuel.
pip install cnrgh-dl # Installation du client.

Avant chaque utilisation de cnrgh-dl, il faudra activer cet environnement virtuel avec la commande source. L'environnement est désactivable à tout moment avec la commande deactivate.

Pour des raisons de stabilité, il est déconseillé :

  • d'installer d'autres paquets dans l'environnement virtuel dédié,
  • d'installer globalement cnrgh-dl, c'est-à-dire en dehors d'un environnement virtuel. Si vous souhaitez que la commande cnrgh-dl soit disponible sans avoir à l'activer manuellement avant chaque utilisation, installez le paquet à l'aide de pipx.

Vérification de l'installation

Vérifiez l'installation en exécutant la commande suivante :

cnrgh-dl -h

Si l'installation a réussi, cnrgh-dl affichera son message d'aide.

Mise à jour

Si une version plus récente est disponible, elle sera signalée à chaque exécution via le message suivant :

A newer version of cnrgh-dl is available.
Please update to the latest version: x.x.x (installed version: x.x.x).

Nous vous recommandons de mettre à jour le client dès que possible pour garantir la compatibilité avec le portail de téléchargement.

Les modifications apportées à chaque nouvelle version sont listées dans le changelog.

Si cnrgh-dl a été installé avec pipx, lancez la commande suivante pour effectuer la mise à jour :

pipx upgrade cnrgh-dl

Si cnrgh-dl a été installé avec pip, assurez-vous que l'environnement virtuel dans lequel le client de téléchargement a été installé est bien activé :

source cnrgh_dl_venv/bin/activate

Ensuite, lancez la commande suivante pour effectuer la mise à jour :

pip install cnrgh-dl --upgrade

Enfin, vérifiez que la mise à jour a bien été appliquée avec :

cnrgh-dl --version

Utilisation

⚠ En raison de certaines contraintes techniques liées à l'accès aux fichiers, une seule instance de cnrgh-dl peut être exécutée à la fois. Cette limitation vise à garantir une utilisation fluide et équitable du service pour l'ensemble des utilisateurs.

Sélection des fichiers

cnrgh-dl a besoin d'une liste d'URLs pointant vers les fichiers à télécharger. Vous pouvez réaliser une sélection des fichiers que vous souhaitez télécharger sur le nouveau portail de téléchargement.

Une fois les fichiers d'intérêt sélectionnés, le portail vous donne le choix de copier votre sélection dans le presse-papier ou de l'exporter au format .txt.

Si vous choisissez d'exporter votre sélection, vous devrez lancer cnrgh-dl avec l'argument optionnel -i INPUT_FILE / --input-file INPUT_FILE, où INPUT_FILE est le chemin vers le fichier exporté au format .txt.

Sans cet argument, cnrgh-dl se lance en mode "interactif" et demande à l'utilisateur de saisir une liste d'URLs des fichiers à télécharger via l'entrée standard. Collez votre sélection, puis appuyez sur la touche "Entrée" pour que les URLs soient ajoutées à la file de téléchargement.

En mode "interactif", les actions suivantes sont disponibles :

  • l / list : Lister les URLs présentes dans la file de téléchargement,
  • c / clear : Supprimer toutes les URLs présentes dans la file de téléchargement,
  • v / validate : Valider le contenu de la file et démarrer le téléchargement,
  • q / quit : Quitter.

Après avoir saisi une action dans le terminal, exécutez-la en appuyant sur la touche "Entrée".

Authentification

Après avoir vérifié la validité des arguments passés en ligne de commande, et (en mode "interactif") obtenu la liste des URLs des fichiers à télécharger, cnrgh-dl démarrera la procédure d'authentification. Vous verrez apparaître dans le terminal le message suivant :

To login, please open
https://keycloak.ibfj-evry.fr/realms/IBFJ-EVRY-OU-CollabExt/device
in a web browser and enter the following code :
XXXX-XXXX (expiring in 600 seconds).

Vous disposerez alors d'une fenêtre de 10 minutes pour vous authentifier, sous quoi vous devrez recommencer la procédure. Ouvrez un navigateur et rendez-vous à l'adresse suivante : https://keycloak.ibfj-evry.fr/realms/IBFJ-EVRY-OU-CollabExt/device.

ℹ Pour faciliter les prochaines authentifications, nous vous conseillons d'enregistrer ce lien en tant que marque-page dans votre navigateur.

Une fois sur la page, saisissez le code à huit caractères affiché par cnrgh-dl puis suivez les instructions pour vous authentifier avec votre clé physique. Une fois la procédure d'authentification terminée, vous pourrez fermer la page (la page vous en informera).

La procédure de double authentification nécessite un navigateur internet, mais il n'a pas besoin d'être exécuté dans le même environnement que cnrgh-dl. Par exemple, si vous réalisez vos téléchargements sur un serveur via une session SSH, il n'est pas nécessaire d'ouvrir un navigateur directement sur le serveur. Vous pouvez ouvrir un navigateur localement sur votre machine, à condition qu'elle possède un port USB Type-A afin que vous puissiez y insérer votre clé physique et compléter la procédure d'authentification.

⚠ Pour des raisons de sécurité, cette procédure devra être répétée à chaque lancement du client de téléchargement.

Une fois authentifié, le client téléchargera les fichiers de la file d'attente pendant une période maximale de 72 heures. À l'expiration de cette période, le client complètera le téléchargement en cours, puis s'arrêtera. Vous pourrez relancer le client avec les mêmes arguments et les mêmes fichiers ; les fichiers déjà téléchargés seront ignorés.

Démonstration vidéo

  • ÉTAPE 1 (0:00) : Dans un terminal, on lance le client de téléchargement cnrgh-dl. Ici, on lui demande de télécharger les fichiers dans le répertoire ~/Downloads/cnrgh-dl/.
  • ÉTAPE 2 (0:09) : On copie et ouvre le lien suivant dans un navigateur : https://keycloak.ibfj-evry.fr/realms/IBFJ-EVRY-OU-CollabExt/device. Ensuite, on copie le code généré par cnrgh-dl, on le renseigne dans le formulaire puis on clique sur Soumettre.
  • ÉTAPE 3 (0:20) : On se connecte à son compte collaborateur avec la double authentification. Les actions à réaliser sont les mêmes que celles de l'authentification sur le portail de téléchargement : on renseigne son nom d'utilisateur (ici colltest_DUMMY), on connecte la clé physique à son ordinateur et on renseigne son code PIN puis on la touche sur son contact doré.
  • ÉTAPE 4 (0:36) : On accorde les privilèges d'accès requis par le client cnrgh-dl.
  • ÉTAPE 5 (0:39) : La procédure d'authentification est terminée. Le téléchargement des fichiers peut commencer.

Téléchargement

Vérification de l'intégrité

Un fichier mis à disposition sur le portail de téléchargement est accompagné de son fichier de somme de contrôle MD5. Ce dernier permet de vérifier l'intégrité du fichier téléchargé. Si un fichier est présent dans la file de téléchargement sans son fichier MD5, alors ce dernier sera automatiquement téléchargé s'il existe sur le portail. De cette manière, l'intégrité d'un maximum de fichiers téléchargés sera vérifiée. Cette vérification a lieu une fois que tous les fichiers de la file ont été téléchargés.

Si aucun fichier de somme de contrôle MD5 n’est disponible sur le portail pour un fichier donné, alors la vérification de son intégrité sera indiquée comme SKIPPED (ignorée), avec le message suivant : no MD5 checksum file available to download (aucun fichier de somme de contrôle MD5 disponible au téléchargement).

Vous pouvez désactiver le téléchargement automatique de fichiers de somme de contrôle MD5 additionnels avec l'option --no-additional-checksums, et la vérification automatique de l'intégrité avec l'option --no-integrity-check.

⚠ Il est vivement recommandé de laisser ces options activées pour s'assurer de l'intégrité des fichiers téléchargés.

Gestion des fichiers existants

Le téléchargement d'un fichier sera ignoré si un fichier avec le même nom est déjà présent dans le répertoire de sortie. Si un fichier est partiellement téléchargé (c'est-à-dire que son nom est suffixé par .part), alors son téléchargement sera repris.

Il est possible de forcer le téléchargement avec l'option -f / --force. Les fichiers déjà présents dans le répertoire de sortie seront écrasés. Les fichiers partiellement téléchargés seront supprimés et leur téléchargement recommencera.

Exécution en arrière-plan

cnrgh-dl peut traiter la file de téléchargement dans un processus en arrière-plan, ce qui lui permet de ne pas être stoppé si le terminal est fermé ou si l'utilisateur se déconnecte, que ce soit volontaire ou non.

Ce mode s’active grâce à l’option -b / --background. Il est recommandé de l’utiliser avec l’option -j / --json-report afin de générer un rapport JSON en fin d’exécution. Ce rapport contient, pour chaque fichier, le statut (SUCCESS, SKIPPED, ERROR) de leur téléchargement et de leur vérification d’intégrité.

cnrgh-dl passe en arrière-plan lorsqu'il a obtenu tout ce dont il a besoin pour travailler :

  • les arguments passés en ligne de commande sont valides,
  • l'utilisateur a saisi la liste des URLs des fichiers à télécharger (en mode "interactif"),
  • l'utilisateur s'est authentifié avec succès.

Une fois détaché du terminal, le processus en arrière-plan n’écrit plus rien sur les sorties standard. La commande ps permet de vérifier que le processus est toujours actif et d’obtenir des informations générales sur son exécution :

ps -C cnrgh-dl -o pid,lstart,etime,stat,args

Cette commande affichera, entre autres, l'ID du processus (PID), la date et l’heure de démarrage du processus (STARTED) et le temps écoulé depuis le lancement (ELAPSED) au format [[dd-]hh:]mm:ss.

ℹ Pour interrompre le processus de téléchargement en arrière-plan, utilisez kill PID, en remplaçant PID par l'identifiant du processus obtenu avec la commande ps ci-dessus.

Pour suivre précisément l’avancement des téléchargements et diagnostiquer d’éventuels problèmes, consultez directement les logs. Le chemin du fichier de log est indiqué dès le lancement de cnrgh-dl. Utilisez la commande suivante pour afficher les 20 dernières lignes de logs :

tail -n 20 chemin/vers/les/logs/cnrgh_dl.log

Exemple

Prenons le cas d'un projet fictif appelé DEMO. Sur le portail de téléchargement, la page du projet serait accessible à l'URL suivante : https://www.cnrgh.fr/dl/project/DEMO. Sur cette page, une sélection de fichiers a été réalisée et enregistrée dans le fichier DEMO_download_links.txt.

Téléchargement avec vérification de l'intégrité

cnrgh-dl ~/Downloads/DEMO/ -i ./DEMO_download_links.txt

Dans la commande ci-dessus, les fichiers sont téléchargés dans le répertoire ~/Downloads/DEMO/. Avec l'option -i, on charge les URLs de la sélection à télécharger depuis le fichier DEMO_download_links.txt.

ℹ Le répertoire de sortie DEMO doit avoir été créé au préalable.

Liste des arguments

Arguments positionnels :

  • outdir : répertoire de sortie où les fichiers téléchargés sont stockés.

Arguments optionnels :

  • -i INPUT_FILE, --input-file INPUT_FILE : chemin vers un fichier contenant une liste d'URLs à télécharger (une URL par ligne). Sans cet argument, cnrgh-dl sera exécuté en mode "interactif" et demandera une liste d'URLs des fichiers à télécharger via l'entrée standard.

  • --no-integrity-check : Utiliser cette option désactivera la vérification de l'intégrité des fichiers téléchargés.

  • --no-additional-checksums : Utiliser cette option désactivera le téléchargement automatique de fichiers de somme de contrôle MD5 additionnels : seulement les fichiers présents dans la file de téléchargement seront téléchargés.

  • -f, --force-download : Utiliser cette option relancera le téléchargement de tous les fichiers déjà présents dans le répertoire de sortie, que leur téléchargement soit complet ou partiel.

  • -j, --json-report : Génère un rapport au format JSON contenant l'état des fichiers téléchargés ainsi que l'état de leur vérification d'intégrité. Le rapport est enregistré dans le répertoire de sortie outdir.

  • -b, --background : Traite les téléchargements en arrière-plan. Une fois les arguments validés, l’utilisateur authentifié, et (en mode "interactif") la liste des URLs des fichiers à télécharger saisie, cnrgh-dl se termine après avoir lancé un processus en arrière-plan (daemon) chargé de traiter la file de téléchargements de manière autonome. Ce processus est détaché du terminal, ce qui permet aux téléchargements de continuer même si le terminal est fermé ou que l’utilisateur est déconnecté (par exemple à la suite d’une déconnexion SSH ou d’un problème réseau). Il est recommandé d’utiliser cette option avec -j / --json-report afin que le processus en arrière-plan génère un rapport de téléchargement à la fin de l’exécution. ⚠ Cette option n’est pas supportée sous Windows.

Changelog

2.0.0 - 2026-02-18

Ajouts

  • Ajout du support de Python 3.14.

Corrections

  • Certains fichiers, dont le type le permettait, étaient compressés par le serveur de téléchargement. cnrgh-dl ne les décompressait alors pas correctement, ce qui pouvait entraîner des fichiers corrompus.

Suppressions

  • Abandon du support de Python 3.9 : Python 3.9 n'étant plus supporté depuis octobre 2025, la version minimale requise par cnrgh-dl est désormais Python 3.10.

    Python 3.10 nécessite OpenSSL 1.1.1 ou plus récent.

1.1.1 - 2025-06-23

Ajouts

  • Pour faciliter la consultation des logs, le chemin du fichier de log est affiché au démarrage.

Modifications

  • Amélioration de l'affichage de la vérification d'intégrité des fichiers,
  • Clarification du message d'erreur affiché lorsqu'une liste de fichiers de somme de contrôle MD5 ne peut pas être obtenue auprès du portail de téléchargement.

Corrections

  • La restriction d'instance unique n'est plus appliquée aux commandes --help et --version. Étant donné qu'elles affichent leur résultat et quittent immédiatement, elles ne doivent pas être soumises à cette restriction.

1.1.0 - 2025-04-18

Ajouts

  • Ajout du support de Python 3.13,
  • Option -b / --background pour traiter les téléchargements en arrière-plan,
  • Ajout d'un lien vers ce changelog dans le message affiché lorsqu'une mise à jour de cnrgh-dl est disponible.

Modifications

  • cnrgh-dl refusera désormais de démarrer s’il détecte qu'une autre instance est déjà en cours d’exécution sur la machine,
  • Le rapport généré par l'option -j / --json-report inclut désormais, en plus de l'état des fichiers téléchargés, l'état de leur vérification d'intégrité,
  • Le statut des fichiers n’ayant pas pu être téléchargés parce que la durée maximale de la session (72h) a été atteinte est désormais SKIPPED (ignoré) au lieu de ERROR (en erreur),
  • La validité de tous les arguments est désormais vérifiée avant le démarrage de la procédure d’authentification,
  • Amélioration des messages de statut affichés lors de la vérification de l'intégrité des fichiers,
  • Amélioration du message d'erreur quand une liste de fichiers de somme de contrôle MD5 ne peut pas être obtenue auprès du portail de téléchargement.

Corrections

  • Une faible variation de la durée de vie d’un nouveau jeton d’accès par rapport à la durée attendue entrainait une terminaison prématurée,
  • La valeur du code de sortie retourné en fin d'exécution était l’inverse de celle attendue,
  • La lecture des fichiers MD5 téléchargés a été rendue plus robuste,
  • La vérification de l'intégrité traite les fichiers selon leur ordre de téléchargement (alphabétique).

Suppressions

  • Plus aucune confirmation n'est demandée avant de quitter lorsque CTRL+C est pressé.

1.0.0 - 2025-02-19

Modifications

  • Sortie de la version stable de cnrgh-dl,
  • Mise à jour pour fonctionner avec la dernière version du portail de téléchargement.

0.2.0 - 2024-12-11

Ajouts

Modifications

  • La gestion des jetons d'accès a été modifiée pour permettre une session de téléchargement plus longue que précédemment. La durée maximale d'une session a été étendue de 10 à 72 heures. Lorsque la session arrivera à terme, un message sera affiché et le téléchargement en cours sera terminé proprement.

Corrections

  • Une URL de téléchargement vers un fichier sans extension était considérée comme invalide.

Suppressions

  • Abandon du support de Python 3.8 : Python 3.8 n'étant plus supporté depuis octobre 2024, la version minimale requise par cnrgh-dl est désormais Python 3.9.

0.1.2 - 2024-09-25

Corrections

  • Sous certaines conditions, le téléchargement d'un fichier était passé si cnrgh-dl avait été précédemment interrompu lors d'un téléchargement en utilisant l'option -f / --force.

0.1.1 - 2024-09-24

Corrections

  • Une erreur lors du rafraîchissement du jeton d'accès auprès du serveur entrainait une terminaison abrupte. Désormais, si une erreur se produit, le téléchargement en cours continuera jusqu'à son terme et tous les prochains téléchargements seront passés. La vérification des sommes de contrôle sera réalisée pour les fichiers téléchargés avant l'erreur.

0.1.0 - 2024-07-17

  • Sortie de la version initiale de développement de cnrgh-dl.