Overview
Install & usage
Changelog
Pricing

Edge Shield for Emby — guide

Installation

You need Emby Server 4.10.1 or newer.

  1. Sign in to your MediaLab Works account, open Licenses and download the plugin DLL (available on an active subscription, a lifetime license within its update window, or during the free 30-day trial).
  2. Copy the DLL into the Emby plugins folder and restart Emby Server:
    • Linux (package): /var/lib/emby/plugins/
    • Docker: the plugins folder inside your Emby config volume
    • Windows: %AppData%\Emby-Server\programdata\plugins\
  3. Open Edge Shield in the Emby dashboard menu and click License. Paste your license key and activate it, or enter your e-mail to start the free 30-day trial or buy a license. The plugin contacts the license server, binds the key to this Emby server and shows the license as Active.

The license is checked once a day (and at every Emby start). Without internet the plugin keeps working for 7 days after the last successful check; after that it is stopped until it can check again.

License

Without a valid license the plugin is stopped; only the License page keeps working (there you can start the trial, buy, enter the key or update).

With a valid license, the same page can install an update or roll back to the previous version if an update causes trouble. Restart Emby after either.

Configuration

  1. Connection: in Cloudflare create an API token (Create Token → Custom token), restricted to your zone, with the permissions the page lists: 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 and Account · Account Filter Lists · Edit. Paste it, then pick the zone (your domain). The token is stored encrypted on the server and is never shown again; a missing permission is named on the status page.
  2. Mode:
    • Recommended: UI through Cloudflare, video direct ("stream offload"). The app host goes through the Cloudflare proxy; video, audio and download requests are redirected (307) to the streaming host, which is "DNS only" and goes straight to your server.
    • DNS only (no proxy): Cloudflare only for DNS, DDNS and the certificate. WAF rules and edge blocking do not apply, because traffic does not pass through Cloudflare.
  3. Names and ports: the app host (for example media.example.com) with the HTTPS port your clients use (443, or one of the ports Cloudflare proxies: 2053, 2083, 2087, 2096, 8443), the external port your router forwards to the server (if it differs, Edge Shield adds an origin rule), and the streaming host (for example direct.example.com) with its external HTTPS port. The public IPv4 is detected when the field is empty; DDNS keeps the records up to date when it changes.
  4. Server certificate: Let's Encrypt automatically (DNS-01, with the token) for both names, or one you manage yourself. Full (strict) needs a valid certificate on the server. The certificate is renewed 30 days before it expires.
  5. TLS: minimum TLS version and, optionally, HSTS on the app host (turn it on only once HTTPS works reliably; it is hard to undo).
  6. Protection: automatic blocking of IPs with failed sign-ins (5 in 10 minutes and 24 hours by default, ×4 on every repeat), the IPs or CIDR ranges never to block, the login rate limit (more than 10 requests in 10 s from one IP → 10 s block), blocking of client-sent IP headers, and the allowed countries (ISO codes; empty means all).
  7. Save, then open Status and fixes and click Fix everything, so the settings and rules reach Cloudflare and Emby. Restart Emby Server when the page says so (HTTPS, certificate and forwarded-address settings take effect after a restart).

Daily use

  • The status page checks the token, the DNS records, the TLS settings, the certificate, the rules, the real client IP and HTTPS in Emby; each problem has a Fix button.
  • Blocked IPs: the list shows the address, the reason and the expiry; you can unblock an IP or block one by hand, with a note and a duration. Your LAN, the Cloudflare ranges and the allowlist are never blocked.
  • Under Attack: turn it on for 30 minutes to 12 hours during an attack; it turns itself off. While it is on, native apps (Android TV, Roku, iOS, Kodi…) cannot connect.
  • Port restriction (firewall): the page shows ready commands to let only Cloudflare reach the app host's port; Edge Shield never changes your firewall itself.
  • Remove the Edge Shield rules deletes only the rules the plugin created; DNS and TLS settings stay as they are.

What it sends where

  • To Cloudflare, with your token: zone settings, DNS records with your public IP, rules and the IPs to block. A block-list entry's comment holds only the expiry and the reason (the count of failed sign-ins, or "manual" with your note). Since 0.1.1 the attempted user name is not sent to Cloudflare; it stays in the block list and the log on your server.
  • https://www.cloudflare.com/cdn-cgi/trace to detect the public IP, and the public Cloudflare API for its IP ranges (daily).
  • To Let's Encrypt: the certificate request for your host names; the private key stays on your server.
  • Nothing goes to medialab.works except the license check.

Troubleshooting

  • "The token lacks the … permission": edit the token in Cloudflare, add the permission shown and click Fix again.
  • "Video would flow through the Cloudflare CDN": the app host is proxied but no streaming host is set. Set a streaming host ("DNS only") or switch to DNS only mode.
  • "The server's public IP could not be detected": enter the public IPv4 in the settings.
  • The apps cannot connect: check that Under Attack is off, and that the streaming host's external port is forwarded to Emby's HTTPS port.
  • Changes do not show in Emby: the status page says Restart needed; restart Emby Server.
Tell me when it is availableProducts