restream-tools/scripts/nginx

nginx caching reverse proxy config

This is a good-enough example configuration for a caching reverse proxy for HLS live streams.

See it in action

# Download and compile a local version of nginx
$ ./build.sh

# Run the example configuration
$ ./run.sh

Once running, check out http://localhost:8080. By The example config proxies to restream.dev, so you should see a blank player page. Feel free to check out the restream.conf file and tune it to your liking.

The build script doesn't litter your system with random junk. When you're done you can just wipe the ./nginx folder.

Reverse proxying from existing nginx

If you don't wanna bother merging the config, you can just use your existing nginx to reverse-proxy to this one. It'd look something like this:

         your server
         ----------------------------------
         |                                |
viewer --|--> main nginx --> this nginx --|--> upstream
         |      w/ SSL                    |
         ----------------------------------

You can just do something like this:

location / {
    proxy_pass http://127.0.0.1:8080/;
}

Merging with your existing nginx

If you want to merge it with an existing nginx config, you can copy these directives to the http block:

• resolver and resolver_timeout (if you plan on using a domain name for the upstream)
• proxy_cache_path
• upstream

And then you can copy the server block in too. If you want to merge it with an existing server, you can just copy all the proxy_ directives. Note that it'll add caching to the whole server by default, so if you don't want that, you can change proxy_cache to off, and then in the location blocks where you do the reverse proxy, set proxy_cache back to restream_cache.

Feel free to tweak the parameters to fit your needs, but generally the values in restream.conf should just work alright for caching live streams.

Setting this up on a remote server

The convenience script remote_setup.sh can be used to ssh into a fresh remote server, install nginx there, configure the upstream and set up SSL. This should work on a fresh Ubuntu 20.04 server.

Run the script:

./remote_setup.sh \
  --domain relay1.stream.example.org \
  --upstream-server https://restream.dev:443 \
  --acme-email your.email@example.org \
  --target-server root@relay1.stream.example.org

Important note: you must specify the protocol (https://) and the port (:443) for the --upstream-server flag.

Once the script is done, your server should be accessible from https://relay1.stream.example.org and proxying all requests to https://restream.dev.

Example 2: setting up a relay for SPWN:

./remote_setup.sh \
    --domain relay1.stream.example.org \
    --upstream-server 'https://vod.spwn.jp:443' \
    --upstream-base '/spwn-archives/xxxxx/xxxx' \
    --acme-email acme@example.org \
    --target-server root@relay1.stream.example.org \
    --pass-header User-Agent '[user agent string]' \
    --pass-header Cookie '[redacted]' \
    --pass-header Referrer 'https://spwn.jp/'

Notes

• --upstream-server: Include the https:// in front and the :443 port number, and do not include a trailing /.
• --upstream-base: The rest of the URL before the index.m3u8 file. Start with a / but do not add a / at the end.