AIO Ep14. Solving Plugin/App Download Network Issues on Unraid Without Gateway Proxy

Introduction

Recently, I upgraded my HomeLab’s Unraid system to the latest 6.11.5 version (the previous cracking method no longer works — search online for new ones if needed). After running for about half a year, many plugins and Docker containers now require updates. However, GitHub’s accessibility has been getting worse lately, so addressing network issues during upgrades is necessary. Setting up a system-wide proxy on Unraid, however, is relatively complicated. Therefore, I’m documenting my current solution here.

Docker Container Update Method

For Docker, switching to a domestic mirror registry alone can resolve slow updates or WebUI freezes. But since Unraid doesn’t persist configuration files across reboots (they’re stored in ramfs), and numerous Docker services start automatically at boot, manually modifying configurations and restarting Docker can be cumbersome. To simplify this, add the following content to the beginning of the /boot/config/go file so that the registry mirror is configured at startup:

1
2
3
4
5
6

mkdir -p /etc/docker
tee /etc/docker/daemon.json <<-'EOF'
{
 "registry-mirrors" : ["https://hub-mirror.c.163.com", "https://mirror.baidubce.com"]
}
EOF

After this, updating Docker-based apps or custom Docker images should proceed smoothly without network issues.

Plugin Update Methods

Most plugins nowadays download files from raw.githubusercontent.com. Common workarounds found online involve setting a gateway-level proxy or modifying the emhttp startup command in /boot/config/go to include the HTTP_PROXY environment variable.

The downside of these methods is that changing network settings or environment variables is both tedious and inflexible — it usually requires shutting down all VMs and Docker containers. Moreover, such changes are invasive to the system.

Previously, editing the hosts file to access raw.githubusercontent.com worked, but even that method has become unreliable recently.

Inspired by the hosts modification approach, I came up with a better way to proxy specific websites.

1. Run the following bash script on any Linux machine accessible to Unraid (either on the public internet or local network). (Replace x.x.x.x:xxxx with a working SOCKS5 proxy.)

   1 2 3 4 5

   while : do echo Waiting for a new connection... ncat -l -p 443 -c "ncat --proxy-type socks5 --proxy x.x.x.x:xxxx raw.githubusercontent.com 443" done

2. Edit Unraid’s hosts file and add the following line, where a.b.c.d is the IP address of the machine running the script.

   1	a.b.c.d raw.githubusercontent.com

With this setup, all Unraid requests to raw.githubusercontent.com will be routed to a.b.c.d, where netcat forwards them through a SOCKS5 proxy to the actual destination. This way, the rest of Unraid’s network traffic remains unaffected.

The drawback? Each domain requires a dedicated IP — one machine can only proxy one domain this way. But for this use case, it’s more than sufficient. If you need to proxy other domains, just apply the same technique.

Side note: This method sparks an interesting idea. It could be extended — for example, on a mobile device (light usage, HTTP only), you could point a few domains to your own server via DNS or hosts. The server listens on port 443 and, based on the SNI field in the TLS ClientHello, forwards the entire TLS connection to the real destination. That way, you wouldn’t need to run a proxy client on the phone at all.