INSTALLATION ============ Vous venez de recevoir un fichier nommé "peer.tar.gz" de la part de "vito", votre parrain dans le système "peer". Voici comment procéder pour entrer dans la famille. Nous supposons que vous êtes "johnny" et que vous avez un compte appelé "johnny" sur l'ordinateur. Assurez-vous que les outils nécessaires suivants sont disponibles sur l'ordinateur: ssh ssh-keygen ssh-agent ssh-add git iconv awk Les outils suivants ne sont pas nécessaires, mais fortement recommandés: gettext, rsync, nc, sendmail, cstream, gzip, gpg, sha256sum, base64 Créez un nouveau compte (appelé "peer" dans ce qui suit), dédié à l'utilisation du système "peer". Assurez-vous que l'utilisateur "peer" a la permission de se connecter à cet ordinateur depuis l'Internet en utilisant ssh. Logguez-vous sur l'ordinateur en tant que l'utilisateur "peer". En tant que l'utilisateur "peer", ouvrez l'archive de distribution: $ tar zxf peer.tar.gz Cela extrait le script "peer", un fichier de clé nommé "vito" et un répertoire caché ".locale" qui contient les traductions des messages. Initialisez le système en lançant: $ ./peer init Ceci ne fonctionnera pas si les répertoires ~/.ssh ou ~/.share existent. S'ils ont été crées lors d'une tentative d'initialisation précédente, vous devez les supprimer à la main. Si vous n'avez jamais lancé "peer init" auparavant, le script va vous demander des valeurs pour un certain nombre de paramètres: Identifiant du pair : cet identifiant doit être unique dans tout le réseau de pairs, appelons le "johnny" dans ce qui suit. Nom d'utilisateur : nous avons choisi "peer" pour cet exemple. Adresse de la machine : le nom DNS ou l'adresse IP publics de la machine. Port SSH : par défaut, c'est 22. Adresse e-mail : l'adresse à laquelle vous voulez recevoir les messages du système peer, par exemple "johnny" pour l'utilisateur local "johnny", ou "johnny@example.com". Jeu de caractères : le jeu de caractères utilisé pour les noms de fichiers sur l'ordinateur. Répertoire de téléchargement : le répertoire où les fichiers téléchargés doivent être placés par défaut. La commande "init" produit aussi votre fichier de clé, appelé "johnny". Transmettez ce fichier à "vito" et demandez-lui d'ajouter "johnny" à son système. Ajoutez la clé "vito". Ceci permettra à "vito" de se connecter à votre ordinateur. $ ./peer add Si "vito" n'a pas encore ajouté le fichier de clé de "johnny" à son système, le script produira un message d'erreur. C'est normal. Attendez que "vito" ajoute votre fichier de clé à son système. Lorsque "vito" aura fait sa part de travail, vous recevrez un e-mail indiquant le cas échéant les fichiers ajoutés au système. Félicitations, vous faites maintenant partie de la famille ! Note sur l'e-mail ----------------- Si l'ordinateur sait gérer les e-mails locaux, tout va bien. S'il ne gère pas les e-mails locaux mais sait envoyer des e-mails vers l'Internet à condition que l'adresse de l'émetteur soit valide, vous devez ajouter les deux variables suivantes au fichier de configuration ~/.peerrc: - SENDER_ADDRESS qui indique une adresse d'émetteur valide - SENDER_NAME qui contient le nom réel de l'émetteur (utilisé par le serveur de mail pour compléter le champ "From: "). PARTAGER DES FICHIERS ===================== Les fichiers que vous souhaitez partager doivent être placés dans ~/files (un répertoire crée au moment de l'installation). Il est tout à fait possible de ne placer dans ce répertoire que des liens symboliques, les fichiers se trouvant en réalité dans un tout autre répertoire. Si vous souhaitez que le système ignore certains fichiers qui se trouvent dans ~/files, vous pouvez placer dans ~/.peerignore des expressions régulières correspondant au chemin de ces fichiers ou répertoires relativement à ~/files. Par exemple, pour ignorer tous les fichiers se trouvant dans le répertoire ~/files/A/B/C il faut ajouter la ligne A/B/C/.* dans le fichier ~/.peerignore (il faut au besoin créer ce fichier). UTILISER PEER ============= Voici les commandes de peer. Elles sont toutes des paramètres du script "peer", donc la commande "help" par exemple s'utilise en lançant "peer help". help : la liste des commandes readme : affiche le readme init : initialise un compte vierge pour être utilisé dans le système peer add : ajoute le fichier de clé à votre réseau de pairs. Le pair sera identifié en tant que dans le système. del : supprime du réseau. list : liste tous les pairs et leurs adresses SSH. links : liste tous les fichiers disponible sous forme d'URL rsync/scp. sync : récupère des mises à jour de tous les autres pairs. diff : affiche les différences locales avec le précédent push. push : indique aux autres pairs de récupérer vos mises à jour. agent start : déverrouille votre clé ssh pour permettre aux autres de récupérer vos mises à jour (place la clé dans l'agent ssh). agent stop : arrête l'agent ssh. get : télécharge (une URL rsync) dans le répertoire . q [] : place dans la file d'attente et commence le téléchargement en tâche de fond. getlist : place la/les liste d'URL dans la file d'atttente et commence le téléchargement en tâched e fond. qstart : commence le téléchargement en tâche de fond. qstop : arrête le téléchargement en tâche de fond. qedit : édite la file d'attente. wstart [p h] : démarre le serveur Web interne (port p, host h). L'URL est affichée au démarrage. Par défaut, le port est 8080 et l'hôte 127.0.0.1. wstop : arrête le serveur Web interne. msg : envoie un message à . msgall : envoie un message à tous les pairs. newkey : crée une nouvelle clé ssh. rename : renomme ce pair en . passwd : change le mot de passe de la clé ssh. test [opt] : teste la connexion avec et passe les options [opt] à ssh. distribute [opt] : redistribue le script sous forme d'une archive .tar.gz. Si opt est une adresse e-mail, envoie par e-mail. Si opt est '-', écrit sur la sortie standard. Si opt est absent, écrit dans ~/peer.tar.gz. update_host_key : met à jour le fichier de clé de ce pair à partir des USERNAME, HOSTNAME et PORT dans ~/.peerrc et de la clé SSH publique de l'hôte (à utiliser lorsque les infornations de connexion ou la clé SSH de l'hôte ont changé). Phrase de passe ssh ------------------- La clé ssh est normalement placée dans l'agent ssh. Si vous redémarrez votre ordinateur, la clé sera pas magiquement replacée dans l'agent ; vous devez alors lancer "peer agent start" afin de l'y ajouter et ainsi permettre aux autres pairs de propager des mises à jours vers votre machine. Mises à jour automatiques ------------------------- Lors de l'exécution de la commande "peer init", le script "peer" est renommé "peer.old" et remplacé par un lien symbolique vers "~/.share/peer/peer". Ceci permet que la commande "peer" exécute toujours la version la plus récente du script, qui est mise à jour automatiquement. TÉLÉCHARGER DES FICHIERS ======================== Fichiers individuels -------------------- Vous pouvez obtenir une liste de tous les fichiers disponibles chez les autres pairs avec la commande "peer links". Cette commande liste tous les fichiers sous forme d'URLs rsync, qui peuvent être directement utilisées comme paramètre à la commande "peer get". Comme la sortie de "peer links" est du texte, elle peut être traitée avec les outils habituels (p.ex. grep). Seuls les fichiers sont listés, pas les répertoires. Le nombre affiché après le nom du fichier est sa taille en octets. Après avoir choisi un fichier, copiez son URL rsync (telle qu'affichée par "peer links"). L'URL est aussi une adresse scp valide, donc si rsync n'est pas disponible, vous pouvez télécharger le fichier and lançant $ scp Si rsync est disponible, vous pouvez passer l'URL comme premier paramètre de "peer get". Placez-le entre doubles quotes au cas où il contiendrait des espaces ou des caractères exotiques. Passez le nom du répertoire de destination comme second paramètre de "peer get", par exemple : $ peer get "vito:rép/ert/oire/nom/de/fichier" incoming "vito:rép/ert/oire/nom/de/fichier" étant l'URL rsync et "incoming" le nom du répertoire de destination. Le fichier sera alors téléchargé en utilisant rsync. Vous pouvez passer des arguments supplémentaires à rsync avant l'URL. Par exemple, si vous voulez télécharger récursivement le répertoire "vito:rép/ert/oire", vous pouvez utiliser $ peer get -r "vito:rép/ert/oire" incoming Vous pouvez placer des options courantes de rsync dans la variable RSYNC_OPTS du fichier de configuration ~/.peerrc . Utiliser la file d'attente de téléchargement -------------------------------------------- Au lieu d'utiliser "peer get", vous pouvez utiliser "peer q" pour ajouter une URL rsync et le répertoire de destination correspondant à la file d'attente de téléchargement, et laisser peer télécharger les fichiers en tâche de fond : $ peer q "vito:rép/ert/oire/nom/de/fichier" incoming Notez qu'il n'est pas possible de passer des options à rsync avec cette méthode. Si vous avez besoin de passer des options à rsync, il faut les placer dans la variable RSYNC_OPTS du fichier de configuration ~/.peerrc . Vous pouvez contrôler la file d'attente de téléchargement avec les commandes "qstart" et "qstop". Il est tout à fait acceptable d'arrêter la file d'attente alors qu'un téléchargement est en cours. Ce dernier sera interrompu, et reprendra lorsque vous appellerez à nouveau "qstart". Si vous trouvez nécessaire d'éditer manuellement la file d'attente, vous pouvez utiliser la commande "qedit". Utiliser l'interface Web ------------------------ Si vous trouvez l'interface en ligne de commande ennuyeuse, vous pouvez démarrer l'interface Web à la place, en lançant $ peer wstart La commande affiche l'URL à laquelle l'interface est accessible, par défaut il s'agit de http://localhost:8080/ . Donnez cette URL à votre navigateur Web, et vous y êtes. Vous pouvez spécifier une adresse différente à l'aide de la variable "HTTP_HOST" du fichier de configuration ~/.peerrc . Il en va de même pour le numéro de port, qui peut être défini grâce à la variable "HTTP_PORT" dans le même fichier de configuration. Au haut de la page se trouve une liste de commande, correspondant aux commandes du même nom disponible en ligne de commande (sauf "EXIT" qui appelle "wstop"). En dessous, les fichiers sont listés sous la forme d'une arborescence, représentant la hiérarchie du système de fichiers. Si Javascript est disponible, la list est repliée, et une partie peut être dépliée en cliquant sur le symbole "+" à coté du nom du répertoire. On peut replier en cliquant sur le symbole "-" qui avait remplacé le "+" au moment du dépliage. Chaque fichier et répertoire est en fait un lien. En cliquant sur un lien, vous le placez dans la file d'attente, et le téléchargement commence immédiatement en tâche de fond. La taille de chaque fichier et répertoire est affichée en petits caractères à coté de son nom. Dans le cas de bandes dessinée (c.-à-d. de fichiers qui ont "BD" comme répertoire parent), un lien représenté par un point d'interrogation entre crochets ([?]) permet de lancer une recherche pour cette bande dessinée (ou pour la série de bande dessinée) sur http://www.bedetheque.com/ . PARTAGE DE FICHIERS =================== Partager des fichiers ne requiert aucune opération particulière. Si vous souhaitez limiter le débit utilisée par une connexion entrante (scp ou rsync), vous pouvez indiquer la limite maximale de débit d'envoi (en octets par seconde) grâce à la variable "THROTTLE" du fichier de configuration ~/.peerrc . La limitation du débit fait appel à la commande "cstream", qui doit donc être présente sur le système. Pour des raisons de simplicité, la limite est appliquée à chaque connexion indépendamment ; il n'est pas possible d'indiquer une limite globale à toutes les connexions simultanées. UTILISER PEER À PARTIR D'UN UTILISATEUR NORMAL ============================================== Si vous voulez utiliser le script en ligne de commande mais sans avoir à vous loguer en tant que "peer", voici quelques astuces. Placez la clé ssh de "johnny" dans le fichier ~/.ssh/authorized_keys.default chez l'utilisateur "peer". Vérifiez que vous pouvez vous connecter à l'ordinateur par ssh en tant qu'utilisateur "peer". Ajoutez la fonction suivante au fichier ~/.bashrc de "johnny" : function peer() { [[ "$1" =~ qedit|msg|sync|push|test ]] && local emulate_tty="-t" ssh -q $emulate_tty peer@localhost .share/peer/peer "$@" } Rechargez le ~/.bashrc en lançant $ source ~/.bashrc À partir de maintenant, vous pouvez lancer toutes les commandes de peer en tant qu'utilisateur "johnny". Rappelez-vous simplement que tous les chemins de fichiers relatifs seront basés sur le répertoire "home" de "peer", et non pas sur le répertoire courant. DEVENIR PARRAIN =============== Si vous voulez inviter un nouvel utilisateur dans le réseau peer, vous devez devenir le parrain de cet utilisateur et lui envoyer le script peer et votre clé. Vous pouvez générer une archive .tar.gz qui contient tout cela plus ce fichier README en lançant $ peer distribute Cette commande crée le fichier peer.tar.gz dans le répertoire "home" de "peer". Vous pouvez alors transmettre ce fichier à votre filleul. Si vous utilisez peer depuis un autre utilisateur, tel que décrit dans la section précédente, vous pouvez lancer à la place $ peer distribute - > peer.tar.gz qui écrit le contenu de l'archive sur la sortie standard, et vous pouvez alors la rediriger vers un fichier situé à l'emplacement qui vous convient. Enfin, si votre ordinateur peut envoyer des e-mails vers l'Internet, vous pouvez passer une adresse e-mail comme argument à la commande "distribute", par exemple $ peer distribute filleul@example.com et le script enverra l'e-mail de lui-même à filleul@example.com . À un moment, votre filleul vous enverra son fichier de clé, que vous devrez alors ajouter à votre réseau à l'aide de la commande "peer add". SOUS LE CAPOT ============= Le but du système peer est de faciliter les connexions par ssh entre les ordinateurs appartenant à un même réseau. Chaque nœud dans le réseau possède un dépôt git qui contient les clés RSA publiques des chaque pair ainsi que la liste des fichiers disponibles chez ces pairs. Le dépôt est aussi utilisé pour conserver la version la plus récente dy script peer. L'utilsation de git permet à n'importe quel membre du réseau de mettre à jour un fichier dans le dépôt (typiquement la liste de ses fichiers, après avoir ajouté ou supprimé des fichiers en partage) puis de propager ("push") ces changements chez les autres pairs (ceci s'effectue en pratique en faisant un "git push" vers une branche spéciale chez le destinataire, puis en utilisant le hook "post-update" pour faire un "git merge" de cette branche dans la branche master). L'opération réciproque "sync" est aussi possible, un pair appelant "git pull" pour chacun des autres pairs, à tour de rôle. Étant donné que les clés RSA sont protégées par une phrase de passe, il est nécessaire de placer la clé dans l'agent ssh du nœud afin de permettre un nœud de se connecter automatiquement à un autre nœud (mais ceci n'est nécessaire que pour l'opération "peer push"). Un corollaire de ceci est que tous les membres du réseau peuvent se connecter par ssh chez tous les autres ordinateurs dans ce réseau. SÉCURISATION DU SYSTÈME ======================= Au niveau des accès par SSH --------------------------- Afin d'empêcher un ordinateur compromis de pouvoir se connecter à tous les autres membres du réseau et par là d'utiliser leur ordinateur pour lancer des attaques vers l'Internet, les commandes qu'un client SSH se connectant sur votre ordinateur peut lancer sont limitées : le fichier ~/.ssh/authorized_keys force l'utilisation de "peer -D" pour les connexions entrantes. Cette dernière commande vérifie quelle commande devrait être exécutée à travers la connexion SSH et s'il s'agit d'une commande autre que celles nécessaires au bon fonctionnement de peer, la connexion sera fermée immédiatement. Il faut noter que les chemins des fichiers qui sont accédés par rsync et scp ne sont pas limités, un utilisateur se connectant depuis une machine du réseau a donc accès à l'ensemble du système de fichier de votre ordinateur. Au niveau de l'intégrité du code -------------------------------- Le script et les fichiers associés sont accompagnés d'une liste de sommes de contrôle SHA256 ($HOME/.share/peer/sha256sums), cette liste étant signée avec la clé GnuPG 88BB DC17 2A81 1C8D (la signature se trouve dans $HOME/.share/peer/sha256sums.asc). Cette vérification se fait par le script ~/.share/.git/hooks/post-merge (qui est indépendant du script peer). Si la signature ou les sommes de contrôle ne correspondent pas au code, le script supprime toutes les permissions sur $HOME/.share, rendant ainsi le compte peer inaccessible par SSH. Le script ~/.share/.git/hooks/post-merge est crée au moment de l'installation de peer et n'est plus modifié ensuite. Pour mettre à jour ce script, il faut lancer la commande $HOME/.share/peer/peer make_git_post_merge_hook en tant qu'utilisateur peer.