emby.wiki · DOCUMENTATION
Nginx-X Reverse Proxy Guide
Guides to Emby features, configuration, and usage.
🚀 Nginx-X Beginner's Guide#
Nginx-X is a lightweight Nginx management script that has been optimized extensively for reverse-proxying Emby connection lines. If your Emby service has poor direct-connection performance, using this script to create a relay on your own VPS is a good solution.
📥 Step 1: Install the Script#
Run this in the VPS terminal:
bash -c "$(curl -fsSL https://raw.githubusercontent.com/Xiuyixx/Nginx-X/main/install.sh)"
After installation, enter:
nx
to open the management menu.
🛠 Step 2: Install Nginx First#
The first time you open the menu, run:
Enter 1 → Install or Upgrade Nginx
The script will install or check Nginx automatically.
🌐 Step 3: Add the Emby Reverse Proxy#
Open the menu and proceed in this order:
Enter 2 → Configuration Management
Enter 2 → External Reverse Proxy
📖 Scenario A: You Have Only One Emby Address#
If the provider gave you only one address, choose:
Enter 2 → Stream mode
Example (prompts translated)#
========== Configuration Management ==========
1) Add Configuration
2) External Reverse Proxy
3) Configuration List
4) Import Existing Configuration
0) Return to the Previous Menu
==============================
Choose an option: 2
Enter the domain or local IP: your reverse-proxy entry domain
Enter the listening port: 443
Enter the external upstream URL: your Emby address
Choose a mode: 2
Suitable When#
- You have only one Emby address
- You do not want to study the routing rules yourself
- There is no frontend/backend separation, so you can use the address directly
🚀 Scenario B: You Have Multiple Addresses (Access Domain + Streaming Domain)#
If the provider gave you multiple addresses, choose:
Enter 5 → LilyEmby option
Example (prompts translated)#
Enter the domain: your reverse-proxy entry domain
Enter the listening port: 443
Enter the external upstream URL: https://access.example.com:443
Choose a mode: enter 5
Enter the streaming node URL: https://stream.example.com:443
Enter the public origin URL: https://access.example.com:443
Enter the Referer URL (default https://access.example.com:443/web/index.html):
Multiple streaming addresses are supported; separate them with ASCII commas.
What Should I Enter for Referer URL?#
Generally, you do not need to enter it manually. Press Enter to use the default value.
The default is usually:
https://access.example.com:443/web/index.html
What Does This Referer URL Do?#
In simple terms, it tells the origin server:
“This request appears to come from the Emby web client.”
Some origin servers, or a CDN or hotlink-protection system in front of them, check the Referer header. This value is useful when the origin expects requests to look as though they came from the Emby web page.
The script therefore fills in this default:
https://access.example.com:443/web/index.html
What Should You Do?#
Press Enter and use the default value ✅
When Should You Change It?#
Change it only if you later encounter one of these problems:
- A 403 response
- A hotlink-protection warning
- A playback API error
- A message such as
invalid referer
You can then try a more permissive or better-matching value, for example:
https://access.example.com/web/index.html
This removes the port.
If the provider's actual page path is not /web/index.html, you can also change it to the path the provider uses.
Recommendation for Beginners#
In this scenario, pressing Enter and using the default is the safest first step. Get it running first. Return and change it only if you actually encounter a 403 or a Referer error.
🔒 Step 4: Request a Certificate and Enable HTTPS#
If you entered 443 as the listening port, the script will generally ask whether to request a certificate automatically and enable HTTPS after configuration is complete.
Enter:
y
A typical prompt, translated into English, looks like this:
Request a certificate now and enable HTTPS (redirect port 80 to 443)? [y/N]: y
📧 Step 5: Enter an Email Address the First Time You Request a Certificate#
If this is the first time Nginx-X has requested a certificate on this machine, the script may ask you to set an Acme email address first.
You may see a prompt like this (translated into English):
[Warning] No Acme email address is currently configured. Enter an email address (it will be saved to /root/.config/nginxx/email.conf):
At this point, simply:
Enter an email address you regularly use.
What Is the Email Address Used For?#
The certificate-request tool uses it to retain the request information. The script saves the address for future use, so you generally do not need to enter it each time.
What Is the Easiest Choice for a Beginner?#
When prompted, enter a working email address of your own and press Enter.
What Happens Automatically Afterward?#
After you enter the email address, the script will generally continue with these tasks automatically:
- Save the email configuration
- Check DNS and HTTP-01 validation
- Install acme.sh if it is not already installed
- Request the certificate automatically
- Install the certificate in Nginx automatically
- Enable HTTPS automatically
- Configure the redirect from port 80 to port 443 automatically
- Check the renewal job automatically
In other words, you only need to enter the email address. In most cases, you can then continue by following the prompts.
🔍 Step 6: Using the Health Check and Understanding Its Results#
After configuration, use menu 4 → 3 Health Check to check the site status.
Checks include: the entry URL, HTTP status code, DNS, resolved IP, certificate days remaining, primary upstream status, streaming upstream status, and more.
⚠️ Note: A
403,404,abnormal, or similar result in the health check does not necessarily mean the configuration is wrong. Some Emby upstreams, or upstreams with hotlink-protection or CDN rules, intentionally block scripted web probes even though they work normally in a browser or client. Treat actual browser or client access as authoritative; the script result is only a reference.
✅ A Common Complete Workflow#
For a first-time setup, the usual flow can be summarized as:
Enter 2 → Configuration Management Enter 2 → External Reverse Proxy
Enter the domain: your reverse-proxy entry domain Enter the port: 443 Enter the external upstream URL: your Emby address Choose a mode:
- One address → enter 2
- Two addresses → enter 5
If asked whether to request a certificate and enable HTTPS → enter y If asked for an email address → enter your own email address If later prompts ask for confirmation, generally enter y
🧠 The Simplest Explanation#
Stream Mode#
All requests use the same address.
LilyEmby Mode#
- Web access uses the access domain
- Video playback uses the streaming domain
✅ What Should a Beginner Choose?#
- One address: enter 2 → Stream mode
- Multiple addresses: enter 5 → LilyEmby option
📎 Project Address#
For more information, see the project homepage: Xiuyixx/Nginx-X