diff --git a/support/documentation/content/documentation/admin/advanced/xmpp_clients.en.md b/support/documentation/content/documentation/admin/advanced/xmpp_clients.en.md index d8491d6b..07dd85b4 100644 --- a/support/documentation/content/documentation/admin/advanced/xmpp_clients.en.md +++ b/support/documentation/content/documentation/admin/advanced/xmpp_clients.en.md @@ -52,16 +52,7 @@ Some XMPP servers may refuse to connect, depending on their configuration. In this case, you can indicate here a path on the server, in which you must place certificates to be used by the module. It is up to you to generate and renew them. -You can refer to the [Prosody documentation](https://prosody.im/doc/certificates). - -{{% notice tip %}} -If you want to use the ProsodyCtl utility to import -certificates, this utility is available (once Peertube is started) using -the following command (adapting the path to your Peertube data folder, -and replacing "xxx" with the arguments you wish to pass to -prosodyctl): -`sudo -u peertube /var/www/peertube/storage/plugins/data/peertube-plugin-livechat/prosodyAppImage/squashfs-root/AppRun prosodyctl xxx` -{{% /notice %}} +See bellow for more information. ### Firewall @@ -98,6 +89,109 @@ $ dig +short _xmpp-server._tcp.room.videos.john-livingston.fr. SRV 0 5 5269 videos.john-livingston.fr. ``` +### Using trusted certificates + +The self-signed certificates that this plugin uses by default can be rejected by some XMPP servers, for security reasons. + +It is possible to use certificates validated by a certification authority. +However, this requires advanced system administration knowledge. +Indeed, due to the multitude of possible use cases, it is impossible to document all situations here. +This documentation will therefore only explain the goal to be reached, and give an example which will only be suitable for a "basic" situation (manual installation of Peertube, using letsencrypt). +If you are in another situation (Docker installation, certificates signed by another authority, etc...), you will have to adapt this approach by yourself. + +#### Basic principle + +It is up to you to generate valid certificates for domains `your_instance.tld` and `room.your_instance.tld`. +You can use any [method supported by Prosody](https://prosody.im/doc/certificates). + +You must then place these certificates in a folder that will be accessible to the `peertube` user, and specify this folder in the plugin setting "Certificate folder". + +{{% notice tip %}} +If you want to use the ProsodyCtl utility to import +certificates, this utility is available (once Peertube is started) using +the following command (adapting the path to your Peertube data folder, +and replacing "xxx" with the arguments you wish to pass to +prosodyctl): +`sudo -u peertube /var/www/peertube/storage/plugins/data/peertube-plugin-livechat/prosodyAppImage/squashfs-root/AppRun prosodyctl xxx` +{{% /notice %}} + +The plugin will check once a day to see if any files have been modified in this folder, and reload Prosody if necessary. + +#### Method for the simple case + +We assume here that your Peertube installation is "classic" (no use of Docker), and that the certificates are generated by letsencrypt, using the certbot tool. + +First of all, we'll have to create a certificate for the subdomain `room.your_instance.tld` : this is the uri of the +MUC (XMPP chat rooms) component. Even if the connections are made on `your_instance.tld`, we will need a valid certificate for this subdomain. + +So start by setting up a DNS entry for `room.your_instance.tld`, which points to your server. +You can use a CNAME entry (or an A entry and a AAAA entry). + +Next, we'll use nginx (already installed for your Peertube) to generate the certbot certificate. +We will create a new site. In the file `/etc/nginx/site-available/room.peertube`, add: + +```nginx +server { + listen 80; + listen [::]:80; + server_name room.your_instance.tld; + + location /.well-known/acme-challenge/ { + default_type "text/plain"; + root /var/www/certbot; + } + location / { return 301 https://votre.instance.tld; } +} +``` + +Then enable the site: + +```bash +ln -s /etc/nginx/sites-available/room.peertube /etc/nginx/sites-enabled/ +systemc reload nginx +``` + +Then we prepare the folder in which we will later import the certificates. +We assume here that you already have the plugin active. We will create the following folder (if it doesn't already exist), +with the user `peertube` to make sure there are no permissions issues: + +```bash +sudo -u peertube mkdir /var/www/peertube/storage/plugins/data/peertube-plugin-livechat/prosody/certs +``` + +Now you have to configure this folder in the plugin settings, for the parameter "Certificate folders". +It's important to do this now, otherwise the certificate import script will put the certificates in the wrong folder. + +We will configure certbot to import the generated certificates into the Prosody folder. +We can use the ProsodyCtl utility packaged in the plugin. + +Note: for it to be available, the plugin must have been started at least once. + +We will create a file `/etc/letsencrypt/renewal-hooks/deploy/prosody.sh` containing: + +```bash +#!/bin/sh +/var/www/peertube/storage/plugins/data/peertube-plugin-livechat/prosodyAppImage/squashfs-root/AppRun prosodyctl \ + --root \ + --config /var/www/peertube/storage/plugins/data/peertube-plugin-livechat/prosody/prosody.cfg.lua \ + cert import \ + room.your_instance.tld your_instance.tld /etc/letsencrypt/live + +chown peertube:peertube /var/www/peertube/storage/plugins/data/peertube-plugin-livechat/prosody/certs/* +``` + +Then we ask to generate the certificate: + +```bash +certbot -d room.videos.john-livingston.fr +``` + +If certbot offers you several methods to generate the certificate, choose "nginx". + +Normally you should now find the certificates in the configured folder. + +Note: the first time you do this, you will have to reload Prosody. The easiest way to do this is to restart Peertube. + ### Troubleshooting If you can't make it work, you can use the diagnostic tool diff --git a/support/documentation/content/documentation/admin/advanced/xmpp_clients.fr.md b/support/documentation/content/documentation/admin/advanced/xmpp_clients.fr.md index 03e301f7..790b51e4 100644 --- a/support/documentation/content/documentation/admin/advanced/xmpp_clients.fr.md +++ b/support/documentation/content/documentation/admin/advanced/xmpp_clients.fr.md @@ -57,16 +57,7 @@ de leur paramétrage. Dans ce cas, vous pouvez indiquer ici un chemin sur le serveur, dans lequel vous placerez des certificats à utiliser par le module. Charge à vous de les générer et de les renouveller. -Vous pouvez vous référer à la documentation de [Prosody](https://prosody.im/doc/certificates). - -{{% notice tip %}} -Si vous voulez utiliser l'utilitaire ProsodyCtl pour importer des certificats -letsencrypts, cet utilitaire est disponible (une fois Peertube démarré) en utilisant -la commande qui suit (en adaptant le chemin vers votre dossier data Peertube, -et en remplaçant «xxx» par les arguments que vous souhaitez passer à -prosodyctl): -`sudo -u peertube /var/www/peertube/storage/plugins/data/peertube-plugin-livechat/prosodyAppImage/squashfs-root/AppRun prosodyctl xxx` -{{% /notice %}} +Voir plus loin pour une explication plus détaillée. ### Pare-feu @@ -103,6 +94,115 @@ $ dig +short _xmpp-server._tcp.room.videos.john-livingston.fr. SRV 0 5 5269 videos.john-livingston.fr. ``` +### Utilisation de certificats de confiance + +Les certificats auto-signés que le plugin utilise par défaut peuvent ne pas convenir à tous les serveurs distants. +En effet, ceux-ci peuvent les refuser pour raison de sécurité. + +Il est possible d'utiliser des certificats validés par une autorité de certification. +Cependant cela demande des connaissances d'administration système avancées. +En effet, devant la multitude de cas possibles, il est impossible de documenter ici toutes les situations. +La présente documentation va donc se contenter de vous expliquer le but à atteindre, et donner un example +qui ne conviendra qu'à une situation «basique» (installation manuelle de Peertube, avec utilisation de letsencrypt). +Si vous êtes dans une autre situation (installation Docker, certificats signés par une autre autorité, etc...), il +vous faudra adapter la démarche. + +#### Principe de base + +À vous de générer des certificats valides pour les domaines `votre_instance.tld` et `room.votre_instance.tld`. +Vous pouvez utiliser n'importe quelle [méthode supportées par Prosody](https://prosody.im/doc/certificates). + +Vous devez ensuite placer ces certificats dans un dossier qui sera accessible au user `peertube`, puis indiquer +ce dossier dans le paramètre du plugin «Dossiers des certificats». + +{{% notice tip %}} +Si vous voulez utiliser l'utilitaire ProsodyCtl (pour importer des certificats +letsencrypts, générer des certificats, etc...), cet utilitaire est disponible +(une fois Peertube démarré) en utilisant la commande qui suit (en adaptant le chemin vers votre dossier data Peertube, +et en remplaçant «xxx» par les arguments que vous souhaitez passer à prosodyctl) : +`sudo -u peertube /var/www/peertube/storage/plugins/data/peertube-plugin-livechat/prosodyAppImage/squashfs-root/AppRun prosodyctl xxx` +{{% /notice %}} + +Le plugin va vérifier une fois par jour si des fichiers ont été modifiés dans ce dossier, et recharger Prosody le cas échéant. + +#### Méthode dans le cas simple + +Nous supposons ici que votre installation de Peertube est «classique» (pas d'utilisation de Docker), et que les +certificats sont générés par letsencrypt, en utilisant l'outils certbot. + +Tout d'abord, on va devoir créer un certificat pour le sous-domain `room.votre_instance.tld` : c'est l'uri du composant +MUC (salons de discussion XMPP). Même si les connections se font sur `votre_instance.tld`, il va nous falloir un +certificat valide pour ce sous-domaine. + +Commencez donc par paraméter une entrée DNS pour `room.votre_instance.tld`, qui pointe sur votre serveur. +Vous pouvez tout à faire faire une entrée CNAME (ou une entrée A et une entrée AAAA). + +Ensuite, nous allons utiliser nginx (déjà installé pour votre Peertube) pour générer le certificat certbot. +On va créer un nouveau site. Dans le fichier `/etc/nginx/site-available/room.peertube`, ajoutez: + +```nginx +server { + listen 80; + listen [::]:80; + server_name room.votre_instance.tld; + + location /.well-known/acme-challenge/ { + default_type "text/plain"; + root /var/www/certbot; + } + location / { return 301 https://votre.instance.tld; } +} +``` + +Ensuite on active ce site: + +```bash +ln -s /etc/nginx/sites-available/room.peertube /etc/nginx/sites-enabled/ +systemc reload nginx +``` + +On prépare ensuite le dossier dans lequel on va plus tard importer les certificats. +On suppose ici que vous avez déjà le plugin actif. On va créer le dossier suivant (s'il n'existe pas déjà), +avec le user `peertube` pour être sûr qu'il n'y a pas de problème de droits: + +```bash +sudo -u peertube mkdir /var/www/peertube/storage/plugins/data/peertube-plugin-livechat/prosody/certs +``` + +Il faut maintenant configurer ce dossier dans les paramètres du plugin, pour «Dossiers des certificats». +C'est important de le faire avant la suite, sinon le script d'import des certificats va les placer au mauvais endroit. + +On va configurer certbot pour qu'il importe les certificats générés dans le dossier de Prosody. +On va pouvoir utiliser l'utilistaire ProsodyCtl packagé dans le plugin. + +Note: pour qu'il soit disponible, il faut que le plugin ai démarré au moins une fois. + +On va créer un fichier `/etc/letsencrypt/renewal-hooks/deploy/prosody.sh` contenant: + +```bash +#!/bin/sh +/var/www/peertube/storage/plugins/data/peertube-plugin-livechat/prosodyAppImage/squashfs-root/AppRun prosodyctl \ + --root \ + --config /var/www/peertube/storage/plugins/data/peertube-plugin-livechat/prosody/prosody.cfg.lua \ + cert import \ + room.votre_instance.tld votre_instance.tld /etc/letsencrypt/live + +chown peertube:peertube /var/www/peertube/storage/plugins/data/peertube-plugin-livechat/prosody/certs/* +``` + +Puis on demande à générer le certificat : + +```bash +certbot -d room.videos.john-livingston.fr +``` + +Si certbot vous propose plusieurs méthodes pour générer le certificat, choisissez «nginx». + +Normalement vous devriez maintenant trouver les certificats dans le dossier configuré. + +Note: la première fois que vous faisez tout ça, il va falloir recharger Prosody. Le plus simple pour cela est de +redémarrer Peertube. + ### En cas de problème Si cela ne fonctionne pas, vous pouvez utiliser l'outils de diagnostic