Edge Shield pour Jellyfin — guide

Installation

Il vous faut Jellyfin Server 12.2 ou plus récent et un compte MediaLab Works avec une licence qui couvre le plugin (un abonnement actif, une licence à vie dans sa période de mises à jour, le pack Jellyfin ou l’essai gratuit de 30 jours).

Depuis votre dépôt de plugins (recommandé). Jellyfin installe alors le plugin et ses mises à jour tout seul.

Dans votre compte MediaLab Works, ouvrez Licences → Dépôt de plugins Jellyfin et cliquez sur Créer l’URL du dépôt. Copiez-la : elle est privée (elle contient un jeton), ne la partagez donc pas ; vous pouvez la régénérer ou la révoquer à tout moment.
Dans Jellyfin, ouvrez Dashboard → Plugins → Repositories, cliquez sur +, donnez un nom au dépôt (par exemple MediaLab Works), collez l’adresse et enregistrez.
Dans Dashboard → Plugins → Catalog, cherchez Edge Shield by MediaLab, cliquez sur Install, puis redémarrez Jellyfin.

Le dépôt ne liste que les plugins couverts par vos licences, et uniquement les versions qu’elles autorisent. Ses liens de téléchargement sont signés et expirent au bout de quelques heures, de sorte que Jellyfin lit toujours une liste à jour.

Depuis le catalogue public. https://medialab.works/jellyfin/manifest.json liste chaque plugin MediaLab Works publié avec sa version compilée publique ; medialab Server l’ajoute lui-même. Vous pouvez l’ajouter de la même manière pour installer un plugin avant d’avoir une clé : le plugin demande alors la licence, ou démarre l’essai, sur sa page License. Avec une licence à vie dont la période de mises à jour est terminée, restez sur votre dépôt privé, qui ne propose que les versions que votre licence autorise.

Manuellement, depuis un fichier zip.

Dans Compte → Licences, téléchargez jf-edgeshield_x.y.z.zip (le SHA-256 du fichier est indiqué à côté du bouton).
Extrayez-le dans un nouveau dossier Edge Shield by MediaLab_x.y.z.0 dans le dossier des plugins de Jellyfin :
- Linux (paquet) : /var/lib/jellyfin/plugins/
- Docker (image officielle) : /config/plugins/ dans le volume de configuration
- Windows : %ProgramData%\Jellyfin\Server\plugins\
Redémarrez Jellyfin.

Activation de la licence

Ouvrez la page du plugin dans Dashboard → Plugins → Edge Shield by MediaLab et cliquez sur License.
Collez votre clé de licence et cliquez sur Activate with key. Le plugin contacte le serveur de licences, lie la clé à ce serveur Jellyfin et affiche la licence comme Active.
Pas encore de clé ? Sur la même page, entrez votre e-mail et démarrez l’essai gratuit de 30 jours (carte requise, rien à payer aujourd’hui) ou achetez une licence ; le plugin s’active tout seul dès que le paiement est effectué.

La licence est vérifiée une fois par jour et à chaque démarrage de Jellyfin. Sans internet, le plugin continue de fonctionner pendant 7 jours après la dernière vérification réussie. Sans licence valide, le plugin cesse son travail et seule sa page License reste fonctionnelle (essai, clé, renouvellement) ; rien n’est supprimé et tout reprend dès que la licence redevient valide. Move license (release this server) sur la même page libère la clé pour un autre serveur.

Mises à jour et retour en arrière

Depuis le dépôt : Jellyfin affiche les nouvelles versions dans Dashboard → Plugins et peut mettre à jour le plugin automatiquement ; redémarrez Jellyfin pour charger la nouvelle version.
Depuis la page License du plugin : avec une licence valide, Install update installe la version la plus récente autorisée par votre licence et Roll back to x.y.z revient à la version précédente (par exemple si quelque chose a cessé de fonctionner après une mise à jour). Redémarrez Jellyfin après l’une ou l’autre opération. Les deux paquets sont vérifiés par rapport à la somme de contrôle publiée par le serveur de licences.
Une licence à vie reçoit les versions publiées pendant sa période de mises à jour ; ensuite, le plugin continue de fonctionner avec la dernière version qu’il est autorisé à utiliser.
Après un retour en arrière, si votre dépôt de plugins est ajouté dans Jellyfin, la tâche planifiée Update Plugins de Jellyfin (au démarrage et chaque jour) installe à nouveau la version la plus récente. Pour rester un moment sur la version précédente, retirez les déclencheurs de cette tâche dans Dashboard → Scheduled Tasks et rajoutez-les plus tard.

Code source

Le code source GPL-3.0 de chaque version se trouve dans Compte → Licences (Code source), à côté du téléchargement, sous forme d’archive .tar.gz créée à partir du commit exact de cette version.

Configuration

Connexion : dans Cloudflare, créez un jeton API (Create Token → Custom token), restreint à votre zone, avec les permissions listées par la page : Zone · Zone · Read, Zone · DNS · Edit, Zone · Zone Settings · Edit, Zone · SSL and Certificates · Edit, Zone · Zone WAF · Edit, Zone · Single Redirect · Edit, Zone · Cache Rules · Edit, Zone · Origin Rules · Edit et Account · Account Filter Lists · Edit. Collez-le, puis choisissez la zone (votre domaine). Le jeton est stocké chiffré sur le serveur et n’est plus jamais affiché ; une permission manquante est nommée sur la page d’état.
Mode :
- Recommandé : UI via Cloudflare, vidéo en direct (« stream offload »). L’hôte applicatif passe par le proxy Cloudflare ; les requêtes vidéo, audio et de téléchargement sont redirigées (307) vers l’hôte de streaming, en « DNS only », qui va directement à votre serveur.
- DNS only (sans proxy) : Cloudflare uniquement pour le DNS, le DDNS et le certificat. Les règles WAF et le blocage en périphérie ne s’appliquent pas, car le trafic ne passe pas par Cloudflare.
Noms et ports : l’hôte applicatif (par exemple media.example.com) avec le port HTTPS utilisé par vos clients (443, ou l’un des ports proxys de Cloudflare : 2053, 2083, 2087, 2096, 8443), le port externe que votre routeur redirige vers le serveur (s’il diffère, Edge Shield ajoute une origin rule) et l’hôte de streaming (par exemple direct.example.com) avec son port HTTPS externe. L’IPv4 publique est détectée quand le champ est vide ; le DDNS maintient les enregistrements à jour quand elle change.
Certificat du serveur : Let’s Encrypt automatiquement (DNS-01, avec le jeton) pour les deux noms, ou un certificat que vous gérez vous-même. Full (strict) nécessite un certificat valide sur le serveur. Le certificat est renouvelé 30 jours avant son expiration.
TLS : version TLS minimale et, en option, HSTS sur l’hôte applicatif (ne l’activez qu’une fois HTTPS fiable ; c’est difficile à annuler).
Protection : blocage automatique des IP avec des échecs de connexion (5 en 10 minutes et 24 heures par défaut, ×4 à chaque récidive), les IP ou plages CIDR à ne jamais bloquer, la limite de débit de connexion (plus de 10 requêtes en 10 s depuis une IP → blocage de 10 s), le blocage des en-têtes d’IP envoyés par les clients et les pays autorisés (codes ISO ; vide signifie tous). L’hôte de streaming n’accepte que les chemins médias (activé par défaut) : toute autre requête qui y arrive reçoit un 403.
Enregistrez, puis ouvrez Status and fixes et cliquez sur Fix everything, pour que les paramètres et les règles atteignent Cloudflare et Jellyfin. Redémarrez Jellyfin quand la page le demande (HTTPS, le certificat et les plages Cloudflare dans les proxies connus de Jellyfin prennent effet après un redémarrage ; les plages sont actualisées chaque jour et la page demande un redémarrage quand elles changent).

Utilisation quotidienne

La page d’état vérifie le jeton, les enregistrements DNS, les paramètres TLS, le certificat, les règles, la véritable IP client et HTTPS dans Jellyfin ; chaque problème a un bouton Fix.
Blocked IPs : la liste affiche l’adresse, la raison et l’expiration ; vous pouvez débloquer une IP ou en bloquer une à la main, avec une note et une durée. Votre réseau local, les plages Cloudflare et la liste d’autorisation ne sont jamais bloqués.
Under Attack : activez-le de 30 minutes à 12 heures pendant une attaque ; il se désactive tout seul. Tant qu’il est actif, les applications natives (Android TV, Roku, iOS, Kodi…) ne peuvent pas se connecter.
Restriction de port (pare-feu) : la page montre des commandes prêtes à n’autoriser que Cloudflare à atteindre le port de l’hôte applicatif ; Edge Shield ne touche jamais lui-même à votre pare-feu.
Remove the Edge Shield rules ne supprime que les règles créées par le plugin ; les paramètres DNS et TLS restent tels quels.

Ce qu’il envoie où

Vers Cloudflare, avec votre jeton : paramètres de zone, enregistrements DNS avec votre IP publique, règles et IP à bloquer. Le commentaire d’une entrée de liste de blocage ne contient que l’expiration et la raison (le nombre d’échecs de connexion, ou « manual » avec votre note). Depuis 0.1.1, le nom d’utilisateur tenté n’est pas envoyé à Cloudflare ; il reste dans la liste de blocage et le journal sur votre serveur.
https://www.cloudflare.com/cdn-cgi/trace pour détecter l’IP publique, et l’API publique de Cloudflare pour ses plages d’IP (chaque jour).
Vers Let’s Encrypt : la demande de certificat pour vos noms d’hôte ; la clé privée reste sur votre serveur.
Rien ne va vers medialab.works, hormis la vérification de la licence.

Dépannage

« The token lacks the … permission » : modifiez le jeton dans Cloudflare, ajoutez la permission indiquée et cliquez à nouveau sur Fix.
« Video would flow through the Cloudflare CDN » : l’hôte applicatif est en proxy mais aucun hôte de streaming n’est défini. Définissez un hôte de streaming (« DNS only ») ou passez en mode DNS only.
« The server’s public IP could not be detected » : saisissez l’IPv4 publique dans les paramètres.
Les applications ne peuvent pas se connecter : vérifiez que Under Attack est désactivé et que le port externe de l’hôte de streaming est redirigé vers le port HTTPS de Jellyfin.
Les changements n’apparaissent pas dans Jellyfin : la page d’état indique Restart needed ; redémarrez Jellyfin.