DiyMediaServer

Contains affiliate links. I may earn a commission at no cost to you.

Monitors That Measure What Your Users Experience

Monitor the public hostname, never the LAN IP. Only the public path exercises DNS, the reverse proxy, the tunnel, and the backend together, and that makes it the only check that can catch an outage your users would actually see.

My three monitors, and why each one exists:

Jellyfin Server (https://flix.example.com/), the thing people actually complain about.
Jellyseerr (https://request.example.com/), the request front end, because “I can’t add movies” is the second most common message I get.
Xfinity, a ping monitor aimed at a LAN-side target over the WireGuard tunnel. The name is my ISP’s, and that’s all it is: a WAN reachability check answering “is the internet at the house working” without publishing my home IP on a public page. This is the monitor that needs the tunnel. No tunnel, no third monitor.

Three monitors, not thirty. Every monitor on a public status page is a line item that anyone can read. Restraint here is a security decision as much as a design one.

For interval and retries, pick numbers that catch a real outage without paging you for a two-second blip. A 60 second interval with retries set to 2 or 3 before the notification fires is a reasonable starting point. Tune it after the first week of real data.

Beelink SER5 (Ryzen 5 5500U). A palm-sized mini PC with a 6-core/12-thread CPU that feels snappy for everyday work and homelab duties, handling Docker stacks, light VMs, and Jellyfin without guzzling power. With NVMe plus a 2.5″ bay, Wi-Fi 6, and multi-display output, it’s a quiet, tidy upgrade for desk or media setups.

Amazon Price: Loading...

Availability: Checking...

Contains affiliate links. I may earn a commission at no cost to you.

Building a Self-Hosted Status Page Worth Checking

In Kuma, go to Status Pages and create one published page. Mine uses the slug media, the title “Jellyfin Media Status”, and one group called Services holding the two monitors non-technical people care about.

Write the display names for humans. “Jellyfin Server”, not “jf-lxc-04 http 8096”.

What to leave off the page: hostnames, IP addresses, port numbers, internal service names, and anything else that reads like an inventory.

The payoff is one link sent to the family. Green means everything is up and running, red means it’s broken and I already know (don’t text me about it). The volume of text messages dropped immediately. A private dashboard only you can see would have done nothing for that.

Write down the slug. You need it for the Caddy config in the next section and again for restores. Rebuild Kuma from scratch with a different slug and the redirect and the allowlist both break.

The Caddy Allowlist That Keeps the Admin UI Off the Internet

This is the most important config in the post.

Uptime Kuma serves its admin dashboard and its public status page from the same port. Proxy the whole vhost and you’ve published the login form, the setup wizard, the Socket.IO endpoint, the upload directory, and the per-monitor badge API. The answer is an allowlist, not a blocklist: name the exact routes the status page needs, proxy only GET and HEAD on those, and 404 everything else at the proxy so it never reaches Kuma at all.

status.example.com {
 log {
 output file /var/log/caddy/status.access.log {
 roll_size 100mb
 roll_keep 5
 }
 format json
 }

 redir / /status/media

 @media_status {
 method GET HEAD
 path /status/media /status/media/ /status/media/rss /api/status-page/media /api/status-page/heartbeat/media /api/status-page/media/manifest.json /api/status-page/media/incident-history /assets/* /icon.svg
 }
 handle @media_status {
 reverse_proxy 127.0.0.1:3001
 }

 handle {
 respond 404
 }
}

Walking the pieces:

redir / /status/media exists because the bare root would otherwise fall through to the 404 handler.
method GET HEAD because a status page never needs to POST anything. Every write method dies at the proxy.
The explicit /api/status-page/* paths are how the page fetches its config, its heartbeats, its manifest, and its incident history. Miss one and the page renders but never updates.
The trailing handle { respond 404 } catches everything else: /dashboard, /socket.io/, /api/badge/*, /upload/*, any other status page slug, and every non-GET request.

Badges get denied for a specific reason: /api/badge/<id>/status leaks per-monitor state by numeric ID, including monitors that aren’t on the public page.

This allowlist fails closed. If a future Kuma release adds a route the status page needs, a page feature breaks and you notice immediately. A blocklist fails the other way: a new admin route appears and stays public until you happen to look at it. That asymmetry is why I reach for allowlists.

I audited this route list against the Kuma 2.4.0 status page router before deploying it. Re-audit on any major version bump, and write that down somewhere instead of trusting your memory.

One thing makes a path allowlist viable at all: the status page doesn’t need a websocket. Heartbeats arrive over REST. Verify it on your own instance before you trust me. Load the status page with browser devtools open and confirm the heartbeat bars populate with no websocket connection.

Connect Uptime Kuma to ntfy the Right Way

In Kuma, add a notification of type ntfy. The setting to get right is the server URL:

Server URL: http://ntfy (the container name on the shared compose network)
Topic: KumaUptime
Priority: high
Access token: the kuma-vps token you minted earlier
Set as default, apply to all existing monitors

Use the container name. The public URL is the tempting choice and the wrong one. Container-to-container means alerting still works when Caddy is down, when DNS is broken, when the certificate has expired, and when the entire lab has gone dark. There’s almost nothing left in the alert path that can fail on its own.

Hit Test and confirm the push lands on your phone before you move on. Don’t skip this. That exact assumption is how I ended up with two producers that had been dead for days.

Prove It, Do Not Assume It

Run every line of this from a machine that isn’t the VPS:

curl -sSI https://status.example.com/ | head -n 1 # 302 to /status/media
curl -sS -o /dev/null -w '%{http_code}\n' https://status.example.com/status/media # 200
curl -sS -o /dev/null -w '%{http_code}\n' https://status.example.com/dashboard # 404
curl -sS -o /dev/null -w '%{http_code}\n' https://status.example.com/socket.io/ # 404
curl -sS -o /dev/null -w '%{http_code}\n' https://status.example.com/api/badge/1/status # 404
nc -zv -w5 203.0.113.10 3001 # must NOT connect
curl -sS -o /dev/null -w '%{http_code}\n' -d "test" https://ntfy.example.com/KumaUptime # 403

About that nc line: both “Connection timed out” and “Connection refused” are passes. A timeout means a DROP-style firewall is swallowing the packet. A refusal means REJECT, or nothing listening on the public interface. Either way the port isn’t reachable. What you must never see is succeeded. If it connects, stop and fix that before you do anything else.

Then repeat the last curl with -H "Authorization: Bearer <token>" and confirm it returns 200.

💡

Tip: The real acceptance test: stop the Jellyfin container and confirm your phone buzzes. This is the exact failure the old topology could never report. If your phone stays quiet, something in the chain is broken. Head to the troubleshooting section below.

Raspberry Pi 5 (8GB) kit. A Pi 5 8GB board bundled with a case, an active cooler, and a screwdriver, which covers the cooling and enclosure you’d otherwise source separately. The board is the biggest generational leap in Pi history. A quad-core Cortex-A76 at 2.4 GHz gives it roughly twice the CPU performance of a Pi 4, with PCIe 2.0 via the new FFC connector for NVMe storage, a real power button, and a dedicated Raspberry Pi RP1 I/O chip. It still sips power and fits in your hand, but now handles heavier Docker workloads, Pi-hole plus Home Assistant simultaneously, and even light Jellyfin duties.

Amazon Price: Loading...

Availability: Checking...

Contains affiliate links. I may earn a commission at no cost to you.

Back Up Both SQLite Files, Because the VPS Is Not in Your Backup Plan

Two small databases now need to be part of your backup plan. kuma.db holds your monitors, the admin account, the status page slug and its uploaded assets, and the ntfy token. user.db holds every ntfy user, token, and ACL.

Stage one runs on the VPS. This script takes a WAL-safe online copy without stopping the container, tars it up with the config and compose file, and keeps 14 dated archives at mode 0640, because both databases contain recoverable secrets:

#!/bin/bash
set -euo pipefail
data_dir="/docker/uptime-kuma/data"
out_dir="/var/backups/kuma-vps"
date_stamp="$(date +%F)"
stage_dir="$(mktemp -d /root/.kuma-stage.XXXXXX)"
trap 'rm -rf "$stage_dir"' EXIT

mkdir -p "$out_dir" "$stage_dir/kuma"
chmod 0750 "$out_dir"

sqlite3 "$data_dir/kuma.db" ".backup '$stage_dir/kuma/kuma.db'"
cp -a "$data_dir/db-config.json" "$stage_dir/kuma/db-config.json"
[ -d "$data_dir/upload" ] && cp -a "$data_dir/upload" "$stage_dir/kuma/upload"
cp -a /docker/compose.yml "$stage_dir/kuma/compose.yml"

archive="$out_dir/kuma-$date_stamp.tar.gz"
tar -czf "$archive" -C "$stage_dir" kuma
chmod 0640 "$archive"

ls -1t "$out_dir"/kuma-*.tar.gz 2>/dev/null | tail -n +15 | xargs -r rm -f

The ntfy version is the same shape with different paths. Here it is in full, because the half of the pair that protects your auth tokens deserves better than “figure it out”:

#!/bin/bash
set -euo pipefail
data_dir="/docker/ntfy/var/lib/ntfy"
conf_dir="/docker/ntfy/etc/ntfy"
out_dir="/var/backups/ntfy-vps"
date_stamp="$(date +%F)"
stage_dir="$(mktemp -d /root/.ntfy-stage.XXXXXX)"
trap 'rm -rf "$stage_dir"' EXIT

mkdir -p "$out_dir" "$stage_dir/ntfy"
chmod 0750 "$out_dir"

sqlite3 "$data_dir/user.db" ".backup '$stage_dir/ntfy/user.db'"
[ -d "$conf_dir" ] && cp -a "$conf_dir" "$stage_dir/ntfy/etc"
cp -a /docker/compose.yml "$stage_dir/ntfy/compose.yml"

archive="$out_dir/ntfy-$date_stamp.tar.gz"
tar -czf "$archive" -C "$stage_dir" ntfy
chmod 0640 "$archive"

ls -1t "$out_dir"/ntfy-*.tar.gz 2>/dev/null | tail -n +15 | xargs -r rm -f

Both scripts call the host’s sqlite3 binary, so apt install sqlite3 on the VPS if it isn’t there. Schedule both in /etc/cron.d, offset by ten minutes so they never collide:

30 3 * * * root /usr/local/sbin/ntfy-backup.sh
40 3 * * * root /usr/local/sbin/kuma-backup.sh

Stage two pulls those archives to a machine at home that is inside your backup system:

15 4 * * * youruser rsync -a -e "ssh -i /home/youruser/.ssh/vps_key" youruser@203.0.113.10:/var/backups/ntfy-vps/ /home/youruser/backups/ntfy-vps/
25 4 * * * youruser rsync -a -e "ssh -i /home/youruser/.ssh/vps_key" youruser@203.0.113.10:/var/backups/kuma-vps/ /home/youruser/backups/kuma-vps/

No --delete on that rsync. A VPS-side deletion should never propagate into the copy you’re keeping.

Once a month, extract the newest pulled archive and check the database inside it:

cd /home/youruser/backups/kuma-vps
tar -xzf "$(ls -1t kuma-*.tar.gz | head -n 1)" -C /tmp
sqlite3 /tmp/kuma/kuma.db 'PRAGMA integrity_check;' # expect: ok

Anything other than ok means that archive is scrap and you fall back to the previous one. If the pulling box doesn’t have the sqlite3 CLI, Python’s bundled module does the same job:

python3 -c "import sqlite3;print(sqlite3.connect('/tmp/kuma/kuma.db').execute('PRAGMA integrity_check').fetchone()[0])"

Run the same check against the newest ntfy-*.tar.gz and /tmp/ntfy/user.db.

The failure signal here is archive age. A backup pipeline that silently stops looks identical to a healthy one right up until the day you need it. I added a check that pages the Backups topic when the newest pulled archive is missing or older than 26 hours.

And yes, that’s circular. If ntfy is down, ntfy can’t tell you its own backup failed. A stale archive is still the ultimate signal, which is why the monthly manual check stays on the calendar.

WD 14TB Elements Desktop External Hard Drive. A desktop external drive that packs 14 TB into a USB 3.0 enclosure, making it one of the cheapest ways to add bulk storage to a homelab or grab a large drive for shucking into a NAS. WD’s CMR recording on these capacities means solid sustained write speeds, and the wide compatibility with Windows, Mac, and Linux makes it an instant-plug backup target.

Amazon Price: Loading...

Availability: Checking...

Contains affiliate links. I may earn a commission at no cost to you.

Restoring Either Database on a Rebuilt VPS

A backup you’ve never restored isn’t a backup, it’s a hope. Rehearse this once while nothing is broken. The middle of an outage is the worst possible time to learn the procedure.

Copy the archive back to the VPS first, then restore Kuma:

docker compose stop uptime-kuma
tar -xzf /root/kuma-2026-07-16.tar.gz -C /tmp
cp /tmp/kuma/kuma.db /docker/uptime-kuma/data/kuma.db
cp /tmp/kuma/db-config.json /docker/uptime-kuma/data/db-config.json
rm -f /docker/uptime-kuma/data/kuma.db-wal /docker/uptime-kuma/data/kuma.db-shm
[ -d /tmp/kuma/upload ] && cp -a /tmp/kuma/upload/. /docker/uptime-kuma/data/upload/
docker compose start uptime-kuma

ntfy is the same dance:

docker compose stop ntfy
tar -xzf /root/ntfy-2026-07-16.tar.gz -C /tmp
cp /tmp/ntfy/user.db /docker/ntfy/var/lib/ntfy/user.db
rm -f /docker/ntfy/var/lib/ntfy/user.db-wal /docker/ntfy/var/lib/ntfy/user.db-shm
cp -a /tmp/ntfy/etc/. /docker/ntfy/etc/ntfy/
docker compose start ntfy

Stop only the affected service, never docker compose down. The compose file is shared, and a down takes both services out at once.

Now verify, because an unverified restore is the same as no restore:

docker exec -it ntfy ntfy user list # owner and publisher should both be there
docker exec -it ntfy ntfy access # per-topic write-only ACLs intact
curl --fail -sS -o /dev/null -w '%{http_code}\n' \
 -H "Authorization: Bearer <token>" -d "restore test" https://ntfy.example.com/KumaUptime # 200

For Kuma, open the SSH tunnel from earlier, log in with the restored admin account, and confirm your monitors are listed and the status page slug still reads media. That slug is the one thing a restore can quietly get wrong. Rebuild Kuma from scratch with a different slug and the Caddy allowlist 404s the public page for everyone, while your dashboard looks perfect.

Troubleshooting

Status page loads but never updates.
- A heartbeat API path is missing from the allowlist. Check the Caddy access log for 404s on /api/status-page/heartbeat/<slug>.
ntfy subscriptions hang or messages arrive in bursts.
- Missing flush_interval -1 on the reverse proxy. Server-sent events are being buffered.
Publishes return 403 and nothing arrives.
- The Authorization header is missing the Bearer prefix, or the token’s ACL is scoped to a different topic than the one you’re publishing to.
Certificate issuance fails on the first deploy.
- The DNS record doesn’t resolve yet. HTTP-01 can’t validate a name with no A record.
Port 3001 answers from outside despite a default-drop firewall.
- The port is published on 0.0.0.0. Docker’s forwarding rules bypass the INPUT chain. Fix the bind, not the firewall.
Message history vanished after a container update.
- In-memory cache, working as configured. Set NTFY_CACHE_FILE if you want history to survive restarts.
A restored Kuma starts empty or throws SQLite errors.
- Leftover kuma.db-wal and kuma.db-shm from the previous database. Stop the container, delete both, start it again.
Caddy reload hangs after adding a new vhost.
- Mine hung for 30 minutes. Root cause: I ran caddy validate as root. Validation provisions the config, which created the new vhost’s access log owned root:root 0600. The caddy service user couldn’t open that file, the real reload never completed, and the systemd unit sat in a stale reloading state. Fix the ownership on /var/log/caddy/<site>.access.log, then run caddy reload --force. Validate as the caddy user from now on.
A major Kuma version bump breaks the status page.
- That is the fail-closed allowlist behaving correctly. Re-audit the route list against the new release and add the paths the page now needs.

Frequently Asked Questions

➤ Do I really need a VPS? Can't I use a second machine at home?

A second box at home shares your power, your ISP, and your router. That’s the same failure domain, and it can’t report the outages that matter most. A VPS in another data center shares fate only with your public front door, which is exactly the isolation you’re paying for.

➤ Is a public status page a security risk?

Only in proportion to what you put on it. Use human-friendly monitor names instead of hostnames, and keep the monitor count small. My published page lists two services by friendly name and nothing else that resembles an inventory.

➤ Why ntfy instead of Discord, Telegram, or email?

It’s self-hosted, so no third party sits in the alert path. Tokens are per-producer and individually revocable, ACLs can be write-only, and Uptime Kuma reaches it over the container network. Alerts still fire when DNS, Caddy, and the entire lab are down.

➤ Can I keep ntfy private instead of exposing it publicly?

You can, but then your phone only receives alerts while on your own network, which defeats the purpose. Publishing it behind Caddy with deny-all auth and write-only producer tokens gives you off-network delivery without opening topics to anonymous readers. That combination is what makes public exposure defensible here.

➤ What happens if my VPS provider has an outage?

Your monitoring goes dark. That’s a real limitation of any single-provider design. For most homelabs it’s an acceptable trade, since provider outages are rarer than lab outages. If uptime reporting is critical to you, add a second lightweight monitor with a different provider in a different region.

Wrapping Up

Your phone gets the alert. Your users get a URL. Neither one depends on the lab being alive.

The security posture, all of it: loopback binds instead of published ports, a Caddy allowlist that fails closed, an SSH tunnel for admin access, write-only per-producer tokens, and nothing on the public page that reads like an inventory.

Monitoring hosted inside the thing it monitors is a nice dashboard. It isn’t a monitoring system.

Next steps once this is running: point fail2ban at ntfy so SSH bans on the VPS push to your Security topic, add your backup job outcomes as another producer, and put the status page link on the household dashboard so people find it before they find your phone number.

Sources

Uptime Kuma project and documentation: https://github.com/louislam/uptime-kuma
ntfy documentation (auth, ACLs, tokens, reverse proxy notes): https://docs.ntfy.sh/
Caddy documentation (matchers, handle, reverse_proxy, automatic HTTPS): https://caddyserver.com/docs/
Docker Compose file reference (port publishing and bind addresses): https://docs.docker.com/reference/compose-file/

NPM to Caddy: Reverse Proxy Dozens of Containers

Fri, 03 Jul 2026 08:44:43 -0600

8 years ago Nginx Proxy Manager was the right call. It was the first way I ever learned how to set up a reverse proxy on my home network without touching a line of Nginx syntax. Point at a container, tick a box for a Let’s Encrypt cert, and ten minutes later sonarr.example.com resolved with a padlock. For the first handful of services it felt like magic.

Several years later, at 31 services, it had become too much to manage through a web UI.

I wanted to add one security header across every proxy host, and I realized that meant opening the same web form 31 times. That was the day I went looking for an effective way to reverse proxy many services without a database standing between me and my own config. The answer was Caddy. This post is the honest case for switching, the actual migration path I took, and the Caddy patterns that make 31 subdomains manageable from a terminal.

💭

TL;DR: Nginx Proxy Manager is a great first reverse proxy, but its web UI and SQLite backend become a liability once you run dozens of internal services. Caddy replaces all of it with one text file plus wildcard TLS via DNS-01.

I ran this migration on Caddy 2.11.4 with the Cloudflare DNS module added via caddy add-package, running in an unprivileged Debian 13 LXC on Proxmox 9.2.3. Every config block below is lifted from the Caddyfile that now manages subdomains and TLS for my whole lab, with the domain and email swapped for placeholders.

What Nginx Proxy Manager Gets Right

Before we go too far, I want to give credit where it’s due. NPM is the best on-ramp to reverse proxying that exists, and if you’re happy with it, nothing here should push you off it.

It teaches the concepts without the syntax.
- Proxy host, upstream, forward port, SSL cert. NPM’s UI makes those ideas concrete before you ever have to write an Nginx location block.
Certificates are automatic and visible.
- You request a Let’s Encrypt cert from a dropdown, and the renewal status sits right there in the interface.
It is genuinely fast to start.
- Three to five services, a couple of subdomains, no need for wildcard certs or bulk edits. NPM does that job in ten minutes and never gets in your way.

I outgrew NPM. That’s a different statement from “NPM is bad.” If you run a small lab and prefer a GUI to a text file, stay there. The pain I’m about to describe only shows up at scale.

Where It Started to Hurt

The 31-form marathon was the last straw. What made me leave was everything underneath it.

Start with backups. The entire proxy layer for my homelab lived inside a SQLite database. I couldn’t read the config as a text file. Nor could I restore a single host. My backup plan amounted to copying the volume and praying, and a rebuild meant restoring a blob of data and hoping the current version still liked the format.

Then there is the moving-parts problem. To write a proxy config that I would never get to read, NPM runs an Nginx instance, a Node.js admin app, and a SQLite database file underneath both. That’s a lot of machinery stacked up to manage text I have no direct access to. As someone who values fewer moving parts, that math stopped adding up.

And there’s no escape from the web UI. There’s no way to bulk edit or find-and-replace. Every change is you, the mouse, and a browser form. None of this is a knock on NPM. It’s the difference between a tool built for point-and-click simplicity and a lab that has grown into wanting a simple way to manage a reverse proxy.

The Intel NUC 12 Pro A compact "Wall Street Canyon" mini PC with a 12th-gen Core i5-1240P and Iris Xe that can drive up to four displays (dual Thunderbolt 4 + dual HDMI), plus 2.5GbE and Wi-Fi 6E. The H-chassis adds a 2.5″ bay alongside NVMe storage and up to 64GB RAM, making it a quiet, versatile homelab node or HTPC/office box.

Amazon Price: Loading...

Availability: Checking...

Contains affiliate links. I may earn a commission at no cost to you.

The Caddy Way: One Text File

The core of this whole migration fits in one sentence. My entire proxy layer is now a single Caddyfile that I can grep, diff, and edit over SSH in seconds.

That single change fixes everything that was a pain above:

Bulk changes take one edit.
- Change a shared snippet once and every site that imports it updates. The 31-form marathon becomes a one-line change.
Backups are a file.
- No database dump, no volume snapshot alignment. The Caddyfile is the backup.
You can dry-run before you apply.
- caddy validate --config /etc/caddy/Caddyfile catches syntax errors before they hit production. The web UI never gave me a preview.

The thing that makes this scale is snippets and import. In Caddy, a snippet is a named block of config you define once and pull into any site. Here is the pattern that lets a host config fit on one screen. My standard HTTP upstream is one snippet:

# Standard HTTP upstream. reverse_proxy passes the Host header through by
# default, so no header_up Host is needed.
(proxy) {
 encode gzip
 reverse_proxy {args[0]} {
 header_up X-Real-IP {client_ip}
 }
}

With that defined, every ordinary service becomes a three-line block:

sonarr.example.com {
 import proxy http://192.168.1.13:8989
}

radarr.example.com {
 import proxy http://192.168.1.13:7878
}

Those upstreams are Docker containers on another host. This is what a Caddy proxy looks like when the proxy itself lives outside Docker: you point reverse_proxy at the container’s IP and port, and the container never has to know Caddy exists. Compare that to the NPM equivalent: two proxy hosts, each requiring a domain field, a scheme dropdown, a forward hostname, a forward port, an SSL tab, and a websocket checkbox, all entered by hand through a browser. The Caddyfile version is git commit-ready and readable at a glance.

This Raspberry Pi 5 (8GB) kit bundles the board with a case, an active cooler, and a screwdriver, which covers the cooling and enclosure you’d otherwise source separately. The board is the biggest generational leap in Pi history. A quad-core Cortex-A76 at 2.4 GHz gives it roughly twice the CPU performance of a Pi 4, with PCIe 2.0 via the new FFC connector for NVMe storage, a real power button, and a dedicated Raspberry Pi RP1 I/O chip. Still sips power and fits in your hand, but now handles heavier Docker workloads, Pi-hole plus Home Assistant simultaneously, and even light Jellyfin hosting duties.

Amazon Price: Loading...

Availability: Checking...

Contains affiliate links. I may earn a commission at no cost to you.

The Setup: Caddy in a Proxmox LXC with a Wildcard Cert

I run Caddy as a plain binary in a dedicated Proxmox LXC, not in Docker. The reasoning is deliberate. The proxy is infrastructure, so I want to run it with the fewest possible moving parts. An LXC with an apt-installed binary is trivially snapshotted by Proxmox, and there’s no Docker layer wrapping the one service that everything else depends on.

Create the container and install Caddy

Spin up an unprivileged Debian 13 LXC, give it a static IP on your LAN, and make sure ports 80 and 443 are reachable. Then install Caddy from the official repository:

sudo apt install -y debian-keyring debian-archive-keyring apt-transport-https curl
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/gpg.key' | sudo gpg --dearmor -o /usr/share/keyrings/caddy-stable-archive-keyring.gpg
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/debian.deb.txt' | sudo tee /etc/apt/sources.list.d/caddy-stable.list
sudo apt update
sudo apt install caddy

That gets you a running Caddy with a systemd config already enabled and started. Confirm it with systemctl status caddy.

There is one wrinkle that trips up almost everyone. The stock Caddy binary doesn’t include DNS provider modules. To solve TLS challenges through Cloudflare DNS (the DNS-01 method), you need a build that includes the caddy-dns/cloudflare module. Every guide on the internet will tell you to compile one with xcaddy and a Go toolchain. You don’t need any of that. Caddy can replace its own binary with one that has the module baked in:

sudo caddy add-package github.com/caddy-dns/cloudflare

That one command grabs the latest Caddy release with the Cloudflare module baked in and swaps it into place at /usr/bin/caddy. Restart the service, then confirm the module is present with caddy list-modules | grep cloudflare.

There’s a catch, and it’s worth fixing now rather than discovering it at renewal time. The binary on disk no longer matches what apt installed, so the next apt upgrade of the caddy package quietly puts the stock module-less binary back, and certificate renewals start failing weeks later. The fix is to keep the package for its systemd unit, caddy user, and default config, but take the binary out of apt’s hands:

sudo apt-mark hold caddy

A held package is never upgraded by apt. From now on, updates come from Caddy itself:

sudo caddy upgrade
sudo systemctl restart caddy

caddy upgrade replaces the binary with the latest release with the same modules installed, so the Cloudflare module survives every update, which is exactly the promise apt couldn’t make. The tradeoff is that Caddy updates are now your job instead of unattended-upgrades’ job, so check caddy version against the releases page once in a while. If you ever want apt back in charge, sudo apt-mark unhold caddy reverses it.

Wildcard TLS via DNS-01

This is the piece that makes many internal subdomains painless. With a DNS-01 challenge, Caddy proves it owns a name by writing a temporary TXT record through the Cloudflare API, so nothing has to listen on port 80 to the public internet. That matters for LAN-only services, because Let’s Encrypt could never reach them over HTTP-01 anyway.

Left alone, Caddy would request a separate certificate for every site block that way. I don’t let it, for a privacy reason that is easy to miss: every certificate ever issued is published to public Certificate Transparency logs, so per-subdomain certs put the name of each internal service into a searchable public index (look your domain up on crt.sh sometime). One wildcard certificate for *.example.com avoids that. The logs show the wildcard entry and nothing else, and outsiders learn nothing about what actually runs in the lab.

Since Caddy 2.10, getting the wildcard takes no special option. If the Caddyfile contains a wildcard site block, every subdomain site it covers automatically shares that block’s certificate instead of requesting its own. So this short block sits near the top of my Caddyfile:

# Holds the *.example.com wildcard cert; every subdomain block shares it.
# Also catches requests for subdomains that don't exist.
*.example.com {
 abort
}

The abort means any subdomain you never defined gets its connection closed instead of a blank page. And don’t delete this block once you rely on it: remove it and Caddy quietly goes back to issuing individual certs, and your hostnames start leaking into CT logs again. (On Caddy 2.8 and 2.9 the same behavior needed the auto_https prefer_wildcard global option; 2.10 made it the default and removed the option.)

The other half of the story is plain DNS. Certificates prove who a host is; something still has to point sonarr.example.com at the proxy in the first place. That happens entirely inside the LAN: add one wildcard record (*.example.com pointing at the Caddy LXC’s IP) to your local resolver, Pi-hole in my case, and every subdomain resolves to Caddy without you ever touching DNS again. No public A records are needed at all. DNS-01 only ever creates that short-lived TXT record at Cloudflare, so the public internet never learns where your hosts live.

First, create a scoped Cloudflare API token. In the Cloudflare dashboard, go to My Profile, then API Tokens, and create a token with Zone > DNS > Edit permission limited to the zone you use for the lab. Copy the token, because Cloudflare only shows it once.

Store it where Caddy’s systemd unit can read it, out of the Caddyfile itself, in /etc/caddy/caddy.env:

CLOUDFLARE_API_TOKEN=your-scoped-token-here

That file holds a live credential, so lock it down: sudo chmod 600 /etc/caddy/caddy.env.

Then point Caddy’s global options block at it. This block is set once and forgotten:

{
 email admin@example.com
 acme_dns cloudflare {env.CLOUDFLARE_API_TOKEN}
 servers {
 trusted_proxies static 10.10.10.0/24
 }
}

The email line is your ACME account contact. acme_dns cloudflare tells Caddy to solve every challenge through Cloudflare DNS, which is what unlocks real certificates for LAN-only hosts. The servers block is only there because another proxy sits in front of this one for external traffic: my WireGuard VPS tunnel forwards public requests over the tunnel subnet, and trusted_proxies tells Caddy to believe the client IP headers that edge proxy sends instead of logging every external visitor as the tunnel address. If nothing forwards traffic to your Caddy, drop the servers block.

That {env.CLOUDFLARE_API_TOKEN} placeholder only works if the token is in Caddy’s environment when systemd starts the service, which means the unit needs an EnvironmentFile= line pointing at /etc/caddy/caddy.env. Do not add it by editing the packaged unit file directly. The next apt upgrade of the caddy package will replace /lib/systemd/system/caddy.service and silently throw your change away. The clean way is a systemd drop-in: a small override file in /etc/systemd/system/caddy.service.d/ that systemd merges on top of the packaged unit, and that survives package upgrades untouched. Mine lives at /etc/systemd/system/caddy.service.d/env.conf:

sudo mkdir -p /etc/systemd/system/caddy.service.d
sudo tee /etc/systemd/system/caddy.service.d/env.conf > /dev/null <<'EOF'
[Service]
EnvironmentFile=/etc/caddy/caddy.env
EOF
sudo systemctl daemon-reload
sudo systemctl restart caddy

Confirm the token actually made it into the service with systemctl show caddy | grep CLOUDFLARE.

This mini workstation built around a 16-core Ryzen 9 9955HX, with dual 10GbE SFP+ plus dual 2.5GbE, flexible storage (U.2 + M.2 including 22110), and triple 8K display outputs. It is ideal for running Proxmox and hosting Caddy as a reverse proxy in a homelab, offering high core counts and robust networking for managing many internal subdomains.

Amazon Price: Loading...

Availability: Checking...

Contains affiliate links. I may earn a commission at no cost to you.

The Migration Itself

The mapping from NPM to Caddy isn’t too bad once you see it. An NPM proxy host becomes a Caddy site block. The forward hostname and port become the argument to reverse_proxy. Any custom Nginx snippet you bolted on becomes a named directive inside the block.

Before writing any site blocks, get the full host list out of NPM. The config that lived in a database you could never read is one query away from becoming a migration checklist. The file is database.sqlite in NPM’s data volume:

sqlite3 database.sqlite "SELECT domain_names, forward_scheme, forward_host, forward_port FROM proxy_host WHERE is_deleted = 0;"

Every row is a site block you are about to write: domain, scheme, upstream IP, and port. Mine came out to 31 lines, and that printout became the cutover checklist.

The order that avoids downtime matters. Here is what I did, and it kept the lab online the whole way:

Stand up Caddy in parallel on its own IP while NPM keeps running untouched.
Move subdomains over in batches by repointing internal DNS one service at a time. Test each one before moving the next.
Keep NPM as the fallback until zero hosts point at it.
Decommission NPM and, if you like, hand its old IP to the Caddy container so nothing downstream notices.

📝

Note: If you change Caddy’s IP make sure you also change the DNS entries.

Per service, the cutover felt trivial: type a four-line block and run caddy reload, and refresh the browser.

Don’t bother revoking NPM’s old Let’s Encrypt certificates. Once your Caddy wildcard cert is issued and serving traffic, the NPM certs are dead weight. Leave them to expire on their own. There is no security benefit to revoking a cert nobody is presenting anymore, and revocation is one more manual step at the exact moment you want to be decommissioning, not fiddling about.

The gotchas I hit

Websockets. In NPM this was a checkbox you had to remember to tick. In Caddy, reverse_proxy upgrades websockets automatically, so most apps work with no extra directives.
Access Lists. If you leaned on NPM’s Access Lists, both halves have direct Caddy equivalents: an IP allowlist becomes a remote_ip matcher (@outside not remote_ip 192.168.1.0/24 followed by abort @outside), and basic auth becomes the basic_auth directive fed a hash from caddy hash-password.
Streaming and server-sent events. A few apps (ntfy, my search backend) buffer badly behind a default proxy. Caddy fixes it with flush_interval -1 to disable response buffering. I keep that in a separate snippet:

# Streaming upstream: disable response buffering.
(proxy_flush) {
 encode gzip
 reverse_proxy {args[0]} {
 header_up X-Real-IP {client_ip}
 flush_interval -1
 }
}

HTTPS upstreams like Proxmox and PBS. Most services behind the proxy speak plain HTTP, but Proxmox (port 8006) and Proxmox Backup Server (8007) terminate their own TLS, so Caddy has to make an HTTPS connection to the backend instead. The catch is that my Caddyfile points at them by IP address. During the TLS handshake, Caddy would send that IP as the server name (SNI), the upstream would answer with a certificate issued for its hostname, and Caddy would reject the mismatch with an error like certificate is valid for pve01.example.com, not 192.168.1.2. The fix is tls_server_name, which tells Caddy which hostname to send as SNI and to verify the upstream’s certificate against. In this snippet that hostname comes in as the second argument:

# HTTPS upstream with a real ACME cert (Proxmox, PBS). Caddy calls by IP, so
# args[1] supplies the cert hostname for SNI + verification.
(proxy_tls) {
 encode gzip
 reverse_proxy {args[0]} {
 header_up X-Real-IP {client_ip}
 transport http {
 tls_server_name {args[1]}
 }
 }
}

A Proxmox node then reduces to import proxy_tls https://192.168.1.2:8006 pve01.example.com.

One stubborn upstream. My OPNsense box runs lighttpd, which negotiates HTTP/2 via ALPN, and HTTP/2 cannot carry websocket upgrades. I had to pin that single hop to HTTP/1.1 with versions 1.1 inside its transport block. That’s the kind of one-off you write inline rather than in a shared snippet:

# OPNsense: lighttpd negotiates HTTP/2 over ALPN, and HTTP/2 cannot carry
# websocket upgrades. Pin this one hop to HTTP/1.1.
opnsense.example.com {
 encode gzip
 reverse_proxy https://192.168.1.1:443 {
 header_up X-Real-IP {client_ip}
 transport http {
 tls_server_name opnsense.example.com
 versions 1.1
 }
 }
}

Advanced Topics

Once the basics work, Caddy has depth that NPM never exposed.

The admin API. Caddy ships a JSON admin API on localhost:2019.

❌

Danger: Read this before you touch it: this API can replace your entire running configuration in less than a second. Not one host. All of it. Anyone who can reach localhost:2019 can wipe or rewrite every proxy you run, so it must never be exposed to the network as-is.

The saving grace is that a stock install binds the admin endpoint to localhost:2019 only, so nothing on your network can reach it until you deliberately publish it. If you need a piece of it, for example so a dashboard can poll upstream health, publish only the read-only path and lock it to your LAN:

:2020 {
 @upstreams {
 path /reverse_proxy/upstreams
 remote_ip 192.168.1.0/24
 }
 handle @upstreams {
 reverse_proxy localhost:2019 {
 header_up Host localhost:2019
 }
 }
 handle {
 respond 403
 }
}

That block publishes only /reverse_proxy/upstreams to the LAN and returns 403 for everything else. The full config-replacement endpoints on 2019 stay bound to localhost, unreachable from the network. Copy this pattern exactly. Do not widen the path matcher to the whole API “for convenience,” because that convenience is a remote config wipe waiting to happen.

Matchers for traffic control. The @upstreams name above is a matcher. Matchers route by path, header, source IP, or method. Send one URL prefix to one backend and everything else to another, all inside a single site block.

Custom headers and security. Shared security headers belong in a snippet you import everywhere, so a policy change is a one-line edit across all 31 hosts:

(security_headers) {
 header {
 Strict-Transport-Security "max-age=31536000"
 X-Frame-Options "SAMEORIGIN"
 X-Content-Type-Options "nosniff"
 }
}

Add import security_headers next to the import proxy line in each site block. One caution before you copy that: HSTS orders browsers to refuse plain HTTP for the whole max-age window, so a broken cert locks you out of any HTTP fallback until it’s fixed. Use a short max-age like 3600 while testing and raise it once everything is stable.

Logs. NPM showed per-host access logs in its UI. Caddy logs to the systemd journal by default, and adding a log directive inside any site block turns on structured access logs for that host. Put it in a shared snippet if you want it everywhere, and read the results with journalctl -u caddy.

Troubleshooting

caddy reload fails. Run caddy validate --config /etc/caddy/Caddyfile first. It reports the exact line for missing snippet names, unbalanced braces, or a bad directive before anything goes live.
The wildcard cert never issues, ACME DNS errors in the log. This is almost always the Cloudflare token. Confirm the module is compiled in with caddy list-modules | grep cloudflare, verify the token has Zone:DNS:Edit on the right zone, and check that the environment variable is actually loaded (systemctl show caddy | grep CLOUDFLARE). If you are stuck, temporarily drop acme_dns and test one public host over HTTP-01 to isolate whether the break is DNS or networking.
Issuance hangs at “waiting for DNS propagation”. This one bites homelabs specifically. Before asking Let’s Encrypt to validate, Caddy checks that the TXT record is visible, and it does that through the system resolver. If your LXC’s resolver is your own split-horizon DNS, the one that answers for the lab domain locally, that check may never see the public record. Point the challenge at a public resolver by swapping the acme_dns one-liner for the fuller issuer form:

{
 email admin@example.com
 cert_issuer acme {
 dns cloudflare {env.CLOUDFLARE_API_TOKEN}
 resolvers 1.1.1.1
 }
}

Proxy works from outside but not inside, or the reverse. This is a DNS resolution mismatch. Internal subdomains need consistent resolution, so point your local resolver (or split-horizon DNS) at the Caddy IP for the wildcard record.
App loads but shows the wrong client IP. If clients reach Caddy directly, the fix is the header_up X-Real-IP {client_ip} line in the snippet the site imports. If another proxy forwards traffic to Caddy, as my VPS edge does, its subnet must be listed under trusted_proxies in the global block, or Caddy ignores the forwarded headers and every visitor shows up as the proxy’s own IP.
A service loses websockets after cutover. Confirm the upstream is not being forced to HTTP/2. Pin that hop to versions 1.1 inside the transport http block, as with the OPNsense example above.

Frequently Asked Questions

➤ Is Caddy harder to learn than Nginx Proxy Manager?

The first site block is harder than clicking through NPM, because you write text instead of filling a form. After that Caddy is easier. Once you have a working snippet, adding a service is a three-line block you copy and edit.

➤ Do I need to open port 80 or 443 to the internet for certificates?

No. With a DNS-01 challenge, Caddy proves domain ownership through your DNS provider’s API instead of an inbound HTTP request. That means you can issue real, trusted certificates for LAN-only services that the public internet can never reach.

➤ Why Caddy and not Traefik for many Docker services?

Traefik’s strength is Docker label discovery, which fits an all-Docker host well. My lab is mixed LXC, VM, and Docker, so a central Caddyfile with explicit upstreams is cleaner for me than labels scattered across hosts. Both are solid; the model fit my layout better.

➤ Can I manage the Caddyfile in git and reload safely?

Yes, and this is the main payoff. Commit the Caddyfile to a private repo, run caddy validate to catch errors, then caddy reload to apply with zero downtime. Every change is diffable and revertible, which no GUI-driven proxy gives you.

➤ Does a reverse proxy make my services secure?

Not on its own. A reverse proxy is not a firewall, despite how often it gets framed that way on Reddit. It terminates TLS and routes traffic. Real security is defense in depth: a firewall, network segmentation, authentication, and keeping services patched.

The Takeaway

The switch had nothing to do with performance or features. Both proxies serve pages fine, and neither one is going to bottleneck a homelab. What changed was ownership of the config. It went from a database I had to visit through a browser to a file I own and can read.

At five services, NPM’s web UI is a convenience. A few dozen or more and it becomes a liability. Caddy gave me the most effective way to reverse proxy many Docker and LXC services on one system: bulk edits in seconds, config tracked in git, backups that are one file, and rebuilds that are one paste into a new LXC. If you’re running a public edge as well, Caddy fits there too. My WireGuard VPS tunnel already uses Caddy at the VPS end, so the internal and external proxies now speak the same language.

One last thing worth repeating. A reverse proxy is not a security product, no matter how often that claim gets made online. It routes traffic and handles certificates. Keep a real firewall in front of it, segment your network, and treat the proxy as one layer among several. Defense in depth is the only honest answer.

If you want a starting point, copy the global block, the wildcard block, the (proxy) snippet, and three example service blocks from above into /etc/caddy/Caddyfile, swap in your own domain and upstream IPs, run caddy validate, then caddy reload. That’s the whole workflow, and it stays the same whether you have three services or 31.

Arr Stack Docker Compose: Full Usenet Setup Guide on Proxmox

Fri, 12 Jun 2026 05:51:42 -0600

I initially built my *arr apps in separate LXC containers, and the result was a mess. The volume paths were hard to manage and never quite lined up right, and Radarr and Sonarr kept failing to import movies and shows because of permission issues. Every “Import failed, path does not exist” error sent me back to the settings page. So I tore the whole thing down and rebuilt it as one Docker Compose file, with a shared bridge network. That was the day automation finally worked. This post is the arr stack docker compose guide I wish I’d had.

If you’ve been searching for a walkthrough that covers the whole suite at once instead of four separate install posts, this is it. We’ll stand up Prowlarr, Radarr, Sonarr, Bazarr, and SABnzbd in a single Compose file on a Debian 13 VM in Proxmox, and we’ll set up Prowlarr as the central indexer hub so you only have to configure your indexers once.

This is a Usenet guide, not a torrent guide. I don’t seed, so there’s no ratio to protect and no need to keep a second copy of every file hanging around. My downloads go to a dedicated NVMe drive where SABnzbd does its repair and unpack work, and the finished media is then written over to my mergerfs NAS pool. The download drive and the media pool are deliberately two different filesystems, and as you’ll see, that’s completely fine for a Usenet setup. If you run torrents and care about seeding from the same files you import, this is not the best guide for you.

💭

TL;DR: Run the entire *arr suite plus SABnzbd from one Docker Compose file on a Debian VM, download to a fast NVMe drive, and let the apps import into a mergerfs media pool. Prowlarr syncs your Usenet indexers into Radarr and Sonarr automatically.

I run this setup on Proxmox 9.3.2 inside a Debian 13 VM with Docker 29.6.0, using the LinuxServer.io images for Prowlarr 2.4.0, Radarr 6.2.1, Sonarr 4.0.17, and Bazarr 1.5.6, SABnzbd 5.0.4 image. Every command and path below is copied from this working stack.

Why One Compose File Beats Four Install Guides

Here’s the biggest lesson from my initial setup: the *arr apps are a system, not a collection of independent programs. Radarr needs to reach SABnzbd. Prowlarr needs to push indexers into both Radarr and Sonarr. Bazarr needs to see the same media folders Radarr and Sonarr write to. When you install each one separately, you make a fresh networking and permissions decision every time, and those decisions drift out of sync.

A single Docker Compose file fixes this at the root. One file defines:

One shared user-defined bridge network, so every app can reach every other app by container name.
One PUID/PGID pair, so every container reads and writes files as the same user.
One lifecycle: docker compose up -d to start the whole arr suite, docker compose down to stop it, and docker compose pull to update.

Compose centralizes networking, volumes, UIDs, and updates in a single source of truth.

Decision First: VM, Bare Metal, or LXC

Before any commands, make the architecture choice, because it changes everything downstream. This guide is written around Proxmox, but nothing here is Proxmox-specific. The stack runs equally well on a dedicated bare-metal server. What you want, either way, is a normal Linux environment for Docker.

Use a VM or bare metal (recommended)

Create a Debian or Ubuntu VM, install Docker inside it, and run the whole stack there. A bare-metal Debian or Ubuntu box with Docker installed directly works exactly the same way, so if you have a spare machine and don’t need Proxmox, point it at that instead. Either path is what I run and what I recommend for almost everyone. Both give Docker a clean, normal Linux environment, so PUID/PGID behave exactly the way every LinuxServer.io guide assumes. No cgroup edits, no device passthrough wrestling, no surprise nobody:nogroup ownership.

Choose this if you want the least UID/GID and networking pain. On Proxmox the cost is a little more RAM overhead than an LXC; bare metal has none of that overhead at all.

The MS-01 i5 is a tiny mini PC with plenty of cores, multiple NVMe slots, and real homelab networking (dual 10G SFP+ plus 2.5 GbE), which makes it perfect for a Proxmox compute node. It has more than enough power for Jellyfin, the *arr stack, downloads, and a few VMs or LXCs, without turning your closet into a jet engine or space heater. The extra NVMe slots matter here, since Usenet leans hard on a fast scratch drive for repair and unpack.

Amazon Price: Loading...

Availability: Checking...

Contains affiliate links. I may earn a commission at no cost to you.

Use a privileged LXC (advanced, not recommended)

An LXC uses fewer resources, but to run Docker inside one on Proxmox it usually needs to be privileged, and you have to edit /etc/pve/lxc/<id>.conf to allow the devices and mounts Docker expects. Here’s the trap that bites almost everyone: an unprivileged LXC with host NFS/SMB storage often shows your media as owned by nobody, which makes imports fail, and you need to understand how to map users and groups in the LXC config. I have guides on this, but it’s outside the scope of this post.

Choose this only if you’re resource-constrained and comfortable debugging Proxmox LXC permissions quirks. A full VM, or a bare-metal box with Docker, is simpler and more reliable for the *arr suite, which is why I don’t recommend the LXC route for this stack. And because I’m weird, I only run unprivileged LXCs and never privileged ones. If something needs that level of permission, it gets a VM, not an LXC.

The rest of this guide assumes the VM (or bare-metal) path. I’ll flag the LXC-specific steps where they differ.

Step 1: Plan the Storage Layout

This is the step that, done wrong, causes import failures down the line. So let me be clear about what this setup is doing, because it’s the opposite of the torrent-focused guides you’ve probably read.

My download drive and my media library are two separate filesystems on purpose. Downloads land on a fast NVMe drive, where SABnzbd does the heavy, IO-intensive work of par2 repair and rar extraction. The finished files are then imported onto a mergerfs pool mounted at /media/Storage, which is where the actual library lives. When Radarr or Sonarr import a file, it gets copied from the NVMe onto the pool.

That copy is not a bug, and it’s not something to engineer away. For Usenet there’s nothing to seed, so there’s no reason to keep the downloaded file linked to the library file. The bytes have to physically move from the NVMe onto the pool to end up in the library no matter what, so a one-time copy on import is exactly the behavior you want. You get NVMe speed where it actually matters, during repair and unpack, and your bulk storage stays on the pool. The only cost is a brief moment of the file existing in two places during the copy, which the app cleans up afterward.

This is also why you will not see a single /data mount or any hardlink settings in this guide. Those exist to keep a seeding torrent and its imported copy as one set of bytes on one filesystem. With Usenet you don’t need that, so the layout is simpler.

On the VM, create the download tree on the NVMe drive. Set DOWNLOADS_PATH to wherever your NVMe is mounted:

sudo mkdir -p /downloads/{incomplete,complete/{movies,tv}}

Create the media library on the mergerfs pool:

sudo mkdir -p /media/Storage/{Movies,Shows,Hallmark}

I keep a separate Hallmark library because Radarr handles it as its own root folder, which keeps those movies out of my main collection. You can drop that folder if you don’t need a second movie root.

Finally, create a tree for container configuration. Keep it off $HOME to avoid permission and backup headaches:

sudo mkdir -p /docker/{prowlarr,sonarr,radarr,bazarr,sabnzbd}

Set ownership and capture PUID/PGID

Pick a user that will own the media. I use a dedicated user myuser who is a member of the media group. Find its numeric IDs:

id myuser

That prints something like uid=1000(myuser) gid=1001(media). Those two numbers become your PUID and PGID in the .env file, and they don’t have to match each other. Mine are 1000 and 1001. Now hand the download and config folders to that user:

sudo chown -R myuser:media /downloads /docker
sudo chmod -R 770 /downloads /docker

Don’t let that chmod string scare you. It gives the owner and the media group full read and write, and traverse on directories, while locking everyone else out completely. That lines up with the UMASK=0007 in your .env, which tells the containers to create new files the same way: owner and group only, nothing for anyone else.

The mergerfs pool is the one place to slow down. Because the pool sits on top of your NAS disks, its ownership is governed at the storage layer, not by a simple chown on the mount. The thing that actually matters is that the PUID/PGID your containers run as can write to /media/Storage. Confirm that before you go further, because a pool the apps can’t write to is the most common cause of silent import failures in this kind of split setup.

ℹ️

Info: Lessons learned: the user that owns your downloads and the user that can write to your media pool must both line up with the PUID/PGID the containers run as. Write the UID and GID down now, you’ll paste them into the .env file in a minute.

Checkpoint: log in as myuser and run touch /downloads/complete/movies/test and touch /media/Storage/Movies/test. No permission error on either means you’re good. Delete the test files afterward.

Samsung 9100 PRO 2TB is a high-performance NVMe SSD that delivers fast PCIe speeds and responsive everyday performance, making it an ideal SABnzbd scratch and processing drive.

Amazon Price: Loading...

Availability: Checking...

Contains affiliate links. I may earn a commission at no cost to you.

Step 2: Prepare the VM and Install Docker

Update the OS and install Docker using the official convenience script:

sudo apt update && sudo apt upgrade -y
curl -fsSL https://get.docker.com | sudo sh
sudo usermod -aG docker myuser

Log out and back in as myuser so Docker runs without sudo. Verify:

docker run hello-world

For the LXC path instead: create a privileged Debian/Ubuntu container, bind-mount your storage into it, then install Docker the same way. Be aware of the nobody:nogroup trap mentioned earlier, which is the main reason I steer people toward a VM for this.

Checkpoint: docker info runs cleanly and hello-world prints its success message.

Step 3: Write the Docker Compose File

This is the heart of the arr stack docker compose setup. First, a quick note on two design choices in my file.

I keep every tunable value in a .env file rather than hardcoding it in the Compose file. Ports, paths, and the user IDs all live in one place, which makes the Compose file readable and easy to reuse. I also run every service on an external network called media_network, which means the network is created once, outside of Compose, and the stack attaches to it. That keeps the network stable even when I tear the stack down and bring it back up.

Create a project directory and the .env file:

sudo mkdir -p /docker && cd /docker

cat > .env <<EOF
# User and Group ID (Prevents permission issues)
# Main user ID
PUID=1000
# Main group ID:
PGID=1001
# File permission mask
UMASK=0007

# Timezone (Ensures correct scheduling and logs)
TZ=America/Denver

# Define Ports (Ports for each container are defined here)
RADARR_PORT=7878
SONARR_PORT=8989
SABNZBD_PORT=8080
PROWLARR_PORT=9696
BAZARR_PORT=6767

# Data Directories (Keeps storage paths centralized)
CONFIG_PATH=/docker
DOWNLOADS_PATH=/downloads
MEDIA_PATH=/media/Storage
HALLMARK_PATH=/media/Storage/Hallmark
EOF

Replace the PUID and PGID with the values you captured from id myuser, set TZ to your timezone, and point the paths at your real download drive and media pool.

Now create the external network, since the Compose file expects it to already exist:

docker network create media_network

Then create docker-compose.yml:

services:
 #################################
 # PROWLARR
 #################################
 prowlarr:
 image: lscr.io/linuxserver/prowlarr:latest
 container_name: prowlarr
 env_file: .env
 ports:
 - ${PROWLARR_PORT}:9696
 volumes:
 - ${CONFIG_PATH}/prowlarr:/config
 healthcheck:
 test: wget --no-verbose --tries=1 --spider http://localhost:9696/ping || exit 1
 start_period: 30s
 timeout: 3s
 interval: 30s
 retries: 3
 networks:
 - media_network
 restart: unless-stopped

 #################################
 # SONARR
 #################################
 sonarr:
 image: lscr.io/linuxserver/sonarr:latest
 container_name: sonarr
 env_file: .env
 ports:
 - ${SONARR_PORT}:8989
 volumes:
 - ${CONFIG_PATH}/sonarr:/config
 - ${MEDIA_PATH}/Shows:/tv
 - ${DOWNLOADS_PATH}:/downloads
 healthcheck:
 test: wget --no-verbose --tries=1 --spider http://localhost:8989/ping || exit 1
 start_period: 30s
 timeout: 3s
 interval: 30s
 retries: 3
 networks:
 - media_network
 restart: unless-stopped

 #################################
 # RADARR
 #################################
 radarr:
 image: lscr.io/linuxserver/radarr:latest
 container_name: radarr
 env_file: .env
 ports:
 - ${RADARR_PORT}:7878
 volumes:
 - ${CONFIG_PATH}/radarr:/config
 - ${MEDIA_PATH}/Movies:/movies
 - ${HALLMARK_PATH}:/hallmark
 - ${DOWNLOADS_PATH}:/downloads
 healthcheck:
 test: wget --no-verbose --tries=1 --spider http://localhost:7878/ping || exit 1
 start_period: 30s
 timeout: 3s
 interval: 30s
 retries: 3
 networks:
 - media_network
 restart: unless-stopped

 #################################
 # BAZARR
 #################################
 bazarr:
 image: lscr.io/linuxserver/bazarr:latest
 container_name: bazarr
 env_file: .env
 ports:
 - ${BAZARR_PORT}:6767
 volumes:
 - ${CONFIG_PATH}/bazarr:/config
 - ${MEDIA_PATH}/Movies:/movies
 - ${MEDIA_PATH}/Shows:/tv
 healthcheck:
 test: wget --no-verbose --tries=1 --spider http://localhost:6767/ || exit 1
 start_period: 30s
 timeout: 3s
 interval: 30s
 retries: 3
 networks:
 - media_network
 restart: unless-stopped

 #################################
 # SABNZBD
 #################################
 sabnzbd:
 image: lscr.io/linuxserver/sabnzbd:latest
 container_name: sabnzbd
 env_file: .env
 ports:
 - ${SABNZBD_PORT}:8080
 volumes:
 - ${CONFIG_PATH}/sabnzbd:/config
 - ${DOWNLOADS_PATH}:/downloads
 healthcheck:
 test: wget --no-verbose --tries=1 --spider http://localhost:8080/ || exit 1
 start_period: 30s
 timeout: 3s
 interval: 30s
 retries: 3
 networks:
 - media_network
 restart: unless-stopped

#################################
# NETWORK
#################################
networks:
 media_network:
 name: media_network
 external: true

A few things worth pointing out in that file.

Every service joins media_network, the user-defined bridge, so they resolve each other by container name like http://radarr:7878. Each service also gets a healthcheck, so docker ps tells you at a glance whether an app is genuinely up and answering rather than merely running.

Notice that Prowlarr mounts only its /config folder. It manages indexers and never touches your media or downloads, so there’s no reason to give it those mounts. Sonarr and Radarr each mount their library folder plus the shared /downloads path, and Radarr gets the extra /hallmark root on top of /movies. Bazarr mounts the two media folders it writes subtitles into and nothing else.

The key detail that keeps imports working is that SABnzbd, Sonarr, and Radarr all see the completed download at the exact same container path, /downloads. Because that path is identical across all three, Sonarr and Radarr can find what SABnzbd finished without any remote path mapping. The media folders differ between containers (/tv, /movies, /hallmark), but those are import destinations, so that’s fine.

Want this Compose file with your own paths, IDs, and service selection already filled in? The arr stack generator produces the .env, docker-compose.yml, and launch commands from the exact template above.

Generate your files

Validate before launch:

docker compose config

If that prints your merged config without errors, you’re ready.

Step 4: Bring Up the Stack

From /docker:

docker compose up -d

Check health:

docker ps

All containers should read Up, and after a minute the healthchecks should report healthy. Now reach the web UIs at your VM’s IP:

Prowlarr: http://<vm-ip>:9696
Radarr: http://<vm-ip>:7878
Sonarr: http://<vm-ip>:8989
Bazarr: http://<vm-ip>:6767
SABnzbd: http://<vm-ip>:8080

⚠️

Warning: Do this early: open SABnzbd, run through its first-launch wizard, and set a username and password under Config, General before you expose the port anywhere beyond your LAN. While you’re there, lock down the host whitelist so only your VM and the *arr containers can reach it.

Step 5: Configure SABnzbd

SABnzbd is the download client, so it needs your Usenet provider and a folder layout that matches the paths the containers expect.

Open SABnzbd at http://<vm-ip>:8080 and run the startup wizard. Add your Usenet provider’s server details (host, port, SSL, username, password, and connection count) under Config, Servers.
Under Config, Folders, set the temporary download folder to /downloads/incomplete and the completed download folder to /downloads/complete. Both of these resolve to your NVMe drive inside the container.
Under Config, Categories, create two categories so Sonarr and Radarr can route their grabs:
- tv with folder /downloads/complete/tv
- movies with folder /downloads/complete/movies

Pointing the incomplete and complete folders at the NVMe is what keeps repair and unpack fast. The completed files sit there only until Radarr or Sonarr import them onto the pool.

Test: send a test NZB to the movies category and confirm the finished files land in /downloads/complete/movies on the host. Because SABnzbd sees /downloads at the identical path the *arr apps see, no remote path mapping is needed later.

A 3.5-inch SATA desktop-class drive that delivers huge capacity for bulk storage. Perfect for media libraries managed by Radarr and Sonarr, where capacity per dollar matters more than raw speed.

Amazon Price: Loading...

Availability: Checking...

Contains affiliate links. I may earn a commission at no cost to you.

Step 6: Wire Prowlarr as the Central Indexer Hub

Here’s the payoff of the shared network. Prowlarr is the Servarr indexer manager, and its job is to hold all your Usenet indexers in one place and sync them into Radarr and Sonarr automatically. If you want the deeper, single-app walkthrough for this piece, see How to Install Prowlarr in Docker. You add an indexer once in Prowlarr, and it appears in both apps.

In Prowlarr, go to Settings, Indexers, and add your Usenet indexers. These are API-based, so each one needs its API key and host. Test each one.
Go to Settings, Apps, and add Radarr:
- Prowlarr Server: http://prowlarr:9696
- Radarr Server: http://radarr:7878
- API key: from Radarr, Settings, General
Repeat for Sonarr with http://sonarr:8989.
Save. Prowlarr’s Sync App integration pushes every indexer into Radarr and Sonarr.

Notice the container names in those URLs. That only works because every app shares media_network.

One nice thing about a Usenet-only setup: you can skip the whole FlareSolverr thing that torrent guides walk you through. FlareSolverr exists to solve Cloudflare anti-bot challenges on public torrent trackers. Usenet indexers talk over a clean API, so there’s nothing to solve and one less container to run.

Test: open Radarr, Settings, Indexers, and confirm the Prowlarr indexers appear there without you adding them manually. Run an interactive search for a known movie and verify results come back.

Step 7: Configure Radarr and Sonarr

Now connect Radarr and Sonarr to SABnzbd and set the root folders. If you only need to stand up one of these on its own, the per-app guides go deeper: install Radarr on its own or install Sonarr on its own.

Root folders

Set Root Folders to the media paths the containers see:

Radarr: /movies, and add /hallmark as a second root folder if you keep that library
Sonarr: /tv

Download client

In Radarr, go to Settings, Download Clients, add SABnzbd:

Host: sabnzbd (the container name; an IP will not resolve here)
Port: 8080
API key: from SABnzbd, Config, General
Category: movies

Repeat in Sonarr with category tv. Because both apps and SABnzbd see /downloads at the same path, leave remote path mappings empty. That’s what eliminates the “path does not exist” import failures.

When Radarr or Sonarr import a finished download, it copies the file from /downloads on the NVMe to its root folder on the pool, then tidies up the download. That copy is expected and correct for Usenet, as covered back in Step 1.

Test: grab a single movie or episode, let it download and import, and confirm a finished file appears under /media/Storage/Movies (or Shows) on the host. A clean import with the file landing on the pool means the whole chain is wired correctly.

Step 8: Configure Bazarr for Subtitles

Bazarr connects to both Radarr and Sonarr, watches their libraries, and fetches subtitles automatically.

Open Bazarr, go to Settings, Sonarr:
- Address: sonarr, Port 8989, API key from Sonarr
Settings, Radarr:
- Address: radarr, Port 7878, API key from Radarr
Because Bazarr mounts the same /movies and /tv folders, its library paths line up with what Radarr and Sonarr report. No path mapping needed.
Under Settings, Languages, set your subtitle languages. Then under Settings, Providers, add a provider. OpenSubtitles.com is the usual starting point: create a free account on their site, then enter those credentials in the Bazarr provider config. If you want a second source, Podnapisi is a solid no-account-needed backup.
Trigger a scan. Bazarr should list every title Radarr and Sonarr know about and start pulling subtitles.

Checkpoint: open a movie folder under /media/Storage/Movies and confirm .srt files show up after Bazarr runs.

Troubleshooting the Common Failures

These are the failures I hit, in roughly the order they bit me. The FAQ at the end gives quick one-line answers. This section is the diagnostic walkthrough for when something is actually broken.

“Import failed, path does not exist”

This almost always means the path the download client reports does not match what Radarr or Sonarr can see. With this layout it should not happen, because SABnzbd and both *arr apps all mount the downloads drive at the identical /downloads path. If it does happen, check that you didn’t accidentally rename a volume target in Compose (for example mounting ${DOWNLOADS_PATH}:/data in SABnzbd but leaving the *arr apps on /downloads). Keep the download path identical across all three and delete any remote path mappings.

Radarr or Sonarr can’t write to the pool

If imports fail with permission errors on the media side, the apps can’t write to /media/Storage. Confirm the PUID/PGID in your .env match a user that has write access to the mergerfs pool. This is the split-mount gotcha: downloads on the NVMe might be perfectly writable while the pool is not, because the pool’s permissions are governed at the NAS layer. Fix write access to the pool and imports start landing.

Files show as nobody:nogroup (LXC users)

This is the classic unprivileged-LXC trap. The container cannot map your host user, so it sees media as nobody, and imports fail. Either convert the LXC to privileged, or configure UID/GID mapping and ACLs, which is fiddly and error-prone. This is the single best reason to use a VM.

Containers cannot reach each other

If Prowlarr cannot talk to Radarr by name, confirm both services list media_network under networks in Compose, that you created the external network with docker network create media_network before bringing the stack up, and that you used container names, not localhost or 127.0.0.1, in the app URLs. From inside one container you can test with docker exec -it prowlarr ping radarr.

Permissions sanity check

When in doubt, validate the chain. Run id myuser on the host, confirm it matches the PUID/PGID in .env, and test a write as that user to both the download drive and the pool:

sudo -u myuser touch /downloads/complete/movies/perm-test && echo "downloads OK"
sudo -u myuser touch /media/Storage/Movies/perm-test && echo "pool OK"

Maintenance: Updates and Backups

Updating the stack is two commands from /docker:

docker compose pull
docker compose up -d

For backups, the important data is small. Back up /docker/*, which holds every app’s config and database. The media under /media/Storage is large, so handle that at the storage layer with NAS or pool-level snapshots rather than copying it.

To grow the stack later, add more services to the same Compose file and media_network: Lidarr for music, Readarr for books, or Jellyfin pointed at the same /media/Storage media folders.

Frequently Asked Questions

➤ Why are my downloads and media on different filesystems? Isn't that wrong?

Not for Usenet. Different filesystems only cause problems when you need hardlinks to seed torrents from the same files you import. With Usenet there’s nothing to seed, so downloading to a fast NVMe drive and importing onto a separate media pool is the right design. The one-time copy on import is expected, and it lets the NVMe handle repair and unpack at full speed.

➤ Should I run the *arr suite in a Proxmox VM, on bare metal, or in an LXC?

Use a VM or a bare-metal Linux box for the smoothest experience. Nothing here is Proxmox-specific, so a dedicated machine with Docker installed directly works exactly the same. Docker in an LXC, by contrast, needs a privileged container and config edits, and unprivileged LXCs with host storage often show media as nobody, breaking imports. An LXC saves resources but costs you debugging time, which is why I don’t recommend it for this stack. A VM or bare-metal box behaves like a normal Linux box.

➤ How do I connect Prowlarr to Radarr and Sonarr?

In Prowlarr go to Settings, Apps, and add each app using its container name URL (http://radarr:7878, http://sonarr:8989) plus the API key from that app’s Settings, General page. Prowlarr’s Sync App feature then pushes all indexers into both automatically, so you configure indexers only once.

➤ Do I still need Jackett with Prowlarr?

No. Prowlarr is the modern Servarr indexer manager and fully replaces Jackett for Radarr, Sonarr, and the rest of the suite. It manages your indexers and syncs them directly into the apps. Older guides used Jackett, but new Prowlarr-centric stacks retire it entirely.

➤ Why does my import fail with a path error?

The download path the client reports doesn’t match what Radarr or Sonarr can see. In this setup, SABnzbd and both *arr apps all mount the download drive at /downloads, so the paths line up and remote path mapping stays empty. If you renamed that mount target in one container, fix it back to /downloads everywhere.

Wrapping Up

The shortcut I learned the hard way: treat the *arr apps as one system from the start. A single Docker Compose file, one shared media_network bridge, a fast NVMe download drive, and a mergerfs media pool, with matching PUID/PGID across every container, turns a fragile pile of containers into automation that genuinely works. SABnzbd does the heavy lifting on fast storage, Prowlarr feeds both apps your Usenet indexers, and Bazarr fills in subtitles without a second thought. That’s the whole arr stack docker compose payoff.

From here, bring up the stack, run a test grab end to end, then layer on a media server like Jellyfin against the same /media/Storage. If you came in from one of our per-app install guides for Radarr, Sonarr, or Prowlarr, this is the stack they were always meant to plug into.

Automated MKV Cleanup With mkvmerge, SABnzbd & Cron

Wed, 10 Jun 2026 06:19:48 -0600

Every media library eventually runs into the same problem. You open a movie in Jellyfin, it starts playing in a French dub you didn’t ask for, and you spend twenty seconds digging through the audio menu while the family gives you the side-eye. Multiply that by a library full of releases stuffed with five audio dubs, a commentary track, and a dozen subtitle tracks, and you have a real problem. My library had grown to roughly 2,200 MKV files, and each one was carrying around junk it did not need.

The good news? This is automatable, and the right tool does it losslessly in seconds rather than hours. The bad news, which I learned the hard way, is that the obvious approach quietly destroys foreign films and anime. This post walks through how I built an automated MKV cleanup tool with mkvmerge, including every mistake I made before it worked. The whole thing is now open source: two self-contained Python scripts in the mkv-track-stripper repo on GitHub, MIT licensed, ready to drop into your own setup. You’ll get the script logic, the SABnzbd hook, the cron sweep, and the reasoning behind each safety decision. The mistakes are where the real lessons live.

💭

TL;DR: Use mkvmerge to losslessly remux MKVs and strip unwanted audio and subtitle tracks, then set it up at two points: a Python SABnzbd post-processing hook (mkv_strip_pp.py) cleans new downloads before Radarr and/or Sonarr imports them, and a Python library sweep (mkvclean.py) handles the back catalog and can run as a cron job as an unattended catch-all. The mkvclean script tracks processed files in a checkpoint file so nothing gets processed twice, every remux is verified before the original is replaced, and forced subtitles always survive. Both scripts live in the mkv-track-stripper repo.

I ran this entire pipeline on Debian 13 with MKVToolNix 92.0 & 96.0, SABnzbd 5.0.3, and Radarr 6.11, validating the output in Jellyfin 10.11.10 before letting it loose on the full library. Everything in this post is a real lesson learned, scars included.

Why mkvmerge Beats ffmpeg for Stripping Tracks

For anything video-related, most people reach for ffmpeg or Tdarr first. I did too. They’re capable tools, but for stripping tracks out of MKVs at scale, mkvmerge from the MKVToolNix suite is the better fit. The reason comes down to what each tool is built for.

mkvmerge is a lossless remuxer, not a transcoder. It copies streams as-is into a new MKV while letting you drop, reorder, or relabel tracks, with no re-encoding involved. The operation is fast and there’s zero quality loss. ffmpeg is designed around decode and encode processes. Copying a subset of tracks usually means more verbose -map expressions, and some Matroska features don’t copy 1:1 without surprises.

With mkvmerge you can keep or drop tracks by ID or by language with flags like --audio-tracks, --subtitle-tracks, and --language, and you set default and forced flags per track. MKVToolNix is dedicated to Matroska. It handles chapters, tags, editions, and segment linking cleanly. ffmpeg’s Matroska muxer is good but not tuned for every edge case, and users report occasional player quirks with ffmpeg-muxed MKVs on ordered chapters and dual-subtitle anime.

I Started With Tdarr, and It Was the Wrong Tool

Before I discovered MKVToolNix, I reached for Tdarr. It’s the tool everyone points you at: a slick web UI, a node-and-worker architecture, and a plugin library that promises hands-off library maintenance. I spent an evening standing up the server, attaching a node, and wiring a flow to drop the tracks I didn’t want.

It was the wrong tool for two reasons. First, Tdarr is built around transcoding, and its flows kept nudging me toward re-encoding the video to “process” a file. I didn’t want a new encode. I wanted the exact same video and one or two audio tracks copied into a fresh container, untouched. Running a lossy, hours-long transcode only to delete a subtitle track is the opposite of what this job needs.

Second, the whole tool was wildly oversized for the task. A server, a worker node, a database, and a huge list of plugins is a lot of moving parts to own and debug when the actual operation is “remove these track IDs.” Tdarr is genuinely good at what it’s for - bulk transcoding and health-checking a library on dedicated hardware - but for lossless track stripping it buried a one-line mkvmerge call under a stack of infrastructure I’d have to maintain forever. I tore it down and went back to a script.

To be clear, none of this is a knock on Tdarr for the job it’s built for. If you want to re-encode your library, say converting H.264 to H.265 to reclaim storage, Tdarr’s node-and-worker setup is the right tool. I wrote a full walkthrough for that:

Tdarr Setup Guide: Install, Configure & Transcode

Beelink SER5 (Ryzen 5 5500U). A palm-sized mini PC with a 6-core/12-thread CPU that feels snappy for everyday work and homelab duties, handling Docker stacks, light VMs, and Plex without guzzling power. With NVMe plus a 2.5″ bay, Wi-Fi 6, and multi-display output, it’s a quiet, tidy upgrade for desk or media setups.

Amazon Price: Loading...

Availability: Checking...

Contains affiliate links. I may earn a commission at no cost to you.

Inspect Before You Touch Anything

Before automating, you need to see what’s actually inside a file. Two commands do everything:

mkvmerge -i movie.mkv

This lists tracks with their IDs, types, languages, and names in human-readable form. For scripting, you want the JSON version:

mkvmerge -J movie.mkv

This is a machine-readable description you can parse safely. The fields that matter are tracks[].id, tracks[].type, tracks[].properties.language, and tracks[].properties.track_name. When a release is genuinely strange (ordered chapters, segment linking), mkvinfo movie.mkv gives even deeper details for debugging.

One thing early on that I had to learn: mkvmerge -J exits with code 1 when it has warnings about a file, but it still emits perfectly valid JSON. An early version treated that as a probe failure and skipped the file. Only exit codes of 2 or higher mean the probe actually failed.

The First Script, and the Trap Hiding in It

My first script was embarrassingly simple: keep only English audio and English subtitles, drop everything else. It looked completely reasonable. It ran fine against a folder of Hollywood blockbusters. Then I pointed it at my anime folder.

Every single file came out silent.

The script had stripped the only audio track in each file because the language tag said jpn, not eng. There was no error and no warning. Dead silence when I started movie night while everyone stared at me. That moment is when I stopped writing naive language filters and started reasoning from what tracks are actually present, rather than what I assumed should be there.

The fix is conditional logic, and it’s conservative on purpose. Breaking one film is worse than failing to clean five.

If a file has a single audio track, keep it no matter the language. A movie with one audio stream is never a candidate for audio removal.
If a file has multiple audio tracks but none match your preferred languages, keep them all and log a notice rather than risk going silent.
Never drop all subtitle tracks when the audio is in a language you don’t understand.

There’s no reliable original-language flag to lean on. Real-world files have audio mistagged as und, fansubs with multiple eng subtitle tracks (full subs versus signs-and-songs), and scene releases that label things inconsistently.

That und (undetermined) tag deserves its own rule, because it’s a coin flip: it might be the English track a sloppy release group forgot to label, or it might be a dub you’ll never play. The selection logic in both scripts treats und as a preferred language only until a real English track shows up. If the file has properly tagged English audio, und tracks are no longer given the benefit of the doubt:

has_eng_audio = any(t.get("properties", {}).get("language") == "eng" for t in audio)
target_audio_langs = list(audio_langs)
if has_eng_audio and "und" in target_audio_langs:
 target_audio_langs.remove("und")

⚠️

Warning: Lessons learned: Filtering blindly by language is the single most dangerous thing you can do to a media library. A silent movie is a broken movie. Always handle the single-track, no-preferred-match, and und cases before you let any removal logic run.

Safety as a First Principle

Once the language logic was sane, the next set of mistakes were about how I handled the files themselves. Three rules emerged, and all of them are non-negotiable.

Write a new file, verify it, then and only then replace the source. Both scripts remux to a hidden temp file (via tempfile.mkstemp) in the same directory as the original, then call os.replace to swap it atomically onto the original path. Same-directory output is deliberate twice over: a rename within one filesystem is atomic, so Radarr, Sonarr or Jellyfin never catches a half-written file mid-swap, and it sidesteps cross-device link errors when your storage is a MergerFS or ZFS pool. Before any of that, a pre-flight check confirms the directory has at least 105% of the original’s size free, so a full disk can’t produce a truncated output.

Verify means actually verify. A non-empty output file and a happy exit code aren’t proof of a good remux. Before the swap, verify_remux() re-probes the temp file with mkvmerge -J and confirms it still contains a video track and exactly the audio and subtitle track counts that were requested. If the re-probe fails or the numbers don’t add up, the original stays put and the error is logged. This is the guard against a truncated-but-nonzero output silently overwriting a perfectly good source.

Read exit codes correctly. This one trips people up (including me). mkvmerge does not use the standard “0 good, anything else bad” convention. It returns 0 on full success, 1 on success with warnings, and 2 for a genuine error. A warning often means a track had a minor inconsistency that mkvmerge handled fine, so the scripts accept both:

result = subprocess.run(cmd, capture_output=True, text=True)
ok = (result.returncode in (0, 1) and os.path.exists(tmp) and os.path.getsize(tmp) > 0)

Only code 2, or a zero-byte output file, or a failed verification re-probe, means stop and preserve the original intact.

There’s one more thing the swap has to get right that I didn’t anticipate: the cleaned file is a new file, so it arrives owned by whoever ran the script, with fresh permissions and timestamps. On a library shared between Radarr, Sonarr, Jellyfin, and an NFS export, that’s a quiet way to break things days later. After a successful remux, preserve_metadata() copies the original’s ownership, mode, timestamps, extended attributes, and POSIX ACLs onto the cleaned file before the swap. If ownership can’t be restored (you’re not running as root or as a user who doesn’t own the files), it logs a warning and keeps going rather than dying - the cleanup still worked, the file has a new owner.

The subtitle judgment call. Subtitles get a more aggressive policy than audio, and I want to be honest that this is a choice rather than an obvious truth. A missing subtitle doesn’t break playback the way missing audio does - worst case, you re-add a sub later. So: keep your preferred languages, drop the rest, and drop SDH/hearing-impaired tracks along the way. But there’s one exception that’s absolute. Forced subtitles - the ones that translate the single line of Elvish in an otherwise English film - are always kept, no matter what language they’re tagged as:

is_forced = props.get("forced_track") or "forced" in track_name
is_sdh = props.get("flag_hearing_impaired") or "sdh" in track_name

if is_forced:
 keep_subs.append(t["id"])
elif lang in sub_langs and not is_sdh:
 keep_subs.append(t["id"])

Note the fallback to a "forced" substring in the track name. An earlier version trusted the Matroska flag alone, and plenty of real-world releases name the track “Forced” without ever setting the flag. If you rely on SDH subtitles, add them back by removing the is_sdh check or adjusting the config to your needs.

The Bash Era, and Why It Didn’t Survive

The first working version of all this was a pair of Bash scripts gluing mkvmerge -J to jq, and they taught me a lot of lessons that anyone scripting against a real library will hit.

Filenames with spaces, apostrophes, and brackets will quickly break a naive loop. A movie called Amelie (2001) [1080p].mkv breaks for f in $(find ...) instantly, because the shell splits on whitespace. The fix is NUL-safe handling: find ... -print0 piped into IFS= read -r -d ''. Then the progress counter I added always reported zero at the end, because piping find into a while loop runs the loop in a subshell where incremented variables die on exit - the fix is process substitution, done < <(find ...). And to make re-runs skip finished files, the Bash version renamed every cleaned file to movie.cleaned.mkv and excluded that pattern from the next find. The name was the marker.

It all worked. I still retired the whole thing, for three reasons:

The marker rename was the wrong kind of clever. Renaming every file in the library means renaming it out from under Radarr, Sonarr and Jellyfin, which tracks files by path.
The logic outgrew Bash. Once I wanted forced-subtitle detection, junk-track flags, metadata edits, and output verification, the jq one-liners turned into the hardest-to-read part of the system. The same selection logic in Python is named functions you can reason about.
Two scripts, one brain. The cron sweep and the bulk-pass script were 90% copy-paste of each other, drifting apart with every fix. The Python rewrite collapsed them into one script, mkvclean.py, that handles both jobs.

The shell lessons still stand - NUL-safe loops and subshell scoping will bite you in any Bash project. But the shipped versions of these tools are Python 3.10+, end to end, with no jq dependency at all.

⚠️

Warning: Lessons learned: Write the quick Bash version to learn the problem, but notice the moment the logic outgrows it. For me that moment was the third nested jq expression. Every safety feature that now guards my library - verification, forced-sub detection, metadata healing - would have been miserable to bolt onto the Bash scripts and was straightforward in Python.

The Checkpoint That Makes the Whole Thing Self-repeating

Here’s something worth calling out: mkvmerge doesn’t skip files it already cleaned. The tool has no memory whatsoever. It will happily re-remux a file you cleaned yesterday, every single run. Your script has to do all the skipping.

mkvclean.py solves this with a checkpoint file instead of the old rename-marker. Every successfully handled file is appended to ~/.mkvclean_checkpoint as a JSON line recording its path, modification time, and size. On the next run, any file whose path, mtime, and size all match its checkpoint entry is skipped instantly - no probe, no remux, nothing. Filenames never change, so Radarr, Sonarr, and Jellyfin are none the wiser.

The mtime-and-size part does something the rename-marker never could: it detects upgrades. When Radarr replaces a movie with a better release, the new file has a new size and mtime, the checkpoint entry no longer matches, and the sweep cleans the new file automatically on its next pass.

The checkpoint is append-only during a run, so it compacts itself at startup - duplicate entries collapse to one line per file and entries for files that no longer exist under the scanned root are pruned. Combined with fcntl file locking (a manual run and a cron run can physically never overlap) and an os.scandir-based traversal that pulls file metadata during the walk instead of stat-ing everything twice, the sweep stays fast and safe on a multi-terabyte array.

The --batch flag is the right way to start cautiously and build confidence before committing to the whole library:

./mkvclean.py /media/Storage/Movies --batch 20 # first run: 20 files only
./mkvclean.py /media/Storage/Movies --batch 50 # next run: 50 more (checkpointed files are skipped)
./mkvclean.py /media/Storage/Movies --batch 0 # 0 = no limit: finish everything remaining

Stop at any point with Ctrl+C - the script traps the signal, logs that it was interrupted, and the checkpoint means re-running always picks up exactly where you left off. It also removes the tmp file it was building.

The SABnzbd hook doesn’t need a checkpoint at all. It runs once on each download’s folder right after the download completes, and it skips the remux entirely when there’s nothing to remove. A DRY_RUN constant at the top (and a --dry-run flag on the sweep) lets you see exactly what would happen before anything touches real files.

While you’re still learning your own language rules, run in small batches and spot-check a handful of files in Jellyfin before continuing.

What Gets Stripped Beyond Languages

Language filtering was the original goal, but once the scripts were reading every track’s properties anyway, a second category of junk became impossible to ignore.

Commentary and descriptive audio. Director’s commentary, “descriptive video service” tracks, and audio descriptions are junk for most libraries, and they’re often tagged eng - so a pure language filter keeps them. The scripts detect them through the explicit Matroska flags first (flag_commentary, flag_visual_impaired), which catch untitled or non-English commentary tracks, then fall back to track-name matching:

is_junk = (
 props.get("flag_commentary")
 or props.get("flag_visual_impaired")
 or any(x in track_name for x in JUNK_AUDIO_NAME_PATTERNS)
)

where the name patterns are commentary, description, director, and dvs.

Default-flag enforcement. This fixes the single most common Jellyfin complaint - the wrong audio track playing by default. The first kept audio track becomes the sole default, and the default flag is explicitly cleared on every other kept track, so a stale flag carried over from the source can’t leave two defaults fighting each other:

for i, tid in enumerate(keep_audio):
 cmd += ["--default-track-flag", f"{tid}:{1 if i == 0 else 0}"]

Subtitle default flags are cleared across the board, so nothing forces subs on by default.

Cosmetic metadata. Release groups leave a trail: the global container title set to the release filename, tag blocks, track names like “Commentary by…”. The scripts strip the global title, wipe tags, and clear junk track names by default (each pass individually toggleable). They’ll also fill in an undefined track language when the track’s name gives it away - a track named “English” tagged und gets relabeled eng, and crucially this inference runs before the language filter so the corrected tag affects what’s kept. Attachment removal (cover art, embedded fonts) exists but is off by default, because embedded fonts can matter for styled ASS/SSA subtitles.

The mkvpropedit fast-path. Here’s a neat optimization that fell out of all this: when a file’s tracks are already exactly what you want but its header is still wrong - a stale default flag, a junk title - there’s no reason to remux gigabytes. mkvpropedit (also from MKVToolNix) edits headers in place on the existing file, in milliseconds, with no temp file, no disk-space requirement, and ownership/permissions preserved for free because the file never moves. The scripts plan header-only edits whenever track selection comes back unchanged, so a second pass over a clean library is nearly instant and still fixes metadata.

Intel NUC 12 Pro (NUC12WSHi5). A compact mini PC with a 12th-gen Core i5-1240P and Iris Xe that can drive up to four displays (dual Thunderbolt 4 + dual HDMI), plus 2.5GbE and Wi-Fi 6E. The H-chassis adds a 2.5″ bay alongside NVMe storage and up to 64GB RAM, making it a quiet, versatile homelab node or HTPC/office box.

Amazon Price: Loading...

Availability: Checking...

Contains affiliate links. I may earn a commission at no cost to you.

Moving Cleanup Into the Pipeline With SABnzbd

Sweeping the entire library on a schedule works, but the smarter move is to clean each file once, at download time, before Radarr or Sonarr ever imports it. SABnzbd makes this possible with post-processing scripts. That’s the job of mkv_strip_pp.py: drop it into your SABnzbd scripts directory, make it executable, then assign it to your movies (and/or tv) category in Settings → Post-Processing in the SABnzbd UI so only those downloads trigger cleanup.

SABnzbd exports job details as both positional arguments and environment variables. The hook reads the job folder from SAB_COMPLETE_DIR (falling back to argv[1] for manual testing on the command line) and the download status from SAB_PP_STATUS (falling back to argv[7]). If the download was already marked failed, the hook exits immediately without touching anything.

Because the cleaned file is swapped atomically onto the original path, the filename Radarr or Sonarr expects to import never changes. They never see a seam - it imports the file it expected, already trimmed.

The most important design principle here: cleanup must never block an import. If stripping a file fails, leave the original intact, log it, and still let the import proceed. A working movie that didn’t get cleaned is fine. A broken import because your cleanup script choked is not.

Two Different Exit-Code Systems (Don’t Mix Them)

This trips people up because two separate exit-code conventions show up in the same context, and they mean different things.

SABnzbd’s exit codes tell SABnzbd what to do with the job after your post-processing script runs:

Exit code	SABnzbd interpretation
`0`	Success
`1`	Job failed
`2`	Retry the download

mkvmerge’s exit codes (covered earlier) describe the remux itself: 0 success, 1 success with warnings, 2 real error. Same numbers, completely different meanings. If you setup your SABnzbd hook to mkvmerge’s convention, a remux warning (mkvmerge 1) would mark a perfectly good download as failed in SAB. That’s exactly the kind of silent breakage you don’t want.

The hook keeps these rigorously separated. Any cleanup failure - mkvmerge returning 2, a failed verification, an unexpected exception on one file - is handled as “log it, leave the original, move on.” The hook still exits 0 in all those cases, because a movie that wasn’t cleaned is still importable. The only time it exits 1 is for genuine setup problems (mkvmerge or mkvpropedit not found, job directory missing), because those mean nothing can work at all.

log.info("Found %d MKV file(s).", len(mkvs))
for path in mkvs:
 log.info("Inspecting: %s", os.path.basename(path))
 try:
 result = process_file(path, AUDIO_LANGS, SUB_LANGS, resolved_mkvmerge,
 resolved_mkvpropedit, DRY_RUN, CLEANUP)
 if result == "nothing":
 log.info(" Nothing to strip, leaving file as-is.")
 elif result == "stripped":
 log.info(" Done.")
 elif result == "fixed":
 log.info(" Metadata fixed in place (no remux).")
 except Exception as e: # never let one bad file break the import
 log.error("Unexpected error on %s: %s. Original kept.", os.path.basename(path), e)

log.info("Finished. Exiting 0 so import proceeds.")
return 0

Even the logging follows the never-block rule. SABnzbd captures the script’s stdout into its job history, and the file log (defaulting to /config/mkv_strip_pp.log, which lands on the persistent volume in Docker) is best practice - an unwritable log path produces a warning instead of a crash, because an earlier version managed to fail an entire download over a log file it couldn’t open.

Configuration is a block of constants at the top of the script - preferred languages, dry-run, and toggles for each cleanup pass:

AUDIO_LANGS = ["eng", "jpn", "und"]
SUB_LANGS = ["eng", "und"]
LOG_FILE = "/config/mkv_strip_pp.log"
DRY_RUN = False

STRIP_TITLE = True
STRIP_TAGS = True
INFER_LANGUAGE = True
CLEAR_JUNK_TRACK_NAMES = True
STRIP_ATTACHMENTS = False

Installing mkvmerge Inside a Docker Container

If you run SABnzbd in Docker, you hit an error the first time you try to use mkvmerge inside it: the binary isn’t there. The tempting fix is docker exec into the running container and installing it by hand. Don’t do this. The moment you pull a new image, your install vanishes.

The correct fix is a tiny custom Dockerfile that extends the base image, and the repo ships one:

FROM lscr.io/linuxserver/sabnzbd:latest

# Add mkvmerge (from MKVToolNix) and the optional ACL so the post-processing script can run.
# The LinuxServer.io image is Alpine-based, so use apk.
RUN apk add --no-cache mkvtoolnix acl

That apk line hides my actual debugging moment. My first Dockerfile used apt-get, and the build died with apt-get: not found. The base image was Alpine, not Debian. Alpine uses apk, not apt.

In docker-compose.yaml, point the service at the Dockerfile with build: instead of a plain image:, and mount the hook into the container’s scripts directory:

services:
 sabnzbd:
 build: .  # builds the Dockerfile in this repo
 container_name: sabnzbd
 environment:
 - PUID=1000
 - PGID=1000
 - TZ=Etc/UTC
 ports:
 - "8080:8080"
 volumes:
 - /path/to/appdata/sabnzbd:/config
 - ./mkv_strip_pp.py:/config/scripts/mkv_strip_pp.py
 - /path/to/downloads:/downloads
 restart: unless-stopped

One habit changes after adding packages to a custom Dockerfile. Updating the container is now docker compose up -d --build --pull always rather than a plain docker compose pull, so your added packages get rebuilt on top of the fresh base.

The mkvclean.py runs directly on the host, so the host needs Python 3.10+ and MKVToolNix there, plus the optional acl package if you want POSIX ACLs preserved on cleaned files:

apt-get install -y mkvtoolnix python3 acl

MINISFORUM MS-A2. A compact mini-workstation built around up to a 16-core Ryzen 9 9955HX, with dual 10GbE SFP+ plus dual 2.5GbE, flexible storage (U.2 + M.2 including 22110), and triple 8K display outputs. A strong homelab node or small server with serious I/O.

Amazon Price: Loading...

Availability: Checking...

Contains affiliate links. I may earn a commission at no cost to you.

The Cron Sweep, or Why You Still Need One

With per-download cleanup in place, you might think the sweep is redundant. It’s not. The SABnzbd hook only sees files SABnzbd downloads. It misses manual rips, files copied in from elsewhere, media you reorganized, and anything from a category the hook isn’t attached to. A scheduled sweep is your catch-all for eventual consistency across the whole library.

The sweep is mkvclean.py again - the same checkpoint-aware script from the bulk pass, run unattended. Install it somewhere on the PATH:

sudo cp mkvclean.py /usr/local/bin/
sudo chmod +x /usr/local/bin/mkvclean.py

Locking is built in: the script takes a kernel-level fcntl lock on /tmp/mkvclean.lock at startup and exits quietly if another run already holds it, so a cron firing while a manual run is still chewing through the library can never cause two sweeps to step on each other. Logging is built in too - everything goes to the path given by --log (default ~/mkvclean.log) as well as stdout - so the crontab line stays clean with no redirection:

0 4 * * * /usr/local/bin/mkvclean.py /media/Storage/Movies --batch 0 --log ~/mkvclean-cron.log

Thanks to the checkpoint, a typical nightly run skips almost everything instantly and only touches whatever’s new or upgraded since the last pass. Safe to run as often as you like.

The One-Time Bulk Pass

The third job is the one you run once: cleaning the back catalogue that existed before any of this automation. Same script, run by hand, starting with a dry run.

Always do the dry run first on a new library. It reports exactly what would be stripped from every file without modifying a single byte:

./mkvclean.py /media/Storage/Movies --dry-run

Read the log. Confirm it’s keeping what you expect - especially on anime and foreign films. Then start small, with a batch spanning different languages and sources:

./mkvclean.py /media/Storage/Movies --batch 20

Spot-check a handful of files in Jellyfin to confirm audio and subtitle selection looks right. If everything looks good, continue in larger batches:

./mkvclean.py /media/Storage/Movies --batch 100
./mkvclean.py /media/Storage/Movies --batch 0 # 0 = no limit: finish everything remaining

The language preferences are flags rather than edits to the script - --audio eng,jpn,und --subs eng,und are the defaults. If you catch a bad rule, stop with Ctrl+C, adjust the flags, and re-run; checkpointed files won’t be touched again. There’s also a --prefer-audio-channels flag for the hoarder special: releases carrying both a lossless 7.1 track and an AC3 5.1 track in the same language. Set it and the sweep keeps only the best English track (exact channel-count match wins, otherwise most channels) instead of all of them.

Files a bad run already processed may need re-downloading; that’s exactly why you dry-run first and verify in batches rather than letting it run unattended overnight.

MINISFORUM MS-01 Mini Workstation. The MS-01 i5 is a tiny mini PC with plenty of cores, multiple NVMe slots, and real homelab networking (dual 10G SFP+ plus 2.5 GbE), which makes it perfect for a Proxmox compute node. It has more than enough power for Jellyfin, the *arr stack, downloads, and a few VMs or LXCs, without turning your closet into a jet engine or space heater.

Amazon Price: Loading...

Availability: Checking...

Contains affiliate links. I may earn a commission at no cost to you.

How Jellyfin Sees the Result

A quick note on the playback side, because it’s where you confirm the whole thing worked. Jellyfin uses ffmpeg for transcoding. That behavior is unaffected by whether the file was muxed with ffmpeg or mkvmerge, as long as the MKV is spec-compliant. So cleaning with mkvmerge causes Jellyfin no trouble.

The two issues Jellyfin users hit most are the wrong default audio track and missing subtitles. The default-track enforcement described earlier handles the first one directly: every cleaned file comes out with exactly one default audio track (the first kept one) and no default-flagged subtitles, so Jellyfin’s track picker starts from a sane baseline instead of whatever flags the release group left behind. And when a file needs only that flag fixed, the mkvpropedit fast-path patches the header in place without remuxing at all, which is instant.

Missing subtitles are guarded by the forced-track rule - the subtitle that translates the alien dialogue in an otherwise-English film survives every cleanup, even when it’s mistagged.

The Finished System

What started as a one-off cleanup grew into two scripts covering three jobs, now public as mkv-track-stripper on GitHub under the MIT license:

Per-download cleanup via the SABnzbd hook (mkv_strip_pp.py, runs at download time, keeps the original filename so Radarr imports cleanly).
Scheduled catch-all sweep via cron (mkvclean.py --batch 0, locked with fcntl, checkpoint-aware, catches everything the download path misses).
One-time bulk pass over the back catalogue (the same mkvclean.py, dry-run first, batched, resumable, verified in Jellyfin).

The repo carries the Dockerfile for the SABnzbd image, a changelog, and a README covering setup and troubleshooting - including the one warning everyone asks about, Could not preserve ownership ... Operation not permitted, which means the script isn’t root and couldn’t chown the cleaned file back to its original owner. The cleanup itself succeeded.

In practice the logs show three patterns: a file with nothing to strip and a clean header is checkpointed in milliseconds, a file needing only a flag or title fix gets an in-place mkvpropedit edit, and a bloated release with 30 subtitle tracks gets trimmed down in about 30 seconds, losslessly.

Frequently Asked Questions

➤ Will this re-encode my video and lose quality?

No. mkvmerge is a remuxer, not a transcoder. It copies the video and chosen audio and subtitle streams into a new container untouched, so there’s zero quality loss and the operation finishes in seconds rather than the hours a re-encode would take.

➤ Will it ever leave a movie silent?

Not if you build the safety logic in. The rules that prevent it are simple: never strip the only audio track, and when no audio matches your preferred languages, keep everything and log a notice instead of dropping anything. Undetermined (und) tracks only get dropped when a properly tagged English track exists alongside them. The output is also re-probed before the original is replaced, so a broken remux can never overwrite a good file.

➤ Will it delete forced subtitles?

No. Forced subtitles are always kept regardless of language, detected through the Matroska forced_track flag or a “forced” marker in the track name. Those are the subs that translate the one line of Elvish in an otherwise-English film, and losing them genuinely breaks the movie.

➤ Does the sweep re-process files it already cleaned?

No. mkvclean.py records every handled file’s path, size, and modification time in a checkpoint file and skips matching files instantly on later runs. If Radarr upgrades a movie, the new size and mtime no longer match, so the replacement gets cleaned automatically on the next sweep.

➤ Does this work with Sonarr too, or only Radarr?

Yes. You bind the SABnzbd post-processing script to a tv category in the SABnzbd UI the same way you bind it to movies. The library sweep doesn’t know or care about Radarr or Sonarr at all - it walks the filesystem.

➤ Why does apk add mkvtoolnix fail in my Docker image?

apk is Alpine’s package manager. If your base image is Debian or Ubuntu, you need apt-get install mkvtoolnix instead. The reverse trips people up too: apt-get: not found means your base is Alpine. Always check the base image distro before picking a package manager.

➤ How do I list MKV tracks and their languages from the command line?

Run mkvmerge -i file.mkv for a quick human-readable list of track IDs, types, and languages. For scripting, use mkvmerge -J file.mkv to get machine-readable JSON you can parse safely, reading tracks[].properties.language for each track.

Wrapping Up

A few themes carried through every layer of this build, and they’re worth restating: verify before you replace, make every operation idempotent, let failures fail safe, and choose your tools for where the project is heading rather than where it started. The single most important lesson, the one that cost me a movie night, is that you reason from the tracks a file contains, never from what you assume it should contain.

A good automation is rarely the first script you write. It’s the system you arrive at after the task has taught you what it needs. Mine started as a ten-line “keep only English” filter, went through a Bash-and-jq era, and ended as two Python scripts with checkpointing, verification, and safety defaults baked in - now maintained in the open at github.com/KryptikWurm/mkv-track-stripper.

If you want to adopt this, you don’t have to rebuild it: clone the repo, run mkvclean.py --dry-run against a test folder, read the log, then layer in the SABnzbd hook and the cron sweep once you trust the selection rules. Keep the verify-before-replace defaults in place, and you can roll this out across thousands of files without ever losing a movie night.

Best Homelab Wi-Fi & Access Points: VLAN-Aware Setup

Thu, 14 May 2026 09:49:15 -0600

Your homelab is humming along. Proxmox running a dozen VMs, a NAS full of media. Then you connect a cheap smart plug or a guest phone to your Wi-Fi, and suddenly you realize every untrusted device on your network can see your hypervisor management interface. That’s the moment most people recognize that their flat wireless network has become a liability.

The fix is a VLAN-aware wireless setup: an access point that maps each SSID to its own VLAN, a managed switch that trunks those VLANs, and a router or firewall that enforces who can talk to whom. Get this right and your IoT junk, guest devices, and homelab services live in separate broadcast domains that can’t reach each other unless you explicitly allow it. This guide walks through hardware selection, how a Proxmox VLAN bridge fits in, and deploying the whole stack end to end.

💭

TL;DR: Pick a controller-based AP (TP-Link Omada or UniFi) over mesh, pair it with a managed 802.1Q switch and an OPNsense or pfSense firewall, then map each SSID to its own VLAN so IoT, guest, and homelab traffic stay isolated by default.

I ran this exact build on my own rack: an OPNsense VM on Proxmox, with a TP-Link TL-SG2008P managed PoE switch, and an Omada EAP610 access point feeding five SSIDs. Everything below is what actually worked, plus the mistakes that cost me an evening.

What Are the Best Homelab Wi-Fi Solutions?

For a homelab, the best Wi-Fi comes from a controller-based access point that tags each SSID to its own VLAN, not a consumer router or a mesh kit. After running this on my own rack, here’s the short answer:

Best overall homelab AP: a TP-Link Omada ceiling-mount (the EAP610 I run, or a current WiFi 7 EAP). Per-SSID VLAN tagging, an optional local controller, and the best cost-to-feature ratio.
Best for multi-AP homes: UniFi, for fast roaming and one-pane policy once you’re past two or three APs.
Budget entry point: the Omada EAP225. 802.11ac, PoE, VLAN-aware, and cheap.
Avoid for segmentation: basic consumer APs and most mesh kits (Deco, Eero). They dump every client into one VLAN.

Pair whichever AP you pick with a managed 802.1Q switch and an OPNsense or pfSense firewall, then map each SSID to its own VLAN. The rest of this guide is the full build, end to end.

Why VLAN-Aware Wi-Fi Matters for a Homelab

A flat network treats every device the same. Your laptop, your hypervisor, a $12 Wi-Fi light bulb, and your neighbor’s phone on guest Wi-Fi all sit in one broadcast domain. Any compromised device can scan for and reach anything else.

VLANs split that single network into isolated segments. Each VLAN is its own broadcast domain with its own IP range, its own DHCP scope, and its own firewall policy. The access point does the wireless half of the job: it broadcasts multiple SSIDs and tags each one with a VLAN ID (VID) before handing frames to the switch.

A sensible homelab segmentation looks like this:

Default (Trusted): Personal laptops, phones, admin access to Proxmox and the firewall
IoT: Smart plugs, cameras, TVs, anything with sketchy firmware and cloud dependencies
Guest: Internet-only, zero LAN access
Secure: VPN egress or sensitive services that should never touch the open internet directly
Homelab: Lab VMs, self-hosted services, Home Assistant

Here’s the important caveat. VLANs are an organization and policy tool, not a security guarantee on their own. They isolate broadcast domains, but a sloppy firewall rule can still expose traffic across segments. VLANs plus a default-deny firewall is the combination that protects you.

A ceiling-mount, PoE-powered, dual-band 802.11ac access point with a Gigabit uplink and Omada controller support. It handles 802.1Q VLANs for clean SSID-to-network mapping (Main/IoT/Guest) and delivers solid, reliable Wi-Fi for the price. The budget entry point into the Omada ecosystem.

Amazon Price: Loading...

Availability: Checking...

Contains affiliate links. I may earn a commission at no cost to you.

Choosing Your Access Point: Omada vs UniFi vs Basic

The access point is the piece that makes or breaks wireless VLAN support. Here’s how the realistic options stack up for a homelab.

Option	VLAN tagging	Controller needed	Best for
TP-Link Omada	Yes, per-SSID on most current models	Optional (local, hardware, or standalone)	One or two APs, best cost-to-feature ratio
UniFi (Ubiquiti)	Yes, trunks to UniFi switches work with no manual tagging	Yes (cloud or self-hosted)	Multi-AP houses, fast roaming, one-pane policy
Basic consumer AP	None	No	Nothing here. Every client lands in one VLAN
Mesh (Deco, Eero)	None or token only	App-based	Simple untrusted Wi-Fi with no segmentation needs

A few notes on the table. Omada APs let you enable multi-SSID, enable VLAN, and assign a VLAN ID (VID) to each SSID. That’s the whole workflow. It’s what I run, and the EAP610 has been reliable across five SSIDs. UniFi is a full ecosystem where the APs, switches, and gateways are designed to work together, at the cost of a steeper learning curve and a mandatory controller. A plain consumer AP with no VLAN support defeats the entire point of segmentation. And mesh kits are built for simplicity and automatic roaming. For a homelab where VLAN isolation is the whole point, mesh is the wrong tool.

📝

Note: If you want simplicity and low cost, choose Omada. If you want scalability and advanced policy across many APs, choose UniFi. If a vendor only sells mesh, look elsewhere.

A ceiling-mount WiFi 7 access point with a 2.5GbE PoE uplink, Omada controller support, and VLAN-aware SSIDs. Dual-band (2.4/5 GHz) with MLO-capable radios for lower latency. The mid-tier pick for homelab and home networks that want WiFi 7 throughput without the tri-band premium.

Amazon Price: Loading...

Availability: Checking...

Contains affiliate links. I may earn a commission at no cost to you.

The Supporting Cast: Switch, Router, and PoE

The AP can’t do this alone. You need two more pieces.

A Managed Switch

You must have a managed switch that supports 802.1Q VLAN tagging. Unmanaged consumer switches can’t tag frames with VLAN IDs. Good options include the TP-Link Easy Smart line, UniFi switches, and Netgear ProSAFE. An 8-port managed switch runs roughly $50 to $150.

A 16-port, fanless Gigabit switch with a metal chassis, web GUI, and the essentials (802.1Q VLANs, trunks, QoS, and IGMP snooping) without the price of a fully managed unit. It’s the budget workhorse for OPNsense and homelab builds that need solid VLAN segmentation across a lot of ports without spending triple digits.

Amazon Price: Loading...

Availability: Checking...

Contains affiliate links. I may earn a commission at no cost to you.

A Router or Firewall for Inter-VLAN Routing

VLANs isolate Layer 2, but something has to route between them and enforce policy at Layer 3. That’s your router or firewall: pfSense, OPNsense, or a UniFi Dream Machine. It creates a logical interface per VLAN tag, runs a DHCP scope per interface, and applies firewall rules per network. An OPNsense VLAN setup on a small mini-PC, or as a VM on Proxmox, handles all of this cleanly.

One tradeoff to understand. Consumer switches often route between VLANs in software, which can throttle inter-VLAN throughput to under 100 Mbps. High-end L3-capable switches offload that routing at line rate. For most homelabs, software routing is fine unless you do heavy cross-VLAN transfers, like frequent VM migrations or large file moves between your lab and NAS.

PoE Budget

If your AP is PoE-powered, check the switch’s PoE budget. A typical AP draws 15 to 30W. A 60W PoE switch can power two to four APs. Add up the wattage of every PoE device (APs plus cameras plus anything else) and confirm the switch can supply it. If you only have one AP and no PoE switch, a single PoE injector works fine. For multiple devices, a PoE switch is far more practical.

Phase 1: Plan Your VLAN Layout Before Touching Hardware

Skipping the planning step is the most common way these projects go sideways. Spend twenty minutes on paper first.

Define your VLANs and assign VIDs. A common scheme:

VLAN 1: Default
VLAN 10: IoT
VLAN 20: Guest
VLAN 30: Secure
VLAN 40: Homelab

Map SSIDs to VLANs. For example: “HomeNetwork” to VLAN 1, “IoT-Devices” to VLAN 10, “Guest-WiFi” to VLAN 20, “Secure-VPN” to VLAN 30.

Document IP ranges per VLAN. Keep it predictable: 192.168.1.0/24 for VLAN 1, 192.168.10.0/24 for VLAN 10, 192.168.20.0/24 for VLAN 20, and so on. Matching the third octet to the VID saves you headaches later.

Write a firewall intent checklist. For each VLAN, what does it actually need to reach? Default gets everything. IoT gets internet plus maybe one homelab service. Guest gets internet only. Homelab gets internal services plus internet. Document the cross-VLAN flows you intend to allow, like Homelab reaching IoT on port 8123 for Home Assistant.

Plan your management VLAN if you run OPNsense as a VM on a single-NIC Proxmox host. This one bites people. If your Proxmox box has only one physical NIC, OPNsense runs as a VM behind that same NIC, and a careless trunk change can lock you out of both the firewall and the hypervisor at once. Decide up front which VLAN carries Proxmox and OPNsense management, keep that VLAN reachable from a trusted access port, and never strip its tag from the trunk while you still need it. More on the Proxmox side later.

Prep the boring stuff. Configure an NTP server on the router, identify your DNS resolvers (internal for homelab, public for guest), and write out a port map: which switch port goes to the AP, which to the router, which are access ports for cameras or the NAS. Label your cables as trunk or access before you plug anything in.

Phase 2: Configure the Managed Switch

With the plan written, the switch comes first because everything else trunks through it.

Create the VLAN IDs. Log into the switch web UI, find the 802.1Q VLAN section, and create VLANs 1, 10, 20, 30, and 40. Label each one clearly.
Configure trunk ports. Identify the uplink ports: one to the AP, one to the router or firewall. Set both as tagged for all VLANs. Set the PVID to 1, or disable the native VLAN entirely if your switch allows it.
Configure access ports. Assign every remaining port to its intended VLAN as untagged, with the PVID matching that VLAN. For example, ports 3 and 4 untagged on VLAN 10 (PVID 10) for IoT cameras, ports 5 and 6 untagged on VLAN 40 (PVID 40) for the NAS.
Save and verify. Save the config, then check the VLAN membership table. Trunk ports should carry all VLANs; access ports should carry only their assigned VLAN. Plug a laptop into an access port and confirm it lands in the right IP range.

The trunk-vs-access distinction is the core concept here. A trunk port carries multiple tagged VLANs and connects switches, APs, and routers. An access port carries one untagged VLAN and connects an end device that knows nothing about VLANs.

Phase 3: Configure the Access Point

Now the wireless half. This example uses a TP-Link Omada AP; UniFi follows the same logic through its controller.

Connect and access the AP. Plug the AP into your laptop via Ethernet. A standalone Omada EAP610 defaults to DHCP, and falls back to 192.168.0.254 if no DHCP server answers. Set your laptop’s IP to that same subnet (something like 192.168.0.10), then open the AP’s web UI in a browser.
Enable multi-SSID and VLAN. Go to Wireless then Wireless Settings. Switch the operation mode to Multi-SSID and check Enable VLAN.
Create SSIDs and assign VIDs. SSID 1 “HomeNetwork” gets VID 1, SSID 2 “IoT-Devices” gets VID 10, SSID 3 “Guest-WiFi” gets VID 20, SSID 4 “Secure-VPN” gets VID 30. Save.
Set the AP uplink as a trunk. The AP’s uplink port to the switch must be tagged for all VLANs, and it must plug into a trunk port on the switch. Reboot the AP if needed.
Test wireless association. Connect a phone to “HomeNetwork” and confirm it gets a 192.168.1.x address. Connect another device to “IoT-Devices” and confirm 192.168.10.x. That proves each SSID lands in the right VLAN. Don’t test cross-VLAN isolation yet. Nothing is blocking that traffic until you configure firewall rules in Phase 4.

⚠️

Warning: The first time I set up my Omada AP, I forgot to set the AP uplink port as tagged. The AP itself was fine, but every SSID dumped clients onto the native VLAN regardless of the VID I assigned. The fix was one checkbox on the AP’s uplink config. If your SSIDs all land in the same VLAN, check the AP uplink before you touch anything else.

A ceiling-mount WiFi 7 tri-band (2.4/5/6 GHz) access point with Multi-Link Operation, a multi-gig PoE uplink, and full Omada controller support including fast roaming and band steering. VLAN-aware SSIDs map cleanly onto OPNsense firewall zones. The top-tier pick for dense homes or offices where the dual-band AP starts to show congestion.

Amazon Price: Loading...

Availability: Checking...

Contains affiliate links. I may earn a commission at no cost to you.

Phase 4: Configure the Router or Firewall

This is where inter-VLAN routing and policy live. The example uses OPNsense; pfSense is nearly identical.

Create VLAN Interfaces

In the firewall UI, go to Interfaces then Assignments and create a virtual interface for each VLAN tag: em0.1, em0.10, em0.20, em0.30, em0.40. Assign each one a static IP that becomes the gateway for that VLAN, like 192.168.10.1 for VLAN 10.

Enable DHCP per VLAN

Under Services then DHCP Server, enable DHCP on each VLAN interface and set a range, for example 192.168.10.100 to 192.168.10.254. Set DNS servers per interface: an internal resolver for the Homelab VLAN, public DNS for Guest. Scoping DNS per VLAN prevents clients from resolving through the wrong resolver.

Set Static IPs for Servers and VMs

While you’re in the DHCP Server section, handle your fixed-address devices. Homelab services like a NAS or a Home Assistant VM want a stable IP, and you have two clean ways to get one. Use a DHCP reservation on OPNsense, which maps a MAC address to a fixed IP, or set a manual static IP on the device itself, chosen from outside the DHCP range. For example, if your Homelab DHCP pool is 192.168.40.100 to 254, assign your NAS 192.168.40.50 manually. I prefer reservations for VMs because the config lives in one place on the firewall, right next to the DHCP scope from the previous step.

Configure Firewall Rules

This is the part that actually enforces isolation. Follow these golden rules:

Allow established and related connections so replies flow automatically.
Deny cross-segment initiation by default.
Grant “LAN to anywhere” only to the trusted Default network.
Add explicit allow rules for the specific services you need.

A concrete example: block VLAN 10 (IoT) from initiating any connection to VLAN 40 (Homelab), then add one narrow rule allowing VLAN 40 to reach a specific IoT device on port 8123 for Home Assistant. Block VLAN 20 (Guest) from every internal VLAN while allowing it out to the internet.

Test Routing and Isolation

Now that firewall rules exist, this is the test that was skipped in Phase 3. Connect a device to the Default SSID and try to ping a device on the IoT SSID: it should fail. Ping the router’s IoT interface (192.168.10.1): it should succeed, because gateway access is allowed. Confirm every VLAN has working internet.

Proxmox and OPNsense Integration

Running this on Proxmox adds one wrinkle. This is where the Proxmox VLAN setup ties into everything you built in the earlier phases.

In Proxmox, create a VLAN-aware Linux bridge. Under Datacenter then your node then System then Network, edit the bridge (usually vmbr0) and check “VLAN aware”. Once the bridge is VLAN-aware, set the VLAN Tag field on each VM’s network device to the VID you want, and the VM inherits that VLAN’s membership. A Home Assistant VM tagged with VID 40 gets an IP from the Homelab DHCP scope automatically.

If you run OPNsense as a VM rather than bare metal, give it two interfaces: one for WAN (untagged, or tagged to your WAN VLAN), and one for LAN connected to the VLAN-aware bridge. OPNsense then handles all inter-VLAN routing and firewall policy for both your physical and virtual machines. The physical switch trunks to the Proxmox host, and every VLAN-aware VM downstream picks up its tag from the bridge.

One more warning if you only have a single physical NIC on the Proxmox host. Both Proxmox management and the OPNsense VM share that one link, so a bad trunk change can cut you off from the hypervisor and the firewall in the same move. This is why Phase 1 told you to plan a management VLAN. Keep that VLAN tagged on the trunk, keep a trusted access port that can reach it, and make trunk changes when you have console access to the Proxmox host as a fallback.

AP Placement: Ceiling vs Desk

Where the AP physically sits affects coverage more than people expect.

Ceiling mount gives better coverage with fewer obstacles between the radio and your devices, and it looks cleaner. It needs PoE or ceiling-run power.

Desk placement is easier for testing and troubleshooting since the AP is right there, but you may get dead zones and visible cable runs.

For a homelab, if you have PoE, mount it on the ceiling. If it sits on a desk or other horizontal surface, make sure a PoE injector or wall outlet is within reach. If you need more than one AP, stagger them across rooms or floors and use the same SSID and VLAN per network so clients roam between them without dropping the connection.

Troubleshooting Common Failures

Most VLAN Wi-Fi problems trace back to a handful of misconfigurations. Here are the ones I’ve hit or watched others hit.

Devices not getting an IP. Check three things in order: DHCP is enabled on the router’s VLAN interface, the DHCP scope has free addresses, and the switch access port PVID matches the device’s VLAN.

Devices landing in the wrong VLAN. Verify the AP’s SSID-to-VID mapping, then check the switch access port PVID. A PVID that doesn’t match the intended VLAN is the single most common cause: frames arriving untagged get stamped with the port’s PVID, so a wrong PVID means a wrong IP range.

Mismatched native VLANs. If two trunk ports have different native VLANs, untagged frames silently land in the wrong segment. The fix is to tag everything and skip the native VLAN where you can.

No internet on a VLAN. Confirm the router has a default route to WAN and that firewall rules permit internet egress from that VLAN.

Slow inter-VLAN traffic. If transfers between VLANs crawl, the switch is probably routing in software. Accept it for a homelab, route through a capable CPU host like your Proxmox box, or buy L3 hardware.

DNS not resolving. Make sure DNS servers are configured on each VLAN interface and that the firewall allows port 53. Verify the client is using the expected resolver with nslookup or dig.

You locked yourself out. If you misconfigure a trunk port and lose connectivity, most switches let you revert to factory defaults or reach the CLI over a serial console. Export your switch and firewall configs at every milestone so you can roll back instead of starting over.

Stale firmware. Older AP and switch firmware sometimes ships VLAN bugs. Update before you rely on the setup in production.

Frequently Asked Questions

➤ What are the best Wi-Fi access points for a homelab?

Controller-based access points that support per-SSID VLAN tagging. For most homelabs a TP-Link Omada ceiling-mount AP (such as the EAP610 or a current WiFi 7 EAP) is the best balance of price and features; step up to UniFi once you run several APs and want fast roaming and unified policy. Avoid basic consumer APs and mesh kits like Deco or Eero, which can’t tag SSIDs to separate VLANs.

➤ Do I need a managed switch to use VLANs?

Yes. Unmanaged consumer switches cannot tag 802.1Q frames, so they cannot carry multiple VLANs on one link. You need a managed switch such as a TP-Link Easy Smart, UniFi switch, or Netgear ProSAFE that exposes VLAN configuration in its UI.

➤ Can I use a mesh Wi-Fi system like Eero or Deco with VLANs?

Usually not. Most mesh systems have no VLAN tagging or only very limited support. If VLAN isolation is your goal, use a controller-based AP like UniFi or TP-Link Omada instead. Mesh is fine only for a simple untrusted network with no segmentation needs.

➤ What is the difference between a VLAN ID and a PVID?

The VLAN ID (VID) is the tag carried inside 802.1Q frames on a trunk. The PVID (Port VLAN ID) is the untagged VLAN assigned to a switch port: any frame arriving untagged gets stamped with that port’s PVID. On access ports, always confirm the PVID matches the device’s intended VLAN.

➤ How do I get a static IP for a Proxmox VM or NAS?

Two ways. Set a DHCP reservation on your firewall that maps the device’s MAC address to a fixed IP, or configure a manual static IP on the device itself, chosen from outside the DHCP range. For a homelab, reservations keep all the config in one place on the router.

➤ Do VLANs give the same security as physically separate networks?

No. VLANs isolate broadcast domains and make policy easy to apply, but a single misconfigured firewall rule can still expose traffic across segments. Treat VLANs as an organization and policy layer, and always pair them with a default-deny firewall ruleset.

Wrapping Up

A VLAN-aware wireless setup turns a flat, fragile homelab network into something you can trust. The recipe is consistent: a controller-based AP that tags SSIDs to VLANs, a managed 802.1Q switch that trunks them, and an OPNsense or pfSense firewall that routes between VLANs and enforces a default-deny policy. Skip mesh if isolation matters, plan your VLAN layout on paper first, and verify each phase before moving to the next.

Start small. One AP, one managed switch, five VLANs, and a firewall is enough to isolate your IoT junk from your hypervisor. Once that’s stable, you can add APs for roaming, tighten firewall rules per service, and integrate your Proxmox VLAN bridge so VMs land in the right segment automatically.

Next steps: back up your switch and firewall configs, document your final VLAN and IP layout, and if you’re running OPNsense on Proxmox, check our other guides on hardening that firewall VM and on building out the rest of your homelab stack.

Build Your Own NAS Storage with MergerFS (2026 Guide)

Sun, 03 May 2026 13:46:27 -0600

If you’ve ever stared at six mismatched hard drives of different sizes and wished there was a way to smash them into one big folder without buying into the ZFS religion, MergerFS is the answer. It pools whatever junk you have lying around and presents it as a single mount point that Jellyfin, Sonarr, and Radarr treat like one giant disk. When you build your own NAS storage for media, this is the path that scales without buying 8 matched drive you don’t need. Especially now with HDD prices through the roof.

This 2026 guide walks through what MergerFS does, why it beats ZFS for a movie/TV library, the creation policies that matter (mfs, lfs, epff, epmfs, pfrd), how to bolt SnapRAID on for parity, and exactly what to put in fstab so your NAS will boot cleanly even when one disk is misbehaving.

💭

TL;DR: MergerFS pools multiple drives into one mount without ZFS’s upfront costs, lets you mix sizes and brands, and pairs cleanly with SnapRAID for parity. Use category.create=mfs for a balanced media pool, epmfs if you organize libraries by top-level folder, and always set minfreespace plus allow_other before pointing Docker at it.

I set this up on an and old gamming rig I had in the closet and through in four 18TB, two 24TB, drives plus a 4TB WD Red I refused to get rid of. The same fstab line has survived two drive swaps and several kernel upgrades without me having to do anything. Everything below is what I ran on that box, with the gotchas that actually bit me called out under the “Tips and Warning” boxes.

What MergerFS Is (And Why It Is Not RAID)

MergerFS is a FUSE-based union filesystem written by Antonio “trapexit” Musumeci. It takes a list of source directories (usually individual drives mounted at /mnt/pool/disk1, /mnt/pool/disk2, etc.) and presents them as one merged directory tree at a target mount like /mnt/storage. The drives keep their own filesystems (ext4, XFS, ZFS, Btrfs, whatever), keep their own data, and stay independently readable if MergerFS ever disappears. Pull a drive out, slap it into a USB dock on a different machine, and your files are right there in plain folders.

That last point is why it eats traditional RAID and ZFS for lunch in a media server context.

The case against RAID for a movie library

Traditional RAID (RAID5, RAID6, RAIDZ) treats your drives as one striped volume. The wins are real: parallel read speed, transparent fault tolerance, and a single namespace. The losses are also real, and they hit homelabs harder than they hit datacenters:

Same-batch failure risk: drives bought together tend to die together. A second failure during a multi-day RAID5 rebuild on 14TB+ disks is a good way to lose everything.
No mismatched sizes: most arrays force the smallest drive’s capacity on every member. Your 14TB sits there pretending to be 4TB.
Expansion is painful: adding a drive usually means a full reshape or a brand-new vdev.
Total loss on catastrophic failure: lose enough drives in the wrong combination and the entire array is gone, including everything that sat on the healthy drives.

MergerFS sidesteps all four. Each drive is its own filesystem with its own files. If a drive dies, you lose only what was on that drive, not the pool. Mismatched sizes are the design, not a workaround. Adding storage is “format new drive, add it to the wildcard, remount.” That last property is why the unraid and jbod school of media servers exists at all: pooling without striping, so growth and failure are both easy on your sanity and wallet.

The tradeoff is honest. MergerFS doesn’t give you striped read speeds. It doesn’t transparently survive a drive failure on its own (you need SnapRAID or backups for that). Small random writes are slower than a native filesystem because they go through FUSE. For a media server where files are huge, written once, and read sequentially, none of those matter. For a database or a VM datastore, they matter a lot. Use the right tool.

⚠️

Warning: Don’t use a MergerFS pool as a download or torrent target. These small reads and writes will cause the pool to slow to a crawl. Use fast storage like SSD or NVMe drives as the download target and then move the files to the MergerFS pool once it is downloaded. Sornarr and Radarr are great at post-processing and moving to a storage pool once the download is completed.

Prerequisites and Drive Prep

Before MergerFS does anything useful, your drives need to be partitioned, formatted, and mounted individually. The pool is a view. The data lives on the source filesystems. You should be comfortable running commands as root and editing /etc/fstab. If sudo and vim /etc/fstab make you nervous, fix that first.

0. Check drive health before you touch it

Look. If you’re adding shucked drives, recertified drives, drives from eBay, or anything that has been sitting in a closet, run a health check first. Formatting a dying disk is a great way to lose hours and discover the problem at 80% of a SnapRAID sync.

Install smartmontools and run a short test on each drive:

sudo apt install smartmontools
sudo smartctl -t short /dev/sdb

To see the progress and review the results:

sudo smartctl -l selftest /dev/sdb
sudo smartctl -a /dev/sdb

You want PASSED under the SMART overall-health status, low values for Reallocated_Sector_Ct, Current_Pending_Sector, and Offline_Uncorrectable, and a power-on hours count that matches what the seller advertised. If anything looks ugly, run a long self-test (sudo smartctl -t long /dev/sdb, then check back in a few hours with sudo smartctl -l selftest /dev/sdb) before committing the disk to the pool.

1. Install MergerFS from upstream, not apt

The Ubuntu/Debian repository version lags the upstream release by months and is missing fixes that matter (the noforget and inodecalc improvements, in particular). Pull the latest .deb from the GitHub releases page GitHub mergerfs releases:

wget https://github.com/trapexit/mergerfs/releases/download/2.42.0/mergerfs_2.42.0.debian-trixie_amd64.deb
sudo dpkg -i mergerfs_2.42.0.debian-trixie_amd64.deb
mergerfs --version

Substitute trixie for bookworm/forky/etc. depending on your distro. Verify the version is current (2.42.0 at the time of writing).

2. Partition and format each drive

You can use ext4 for media drives because it’s boring, well-supported, and resizes cleanly. I use XFS, I find it offers slightly better large-file performance. Avoid ZFS on individual MergerFS branches unless you specifically want ZFS features, because the FUSE layer eats most of the benefits.

sudo parted /dev/sdb -- mklabel gpt
sudo parted /dev/sdb -- mkpart primary ext4 0% 100%
sudo mkfs.ext4 -L disk1 /dev/sdb1
sudo mkdir -p /mnt/pool/disk1

Repeat for each disk, incrementing the label and mount point. Add each one to /etc/fstab by UUID:

sudo blkid /dev/sdb1
# UUID="abc123..." TYPE="ext4"

If blkid returns nothing, the partition table didn’t get written. Re-run the parted commands and check lsblk to confirm /dev/sdb1 exists before formatting.

UUID=abc123... /mnt/pool/disk1 ext4 defaults,noatime,nofail 0 2
UUID=def456... /mnt/pool/disk2 ext4 defaults,noatime,nofail 0 2
UUID=ghi789... /mnt/pool/disk3 ext4 defaults,noatime,nofail 0 2

The nofail is non-negotiable. Without it, a single failed disk will drop your server into emergency mode at boot. Reboot and run df -h to confirm every disk shows up before going further.

3. Decide on a layout

Two layouts dominate. Pick one before you copy data, because changing later is annoying.

Flat pool: every disk has the same top-level structure (or no structure at all) and MergerFS distributes new files across them by free space. Use category.create=mfs. Simplest, works for everyone.
Path-aware pool: every disk has the same top-level folder names (/mnt/pool/disk1/movies/, /mnt/pool/disk1/tv/, /mnt/pool/disk2/movies/, /mnt/pool/disk2/tv/) and MergerFS routes new files to the disk that already has the matching path. Use category.create=epmfs. Better for “I want all of Breaking Bad on one disk so a failure only loses Breaking Bad” thinking.

I run mfs for my library.

The flagship IronWolf Pro for multi-bay NAS enclosures. 7200 RPM CMR with a 512 MB cache and a 550 TB/year workload rating lets you stack three or four of these in a MergerFS pool without cooking them. A 5-year warranty and 3 years of Seagate Rescue data recovery are included, because when (not if) one dies, you will want a parachute.

Amazon Price: Loading...

Availability: Checking...

Contains affiliate links. I may earn a commission at no cost to you.

A pool of identical drives isn’t the goal here. But if you’re starting fresh and want to seed a multi-bay build with one or two big disks you can grow around, this is the slot they fit into.

The Policy Cheat Sheet (mfs vs lfs vs epff vs epmfs vs pfrd)

This is the part of MergerFS that confuses everyone. There are policies for create, search, and action operations. For media servers, you almost always only care about category.create. The relevant create policies, in plain English:

mfs (most free space): write the new file to the branch with the most free space. Best general-purpose pick. Spreads writes evenly so disks fill at roughly the same rate.
lfs (least free space): write to the branch with the least free space (that still has room). Fills disks one at a time. Useful if you want most of your drives spun down most of the time, at the cost of zero balancing.
epff (existing path, first found): only write to a branch that already has the parent path; pick the first one found. Path-aware but order-dependent.
epmfs (existing path, most free space): only write to a branch that already has the parent path; pick the one with the most free space among those. Path-aware and balanced. The right pick for organized libraries.
pfrd (proportional fill, random distribution): weighted random pick by percentage free. The default in current MergerFS releases. Statistically balances drives without the “always picks the same disk” failure mode that mfs can have when sizes are mismatched [trapexit docs].

For the build-your-own-NAS-storage crowd: start with mfs if your library is flat, epmfs if you organize by /movies, /tv, /music folders, and only deviate if you’ve got a specific reason. Ignore lfs unless you have actually measured the spin-up cost on your hardware.

⚠️

Warning: I spent a week debugging “why is disk1 always 90% full and disk4 always empty” before I realized I was using epff with a single existing path on disk1. Switched to mfs and balance restored itself within a few weeks of new downloads. If you do not need path stickiness, do not opt into it.

fstab Configuration That Survives Reboots

The fstab line is where most first-time MergerFS setups break. Here is the line I run on Debian 13, broken down option by option:

# List EVERY source disk in x-systemd.after.
/mnt/pool/disk* /mnt/storage fuse.mergerfs defaults,allow_other,inodecalc=path-hash,cache.files=off,dropcacheonclose=true,category.create=epmfs,minfreespace=50G,fsname=mergerfs,nofail,x-systemd.after=/mnt/pool/disk1,x-systemd.after=/mnt/pool/disk2,x-systemd.after=/mnt/pool/disk3 0 0

/mnt/pool/disk* (the source): glob expansion picks up every numbered disk mount. Add a new disk by mounting it at /mnt/pool/disk4.
defaults: standard mount options.
allow_other: lets users other than root see the pool. Required for Docker containers, Jellyfin, Sonarr, Radarr, Samba, NFS, and pretty much anything useful. Without it your apps see an empty directory.
inodecalc=path-hash: hashes the relative path of the entry in question. This means the inode value will always be the same for that file path.
cache.files=off + dropcacheonclose=true: disables FUSE page caching and drops kernel cache when files close. Counter-intuitive but correct for media. The kernel already caches reads from the underlying filesystems, and the FUSE cache layer mostly causes stale-data bugs in apps that mmap files (Jellyfin’s metadata scanner is one).
category.create=epmfs: see the policy section above.
minfreespace=50G: refuse to write to a branch with less than 50GB free. Stops MergerFS from cramming the last 200MB onto a nearly-full disk and producing ENOSPC errors mid-import.
fsname=mergerfs: cosmetic, makes df -h show mergerfs instead of a random path.
nofail: don’t block boot if the source disks aren’t ready.
x-systemd.after=/mnt/pool/diskN: tells systemd to wait for those source mounts before trying the pool. Without this, on slow-spinning HDD systems, fstab tries to mount the pool before the disks are mounted, and you get a ghost empty pool. List every disk in the pool.

The SnapRAID + MergerFS calculator builds this exact fstab line for your disk layout, plus the snapraid.conf and parity sizing to go with it.

Generate your fstab line

After editing /etc/fstab:

sudo systemctl daemon-reload
sudo mount -a
df -h /mnt/storage

You should see the combined size of all source disks. Write a test file, then check which physical disk it landed on:

echo "test" > /mnt/storage/hello.txt
ls -la /mnt/pool/disk*/hello.txt

Once the pool mounts cleanly, the next thing you’ll care about is what’s under the hood. If you’re running drives off motherboard SATA today, you’ll hit the port count ceiling fast. The fix is an HBA in IT mode.

An 8-port 62 Gb/s SAS/SATA HBA that, when flashed to IT firmware, passes each drive straight to the OS (no RAID). Perfect for MergerFS, ZFS/TrueNAS, Unraid, and clean JBOD setups.

Amazon Price: Loading...

Availability: Checking...

Contains affiliate links. I may earn a commission at no cost to you.

With the HBA sorted, the fstab line above is portable: the source glob doesn’t care whether the drives hang off motherboard SATA or an LSI card.

Performance Tuning for Jellyfin, Sonarr, and Radarr

The defaults above are tuned for media. A few extra tweaks help when you’re pushing 4K remuxes around.

Permissions and ownership

Pick a UID/GID for your media stack and use it everywhere. I use media:media (UID 1000, GID 1000) on the host, mapped through every Docker container with PUID=1000/PGID=1000. Then chown the pool:

sudo chown -R media:media /mnt/storage
sudo chmod -R 775 /mnt/storage

Mismatched UIDs between host and containers are the number-one cause of “Sonarr can see the file but Jellyfin can’t play it.” Pick one and stick with it.

Optional SSD cache branch

MergerFS doesn’t have a true write-back cache, but you can fake one with a “tiered cache” pattern. Mount an SSD at /mnt/cache, build a second pool that prefers the SSD for new writes, then rsync nightly from cache to spinning drives. The community tool mergerfs.cache.tool (from the trapexit/mergerfs-tools repo) automates the move.

# Two pools: one for writes (SSD-first), one for reads (everything).
/mnt/cache:/mnt/pool/disk* /mnt/writes fuse.mergerfs defaults,allow_other,use_ino,category.create=ff,minfreespace=20G,fsname=mergerfs-writes,nofail 0 0
/mnt/cache:/mnt/pool/disk* /mnt/storage fuse.mergerfs defaults,allow_other,use_ino,category.create=epmfs,minfreespace=50G,fsname=mergerfs,nofail 0 0

Then schedule the move with cron:

# /etc/cron.d/mergerfs-cache
0 3 * * * root /usr/bin/mergerfs.cache.tool -m /mnt/cache -p /mnt/pool/disk -t 80 >> /var/log/mergerfs-cache.log 2>&1

The -t 80 flag tells the tool to drain the cache when it crosses 80% full. Flag names and behavior have shifted across mergerfs-tools releases, so run mergerfs.cache.tool --help against your installed build before trusting that exact line. For most homelabs this is over-engineering. For a server that ingests a lot of new content during the day and wants the spinning disks parked, it earns its keep.

If you’re still planning the chassis, port count and drive bays drive every later decision. An eight-bay case with room for an HBA gives you headroom for two or three drive generations of growth.

A budget ATX mid-tower built with storage in mind. 10 drive bays, full ATX board support, and room for HBAs and SATA expanders. The right enclosure for a DIY NAS that needs to grow beyond 4-6 drives without moving to expensive rackmount chassis.

Amazon Price: Loading...

Availability: Checking...

Contains affiliate links. I may earn a commission at no cost to you.

SnapRAID: The Parity Layer MergerFS Does Not Provide

MergerFS by itself protects you from nothing. Lose a disk, lose its files. SnapRAID adds parity, checksums, and silent-corruption detection on a schedule, which fits write-once-read-many media perfectly.

📝

Note: Important, read this before you configure anything: SnapRAID parity is a snapshot, not real-time. Anything written or changed since the last sync is unprotected. If you import 500GB this afternoon and a disk dies before tonight’s sync runs, those 500GB are gone. Plan your sync cadence and your manual-sync habits with that in mind, then read on.

Install:

sudo apt install snapraid

Configure /etc/snapraid.conf:

# Parity disk(s): must be at least as large as your largest data disk.
# NOT part of the MergerFS pool.
parity /mnt/pool/parity1/snapraid.parity
# Content files: SnapRAID writes the file list and checksums here.
# Keep one copy off the data disks plus one on each data disk for redundancy.
# If a data disk dies, you still have a content file on the surviving disks.
content /var/snapraid/snapraid.content
content /mnt/pool/disk1/snapraid.content
content /mnt/pool/disk2/snapraid.content
# Data disks: point to the underlying mounts, NOT the pool path.
# SnapRAID needs the raw filesystem to compute parity correctly.
data d1 /mnt/pool/disk1
data d2 /mnt/pool/disk2
data d3 /mnt/pool/disk3
# Excludes: skip transient files and the downloads branch.
exclude *.unrecoverable
exclude /tmp/
exclude /lost+found/
exclude downloads/

The parity disk is not part of the MergerFS pool. It sits separately, dedicated to parity, and must be at least as large as your largest data disk. The data d1 /mnt/pool/disk1 lines point to the source disks rather than the pool, because SnapRAID needs to see the underlying filesystem to compute parity correctly.

Initial sync:

sudo snapraid sync

This builds the parity file. On a multi-TB library, expect this to take many hours. Schedule a regular sync + scrub via cron or a systemd timer. The community wrapper snapraid-runner (Python) handles “sync, then scrub a percentage, then email me” with one config file. That is what I run nightly.

When a drive dies, you replace it, mount the new disk at the same path, and run snapraid fix -d d2 to rebuild only the dead disk’s contents. No array reshape. No rebuild stress on the surviving disks.

ℹ️

Info: Run a manual snapraid sync after big imports. The cron job covers steady-state. The night you dump a 4TB archive onto the pool needs a manual sync of its own.

Upgrading and Replacing Drives Without Rebuilds

This is the killer feature, and it’s genuinely as simple as advertised.

Adding a new drive

# 0. Check the new drive's health before you trust it
sudo smartctl -a /dev/sde

# 1. Partition, format, mount
sudo parted /dev/sde -- mklabel gpt mkpart primary ext4 0% 100%
sudo mkfs.ext4 -L disk5 /dev/sde1
sudo mkdir /mnt/pool/disk5
sudo blkid /dev/sde1 # grab UUID

# 2. Add to fstab (same pattern as the other disks)
echo "UUID=newuuid /mnt/pool/disk5 ext4 defaults,noatime,nofail 0 2" | sudo tee -a /etc/fstab
sudo mount /mnt/pool/disk5

# 3. If using epmfs, mirror your top-level folders so files route correctly
sudo mkdir -p /mnt/pool/disk5/{movies,tv,music}
sudo chown media:media /mnt/pool/disk5/{movies,tv,music}

# 4. Remount the pool to pick up the new branch
sudo umount /mnt/storage
sudo mount /mnt/storage

# 5. Add it to snapraid.conf as data d5 /mnt/pool/disk5, then sync
sudo snapraid sync

Total downtime: a few seconds during the umount/mount. New writes start landing on the new drive immediately because it has the most free space.

Replacing a failing drive

If smartctl is screaming and the disk is still readable:

# 1. Mount new disk at /mnt/pool/disk2-new
# 2. rsync the dying disk to it
sudo rsync -aHAX --info=progress2 /mnt/pool/disk2/ /mnt/pool/disk2-new/
# 3. Unmount old, mount new at the same path
# 4. Update fstab UUID, sudo mount /mnt/pool/disk2
# 5. snapraid sync (parity is unchanged because data is the same)

If the disk is dead and unreadable, skip the rsync and let SnapRAID rebuild instead:

# 1. Replace physical disk, format, mount at /mnt/pool/disk2
# 2. Run snapraid fix to rebuild that disk's contents from parity
sudo snapraid -d d2 -l fix.log fix
sudo snapraid -d d2 -l check.log check
sudo snapraid sync

This is the moment when SnapRAID earns its keep. Without it, those files are gone.

One more piece you’ll want before you start swapping drives in earnest: the right cable between your HBA and the bays.

A Mini-SAS “forward breakout” cable that lets one HBA/controller SFF-8643 port connect to four individual SATA drives. Use this when your HBA has an internal Mini-SAS port. It isn’t the “reverse breakout” cable for feeding a backplane from motherboard SATA, so check which direction you need before ordering.

Amazon Price: Loading...

Availability: Checking...

Contains affiliate links. I may earn a commission at no cost to you.

Troubleshooting Common MergerFS Failures

“Permission denied” or “no such file” from Docker

You forgot allow_other. Add it to the fstab options, remount, restart the container. If you still see denials, check that the container’s PUID/PGID match the owner of files in the pool.

Pool shows as empty after reboot

The pool mounted before the source disks did. Add x-systemd.after=/mnt/pool/diskN for every required disk to the fstab options, run systemctl daemon-reload, reboot to verify. If you only listed disk1 and disk1 is the slow or dead one, you will reproduce the bug.

`df` shows weird sizes

If your pool is at /mnt/storage and a source disk is also visible inside the pool path (a common typo: /mnt/pool/disk* matching /mnt/pool/disk-old-backup), you’ll see double-counted space. Make sure your wildcard only matches active source disks.

Slow writes on large files

Try direct_io,noforget instead of cache.files=off,dropcacheonclose=true. direct_io bypasses the page cache entirely on the FUSE side, which on modern drives (200MB/s+ sequential) is usually a wash or slight win. noforget reduces inode churn.

“Stale file handle” after long-running operations

Almost always a use_ino issue. Make sure it’s set. If the problem persists, check that the underlying filesystems all support consistent inodes (ext4, XFS yes; some FAT variants no).

SnapRAID sync warns about too many changed files

SnapRAID has a default threshold for how many deletes/moves it’ll accept without a --force-empty or similar flag. If you reorganized your library, this is correct, paranoid behavior. Read the warning, confirm it matches what you actually did, then run with the suggested flag.

Frequently Asked Questions

➤ How do I add a new drive to MergerFS without losing data or rebuilding?

Partition and format the new drive with ext4 or XFS, add it to /etc/fstab using a label or UUID, and mount it at the next sequential path like /mnt/pool/disk5. Because your pool source is a glob (/mnt/pool/disk*), MergerFS picks up the new branch on the next pool remount. No rebuild, no downtime beyond the brief unmount.

➤ Should I use mfs or epmfs for a media server with separate movies and TV folders?

Use epmfs if you want files routed to the disk that already contains the matching top-level folder (so all of one show stays together). Use mfs if your library is flat or you don’t care about per-disk locality. epmfs gives you cleaner failure domains; mfs gives you simpler balancing. Both are fine; pick one and stick with it.

➤ Does MergerFS work with existing data on drives, and how does it handle mismatched sizes?

Yes. Drives can already hold data when you add them to the pool; MergerFS exposes whatever is there and unifies the namespace. Mismatched sizes are a core design assumption. A 4TB and a 14TB drive contribute their actual capacity, and create policies like mfs and pfrd handle the asymmetry without favoritism.

➤ Why pair MergerFS with SnapRAID instead of using ZFS or RAID?

ZFS and RAID strip away the things that make MergerFS attractive for media: mismatched drive sizes, drive-by-drive expansion, and per-disk failure isolation. SnapRAID adds parity and silent-corruption detection without forcing you to give up any of those wins. For write-once-read-many media libraries on commodity drives, the combination is hard to beat.

➤ What happens if a drive fails in MergerFS, do I lose everything like RAID5?

No. Each drive is its own filesystem with its own files. A dead drive takes only its own contents with it; the rest of the pool keeps serving normally. With SnapRAID layered on, you can rebuild the dead drive’s contents from parity onto a replacement. Without SnapRAID, you lose only that drive’s files and the rest of the pool keeps serving.

Wrapping Up

MergerFS solves a specific problem: pooling commodity drives into one mount for a Linux media server, without inheriting RAID’s brittleness or buying matched-drive sets you don’t need. Pair it with SnapRAID for parity, set category.create=mfs or epmfs based on your library layout, lock down the fstab options (allow_other, use_ino, cache.files=off, minfreespace=50G, nofail, and an x-systemd.requires entry per source disk), and use the same UID/GID across host and containers. That stack will outlive several drive generations.

Next steps if you’re building this out:

Read trapexit’s official docs at GitHub mergerfs releases for the full list of policies and runtime options.
For ongoing health monitoring, run smartctl checks on each source disk via a weekly cron and a snapraid scrub on 5-10% of the pool nightly.

Build your own NAS storage that grows with you. The first time you swap a 4TB for a 14TB without anything noticing, you’ll understand why the unraid and jbod approach has stuck around.

Mount a Network Drive in Proxmox LXC the Right Way

Thu, 23 Apr 2026 06:14:52 -0600

If you’re running a homelab on Proxmox and still spinning up full VMs for every little service, you’re burning RAM for no reason.

LXC containers give you near bare-metal performance for a fraction of the overhead. For Pi-hole, Nginx, Jellyfin, Sonarr, or qBittorrent, they sit in the sweet spot between “full VM” and “Docker everywhere.”

Then you try to mount your network share into an LXC. Files show up owned by nobody. Sonarr refuses to move media. Jellyfin logs fill with permission errors.

Don’t ask me how I know. I migrated half my stack from VMs to LXCs to “save resources” without really understanding UID mapping. That afternoon was my crash course in how unprivileged containers work.

This guide will save you that afternoon.

We’ll cover:

When to choose LXC vs VM
Privileged vs unprivileged containers
UID/GID mapping basics
How to mount a network share in Proxmox the right way
Making mounts persistent across reboots
Bind mounts vs NFS vs SMB tradeoffs
Backups, snapshots, and moving containers
How to move an LXC from external drive to local Proxmox storage safely

💭

TL;DR: Use unprivileged LXC containers for lightweight services on Proxmox. Mount storage on the host and bind it into the container. Understand UID/GID mapping before you touch your NAS, or you’ll spend an afternoon chasing permission errors that were never really permission errors.

When to Use an LXC Instead of a VM

LXC containers use OS-level virtualization. They share the host kernel. That makes them lightweight and fast compared to full VMs.

For most homelab services, LXC is the right call. Use one when:

You’re running a single service: Pi-hole, Nginx, Jellyfin, qBittorrent, Home Assistant
You want low RAM overhead and faster startup
You want tight Proxmox integration and easy vzdump backups

Use a VM when:

You need Windows
You need full kernel isolation
You’re doing GPU passthrough with proprietary drivers
You want to run a full Docker Compose stack cleanly

Running Docker inside a VM is still the cleanest approach for complex multi-container stacks. Docker inside LXC works, but it adds friction and security tradeoffs you’ll regret the first time something breaks.

One more option worth knowing: Proxmox VE 9.1 introduced native OCI container support, which lets you run Docker-style images without a full Docker VM in some scenarios. Worth exploring if you’re on 9.1 or later.

Privileged vs Unprivileged Containers

This is where most people get burned.

Unprivileged LXC (Default, Recommended)

By default, Proxmox creates unprivileged containers.

Inside the container, root is UID 0. On the host, that root maps to UID 100000. Container UIDs 0 through 65535 map to host UIDs 100000 through 165535.

This user namespace mapping dramatically improves security. If the container is compromised, the attacker doesn’t get real root on the host. They get a high-numbered unprivileged user that can’t do much.

This is what you want 90% of the time.

Privileged LXC

Privileged containers use real host UIDs. Root inside the container equals root on the host. No UID remapping.

That means fewer permission headaches and sometimes easier hardware passthrough or Docker-in-LXC. It also means weaker isolation and a much bigger blast radius if something goes sideways.

Don’t run privileged unless you have a concrete reason. “It’s easier” is not a concrete reason.

Understanding UID/GID Mapping Without Losing Your Mind

Here’s the core issue.

Inside your LXC, your media app runs as UID 1000. On the host, that same UID 1000 inside the container shows up as UID 101000. The math is simple: 100000 + 1000.

When you bind mount /mnt/media from the host into the container, the container expects to see UID 1000. The host actually sees 101000.

If your NAS files are owned by UID 1000 on the host, the container sees a mismatch. Result: Permission denied, files owned by nobody, and apps that quietly refuse to move or rename anything.

The Safe Default Mapping

Most Proxmox installs use:

lxc.idmap: u 0 100000 65536
lxc.idmap: g 0 100000 65536

Confirm with:

pct config <CTID>

Or test inside the container:

pct exec <CTID> -- id

If you see high-number UIDs on mounted files, the mapping is doing its job. If you see UIDs that look “normal” (under 1000), you’re either looking at a privileged container or a custom idmap. Either way, find out which before you start running chown.

The Right Way to Mount a Synology Drive in Proxmox

This is the most important section if you’re building a media server. Read it twice.

Step 1: Mount Synology on the Proxmox Host

Don’t mount NFS or SMB directly inside the container. Mount on the host.

Mount it on the host first. That gives you one place to manage permissions and makes troubleshooting far easier. If five containers all mount the same share independently, you get to debug five different permission problems.

First, make sure the mount point exists and the right tools are installed.

For NFS (recommended for performance):

apt update
apt install nfs-common
mkdir -p /mnt/synology
mount -t nfs 192.168.1.10:/volume1/media /mnt/synology

For SMB from Synology:

apt update
apt install cifs-utils
mkdir -p /mnt/synology
mount -t cifs //192.168.1.10/media /mnt/synology -o username=user,password=pass,vers=3.0

Verify:

ls -l /mnt/synology

If ownership looks wrong here on the host, fix it before touching the LXC. This single check catches most issues before they spread into the container.

Making Mounts Persistent Across Reboots

Manual mount commands don’t survive a reboot. You need /etc/fstab entries on the Proxmox host.

For NFS:

192.168.1.10:/volume1/media /mnt/synology nfs defaults,_netdev 0 0

For SMB, use a credentials file. Plaintext passwords in /etc/fstab are a bad idea on a system multiple people might log into.

//192.168.1.10/media /mnt/synology cifs credentials=/etc/samba/synology.creds,vers=3.0,_netdev 0 0

Create the credentials file:

mkdir -p /etc/samba
cat > /etc/samba/synology.creds <<'EOF'
username=user
password=yourpassword
EOF
chmod 600 /etc/samba/synology.creds

Then test before rebooting:

umount /mnt/synology
mount /mnt/synology

If it mounts cleanly, you’re set. If it doesn’t, fix it now. A broken fstab entry can stall the host at boot and force you into the rescue console, which is not how you want to spend your evening.

The _netdev flag tells the system to wait for the network before mounting. That matters on Proxmox hosts that finish booting before all interfaces are fully ready.

Step 2: Bind Mount Into LXC

Now bind mount the host path into the container:

pct set <CTID> -mp0 /mnt/synology,mp=/mnt/media,acl=1

A few things to know:

mp0 is the first mount point. If you already have an mp0, this overwrites it. Use mp1, mp2, etc. for additional bind mounts.
acl=1 enables POSIX ACLs on the mount, which most media apps quietly want.
Mount points don’t apply until the container restarts.

Reboot the container:

pct reboot <CTID>

Then check inside:

pct exec <CTID> -- ls -l /mnt/media

If you see UIDs like 101000 or similar, that’s the mapping doing its job. If you see nobody or strange ownership, jump to the next section.

Fixing Permission Denied Errors on NAS Mounts

This is the most common issue with Plex, Jellyfin, and Sonarr. Almost every “my LXC can’t write to my NAS” thread on r/homelab ends here.

Option 1: Adjust Ownership on Host

If your app runs as UID 1000 inside the container, host ownership must be:

100000 + 1000 = 101000

Read the warnings below before running this.

chown -R 101000:101000 /mnt/synology

NFS warning: Whether chown actually does anything depends entirely on your Synology’s NFS export configuration. If the export has root_squash enabled (Synology’s default), the Proxmox host can’t change file ownership on the NAS. The command appears to succeed. The underlying ownership stays exactly where it was. You’ll only notice when you check from another host or from DSM and see nothing changed.

To make chown work over NFS, you need either no_root_squash on the Synology export, or you set anonuid and anongid to the expected host-side UID (101000 in this case). On the Synology, that’s Control Panel > Shared Folder > Edit > NFS Permissions. Check which squash setting is active before you blame Proxmox.

SMB warning: chown does nothing on SMB mounts. Permissions on SMB are controlled by the share configuration on the Synology, not by Linux ownership. Set the Synology user permissions on the share itself.

Option 2: Custom lxc.idmap (Advanced)

Sometimes you need a specific NAS UID to map cleanly into the container. Say your Synology uses UID 1026 for the media user, and you want UID 1026 inside the container to match UID 1026 on the host.

Edit /etc/pve/lxc/<CTID>.conf and add a custom mapping that carves UID 1026 out of the normal offset:

lxc.idmap: u 0 100000 1026
lxc.idmap: u 1026 1026 1
lxc.idmap: u 1027 101027 64509
lxc.idmap: g 0 100000 1026
lxc.idmap: g 1026 1026 1
lxc.idmap: g 1027 101027 64509

This passes UID 1026 through directly. Everything else uses the normal 100000 offset.

You also need to authorize the carved-out UID and GID on the host, or the container will refuse to start. Add these lines to /etc/subuid and /etc/subgid respectively:

root:1026:1

Confirm the default offset on your host before trusting any of this:

grep root /etc/subuid /etc/subgid

You should see something like root:100000:65536. If yours is different, adjust the numbers above to match.

This is genuinely advanced and easy to break. The container won’t even start if the subuid/subgid lines are missing. Unless you have a concrete reason for it, adjusting ownership to match the default mapping is the safer path.

Bind Mount vs NFS vs SMB: What Should You Use?

For media workloads: mount on the host, bind mount into the LXC.

Bind mount on host: Lowest overhead, best performance, single point to manage permissions. This is the right choice for media servers.

NFS directly in container: Possible. Adds network overhead, creates more permission complexity, and is harder to manage centrally. Skip it.

SMB: Higher latency, more permission quirks, more fragile for Linux services. Use it only if NFS isn’t an option on your NAS.

Where Should You Store LXC Root Filesystems?

You can store LXC rootfs on local-lvm, local-zfs, or the boot storage.

Don’t put everything on the boot drive. If your boot drive is also handling heavy media IO, host performance suffers and so does anything else running on it.

A cleaner layout:

OS on boot SSD
Containers on a dedicated ZFS pool or SSD-backed storage
Media on a separate pool or NAS

Keep rootfs small and fast. Put bulk data on larger storage. Avoid booting Proxmox from a USB stick if you can. Proxmox writes logs and cluster state to the boot device constantly, and cheap flash wears out fast under that kind of load.

Backups and Snapshots

One of the biggest advantages of LXC in Proxmox is native backup support. Use it.

Backup

Via GUI: Datacenter > Backup > Add Job. Make sure mount points are included if backup=1 is set on the bind mount. By default, bind mounts are skipped.

CLI:

vzdump <CTID>

Snapshots

pct snapshot <CTID> pre-update --description "Before upgrade"

With ZFS, snapshots are near-instant and cost almost nothing in disk space. Take one before every upgrade. You will eventually need to roll one back, and you’ll be glad you did.

Important: bind-mounted directories are not snapshotted. Your media directory on a NAS won’t be included in a Proxmox snapshot or backup automatically. Plan accordingly. Don’t assume vzdump covers everything, because it won’t.

Troubleshooting Common LXC Storage Issues

1. Files Show as Owned by `nobody`

Cause: UID mismatch due to unprivileged mapping.

Fix: Adjust host ownership to the mapped UID (typically 101000 for app UID 1000). Check Synology NFS export settings first, specifically root_squash, or your chown will lie to you.

2. Sonarr Cannot Move Files

Cause: Download folder and media folder are owned by different mapped IDs, or they’re on different filesystems entirely (which forces a slow copy and can fail on permissions).

Fix: Ensure both paths are owned by the same UID and GID on the host, and that they live on the same mount when possible.

Cause: SMB mounted inside the container instead of on the host. Or cifs-utils is missing on the host.

Fix: Mount on host. Bind mount into container. Install cifs-utils on the host, not the LXC.

4. High IO or Slow Streaming

Cause: Using SMB instead of NFS. Running heavy IO on the boot pool.

Fix: Switch to NFS. Move container rootfs to a dedicated pool. If transcoding is the bottleneck, a CPU with Quick Sync will offload most of it.

A 14-core (6 P-cores plus 8 E-cores), 20-thread Raptor Lake Refresh CPU with strong single-thread performance and UHD 770 graphics, giving you Quick Sync hardware transcoding for Jellyfin/Plex. Ideal for Proxmox homelabs and everyday desktops when you want snappy VM/container workloads without needing a discrete GPU.

Amazon Price: Loading...

Availability: Checking...

Contains affiliate links. I may earn a commission at no cost to you.

5. Permission Denied After Restore

Cause: Restored to a different host with different UID mapping.

Fix: Verify lxc.idmap lines match the original system. Adjust ownership as needed. This bites people who restore a backup to a fresh Proxmox install and forget that the host UID offsets have to line up.

6. chown Does Nothing on Synology NFS Mount

Cause: Synology NFS export has root_squash enabled. The host can’t change file ownership on the NAS.

Fix: Adjust NFS export settings on the Synology (Control Panel > Shared Folder > NFS Permissions). Use anonuid/anongid to control how the NAS presents ownership to Proxmox, or switch to no_root_squash in a controlled environment. Don’t enable no_root_squash on a share that’s reachable from anything you don’t trust.

Frequently Asked Questions

➤ How do I fix permission denied errors when mounting a Synology NFS share into a Proxmox LXC for Plex or Jellyfin?

Mount NFS on the Proxmox host first, not inside the container. Bind mount it into the LXC. Check your Synology NFS export settings, specifically whether root_squash is enabled. If it is, chown won’t change ownership on the NAS side. Set anonuid/anongid on the NFS export, or adjust squash settings on your Synology.

➤ Privileged or unprivileged LXC for running Docker inside Proxmox?

Unprivileged is safer. If you must run Docker in LXC, many people use privileged containers, which reduces isolation and isn’t ideal for internet-exposed workloads. Better option: use a VM for Docker Compose stacks, or explore Proxmox 9.1 native OCI support.

➤ Best way to bind mount a ZFS pool or external drive without UID/GID issues?

Mount on host.
Use pct set <CTID> -mpX /host/path,mp=/container/path,acl=1.
Adjust host ownership to match the mapped UID. Check NFS squash settings before you run chown so you’re not chasing a ghost.

Avoid custom idmap unless you have a specific UID mismatch that can’t be solved by adjusting ownership.

➤ Can I store LXC rootfs on the Proxmox boot drive?

You can. It’s not best practice for heavy workloads. Separate OS and container storage for better stability and performance, and your boot drive will last longer.

➤ Does Proxmox LXC support snapshots of bind-mounted media directories?

No. Snapshots cover the container rootfs only. External bind mounts must be backed up separately, typically with ZFS snapshots on the underlying pool or with native NAS snapshots on the Synology side.

➤ LXC vs VM vs Docker VM for qBittorrent?

Single instance, lightweight: LXC. Full Docker stack with VPN and multiple services: VM with Docker. Need maximum isolation: VM.

If you’re sizing up new hardware for a Proxmox host that runs a dozen LXCs plus a Docker VM, network and storage I/O matter more than raw clock speed.

A compact mini-workstation built around up to a 16-core Ryzen 9 9955HX, with dual 10GbE SFP+ plus dual 2.5GbE, flexible storage (U.2 + M.2 including 22110), and triple 8K display outputs. Great as a homelab node or small server with serious I/O.

Amazon Price: Loading...

Availability: Checking...

Contains affiliate links. I may earn a commission at no cost to you.

Final Thoughts: Mount Network Shares Correctly or Pay for It Later

Proxmox LXC containers are one of the best tools in a homelab. Lightweight, fast, integrated, easy to back up.

But they’re not magic.

The moment you mount a Synology drive in Proxmox or bind mount a ZFS dataset into an LXC, UID and GID mapping becomes real. Ignore NFS squash settings and you’ll spend an afternoon chasing phantom permission errors that aren’t really permission errors at all.

If you remember only three things:

Use unprivileged containers by default.
Mount NAS storage on the host, then bind mount into LXC.
Fix ownership on the host to match mapped UIDs, and check your Synology NFS export settings before you blame Proxmox.

Do that and you’ll skip the wall of errors that ate my afternoon during my VM-to-LXC migration. You don’t need privileged containers and you don’t need custom idmap. You need to understand what the offset does and work with it instead of fighting it.

If you want to go deeper next:

Explore Proxmox 9.1 OCI containers.
Learn ZFS dataset tuning for media workloads.
Build a clean storage layout separating OS, containers, and bulk data.

And if your current box is the bottleneck before you finish reading this, a small Proxmox-friendly node with fast networking will get you further than throwing more RAM at an aging tower.

Amazon Price: Loading...

Availability: Checking...

Contains affiliate links. I may earn a commission at no cost to you.

M5 MacBook Air vs Windows Laptop for Developers

Tue, 21 Apr 2026 14:53:29 -0600

Going back to school as an adult changes how you look at your tools.

I needed a laptop for coursework, software development, running my blog, and working while I travel. That means IDEs, Docker containers, SSH sessions into my homelab, dozens of browser tabs, and long stretches away from power outlets.

I’d been a Windows user for years. My desktop handled everything. Over time, every non-gaming task got worse. Browsing felt sluggish. Actual work became clunky and frustrating. Even checking email started to feel like I was managing an operating system instead of using one.

So I bought a 13-inch M5 MacBook Air.

Here’s how I got there, what I learned, and what I’d tell you if you’re staring down the same macOS vs. Windows decision for school and development.

💭

TL;DR: I chose the M5 MacBook Air because it gives me silent performance, all-day battery, a Unix-native development environment, and a machine I can travel with. I kept my Windows desktop strictly for gaming. Each machine does what it’s good at. That’s the whole story.

Why Windows Finally Wore Me Down

My Windows desktop isn’t slow on paper. Strong CPU, plenty of RAM, capable GPU. But the OS experience degraded over time in ways that specs can’t capture.

Here’s what wore on me:

Background processes spiking CPU at random. I never asked for “Microsoft Compatibility Telemetry” to eat 30% of a core, but there it was.
Disk thrashing from indexing and update downloads, sometimes during active work sessions.
Forced reboots at the worst possible moments. Mid-compile. Mid-deploy. Once, mid-exam.
OEM bloatware on every Windows laptop I evaluated. Fresh installs help, but you shouldn’t need one on day one.
A consistent feeling of fighting the machine instead of using it.

The hardware was fast. The OS felt slow.

You know that moment when you open your laptop to check something quickly and it decides right now is the perfect time to finish installing updates at zero percent? That happened enough times to change my behavior. I started hesitating before reboots. I delayed updates. I kept too many things open to avoid restarting.

That’s not a workflow. That’s damage control.

Microsoft Solved the Reboot Problem, For Enterprise Customers

Windows has always meant: security update equals restart.

Microsoft introduced hotpatching, which applies certain security updates without requiring a reboot. That’s a genuine improvement.

Here’s the catch.

Hotpatching is limited to Windows 11 Enterprise customers with specific Microsoft 365 subscriptions. Not Home. Not Pro. And Windows Server hotpatching now involves per-server subscription licensing.

Microsoft solved the problem. Then put the solution behind Enterprise licensing.

If you’re on Home or Pro, you’re still getting interrupted.

That’s the pattern that finally broke me. Basic workflow stability became a premium feature. It felt like my time was worth less than an enterprise customer’s. Once you see that pattern, you can’t unsee it.

Compare that with macOS: most updates don’t require a reboot at all. When they do, it’s scheduled and predictable. Nobody’s charging you extra to avoid being interrupted.

What I Needed

Before switching platforms, I wrote down requirements. Not wants. Needs. If you skip this step, you’ll end up buying for vibes instead of utility.

School

Office or Google Docs
Secure browser for exams (Respondus, ExamSoft, etc.)
All-day battery for long class days
Quiet operation in lecture halls

Development

VS Code (or your editor of choice)
Git
Docker
SSH into my homelab (Proxmox hosts, pfSense, NAS boxes)
Light to moderate compiles
Occasional Linux VMs for testing

Writing and Blogging

Multiple browser tabs (research, CMS, preview)
Markdown editor
Fast, responsive multitasking

Travel

Lightweight (under 3 lbs preferred)
All-day battery
Silent on planes
USB-C charging (one charger for everything)
Strong Wi-Fi

Once I wrote that out, the M5 MacBook Air stopped looking like a lifestyle choice and started looking like a serious tool match.

Built for Life on the Road

Travel was a real factor in this decision.

The 13-inch M5 Air weighs 2.7 pounds. Most Windows laptops at this price land closer to 4 to 5 pounds, especially anything with a dedicated GPU. That difference doesn’t sound like much until you’ve hauled it through three terminals and a connecting flight.

Fanless Design

The M5 Air has no fan. Zero. For Office, browsing, and typical coding sessions, it runs silently without noticeable throttling. Apple Silicon’s efficiency cores handle idle and light tasks without spinning anything up.

That matters more than you’d think:

Silent in hotel rooms when your partner is sleeping
No fan noise on planes (your seatmate already hates you for existing, no need to add a whining fan)
No heat on your lap during long flights
No dust accumulating in the chassis over years of travel

For sustained heavy rendering or massive build pipelines running all day, a MacBook Pro with active cooling is the right call. For school and development work, the Air handles it without complaint.

Battery Life

Apple rates it at up to 18 hours. In real-world use with Wi-Fi, browser tabs, writing, and SSH sessions, expect a solid 10 to 14 hours depending on workload.

I’ve gone through entire layovers without checking my battery percentage. That changes how you work. You stop hunting for outlets. You stop rationing screen brightness. You get on with it.

Wi-Fi 7

The M5 Air includes Wi-Fi 7 (802.11be). In practice, faster channel negotiation and reduced latency help when pushing Git commits or running SSH sessions over congested hotel and airport networks. It’s not a dramatic day-to-day difference, but on a crowded network it’s noticeably snappier. You’ll need a Wi-Fi 7 access point at home to take full advantage.

This ultra-portable powerhouse features the latest Apple silicon paired with 24GB of unified memory and a massive 1TB SSD, delivering desktop-class performance for heavy multitasking and professional creative workflows. Its fanless, razor-thin design and brilliant 13.6-inch Liquid Retina display make it the ultimate mobile workstation for those who refuse to compromise on speed or storage.

Amazon Price: Loading...

Availability: Checking...

Contains affiliate links. I may earn a commission at no cost to you.

Doing the Budget Math

At roughly $1,400 you’re choosing between two very different machines.

A Windows gaming laptop at that price gives you a strong CPU, dedicated GPU, loud fans, 4 to 6 hour real-world battery, and a heavier chassis. Great if you game on the go. I don’t.

The M5 MacBook Air at the same price is fanless, silent, light, and has genuine all-day battery. Education pricing through Apple’s education store shaves off a bit more. Macs also hold resale value better than most Windows laptops, which matters if you’re planning to upgrade in a few years.

For my workload, the Mac was the better fit at the same price. If gaming on the go is your priority, the Windows laptop wins. Know what you’re actually buying before you buy it.

The Developer Case for Apple Silicon

This is where the decision got easy. And where most “switch to Mac” posts get lazy. They say “it’s Unix!” and move on. Let me spell out what that means and where it bites you.

macOS is Unix-based. That changes the day-to-day development experience in concrete ways. But there are real trade-offs worth knowing before you commit.

What Works Better

Out of the box you get zsh (or bash if you prefer), SSH, and a proper POSIX environment. No WSL layer. No PowerShell vs. bash context switching. No “which terminal am I in right now” mental overhead.

When I SSH into my homelab servers, it feels identical to working locally. The key bindings are the same. The shell is the same. The config file syntax is the same. If you’re the kind of person who debates Debian vs. Ubuntu for servers or tinkers with pfSense vs. OPNsense configs, macOS fits naturally into that workflow. The tooling and conventions align with what you’re managing remotely.

Installing Homebrew

If you’re coming from Windows, macOS doesn’t ship with a built-in package manager like apt or dnf. Homebrew fills that gap. It’s the de facto standard for installing developer tools on macOS, and you’ll want it set up before you do anything else.

Open Terminal (it’s in Applications > Utilities, or hit Cmd+Space and type “Terminal”) and run this:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

The script will explain what it’s going to do and ask for your password. Read what it tells you. After it finishes, it prints instructions to add Homebrew to your shell path. On Apple Silicon Macs, Homebrew installs to /opt/homebrew instead of the old /usr/local path. The installer will show you the exact lines to paste. Follow them.

Verify it’s working:

brew --version

If that prints a version number, you’re good. If it says “command not found,” you skipped the path step above. Go back and do it.

Once Homebrew is set up, installing tools is one command each:

brew install git
brew install node
brew install --cask docker

The difference between brew install and brew install --cask matters. brew install is for command-line tools and libraries. brew install --cask is for GUI applications (things with a window, like Docker Desktop, VS Code, or Firefox). Use the wrong one and you’ll get the wrong thing, or nothing at all.

VS Code, Git, Docker Desktop, and most developer tools run natively on Apple Silicon. For standard workflows, there’s no emulation layer involved.

The arm64 vs amd64 Reality

Here’s what the enthusiast posts skip over: Apple Silicon is arm64, and not every Docker image has an arm64 build.

Most popular images do: postgres, redis, nginx, node, python, the whole *arr stack. But some older or niche images are x86-only. When you pull one of those on Apple Silicon, Docker runs it via Rosetta 2 emulation. For most cases this works fine, but it adds overhead and occasionally fails on images that rely on specific x86 instructions.

You can check whether an image has arm64 support before pulling:

docker manifest inspect <image>:<tag> | grep architecture

If you see "architecture": "arm64", you’re golden. If it’s only amd64, you’re running under emulation.

For day-to-day homelab and school dev work, I’ve hit this maybe twice in several months. It’s not a daily problem. But it’s real, and you should know it exists before you’re blocked on a deadline waiting on a container that refuses to start.

Rosetta 2 and x86-Only Tooling

Rosetta 2 transparently runs x86 apps on Apple Silicon. For most apps and CLI tools, you won’t notice it’s happening. Some x86-only tools work fine under Rosetta. Others, particularly anything touching low-level kernel interfaces or hypervisor APIs, may not.

You can verify whether a binary is running under Rosetta:

file /path/to/binary
# Look for "arm64" (native) vs "x86_64" (Rosetta)

For typical school and homelab development, Rosetta handles the edge cases you’ll encounter. If you’re doing kernel development, low-level fuzzing, or complex hypervisor work, research your specific toolchain before switching platforms.

VM Limitations

Parallels Desktop runs Windows 11 on Arm well. Standard Linux VMs work fine. What’s limited is nested virtualization and complex multi-VM network labs. Some scenarios that work cleanly in VMware Workstation on x86 require workarounds (or don’t work at all) on Apple Silicon.

For standard homelab test VMs and dev environments, Parallels is solid. For complex multi-VM network simulation (think: GNS3 labs with multiple routers and switches), a dedicated x86 box is still the better tool. Your Proxmox server in the closet is perfect for that.

RAM and Storage: Get This Right the First Time

You cannot upgrade either after purchase. Apple solders everything to the board. Buy what you actually need, because there’s no fixing this later.

RAM

The M5 Air goes up to 32 GB of unified memory.

Browsing and writing: 16 GB can work, but you’ll feel it within a year.
Docker plus light VMs: 24 GB is the floor. Do not go below this for dev work.
Parallels with Windows plus heavy multitasking: 32 GB. Don’t argue with me on this one.

Parallels recommends allocating 8 to 12 GB of RAM and about 4 CPU cores for smooth Windows 11 on Arm. On 16 GB total, you’ll feel that constraint immediately. macOS itself wants 4 to 6 GB before you’ve opened anything.

One thing worth knowing: Apple Silicon uses the same memory pool for CPU and GPU (unified memory architecture). Under heavy memory pressure, macOS compresses memory and swaps to the SSD rather than crashing. The SSD speeds make this much less painful than traditional disk swap, but it still shows up as latency spikes under sustained pressure. You can monitor this in Activity Monitor under the “Memory” tab. If that “Memory Pressure” gauge is regularly yellow or red, you bought the wrong RAM tier.

I chose 32 GB. No regrets.

Storage

Base is 512 GB. That sounds like a lot until you start filling it.

A Windows 11 Arm VM consumes 30 to 80 GB. Add projects, Docker images, photos, and blog assets and 512 GB disappears fast. Docker images alone can eat 20 to 50 GB if you’re not pruning regularly (docker system prune is your friend).

1 TB minimum if you’re doing dev plus VM work.
2 TB if this is your only machine.

Neither is upgradeable. Buy once, buy right.

Where macOS Hurts

No platform is perfect. Here’s where macOS will make you swear.

Software licensing and Windows-only tools. Some enterprise software, niche tools, and specialized applications are Windows-only with no viable Mac alternative. If your school or employer requires specific Windows software, check compatibility before you buy. Windows on Arm via Parallels handles most productivity apps, but not everything. Test before you commit.

Corporate IT environments. If you’re in a managed Windows environment where IT controls your machine, a personal Mac doesn’t change your work situation. This post assumes you’re buying your own hardware for personal use and school.

Peripheral compatibility. Most peripherals work fine. Some older USB dongles, specialized input devices, and certain external audio interfaces have better Windows driver support. I haven’t hit a real problem, but check anything specialized before purchasing. Particularly older printers and scanners.

The adjustment period is real. Finder and macOS window management are genuinely different from Windows. Not worse. Different. Rectangle (free, takes five minutes to install) fixes the window snapping problem that will drive you crazy on day one. The broader adjustment takes a couple of weeks. Some long-term Windows users take a month or two to fully re-wire their muscle memory.

The Ecosystem Adjustment

Keyboard shortcuts shift. Ctrl becomes Cmd for most things. Copy is Cmd+C, terminal interrupt stays Ctrl+C. It takes about a week to stop hitting the wrong key.

What surprised me after the adjustment: how consistent everything feels, how rarely the system stutters, and how predictable updates are.

It’s boring. That’s exactly what you want from a work machine. Boring is reliable. Boring means you’re thinking about your code, not your OS.

One Cable at Your Desk

At first, two Thunderbolt ports felt limiting. I came from a desktop with more USB ports than I could fill.

One good Thunderbolt dock fixed that. One cable now handles power, dual monitors, Ethernet, keyboard, mouse, and external storage. I use a CalDigit TS4, but there are solid options from OWC and Anker too.

Unplug that one cable and you’re mobile. Plug it back in and you’re docked. That’s actually cleaner than my old Windows docking setup.

My Windows Desktop Has a New Job

I didn’t abandon Windows. I redefined what it’s for.

The desktop now boots into Steam, runs games, and handles GPU-heavy workloads. That’s its whole job. It does that job extremely well.

Windows still does gaming better than any other platform. Native support, mature GPU drivers, the whole PC gaming ecosystem is built around it. No argument there.

Trying to make one machine handle everything created constant friction. Letting each machine do what it’s good at removed it.

The Mac handles school, dev, writing, and travel. The PC handles games. Everybody wins.

Who Should Pick Which

Get a Windows laptop if:

You game on the go.
You rely on Windows-only software with no viable alternative.
Your school or employer requires specific Windows tooling.
You’re on a tight budget where the Mac premium doesn’t fit.

Get the M5 MacBook Air if:

You’re a developer managing servers or a homelab.
You travel frequently and care about weight and battery.
You’re tired of Windows sluggishness and forced reboots.
You want a silent, reliable machine that gets out of your way.

Non-negotiables if you go Mac:

24 GB RAM minimum for dev work with Docker.
32 GB if you plan to run Parallels regularly.
1 TB storage minimum if you’ll use VMs.
Budget for a good Thunderbolt dock ($150 to $400 depending on features).

The learning curve is real. It’s shorter than you’d expect.

FAQs

Does the M5 MacBook Air handle SSH to a homelab well?

Yes. macOS provides native SSH and a full terminal environment out of the box. No extra software needed. For remote server management and development workflows, it performs great. If you manage pfSense, OPNsense, Proxmox, or Linux servers in your homelab, the tooling feels natural from macOS. You can also use ~/.ssh/config to set up aliases for your homelab hosts, exactly like you would on any Linux box.

What about Docker on Apple Silicon?

Docker Desktop runs natively on Apple Silicon. Most popular images have arm64 builds. Some older or niche images are x86-only and run via Rosetta 2 emulation, which works for most cases but can add overhead. Check image compatibility with docker manifest inspect before building your stack around it. For typical homelab and school projects, it’s rarely a blocking problem.

How much RAM do I need if I’m running Parallels?

Parallels recommends 8 to 12 GB and about 4 CPU cores for Windows 11 on Arm. That means 24 to 32 GB total for comfortable multitasking alongside your other apps. On 16 GB, you’ll feel the squeeze fast.

Will the fanless design throttle on long builds?

For typical dev compiles and school multitasking, it performs well without noticeable throttling. Sustained heavy rendering or extreme build pipelines running all day are better served by a MacBook Pro with active cooling. The Air will thermal throttle under prolonged 100% CPU load. That’s physics, not a defect.

What’s real battery life like?

Apple rates it at up to 18 hours. In mixed use with Wi-Fi, writing, and dev tasks, expect 10 to 14 hours. Heavy Docker builds and VM usage will pull that number down. Light browsing and writing will push it up.

Can I run Windows on the Mac?

Yes, via Parallels Desktop. Windows 11 on Arm runs smoothly for Office and productivity apps. It is not a gaming replacement. Keep a Windows desktop for that.

Is a Thunderbolt dock worth it?

If you work at a desk, absolutely. A good Thunderbolt dock handles charging, dual displays, Ethernet, and peripherals through one cable. It makes the two-port limitation a non-issue. Budget $150 to $400 depending on how many monitors and ports you need.

The Real Decision

Switching to the M5 MacBook Air wasn’t about platform loyalty. It was about friction.

My Windows machine slowly became something I had to manage around. Forced reboots, background sluggishness, and enterprise-gated features chipped away at the experience until I was spending mental energy on the OS instead of on the work.

The M5 MacBook Air gave me silent operation, genuine all-day battery, Unix-native development tools, and predictable behavior. It gets out of the way and lets me work.

Keeping the Windows desktop for gaming stopped me from forcing one machine to do everything. That’s a trap I see people fall into constantly.

The real win isn’t macOS over Windows. It’s using the right tool for the job.

If you’re heading back to school, doing development, managing a homelab, or traveling regularly, the M5 MacBook Air deserves a serious look.

And if you’re still on the fence, ask yourself one thing: are you fighting your computer, or is it helping you?

That answer usually makes the decision clear.

Amazon Price: Loading...

Availability: Checking...

Contains affiliate links. I may earn a commission at no cost to you.

WireGuard Client on OPNsense: VPS Tunnel LAN Routing Guide

Fri, 06 Mar 2026 07:12:23 +0000

If you’re running services at home and want to expose them through a VPS reverse proxy, configuring a WireGuard client on OPNsense is one of the cleanest ways to do it.

Here’s the setup: a VPS running Caddy (or nginx, or whatever reverse proxy you prefer) accepts requests from the internet and forwards them through a WireGuard tunnel to services on your LAN. Jellyfin, Home Assistant, Nextcloud, whatever you’re running. Traffic enters through the tunnel and leaves the same way. Your home IP stays hidden. No ports open on your home router.

Most guides make this harder than it needs to be. They throw policy routing, full-tunnel configurations, and asymmetric routing fixes at you before you’ve even gotten a handshake. You don’t need any of that for a reverse proxy setup. The VPS initiates the connection, your LAN service replies, and the reply naturally goes back through the tunnel because that’s where it came from. Routing 101.

The only real work is on OPNsense: get the tunnel up, assign the interface, and write a tight firewall rule that lets the VPS reach your service and nothing else.

The pfSense details might be a little off as I haven’t used pfSense in a few years.

💭

TL;DR:

Set up a WireGuard client instance in OPNsense. Assign it as an interface. Add a firewall rule that allows VPS traffic to reach your specific service (like Jellyfin) and nothing else. On the VPS, add a route for your LAN subnet through the tunnel and point Caddy at your service’s LAN IP.

No policy routing. No outbound NAT. No asymmetric routing fixes. This is a reverse proxy setup, not a full tunnel.

pfSense can do the same with its WireGuard package, but OPNsense’s integration is cleaner.

How the Traffic Flows Before touching any config, understand what’s actually happening. If you skip this section and something breaks later, you’ll be guessing. Don’t guess.

Internet client sends a request to https://jellyfin.yourdomain.com
DNS resolves to your VPS public IP
Caddy on the VPS terminates TLS and reverse proxies the request through the WireGuard tunnel to your Jellyfin server’s LAN IP (e.g., 192.168.0.50:8096)
OPNsense receives the packet on the WireGuard interface wg0, checks firewall rules, and routes it to your LAN
Jellyfin processes the request and replies to the source IP 10.10.10.1, the VPS tunnel IP
OPNsense sees the destination is in the tunnel subnet 10.10.10.0/24 and sends it back out wg0
VPS receives the reply, Caddy sends the response to the internet client

The key thing: replies go back through the tunnel naturally because the VPS tunnel IP 10.10.10.1 is in the tunnel subnet. OPNsense already knows how to reach it. No special routing needed.

This is why a reverse proxy setup is simpler than routing all your LAN traffic through a VPS. Traffic that enters through the tunnel leaves through the tunnel. No asymmetric routing, no state mismatches, no dropped packets, no Reddit posts asking why nothing works.

Prerequisites Before touching OPNsense:

VPS running WireGuard server (already configured and tested)
VPS public IP and WireGuard port, default 51820/UDP
VPS WireGuard public key
Tunnel IPs chosen (I use 10.10.10.1 for the VPS, 10.10.10.2 for OPNsense)
Reverse proxy installed on VPS (Caddy, nginx, etc.)
VPS WireGuard [Peer] block has your OPNsense public key, and its AllowedIPs includes your LAN subnet (e.g., 192.168.0.0/24) so the VPS knows to route LAN-bound traffic through the tunnel

Recommended:

OPNsense 24.x or newer
Config backup before changes. System > Configuration > Backups, download the XML. Do it now. Not after you’ve broken something. Now.

On OPNsense 25.x, WireGuard is built in. On 24.x and earlier, it’s a plugin.

If you’re on 24.x:

Go to System > Firmware > Plugins
Install os-wireguard

Then regardless of version:

Go to VPN > WireGuard > General
Enable WireGuard

Glovary N150 Firewall Mini PC
A fanless N150 appliance with six Intel i226-V 2.5GbE ports and hardware AES-NI, built for OPNsense or pfSense. Six ports give you room to separate WAN, LAN, and a couple of VLANs without adding a switch, which keeps the routing rules in this guide easier to follow.

Amazon Price: Loading...

Availability: Checking...

Contains affiliate links. I may earn a commission at no cost to you.

Step 2: Create the WireGuard Client Instance

Go to:

VPN > WireGuard > Instances > Add

Configure:

Enabled: Yes
Name: VPS-WG
Generate a new key pair using the Gear icon
Tunnel Address: 10.10.10.2/24
MTU: 1420 for bare metal, 1380 if OPNsense is virtualized (QEMU/KVM), 1412 if your WAN uses PPPoE
Disable Routes: Unchecked

Save.

Now add a Peer:

VPN > WireGuard > Peers > Add

Enabled: Yes
Name: VPS
Public Key: your VPS server’s public key
Tunnel Address (AllowedIPs): 10.10.10.0/24
Endpoint Address: Your VPS public IP
Endpoint Port: 51820
Instances: VPS-WG
Persistent Keepalive: 25 seconds

After saving the peer, go back to your VPS-WG instance, and under Peers, select the VPS peer you created. Save and Apply.

Why AllowedIPs is `10.10.10.0/24` and Not `0.0.0.0/0`

You’re not routing LAN internet traffic through the VPS. You only need OPNsense to know about the tunnel subnet. Traffic destined for 10.10.10.1 goes through wg0. Everything else goes out WAN as usual.

0.0.0.0/0 is for full-tunnel setups where you want LAN devices to egress through the VPS. That’s a different guide with different problems: policy routing, outbound NAT, asymmetric routing. Don’t go there unless you mean to.

Step 3: Assign the WireGuard Interface

This is where many people stop too early. The tunnel works for OPNsense-to-VPS pings at this point. But without an interface assignment, you can’t write firewall rules for tunnel traffic. That means any traffic the VPS sends toward your LAN gets silently dropped. No log entry. No error. Only silence and confusion.

Go to:

Interfaces > Assignments

You should see wg0 available in the dropdown. Add it.

Then click on the newly created interface (it’ll show as something like OPT1) and configure:

Enable: checked
Description: RackNerdVPS (or whatever name makes sense for your VPS provider)
IPv4 Configuration Type: None

Save and apply.

Why “None” and not “Static”? The tunnel address (10.10.10.2/24) is already configured on the WireGuard instance itself. Setting Static here and re-entering the same address can cause conflicts or weird behavior. Let the instance own the IP. The interface assignment only gives OPNsense a handle to attach firewall rules to. That’s the only reason you’re assigning it.

Step 4: Firewall Rule for VPS Access to Your LAN Service

This is the most important step, and it’s where most people get lazy and create a wide-open rule. Don’t be that person. You will regret it exactly once, and that once will ruin a weekend.

Go to:

Firewall > Rules > RackNerdVPS

Add a rule:

Enabled: Yes
Description: Allow VPS to Jellyfin
Action: Pass
Direction: In
Protocol: TCP
Source: RackNerdVPS net (or 10.10.10.0/24)
Destination: Single host, 192.168.0.50 (your Jellyfin server’s IP)
Destination Port: 8096 (Jellyfin’s default port)
Log: Enable

Save and apply.

This rule says: traffic arriving through the tunnel can reach Jellyfin and nothing else. If someone compromises your VPS, they can talk to Jellyfin on port 8096. They cannot reach your NAS, your Pi-hole, your Home Assistant, or anything else on your LAN. That’s a massive difference from a rule that passes any to any.

Adding More Services Later

If you add more services behind the VPS (Home Assistant, Nextcloud, etc.), don’t widen the existing rule. Add separate rules for each service with specific destination IPs and ports. Or create an alias:

Go to Firewall > Aliases > Add
Name: VPS_Allowed_Hosts
Type: Host(s)
Content: 192.168.0.50, 192.168.0.51 (add each service host IP)

Then use the alias as the destination in a single rule. Either way, keep it explicit. Blanket allow rules on a tunnel interface are how you wake up one morning with someone else browsing your NAS.

TP-Link Omada SG3210X-M2
Full-featured, compact, rack-ready. Eight multi-gig ports, dual 10GbE uplinks, VLAN/QoS/ACL/LACP, and seamless integration with TP-Link’s Omada controller. It locks down your Jellyfin/NAS traffic while scaling effortlessly with your homelab.

Amazon Price: Loading...

Availability: Checking...

Contains affiliate links. I may earn a commission at no cost to you.

Step 5: VPS-Side Configuration

The OPNsense side is done. Now the VPS needs to know how to reach your LAN through the tunnel.

Route for Your LAN Subnet

The VPS needs a static route so it knows that 192.168.0.0/24 is reachable through the tunnel. Without it, the VPS has no idea your LAN exists on the other side of wg0. The cleanest way is to add it to your WireGuard config:

# /etc/wireguard/wg0.conf on the VPS

[Interface]
Address = 10.10.10.1/24
ListenPort = 51820
PrivateKey = <VPS_PRIVATE_KEY>

[Peer]
PublicKey = <OPNSENSE_PUBLIC_KEY>
AllowedIPs = 10.10.10.2/32, 192.168.0.0/24

The important line is AllowedIPs on the peer. It includes 192.168.0.0/24. Without this, WireGuard on the VPS will refuse to send LAN-bound packets through the tunnel. It won’t know that subnet belongs to this peer.

After editing, restart WireGuard:

sudo systemctl restart wg-quick@wg0

Verify the route exists:

ip route | grep 192.168

You should see: 192.168.0.0/24 dev wg0 scope link

If you don’t see it, WireGuard didn’t come up cleanly. Check sudo wg show and journalctl -u wg-quick@wg0 for errors.

Working wg show example:

interface: wg0
 public key: <public key>
 private key: (hidden)
 listening port: 51820

peer: <public key>
 endpoint: <redacted>:5853
 allowed ips: 10.10.10.2/32, 192.168.0.0/24
 latest handshake: 1 minute, 28 seconds ago
 transfer: 42.86 GiB received, 950.45 MiB sent

Caddy Configuration

Point Caddy at your Jellyfin server’s LAN IP through the tunnel:

jellyfin.example.com {
 log {
 output file /var/log/caddy/jellyfin.access.log {
 roll_size 100mb
 roll_keep 5
 }
 format json
 }

 request_body {
 max_size 0
 }

 reverse_proxy <LAN IP>:8096 {
 header_up Host {host}
 header_up X-Real-IP {remote_host}
 header_up X-Forwarded-Proto https

 flush_interval 5s

 transport http {
 read_buffer 65536 # 64KB - reasonable size
 write_buffer 65536 # 64KB
 dial_timeout 30s
 response_header_timeout 0
 }
 }
}

Caddy sends the request to LAN IP. The VPS route table says 192.168.0.0/24 goes via 10.10.10.2 through wg0. The packet enters the tunnel, OPNsense receives it, the firewall rule allows it, and Jellyfin gets the request.

Test End-to-End

From the VPS:

# Can you reach OPNsense through the tunnel?
ping 10.10.10.2

# Can you reach Jellyfin through the tunnel?
curl -I http://<LAN IP>:8096

If the ping works but the curl doesn’t, the problem is almost certainly your OPNsense firewall rule. Check the firewall logs under Firewall > Log Files > Live View and filter on the RackNerdVPS interface. Look for blocked entries with the destination Jellyfin's LAN IP. If you see blocks, your rule is either missing, disabled, or the destination IP/port doesn’t match what Caddy is actually sending.

If both fail, go back to “Verify the Handshake” and start there.

MINISFORUM MS-A2
A compact mini-workstation built around up to a 16-core Ryzen 9 9955HX, with dual 10GbE SFP+ plus dual 2.5GbE, flexible storage (U.2 + M.2 including 22110), and triple 8K display outputs. Great as a homelab node or small server with serious I/O.

Amazon Price: Loading...

Availability: Checking...

Contains affiliate links. I may earn a commission at no cost to you.

MTU Tuning

If large requests stall (pages half-load, big video files buffer forever, SSH works but SCP hangs), your MTU is too high. This is the single most common “it works but not really” problem with WireGuard tunnels. Every time. Without fail. Someone in a forum will tell you it’s DNS. It’s not DNS. It’s your MTU.

WireGuard adds 60 bytes of overhead. Start with:

Setup	Starting MTU
Bare metal, standard Ethernet WAN	`1420`
PPPoE WAN	`1412`
Virtualized OPNsense (QEMU/KVM/Proxmox)	`1380`
PPPoE + VLAN tagging	`1400` or lower

Test with a do-not-fragment ping from OPNsense to the VPS tunnel IP:

ping -s 1352 -M do 10.10.10.1

The -s value should be your MTU minus 28 (that’s 20 bytes of IP header plus 8 bytes of ICMP header). If it fragments or times out, lower the MTU in your WireGuard instance settings (VPN > WireGuard > Instances, edit your instance) and test again. Drop by 20 each time until the ping goes through clean.

For a reverse proxy setup, MTU issues usually show up as Jellyfin streams that start playing and then stall, or web UIs that load the page skeleton but never finish rendering. Small requests work fine. Large ones die. That’s your MTU.

pfSense WireGuard Setup (Step-by-Step)

The concepts are identical, but the UI and some behaviors differ.

Installation

Go to System > Package Manager > Available Packages
Install the WireGuard package

Unlike OPNsense 25.x, pfSense doesn’t ship WireGuard integrated. It’s package-based. Recent versions improved stability significantly, but OPNsense still feels more cohesive for WireGuard setups.

pfSense Client Configuration

Go to:

VPN > WireGuard > Tunnels > Add

Enable: Yes
Description: VPS-WG
Listen Port: leave blank (client mode)
Interface Keys: generate or paste your private key

Save, then go to VPN > WireGuard > Peers > Add:

Tunnel: select VPS-WG
Public Key: VPS public key
Endpoint: VPS_PUBLIC_IP:51820
Allowed IPs: 10.10.10.0/24
Persistent Keepalive: 25

Save.

Assign the Interface in pfSense

Interfaces > Assignments

The WireGuard tunnel appears as tun_wgX. Add it, enable it, rename to RackNerdVPS.

Set IPv4 to Static, address 10.10.10.2/24.

This is the opposite of OPNsense. pfSense wants you to set the static IP on the interface assignment. OPNsense has the instance own the IP and the interface assignment uses “None.” Get this backwards on either platform and you’ll have a confusing afternoon.

Firewall Rule in pfSense

Firewall > Rules > RackNerdVPS

Same logic as OPNsense. Create a rule allowing traffic from the WG net to your Jellyfin host on its specific port. Don’t pass everything.

Action: Pass
Protocol: TCP
Source: RackNerdVPS net
Destination: Jellyfin's LAN IP
Destination Port: 8096

TP-Link 2.5GB PCIe Network Card (TX201)
Plug-and-play 2.5GbE PCIe card that unlocks multi-gig speeds for about $30. Works out of the box with Proxmox, Linux, and Windows. No drama, faster transfers.

Amazon Price: Loading...

Availability: Checking...

Contains affiliate links. I may earn a commission at no cost to you.

pfSense vs OPNsense for WireGuard

Feature	OPNsense	pfSense
WireGuard integration	Built-in (25.x) / Plugin (24.x)	Package (add-on)
Config model	Instances + Peers	Tunnels + Peers tabs
Stability (2024+)	Strong	Much improved, still package-based
Gateway monitoring	Straightforward	Requires more configuration
UI clarity	More intuitive	Functional but more legacy

For WireGuard-heavy homelab setups, I’d lean OPNsense. But pfSense works. Both get the job done once configured.

Troubleshooting Guide

No Handshake

Check:

VPS firewall allows UDP on the WireGuard port
Endpoint IP and port are correct
Keys match (double-check copy-paste errors, especially trailing whitespace)
Run wg show on both OPNsense and VPS

If behind NAT, ensure Persistent Keepalive is set to 25. Without it, the NAT mapping times out and the VPS can no longer reach your OPNsense.

Tunnel is Up but VPS Can’t Reach Jellyfin

The handshake works, ping 10.10.10.2 from the VPS works, but curl http://<Jellyfin's LAN IP>:8096 fails. Work through these in order.

No route on the VPS. Run ip route | grep 192.168 on the VPS. If there’s no route, add one. The VPS doesn’t magically know your LAN subnet exists behind the tunnel.

# Quick fix (doesn't survive reboot):
sudo ip route add 192.168.0.0/24 via 10.10.10.2 dev wg0

AllowedIPs on the VPS peer doesn’t include your LAN subnet. WireGuard won’t send packets to 192.168.0.0/24 through the tunnel unless that subnet is in the peer’s AllowedIPs. Check /etc/wireguard/wg0.conf on the VPS and make sure the [Peer] block includes 192.168.0.0/24.

OPNsense firewall is blocking it. Check Firewall > Log Files > Live View and filter on the RackNerdVPS interface. If you see blocks, your firewall rule is either missing, misconfigured, or the destination IP/port doesn’t match what Caddy is sending.

Jellyfin is only listening on localhost. Some services bind to 127.0.0.1 by default. Check Jellyfin’s network settings (Dashboard > Networking) and make sure it’s listening on 0.0.0.0 or its LAN IP. If it’s bound to localhost, it will ignore everything that isn’t coming from the same machine.

Jellyfin Loads but Streams Buffer or Stall

Small requests work (the web UI loads) but video playback stalls. This is almost always an MTU problem. Large packets are getting fragmented or dropped.

Lower the MTU on your WireGuard instance (try 1380)
Test with a do-not-fragment ping (see MTU Tuning section above)
If you’re on a virtualized OPNsense, the hypervisor network stack often shaves off extra bytes. Go lower.

“no such device wg0”

This means the WireGuard interface doesn’t exist yet. Either the instance isn’t enabled in WireGuard settings, or the WireGuard service isn’t started.

Check VPN > WireGuard > General and make sure the service is enabled and running. If it’s enabled but wg0 still doesn’t exist, try toggling it off and on again. Check System > Log Files > General for errors.

VPS Sees Replies From 10.10.10.2 Instead of the LAN IP

This means outbound NAT is rewriting the source address on the WireGuard interface. For a reverse proxy setup, you don’t need outbound NAT. Remove it if it’s there. The VPS has a route for your LAN subnet, so replies from Jellyfin’s LAN IP will route back through the tunnel without NAT.

If you haven’t manually added outbound NAT and you’re still seeing this, OPNsense’s automatic outbound NAT might be generating a rule for the WireGuard interface. Go to Firewall > NAT > Outbound, switch to Hybrid mode, and verify no auto-generated rules are matching tunnel traffic. If one is, switch to Manual mode or add a manual rule that explicitly excludes the WireGuard interface.

Frequently Asked Questions

➤ Do I need policy routing for a VPS reverse proxy setup?

No. Policy routing is for when LAN devices initiate traffic that needs to exit through the tunnel. In this setup, the VPS initiates. Replies go back through the tunnel naturally because the destination (10.10.10.1) is in the tunnel subnet.

➤ Do I need outbound NAT on the WireGuard interface?

Not for this setup. The VPS already has a route for your LAN subnet. Replies from Jellyfin route back through the tunnel without NAT.

➤ Do I need a gateway defined for the WireGuard interface?

Not strictly. Gateways are needed for policy routing, where you’re forcing LAN traffic out through the tunnel. Since the VPS initiates connections and replies route back naturally, OPNsense doesn’t need a gateway to make routing decisions.

➤ How do I add more services behind the VPS?

Add a firewall rule on the RackNerdVPS interface for each new service, specifying the exact destination IP and port. Or create an alias with all your allowed hosts and use that in a single rule (see Step 4 above). Don’t widen an existing rule to pass all traffic. Each service should be explicitly allowed.

On the VPS side, add a new reverse_proxy block in your Caddyfile (or server block in nginx) pointing to the new service’s LAN IP and port.

➤ AllowedIPs 0.0.0.0/0 vs 10.10.10.0/24?

For a reverse proxy setup, 10.10.10.0/24 is correct. 0.0.0.0/0 tells OPNsense to send all traffic through the tunnel, which is a full-tunnel setup. Different use case, different guide, different headaches.

➤ What if I also want some LAN devices to use the VPS as their internet gateway?

That’s a full-tunnel setup and requires additional configuration: changing AllowedIPs to 0.0.0.0/0, creating a gateway, adding policy-based routing rules on LAN, and setting up outbound NAT on the WireGuard interface. It’s doable, but it’s a separate project. Don’t try to bolt it onto this guide. You’ll break what’s already working.

➤ What MTU should I use?

Start with 1420 on bare metal, 1412 on PPPoE, or 1380 if OPNsense is virtualized. Test with a do-not-fragment ping. If Jellyfin streams stall on large video files but the web UI loads fine, your MTU is too high. See the MTU Tuning section for the full procedure.

➤ Is my home IP exposed in this setup?

No. Internet clients connect to your VPS public IP. Caddy handles TLS termination and reverse proxies through the tunnel. The client never sees your home IP. Your WAN IP is only used for the WireGuard handshake to the VPS, which is encrypted UDP traffic on port 51820. An observer would see your home IP connecting to the VPS, but they can’t see what’s inside the tunnel or what services you’re running.

Wrapping Up

A VPS reverse proxy setup through WireGuard is one of the simplest tunnel configurations you can run. The pieces that matter:

WireGuard instance and peer configured on OPNsense
Interface assigned so firewall rules can attach to it
A tight firewall rule that only allows VPS traffic to your specific services
A route and AllowedIPs entry on the VPS so it knows your LAN subnet lives behind the tunnel

Get those four things right and everything works. Get the firewall rule lazy (pass any to any) and you’ve handed anyone who compromises your VPS a direct path to your entire LAN. Don’t do that. I’ve seen the aftermath, and it’s not a fun weekend.

If you’re building a serious homelab, this setup unlocks:

Secure VPS reverse proxy without exposing home ports
Multiple services behind a single VPS IP
TLS termination at the VPS edge
Hidden home IP for all exposed services

Next step: experiment with adding more services behind the tunnel and segmenting them with per-service firewall rules.

This is Part 3 of a 3-part series on building a VPS-fronted homelab. If you landed here first, start with the why and the tunnel build:

Part 1: Why Your Homelab Needs a VPS Why a VPS edge beats home port forwarding for public-facing services.

Read Part 1

Part 2: Install WireGuard on a VPS Build the VPS-to-homelab WireGuard tunnel with iptables port forwarding and a Caddy reverse proxy.

Read Part 2

Part 3: WireGuard Client on OPNsense and pfSense: LAN Routing for Your VPS Tunnel (this post)

WireGuard VPS to Homelab Tunnel: Port Forwarding + Caddy

Thu, 05 Mar 2026 07:23:42 +0000

Exposing your homelab to the internet is risky. Port forwarding your home router, poking holes in firewalls, juggling dynamic IPs, dealing with CGNAT. It gets messy fast.

A cleaner approach: install WireGuard on a cheap VPS, create a secure tunnel back to your homelab, and let the VPS act as your public gateway. From there, layer in a Caddy reverse proxy for HTTPS, lock down the VPS with iptables.

I’ve done this a few times now. Getting WireGuard running was the easy part. The part that drove me insane was an MTU mismatch silently killing large packet transfers. The fix was two lines. Finding it was the hard part.

This guide walks through the VPS setup, including the parts that usually break.

💭

TL;DR:
Install WireGuard on your VPS. Lock it down with iptables. Test the tunnel with a temporary Linux client. Use Caddy on the VPS to reverse proxy traffic through the tunnel to your homelab services. Tune MTU if large transfers stall or don't work at all. Permanent homelab client setup on OPNsense/pfSense is in Part 3.

Architecture Overview: VPS Gateway + Homelab Client

Here’s what we’re building:

VPS (public IP)
- WireGuard server
- Caddy reverse proxy (handles TLS and proxies to homelab through the tunnel)
- iptables host firewall
Homelab (behind NAT or CGNAT)
- WireGuard client (OPNsense/pfSense setup in Part 3)
- Local services (Jellyfin, Immich, dashboards, etc.)
- Optional internal reverse proxy (Nginx, Traefik, Caddy)

Traffic flow:

Internet -> VPS -> External Reverse Proxy -> WireGuard tunnel -> Homelab service

📝

Note: Caddy terminates the incoming connection and opens a new one to your homelab through the tunnel. This is proxied traffic, not forwarded traffic. The kernel’s FORWARD chain never sees it. That means the base setup needs no FORWARD rules, no NAT, and no IP forwarding. The iptables firewall only needs to protect the VPS itself.

Your home network stays private. No router port forwarding required.

Prepare the VPS (Debian 13)

This guide assumes:

Debian 13 is installed on your VPS. Ubuntu 24.04 or 22.04 works too with the same commands.
First login is with root
No other users have been created

Update the System and Install Required Packages

apt update && apt upgrade -y && apt install sudo iptables -y

Create a New User

adduser <username>

Add the user to the sudo group

usermod -aG sudo <username>

Verify they are in the sudo group:

id <username>

Should return this:

uid=1001(username) gid=1001(username) groups=1001(username),27(sudo),100(users)

You can see that group ID 27 (sudo) was added.

Install WireGuard

apt install wireguard -y && chmod 770 /etc/wireguard/ && chown root:<username> /etc/wireguard/

Switch from root to the normal user with sudo rights

su <username>

Generate WireGuard Keys

On the VPS:

cd /etc/wireguard && sudo wg genkey | sudo tee server_private.key | wg pubkey > server_public.key

server_private.key stays secret. Never paste it into chat, docs, or ticket systems. Not even “only for a second.” Keys leak. They always leak.
server_public.key will be shared with the homelab.

Lock down the private key immediately:

sudo chmod 600 server_private.key

❌

Danger: If you skip this, anyone with shell access to that box can read your tunnel credentials. Don’t skip this.

Configure the VPS WireGuard Server

Create the config file:

sudo nano /etc/wireguard/wg0.conf

Example:

[Interface]
Address = 10.10.10.1/24
PrivateKey = <server_private_key>
ListenPort = 51820

That’s it. No PostUp, no PostDown, no iptables spaghetti crammed into a WireGuard config. The firewall is managed separately, which is where it belongs.

⚠️

Warning: Avoid overlapping subnets. If your home LAN is 10.0.0.0/24, pick something else like 10.13.13.0/24. Overlapping subnets cause traffic to stay local instead of hitting the tunnel, and the resulting behavior looks like the tunnel is broken when it’s actually a routing conflict.

Secure the VPS with iptables

Your VPS is on the public internet. Lock it down before you do anything else.

These rules control what traffic the VPS accepts for itself (the INPUT chain). Since Caddy proxies traffic rather than forwarding it, these INPUT rules are all you need for the base setup.

sudo iptables -A INPUT -m conntrack --ctstate ESTABLISHED,RELATED -j ACCEPT
sudo iptables -A INPUT -i lo -j ACCEPT
sudo iptables -A INPUT -p icmp -j ACCEPT
sudo iptables -A INPUT -p tcp --dport 22 -j ACCEPT
sudo iptables -A INPUT -p tcp --dport 80 -j ACCEPT
sudo iptables -A INPUT -p tcp --dport 443 -j ACCEPT
sudo iptables -A INPUT -p udp --dport 51820 -j ACCEPT
sudo iptables -P INPUT DROP

What each of these do:

Accept return traffic for existing connections
Accept loopback (local services talking to each other)
Accept ICMP (ping, path MTU discovery)
Accept SSH
Accept HTTP
Accept HTTPS
Accept WireGuard
Drop everything else

Rule order matters here. The conntrack rule goes first because it handles the bulk of traffic in a single check. Everything after that is for new inbound connections only. The policy DROP at the end catches anything you didn’t explicitly allow.

Persist across reboots:

sudo apt install iptables-persistent -y
sudo netfilter-persistent save

Verify your rules are in place:

sudo iptables -L INPUT -n -v --line-numbers

Your rules should look like this:

Chain INPUT (policy DROP 3 packets, 171 bytes)
num pkts bytes target prot opt in out source destination 
1 7 492 ACCEPT all -- * * 0.0.0.0/0 0.0.0.0/0 ctstate RELATED,ESTABLISHED
2 0 0 ACCEPT all -- lo * 0.0.0.0/0 0.0.0.0/0 
3 0 0 ACCEPT icmp -- * * 0.0.0.0/0 0.0.0.0/0 
4 0 0 ACCEPT tcp -- * * 0.0.0.0/0 0.0.0.0/0 tcp dpt:22
5 0 0 ACCEPT tcp -- * * 0.0.0.0/0 0.0.0.0/0 tcp dpt:80
6 0 0 ACCEPT tcp -- * * 0.0.0.0/0 0.0.0.0/0 tcp dpt:443
7 0 0 ACCEPT udp -- * * 0.0.0.0/0 0.0.0.0/0 udp dpt:51820

You should see your rules numbered in order. If you lock yourself out of SSH, most VPS providers have a web console or rescue mode. Test SSH access in a second terminal before you close your current session.

A Note on Firewall Coexistence

These iptables rules assume a clean firewall. If you’re on a fresh VPS from RackNerd, Hetzner, Linode, Vultr, or DigitalOcean with no custom firewall configured, you’re good.

If you’ve customized your firewall or aren’t sure, check what’s running:

sudo ufw status
sudo nft list ruleset

If UFW is active: Disable it or manage your rules through UFW instead. Running both UFW and raw iptables rules leads to confusion. Pick one.

If nftables is running: On many VPS images, iptables is actually a compatibility layer over nftables. Your commands will still work, but it’s worth knowing what’s underneath. Consider writing your rules in nft syntax instead if you prefer.

Cloud provider firewalls: Check your provider’s security group or firewall panel separately. AWS, Oracle Cloud, and Hetzner Cloud all have external firewalls that block traffic regardless of what you configure on the box itself. You’ll need to allow UDP 51820, TCP 80, TCP 443, and TCP 22 there too. This trips people up all the time. You can have perfect iptables rules and still get nothing because the cloud firewall is dropping it upstream.

Start WireGuard

sudo wg-quick up wg0
sudo systemctl enable wg-quick@wg0

Verify:

sudo wg show

Should look like this:

interface: wg0
 public key: <Server_Public_Key>
 private key: (hidden)
 listening port: 51820

If this shows your interface and listening port, the VPS side is ready. If it shows nothing, go back and check that wg0.conf has valid syntax and your private key file is readable.

Test the Tunnel with a Temporary Client

Before configuring your firewall appliance as the permanent WireGuard client (covered in Part 3), verify the VPS side works with a quick throwaway Linux client. Any machine on your homelab network will do. You need something that can run WireGuard long enough to confirm the tunnel is alive.

Install WireGuard and generate keys:

sudo apt install wireguard -y
wg genkey | tee client_private.key | wg pubkey > client_public.key
chmod 600 client_private.key

Copy the contents of client_public.key and paste it into the [Peer] section of your VPS wg0.conf.

cat client_public.key

On the VPS, paste the key into wg0.conf

sudo nano /etc/wireguard/wg0.conf

It should look like this:

[Interface]
Address = 10.10.10.1/24
PrivateKey = <Server_Private_Key>
ListenPort = 51820

[Peer]
PublicKey = <Client_Public_Key>
AllowedIPs = 10.10.10.2/32

Then restart WireGuard on the VPS:

sudo wg-quick down wg0
sudo wg-quick up wg0

Create a minimal config on the test client:

sudo nano /etc/wireguard/wg0.conf

It should look like this:

[Interface]
Address = 10.10.10.2/24
PrivateKey = <Client_Private_key>
MTU = 1420

[Peer]
PublicKey = <Server_Public_Key>
Endpoint = <VPS_Public_IP>:51820
AllowedIPs = 10.10.10.0/24
PersistentKeepalive = 25

PersistentKeepalive = 25 is required if your homelab is behind NAT or CGNAT. Without it, the NAT mapping expires, and the tunnel goes silent. If you’re not sure whether you need it, you need it.

Bring the tunnel up:

sudo wg-quick up wg0

Don’t enable it as a service. This is a test, not the permanent setup.

Now verify from both sides. On the test client:

ping 10.10.10.1

On the VPS:

ping 10.10.10.2

Check the handshake:

sudo wg show

If it is working it should look like this:

interface: wg0
 public key: <Client_Public_Key>
 private key: (hidden)
 listening port: 45365

peer: <Server_Public_Key>
 endpoint: <VPS IP>:51820
 allowed ips: 10.10.10.0/24
 latest handshake: 1 minute, 10 seconds ago
 transfer: 1.27 KiB received, 2.08 KiB sent
 persistent keepalive: every 25 seconds

You should see a recent handshake timestamp. If you don’t, jump to the troubleshooting section below.

If pings work in both directions, the VPS side is solid. Tear down the test client when you’re done:

sudo wg-quick down wg0

I will cover a permanent client setup on OPNsense or pfSense in next week’s post, including interface assignment, gateway creation, and LAN routing so all devices on your network can reach the tunnel.

MINISFORUM MS-A2 A compact mini-workstation built around up to a 16-core Ryzen 9 9955HX, with dual 10GbE SFP+ plus dual 2.5GbE, flexible storage (U.2 + M.2 including 22110), and triple 8K display outputs. Great as a homelab node or small server with serious I/O.

Amazon Price: Loading...

Availability: Checking...

Contains affiliate links. I may earn a commission at no cost to you.

Set Up Caddy on the VPS

Now expose services safely using Caddy as a reverse proxy. Caddy is installed directly on the VPS as a system package. No Docker required. It binds to ports 80 and 443 on the host, handles Let’s Encrypt certificates automatically, and proxies traffic through the WireGuard tunnel to your homelab. No bridge networks, no volume mounts, no container restarts to debug. One less layer between the internet and your services.

Install Caddy

Add the official Caddy repository and install:

sudo apt install -y debian-keyring debian-archive-keyring apt-transport-https curl
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/gpg.key' | \
 sudo gpg --dearmor -o /usr/share/keyrings/caddy-stable-archive-keyring.gpg
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/debian.deb.txt' | \
 sudo tee /etc/apt/sources.list.d/caddy-stable.list
sudo apt update
sudo apt install caddy -y

This installs Caddy as a systemd service. It starts automatically and runs as the caddy user. Verify it’s running:

sudo systemctl status caddy

You should see active (running). If it failed, check the journal:

journalctl -u caddy --no-pager -n 50

Configure the Caddyfile

The default Caddyfile lives at /etc/caddy/Caddyfile. Open it:

sudo nano /etc/caddy/Caddyfile

Replace the contents with your reverse proxy config:

flix.example.com {
 reverse_proxy 10.10.10.2:8096 {
 header_up Host {host}
 header_up X-Real-IP {remote_host}
 header_up X-Forwarded-Proto https

 flush_interval 5s

 transport http {
 read_buffer 65536
 write_buffer 65536
 dial_timeout 30s
 response_header_timeout 0
 }
 }
}

photos.example.com {
 reverse_proxy 10.10.10.2:2283 {
 header_up Host {host}
 header_up X-Real-IP {remote_host}
 }
}

After editing, reload Caddy to pick up the changes:

sudo systemctl reload caddy

Use reload, not restart. A reload validates the new config first and keeps the old config running if validation fails. A restart kills the process and hopes for the best. Get in the habit of using reload.

This forwards HTTPS traffic from the internet to the VPS, through WireGuard, to your homelab services.

Caddy handles Let’s Encrypt certificates automatically. Make sure each subdomain has a DNS A record pointing to the VPS public IP before you reload. Caddy will try to provision certificates immediately and will fail if DNS isn’t ready. Check journalctl -u caddy if certificates aren’t appearing.

Preserving Client IP

By default, Caddy sets X-Forwarded-For headers. If your homelab service needs the real client IP (Jellyfin’s fail2ban integration, for example), make sure the internal service trusts the VPS tunnel address (10.10.10.1) as a proxy. Without this, every request your services see will appear to come from the tunnel IP. Your access logs become useless and any IP-based rate limiting or banning breaks.

MINISFORUM MS-01 Mini Workstation The MS-01 i5 is a tiny mini PC with plenty of cores, multiple NVMe slots, and real homelab networking (dual 10G SFP+ plus 2.5 GbE), which makes it perfect for a Proxmox compute node. It has more than enough power for Jellyfin, the *arr stack, downloads, and a few VMs or LXCs, without turning your closet into a jet engine or space heater.

Amazon Price: Loading...

Availability: Checking...

Contains affiliate links. I may earn a commission at no cost to you.

MTU Problems: The Silent Killer

This cost me hours. It will cost you hours too if you don’t read this section before you need it.

Symptoms:

Small pings work.
HTTPS loads halfway, then stalls.
File uploads freeze.
No obvious errors in logs.

Everything looks fine. Nothing works fine. The issue is usually an MTU mismatch between your VPS provider and home ISP. Packets too large for the tunnel get silently dropped because ICMP “fragmentation needed” messages are blocked somewhere along the path. This is called a PMTU black hole, and it is exactly as fun as it sounds.

WireGuard defaults to 1420. Some VPS networks require lower values.

How to Diagnose MTU Issues

On homelab:

ping -M do -s 1372 10.10.10.1

Start at 1372 and increase by 10 until packets fail. The highest working value plus 28 bytes (IP + ICMP headers) is your effective MTU.

If fragmentation fails above 1380, try:

MTU = 1280

Add it to both configs under [Interface], then restart WireGuard on both ends.

This small change fixes a surprising number of “random” tunnel issues. If you’re seeing intermittent stalls on large transfers, check MTU first. Always MTU first.

An MTU of 1380 is what worked best for me streaming Jellyfin on my RackNerd VPS.

Dual Reverse Proxy Architecture (Advanced)

For larger setups, a two-proxy approach keeps things clean:

VPS: Caddy public-facing, handles TLS termination
Homelab: Nginx, Traefik, or Caddy internally, handles service routing

Flow:

Internet
|
VPS Caddy (TLS termination, public certificates)
|
WireGuard tunnel
|
Homelab Reverse Proxy (service routing, internal TLS optional)
|
Service containers

Advantages:

SSL termination at the VPS keeps certificate management in one place
Adding new services means updating the homelab proxy only. The VPS side stays stable.
Zero exposed home ports

The VPS proxy passes X-Forwarded-For and X-Real-IP headers. Your homelab proxy should trust the tunnel source IP (10.10.10.1) and preserve these headers for accurate logging.

Example: VPS Caddy + Homelab Nginx

On the VPS, edit /etc/caddy/Caddyfile to point everything at the homelab’s internal reverse proxy on a single port:

jellyfin.yourdomain.com {
 reverse_proxy 10.10.10.2:8080
}

nextcloud.yourdomain.com {
 reverse_proxy 10.10.10.2:8080
}

dashboard.yourdomain.com {
 reverse_proxy 10.10.10.2:8080
}

Then reload:

sudo systemctl reload caddy

On the homelab, Nginx listens on port 8080 and routes by hostname:

server {
 listen 8080;
 server_name jellyfin.yourdomain.com;

 set_real_ip_from 10.10.10.1;
 real_ip_header X-Forwarded-For;

 location / {
 proxy_pass http://127.0.0.1:8096;
 proxy_set_header Host $host;
 proxy_set_header X-Real-IP $remote_addr;
 proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
 }
}

server {
 listen 8080;
 server_name nextcloud.yourdomain.com;

 set_real_ip_from 10.10.10.1;
 real_ip_header X-Forwarded-For;

 location / {
 proxy_pass http://127.0.0.1:8443;
 proxy_set_header Host $host;
 proxy_set_header X-Real-IP $remote_addr;
 proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
 }
}

The key lines are set_real_ip_from 10.10.10.1 and real_ip_header X-Forwarded-For. Without these, every request your services see will appear to come from the tunnel IP instead of the real client.

This pattern scales well. You add new services by updating your homelab proxy config. The VPS Caddyfile needs one more reverse_proxy block pointing at the same homelab port.

Using Private Internet Access WireGuard

If you already use Private Internet Access WireGuard, do not reuse that interface for your VPS tunnel. I cannot stress this enough. Mixing them on the same interface causes conflicting routes that silently break one tunnel or the other, default route overrides that send your VPS traffic through PIA, and DNS conflicts where PIA’s settings clobber your homelab DNS.

Keep them on separate interfaces:

Use wg0 for the VPS tunnel.
Use wg1 for PIA.

If you need both active simultaneously, you’ll need policy routing with separate routing tables and fwmark rules to keep traffic on the right path. That’s a full topic on its own and easy to get wrong. I’ll cover it in a dedicated post. For now, the important thing is: separate interfaces, separate routing tables, no stacking.

Glovary N150 Firewall Mini PC A fanless N150 appliance with six Intel i226-V 2.5GbE ports and hardware AES-NI, built to run OPNsense or pfSense. AES-NI is what keeps WireGuard throughput high without pinning the CPU, and the six ports give you somewhere to terminate the tunnel that isn’t your ISP router.

Amazon Price: Loading...

Availability: Checking...

Contains affiliate links. I may earn a commission at no cost to you.

Troubleshooting Checklist

No Handshake

Is UDP 51820 open on the VPS? Check both the OS firewall (sudo iptables -L INPUT -n -v) and the cloud provider’s security group.
Correct public key on both sides? One wrong character and the handshake silently fails.
Correct endpoint IP and port?
NAT blocking outbound UDP from the homelab?
PersistentKeepalive = 25 set on the client?

Check:

sudo wg show

If no “latest handshake” time appears, the two sides aren’t talking at all. This is a network-level issue, not a WireGuard config issue. Focus on firewalls, security groups, and port reachability.

Caddy Returns 502 Bad Gateway

Caddy is running and serving certificates, but the proxied connection to your homelab is failing. This means the tunnel is probably up but the service on the other end isn’t reachable.

Can the VPS ping the homelab? ping 10.10.10.2
Is the homelab service listening on the expected port? SSH into your homelab and check with ss -tlnp | grep <port>.
Firewall on the homelab blocking inbound connections from the tunnel? Check iptables -L INPUT -n -v on the homelab side.

Caddy Not Serving or Certificates Failing

Check status and logs:

sudo systemctl status caddy
journalctl -u caddy --no-pager -n 50

Common causes: DNS A records not pointing at the VPS yet, port 80 or 443 already in use by another process (check with sudo ss -tlnp | grep ':80\|:443'), or a syntax error in the Caddyfile. Validate your config before reloading:

caddy validate --config /etc/caddy/Caddyfile

High Latency or Slow Throughput

Check MTU first. Seriously. I said this already. I’ll say it again.
Ensure no overlapping subnets between tunnel and LAN.
Avoid double NAT when possible.
Try lowering MTU to 1280 and test again.
Check VPS provider for bandwidth caps or throttling.

Frequently Asked Questions

➤ How do I forward specific ports from VPS to homelab over WireGuard?

Two options. For HTTP and HTTPS, use Caddy as a reverse proxy. It handles TLS, routing, and is simpler to manage.

➤ Do I need IP forwarding enabled?

The Caddy reverse proxy setup does not need IP forwarding because Caddy terminates connections locally and creates new ones through the tunnel. The kernel never forwards packets between interfaces in that case.

➤ Why is my WireGuard tunnel dropping packets?

Most of the time this is MTU. Lower MTU to somewhere between 1280 and 1400 and test with ping -M do. If that fixes it, you’ve found your problem.

➤ Do I need PersistentKeepalive?

Yes, if the homelab is behind NAT or CGNAT. Set it to 25 seconds. Without it, the NAT translation table entry expires and incoming packets get dropped.

➤ Can I run Caddy on the VPS and Nginx on my homelab?

Yes. This is the dual reverse proxy architecture described above. The VPS handles public TLS. The homelab proxy handles internal service routing. It’s the setup I recommend for homelabs with more than two or three exposed services.

➤ How do I generate and exchange keys securely?

Generate keys locally on each machine. Share only public keys. Transfer them over SSH or a secure channel. Never paste private keys into chat apps, shared documents, or ticket systems. If a private key has ever been visible to anyone or anything you don’t control, generate a new one.

Final Thoughts

WireGuard port forwarding through a VPS is one of the cleanest ways to expose your homelab to the internet.

The core steps covered in this post:

Install WireGuard on the VPS.
Generate keys.
Configure wg0.conf on the VPS.
Lock down the VPS with iptables.
Test the tunnel with a temporary Linux client.
Install Caddy and configure reverse proxy for HTTPS.
Fix MTU if large traffic stalls.

Next up: Part 3 covers setting up the permanent WireGuard client on OPNsense or pfSense with LAN routing so every device on your network can reach the tunnel.

The hardest part is rarely WireGuard itself. It’s understanding which traffic flows through which iptables chains, and MTU edge cases. Once you understand those pieces, the rest falls into place.

If you want to go further:

Add fail2ban on the VPS for SSH and service protection.
Use Cloudflare DNS with proxy mode for DDoS protection.
Add a second VPS for high availability.
Implement policy routing with multiple WireGuard tunnels.

Secure tunnels beat router port forwarding every time.

This is Part 2 of a 3-part series on building a VPS-fronted homelab. For the why behind this architecture, and how to route the tunnel into your LAN, see the other parts:

Part 1: Why Your Homelab Needs a VPS Why a VPS edge beats home port forwarding for public-facing services.

Read Part 1

Part 3: Route the Tunnel to Your LAN Set up the WireGuard client on OPNsense or pfSense so every device on your network reaches the tunnel.

Read Part 3

RaspberryPi 4GB A palm-sized single-board computer with a quad-core ARM CPU and 4GB RAM that runs full Linux, with Gigabit Ethernet, dual-band Wi-Fi, USB 3.0, and dual micro-HDMI. Ideal for lightweight homelab duties like running a WireGuard endpoint, Pi-hole, or small Docker stacks while sipping a few watts.

Amazon Price: Loading...

Availability: Checking...

Contains affiliate links. I may earn a commission at no cost to you.

VPS + WireGuard: Why Your Homelab Needs a Public Edge

Wed, 04 Mar 2026 07:42:23 +0000

You finally got your homelab dialed in. Jellyfin streams flawlessly. Your dashboards are organized. Maybe you’re even self-hosting Gitea, Nextcloud, or a personal blog.

Then comes the big question: how do you safely share those services with the outside world?

If your answer is port forwarding on your router, you’re not alone. I did the same thing. I slapped a reverse proxy and Cloudflare in front and called it a day. It worked. It felt secure. It was not as secure as I thought.

When I moved to a Virtual Private Server (VPS) running a second reverse proxy with a WireGuard tunnel back to my homelab, everything changed. My home IP disappeared from the public internet. My router stopped getting hammered. I stopped lying awake wondering what was poking at my network.

If you’re serious about running public-facing services from home, a VPS in front of your homelab is the smarter move. Not because port forwarding is automatically a problem, but because a VPS shrinks your attack surface and limits the blast radius when something goes wrong. And something always goes wrong eventually.

💭

TL;DR:
Direct port forwarding exposes your home IP to constant scanning and increases your attack surface. A VPS acting as a reverse proxy with a WireGuard tunnel hides your home network, reduces blast radius, and gives you more control than relying only on Cloudflare or other zero trust tunnel solutions.

The Real Problem With Port Forwarding at Home

Your Attack Surface Is Bigger Than You Think

When you forward ports on your router, you’re publishing your home IP address to the world. That’s not automatically a death sentence. ISPs rotate IPs, CGNAT exists, and plenty of people run services this way for years without incident. But every open port is another door you’re daring the internet to try.

That means:

Bots can scan and fingerprint your services
DDoS attempts can target your home connection directly
Persistent probing never stops, even on non-standard ports
A single misconfigured service becomes a direct entry point to your home network

Automated scanners are relentless. Within minutes of opening ports 80 or 443, you’ll see probes in your logs. Open 8096 for Jellyfin. Same story. The entire public IPv4 space gets scanned constantly, and your little corner of it is not special enough to be ignored.

Here’s why that matters more for homelabs than enterprise. You likely don’t have:

An IDS/IPS appliance doing deep packet inspection
Upstream DDoS mitigation from your ISP
A SOC team monitoring logs around the clock
Redundant uplinks or failover

Your home internet connection is a single point of failure. If someone floods it, your family loses internet too. That’s not a hypothetical. That’s a Tuesday for anyone running public services on a residential line.

The Myth of “Safe Port Forwarding”

Some argue that best practices, diligent patching, and network isolation make you 99% safe. In theory, maybe.

In practice:

Zero-days happen
Misconfigurations happen
Humans make mistakes
Bots don’t sleep

The issue isn’t only application security. It’s about reducing how much of your lab is reachable from the internet and limiting the damage when something inevitably slips through. Defense in depth isn’t paranoia. It’s plumbing.

Glovary N150 Firewall Mini PC
A fanless N150 appliance with six Intel i226-V 2.5GbE ports and hardware AES-NI, built for OPNsense or pfSense. AES-NI is what lets a box this small push WireGuard near line rate, and running the tunnel on the firewall rather than on one client puts your whole LAN behind it.

Amazon Price: Loading...

Availability: Checking...

Contains affiliate links. I may earn a commission at no cost to you.

What a VPS Changes for Your Homelab

A VPS Becomes Your Public Edge

A Virtual Private Server acts as your public-facing gateway. Instead of traffic going straight to your house, it hits the VPS first.

Instead of:

Internet → Your Home Router → Homelab

You get:

Internet → VPS → WireGuard Tunnel → Homelab

The world only sees the VPS IP address. Your home IP is never published. That one change shifts your entire risk profile.

Your Home IP Stays Private

All traffic terminates at the VPS first. The VPS forwards it over an encrypted WireGuard tunnel to your homelab.

From the outside:

DNS resolves to the VPS IP
Nmap scans hit the VPS
Attack traffic hits the VPS

If someone decides to DDoS your public endpoint, they’re punching the VPS, not your home router. Your family’s Netflix and your kid’s Minecraft session keep working.

No More Port Forwarding at Home

With the VPS plus WireGuard model, your home router stays locked down:

No forwarding ports 80 or 443
No exposing random service ports
No inbound NAT rules on your residential gateway

Only the VPS exposes ports publicly. On the home side, the WireGuard tunnel is outbound-initiated. Your homelab reaches out to the VPS, not the other way around. No inbound firewall rules needed on your router. That alone is a massive reduction in exposure.

Why Cloudflare Alternatives Matter

I used Cloudflare. Many homelabbers do.

Cloudflare Tunnel and Zero Trust solutions avoid open ports at home. That’s a real improvement over raw port forwarding. But there are trade-offs worth understanding before you go all-in.

Pros

No ports open at home
Easy setup
Automatic HTTPS
Built-in DDoS mitigation

TLS Termination and Trust

Cloudflare terminates TLS. That means Cloudflare decrypts your traffic and re-encrypts it to your origin. For hobby projects, that’s usually fine.

But here’s the trade-off: any reverse proxy you don’t control can see your decrypted traffic. That includes Cloudflare. It also includes a VPS provider if they wanted to snapshot RAM on the host, though that’s a different threat model. Both approaches involve trusting a third-party infrastructure provider. With a VPS you control, you at least decide where TLS terminates and you manage the certificates yourself.

You own the edge.

Vendor Lock-In

Cloudflare is excellent. It’s still a vendor. If you hit bandwidth limits, violate ToS unintentionally, need advanced routing, or want to proxy non-HTTP services, you can run into walls fast.

High-bandwidth media streaming is especially risky. Depending on your plan and usage, Cloudflare may throttle or flag you. Streaming terabytes of Jellyfin through their free tier is not what they had in mind.

With a VPS, you’re not tied to one company’s proxy layer. You can move providers without redesigning your entire network.

Non-HTTP Services

Cloudflare excels at HTTP and HTTPS. It is not built for everything else.

What about custom TCP services, game servers, experimental protocols, or self-hosted APIs over raw TCP? A VPS gives you full Layer 4 and Layer 7 control. You can proxy HTTP, HTTPS, TCP, UDP, and anything else WireGuard can tunnel.

That flexibility matters the moment you move beyond basic web apps.

The VPS + WireGuard Architecture Overview

No install steps here (the next post covers that). This is the lay of the land.

The Components

VPS in the cloud
- Static public IP
- Reverse proxy such as Caddy or Nginx
- Strict firewall rules (only ports 80, 443, and your WireGuard UDP port)
- WireGuard server
Homelab server
- WireGuard client (initiates the tunnel outbound)
- Services bound to private interfaces only
Secure tunnel
- Encrypted point-to-point VPN between VPS and homelab
- VPS routes inbound requests over the tunnel to your services

How Traffic Flows

User visits app.yourdomain.com
DNS points to the VPS public IP
VPS reverse proxy receives the request
VPS forwards the request over WireGuard to the homelab
Homelab responds through the tunnel
VPS returns the response to the user

At no point is your home IP exposed publicly.

If someone runs:

nmap yourdomain.com

They only see:

VPS ports
VPS fingerprint
VPS OS signature

Not your home network. Not your ISP. Nothing useful.

Security Layers You Gain

On the VPS you can stack additional defenses:

Rate limiting (via Caddy’s rate_limit directive or Nginx’s limit_req)
Fail2ban watching your proxy logs
Basic WAF rules
Geo-blocking at the firewall level
Strict ufw or nftables rules allowing only ports 80, 443, and your WireGuard UDP port

In most cases, you only need ports 80 and 443 open publicly. Restrict WireGuard’s UDP port to known peer IPs where possible with something like ufw allow from <home-ip> to any port 51820.

Your homelab becomes private infrastructure behind a single hardened edge node.

MINISFORUM MS-01 Mini Workstation
The MS-01 i5 is a tiny mini PC with plenty of cores, multiple NVMe slots, and real homelab networking (dual 10G SFP+ plus 2.5 GbE), which makes it perfect for a Proxmox compute node. It has more than enough power for Jellyfin, the *arr stack, downloads, and a few VMs or LXCs, without turning your closet into a jet engine or space heater.

Amazon Price: Loading...

Availability: Checking...

Contains affiliate links. I may earn a commission at no cost to you.

Trade-Offs You Should Understand

A VPS is not magic. It adds responsibility. Go in with your eyes open.

Cost

Expect around $5 per month at minimum for a basic VPS with reasonable bandwidth.

You need:

Enough bandwidth for your traffic (1-2 TB/month covers most homelabs)
Stable networking
Latency to your home under 100 ms if possible

For most homelabs, this is the cost of a fancy coffee once a month.

Added Latency

Traffic now takes a detour:

User → VPS → Home → VPS → User

That adds latency. How much depends on the distance between you and your VPS.

For dashboards, usually negligible. For media streaming, typically acceptable because buffering absorbs the delay. For real-time gaming, possibly noticeable. If latency climbs above 200 ms, choose a VPS region closer to you. You can also tune WireGuard MTU (try 1280) if you suspect packet fragmentation is making things worse.

You Must Secure the VPS

The VPS becomes your edge. Treat it like one. If you leave it misconfigured, you’ve only moved the problem from your house to a server you’re also responsible for.

You should:

Use SSH keys only (disable password auth in /etc/ssh/sshd_config)
Configure a host firewall (ufw or nftables)
Keep the system updated (unattended-upgrades on Debian/Ubuntu is your friend)
Monitor logs (even a simple logwatch cron job beats nothing)
Run nothing else on this box if you can help it

A VPS introduces its own management and patching burden. But it’s far easier to defend a minimal single-purpose VPS than an entire lab network with dozens of services hanging off your residential IP.

Realistic DDoS Expectations

A $5 VPS is not a bulletproof DDoS shield. Budget providers may null-route your IP if you attract significant attack traffic. That means your services go offline until the attack subsides.

But here’s why it’s still better than direct exposure: the attack lands on the VPS. Your family’s internet keeps working. You redeploy the VPS with a new IP, update DNS, and move on. Compare that to someone DDoSing your home connection directly, where your only option is to call your ISP and wait on hold.

The VPS shifts where the attack lands. It doesn’t eliminate DDoS risk entirely. Don’t kid yourself on that.

Amazon Price: Loading...

Availability: Checking...

Contains affiliate links. I may earn a commission at no cost to you.

Alternatives Compared

Approach	Home IP Hidden	Protocol Support	Management	Cost	Best For
Direct Port Forwarding	No	All	Low	Free	Temporary testing only
Cloudflare Tunnel / Zero Trust	Yes	HTTP/HTTPS mainly	Low	Free tier available	Low-traffic web apps
Tailscale / WireGuard Only	No (if publishing)	All	Low	Free tier available	Private remote access
VPS + WireGuard	Yes	All	Medium	~$5/month	Public-facing homelab services
Full Cloud Migration	Yes	All	High	$$$	Business-critical workloads

Direct Port Forwarding

Pros: Free, simple.
Cons: Exposes home IP, constant scanning, no DDoS buffer, high risk if misconfigured.
Best for: Temporary testing only. If you’re still using this in production, you’re living on borrowed time.

Cloudflare Tunnel / Homelab Warp or Zero Trust

Pros: No open ports, easy setup, DDoS mitigation, good for web apps.
Cons: TLS termination by a third party, vendor lock-in, bandwidth constraints for streaming, limited protocol flexibility.
Best for: Low-traffic HTTP apps, quick deployments.

Tailscale or Direct WireGuard Only

Using WireGuard or Tailscale without a VPS works well for internal access. It’s great for reaching your lab from your phone or laptop on the road.

Pros: Secure, no public exposure, excellent for private access.
Cons: Not designed for anonymous public users. If you publish services directly, your home IP is still exposed.
Best for: Personal remote access, admin connections.

VPS Reverse Proxy + WireGuard

Pros: Hides home IP, full control over TLS, works for HTTP and non-HTTP, flexible routing, reduced residential exposure.
Cons: Monthly cost, added latency, extra management layer.
Best for: Serious homelabbers running public-facing services, media servers, or custom apps.

Full Cloud Migration

Pros: Enterprise-grade infrastructure, no home exposure.
Cons: Higher recurring costs, less homelab control, less fun.
Best for: Business-critical services, high-risk workloads, or when compliance requirements enter the picture.

Troubleshooting and Operational Realities

Even good solutions need maintenance. Here’s where things break.

WireGuard Tunnel Drops

Symptoms:

Services intermittently unavailable
Reverse proxy returns 502
wg show shows no recent handshake (or a handshake timestamp from hours ago)

Common causes:

Home IP changed (dynamic IP from your ISP)
NAT timeout on your home router killed the session
MTU mismatch causing packet fragmentation

Mitigations:

Set PersistentKeepalive = 25 on the home peer’s WireGuard config. This sends a keepalive packet every 25 seconds, preventing NAT tables from expiring your session.
Lower MTU to 1280 in your WireGuard interface config if fragmentation is suspected
Monitor handshake timestamps with a cron job. Something like wg show wg0 latest-handshakes piped into a simple alerting script works.
Use a dynamic DNS updater (ddclient or a provider’s API script) if your home IP changes frequently

Reverse Proxy Errors

If the VPS returns 502 or 504:

Confirm the homelab service is actually running (systemctl status <service>)
Verify routing over the tunnel subnet (can the VPS ping your homelab’s WireGuard IP?)
Check SNI and TLS configuration in your reverse proxy
Ensure firewall rules on both ends allow tunnel traffic

Unexpected Public Exposure

Run:

nmap yourdomain.com

You should only see the VPS ports.

If you see your ISP IP in DNS records, HTTP headers, or service responses, investigate immediately. Check for DNS leaks (stale A records pointing home), misconfigured X-Forwarded-For headers, or services that embed your local IP in responses (some apps are chatty about this in their default configs).

RaspberryPi 4GB
A palm-sized single-board computer with a quad-core ARM CPU and 4GB RAM that runs full Linux, with Gigabit Ethernet, dual-band Wi-Fi, USB 3.0, and dual micro-HDMI. Ideal for lightweight homelab duties or for running a WireGuard endpoint while sipping a few watts.

Amazon Price: Loading...

Availability: Checking...

Contains affiliate links. I may earn a commission at no cost to you.

Frequently Asked Questions

➤ How does a VPS hide my homelab IP from attacks?

All public DNS records point to the VPS IP. Attackers reach the VPS and stop there. Your home IP is never published in DNS or exposed through HTTP headers. The WireGuard tunnel is outbound-initiated from your home, so no inbound firewall rules are needed on your router.

➤ What happens if my VPS provider null-routes me during an attack?

Your public services go offline temporarily, but your home internet stays unaffected. You can redeploy the VPS with a new IP, update DNS, and be back online. This is far better than having your entire home connection taken down.

➤ Can I use WireGuard port forwarding without a VPS for public services?

WireGuard alone is excellent for private access between your devices. For public-facing services without a VPS, you still need to forward ports on your home router, which exposes your residential IP. The VPS is what removes that exposure.

➤ What about CGNAT? Does that change the equation?

If your ISP uses CGNAT, you can’t port forward at all without their cooperation. A VPS with WireGuard actually solves this problem entirely. Your homelab connects outbound to the VPS, and the VPS handles all public traffic. CGNAT doesn’t matter because you’re never accepting inbound connections at home.

➤ How do I handle a dynamic home IP with this setup?

Set up a dynamic DNS client (like ddclient or your DNS provider’s update API) on your homelab that updates a hostname whenever your IP changes. Configure the WireGuard peer on the VPS side to use that hostname instead of a hardcoded IP. Combined with PersistentKeepalive, the tunnel re-establishes automatically after an IP change.

➤ What's the cheapest VPS that works for homelab proxying?

Look for:

Around $5 per month
1 GB RAM
1 vCPU
Generous bandwidth (1-2 TB minimum)
Static IPv4
KVM virtualization (avoid OpenVZ for WireGuard kernel module support)

Latency to your home should ideally be under 100 ms.

➤ When should I stop self-hosting and move to the cloud?

If you:

Handle sensitive client data
Require guaranteed uptime with SLAs
Face compliance requirements (HIPAA, SOC 2, etc.)
Attract sustained, large-scale attack traffic

It may be time to move critical services fully to the cloud. A VPS plus homelab combo works great for personal projects and media, but it’s not a substitute for managed infrastructure when the stakes are high.

Lessons Learned From Doing It Wrong First

I ran my homelab with a reverse proxy at home, Cloudflare in front, and strong passwords. I figured that was enough.

It wasn’t.

My IP was still exposed in certain scenarios. My logs showed constant probing. I was handing TLS termination to a third party without fully considering what that meant. And my home network was still in the blast radius if anything went sideways.

After moving to a VPS running Caddy as a reverse proxy with a WireGuard tunnel back home, I got IP privacy, cleaner architecture, zero exposed ports on my router, and a lot more confidence that a bad day on the internet wouldn’t become a bad day for my household.

The setup isn’t complicated. It requires you to accept that “good enough” wasn’t good enough.

The Right Architecture for Serious Homelabs

If you’re casually experimenting, port forwarding might feel fine for now. Know what you’re accepting.

If you’re serious about running public-facing services, a VPS in front is the better way to keep your home network out of the blast radius. It hides your home IP, eliminates router port forwarding, gives you full TLS control, works beyond HTTP, and scales with you.

Cloudflare and zero trust tools are useful. Tailscale is fantastic for private access. But if you want full control, privacy, and protocol flexibility, the VPS plus WireGuard model is the sweet spot for anyone looking to self-host their own edge.

Your homelab should be a playground, not a liability. If you’re going to open it to the internet, do it the right way.

This is Part 1 of a 3-part series on building a VPS-fronted homelab. Once you understand why a VPS edge beats home port forwarding, the next two parts walk through building it:

Part 2: Install WireGuard on a VPS Build the VPS-to-homelab WireGuard tunnel with iptables port forwarding and a Caddy reverse proxy.

Read Part 2

Part 3: Route the Tunnel to Your LAN Set up the WireGuard client on OPNsense or pfSense so every device on your network reaches the tunnel.

Read Part 3

Part 3: WireGuard Client on OPNsense and pfSense: LAN Routing for Your VPS Tunnel

How to Fix Stale File Handles NFS Errors with MergerFS

Sat, 14 Feb 2026 05:26:30 -0700

If you’re running a homelab NAS with a MergerFS and SnapRAID setup and sharing that pool over NFS, there’s a good chance you’ve hit one of the most frustrating errors in self-hosting: stale file handles. Files that were accessible five minutes ago suddenly aren’t. Containers break. Plex stops mid-stream. You restart everything, it works for a while, and then it happens again.

I spent way too long chasing stale file handles on NFS before landing on the real cause. It turned out to be a fundamental mismatch between how MergerFS works as a FUSE filesystem and what NFS expects from its exports. This post walks through the problem, why it happens, and the fix that finally made it go away for good.

💭

TL;DR:
Sharing a MergerFS pool directly over NFS causes stale file handles because NFS can't reliably track file handles across a FUSE filesystem. The fix is to export each underlying disk individually over NFS, then install MergerFS on the client machine and pool them there. Your SnapRAID config on the NAS doesn't need to change at all since it already points at the individual drives. The stale handle errors go away permanently because NFS is finally working with real filesystems instead of a FUSE layer.

Why MergerFS and NFS Cause Stale File Handles

MergerFS is a FUSE-based union filesystem. It takes multiple individual drives and presents them as a single merged mount point. If you’re running a typical MergerFS and SnapRAID homelab stack, you probably have several data disks pooled together with MergerFS for day-to-day use and SnapRAID providing parity protection on top. That architecture is great for local use. Your applications see one big pool and MergerFS handles file placement across the underlying disks based on your chosen policy.

The trouble starts when you export that merged FUSE mount point directly over NFS. NFS relies on file handles to track files across the network. These handles are tied to the underlying filesystem’s inode and device information. Because MergerFS runs as a FUSE filesystem in userspace rather than as a native kernel filesystem, it generates its own virtual file handles. When MergerFS resolves paths across drives, or when SnapRAID maintenance operations like syncs and scrubs touch the underlying files, those FUSE-generated handles can become invalid from NFS’s perspective. The NFS client asks for a file using a handle that no longer points to anything valid, and you get the dreaded Stale file handle error.

This isn’t a bug or a misconfiguration you can tune away.

MergerFS official Documentation
Explicitly calls this out. Exporting a FUSE-based MergerFS pool directly over NFS is not a supported workflow.

The Fix: Export Individual Drives Over NFS, Run MergerFS on the Client

The solution is to flip the architecture. Instead of pooling on the server and exporting the MergerFS mount, you export each underlying drive individually over NFS and then run MergerFS on the client side to combine them back into a single merged view.

It sounds like more work, but the setup is straightforward and the result is rock solid. NFS gets stable, predictable file handles because each export is a real ext4 or XFS filesystem on a real disk, not a virtual FUSE layer. MergerFS still gives you a single unified pool. It runs on the machine that actually consumes the data. And your SnapRAID parity setup on the NAS stays completely untouched, since SnapRAID operates on the individual drives rather than the merged pool.

Step 1: Export Each Drive Individually from the NAS

On your NAS (the NFS server), edit /etc/exports to export each disk in your MergerFS pool as its own NFS share. The critical detail here is that each export needs a unique fsid value. NFS uses fsid to distinguish between exports, and if you skip this or duplicate values, you’ll get weird cross-mount issues that look a lot like the stale file handle problem you’re trying to fix.

/mnt/Pool/Disk1/ 192.168.1.0/24(all_squash,anongid=1001,anonuid=1000,insecure,rw,subtree_check,fsid=1)
/mnt/Pool/Disk2/ 192.168.1.0/24(all_squash,anongid=1001,anonuid=1000,insecure,rw,subtree_check,fsid=2)
/mnt/Pool/Disk3/ 192.168.1.0/24(all_squash,anongid=1001,anonuid=1000,insecure,rw,subtree_check,fsid=3)

Repeat this pattern for every data disk in your pool. If you’re running SnapRAID, these are your data disks. You don’t need to export the SnapRAID parity disk. A few things to double-check on the export options:

anonuid and anongid should match the user and group IDs that own your media files (or whatever you’re serving). Run id <username> on the NAS if you’re not sure what these should be. Getting this wrong leads to permission denied errors that are easy to confuse with stale NFS file handles.
all_squash maps all client requests to the anonymous user, which keeps permissions simple in a homelab. If you need per-user access control, you’ll want a different approach, but for most media server and homelab setups this is the right call.
insecure allows connections from ports above 1024. Some NFS clients (especially on non-Linux systems or inside containers) need this.
The subnet (192.168.1.0/24 in this example) should match your actual network. Restrict this to the range that needs access.

After editing, apply the changes:

sudo exportfs -ra

Confirm the exports are live:

sudo exportfs -v

Step 2: Mount the Individual NFS Shares on the Client

On each client machine that needs access to the pool, start by creating the local mount points:

sudo mkdir -p /mnt/pool/disk1 /mnt/pool/disk2 /mnt/pool/disk3

Then add the NFS mounts to /etc/fstab:

192.168.1.5:/mnt/Pool/Disk1 /mnt/pool/disk1 nfs rw,nofail,hard,intr 0 0
192.168.1.5:/mnt/Pool/Disk2 /mnt/pool/disk2 nfs rw,nofail,hard,intr 0 0
192.168.1.5:/mnt/Pool/Disk3 /mnt/pool/disk3 nfs rw,nofail,hard,intr 0 0

Replace 192.168.1.5 with the actual IP of your NAS. The mount options here are worth understanding:

hard means the client will keep retrying if the NFS server becomes unreachable, rather than returning an error. For a homelab where reboots happen, this is usually what you want. The alternative, soft, gives up after a timeout, which can lead to data corruption if a write was in progress.
intr allows you to interrupt a hung NFS operation with a signal. Without this, a stuck NFS mount can lock up processes in a way that’s hard to recover from without a reboot.
nofail prevents the client from hanging at boot if the NAS isn’t available yet. Especially important if your NAS and clients boot at the same time after a power outage.

Mount everything:

sudo mount -a

Verify each disk is accessible:

ls /mnt/pool/disk1
ls /mnt/pool/disk2
ls /mnt/pool/disk3

Once the individual NFS mounts are stable, the next piece is the network link they all ride on. With three or four NFS shares running side by side, a 1GbE port becomes the bottleneck fast.

TP-Link 2.5GB PCIe Network Card (TX201)
Mounting three or four NFS shares on the client and pooling them through a MergerFS FUSE mount means your network link matters more than ever. This 2.5GbE PCIe card is cheap, works out of the box on most Linux distros, and makes sure the NIC isn’t the bottleneck when you’re streaming from a client-side merged pool.

Amazon Price: Loading...

Availability: Checking...

https://github.com/trapexit/mergerfs/releases

Contains affiliate links. I may earn a commission at no cost to you.

Step 3: Create the MergerFS FUSE Pool on the Client

Install MergerFS on the client if you haven’t already. On Debian/Ubuntu, grab the latest .deb from the MergerFS releases page:

sudo dpkg -i mergerfs_<version>.deb

Create the directory where the merged FUSE pool will appear:

sudo mkdir -p /media/storage

Then add the MergerFS FUSE mount to /etc/fstab:

/mnt/pool/disk* /media/storage fuse.mergerfs direct_io,defaults,allow_other,dropcacheonclose=true,inodecalc=path-hash,category.create=mfs,minfreespace=50G,fsname=storage 0 0

Here’s what the key MergerFS options are doing:

direct_io - Bypasses the kernel page cache. This is important when the underlying filesystems are NFS mounts, since the NFS client has its own caching layer. Double-caching through both NFS and FUSE leads to stale reads and wasted memory.
dropcacheonclose=true - Drops cached data when a file is closed. Another safeguard against stale data when MergerFS operates over NFS-mounted filesystems.
inodecalc=path-hash - Generates inode numbers based on the file path rather than the underlying device. This keeps inode numbers stable even if files exist on different disks, which matters for applications that track files by inode.
category.create=mfs - The “most free space” policy. New files get written to whichever disk has the most available space. Good default for media storage. If you’re using SnapRAID, keep in mind that new files written through this policy won’t be protected until the next snapraid sync runs.
minfreespace=50G - Disks with less than 50GB free won’t receive new files. Adjust this based on your disk sizes. You don’t want a drive filling up to 100%.
allow_other - Lets users other than the one who mounted the FUSE filesystem access it. Required if you’re running services like Plex, Jellyfin, or containerized apps under different user accounts.

Mount it:

sudo mount -a

Check that the merged pool looks right:

df -h /media/storage
ls /media/storage

You should see a single view of all your files across all disks, the same as before, but now without the stale file handle errors. Fewer, larger disks per NAS also means fewer NFS exports to manage and a simpler fstab on every client.

Seagate Barracuda 24TB Internal Hard Drive
When each disk in your MergerFS pool gets its own NFS export, bigger drives mean fewer exports to manage and fewer fstab entries on each client. 24TB per disk also means your SnapRAID parity drive covers a lot of storage per slot. Fewer disks, less complexity, same merged pool on the other end.

Amazon Price: Loading...

Availability: Checking...

Contains affiliate links. I may earn a commission at no cost to you.

Why This Fixes Stale NFS File Handles

The root cause was always about how FUSE filesystems interact with NFS file handles. When NFS exports a real, single-disk filesystem like ext4 or XFS, the file handles are based on stable inode and device IDs that don’t change. The NFS server and client stay in agreement about what each handle points to.

MergerFS, as a FUSE-based filesystem running in userspace, generates its own virtual file handles that can shift when the underlying layout changes. NFS has no mechanism to track those shifts across a FUSE layer, so the handles go stale. This is a fundamental limitation of exporting any FUSE filesystem over NFS, and it isn’t unique to MergerFS.

By moving the MergerFS FUSE mount to the client side, NFS only ever deals with real on-disk filesystems. Each NFS export is a direct, one-to-one mapping to a physical disk partition. The file handles stay valid indefinitely. MergerFS then operates entirely in local userspace on the client, where FUSE handle behavior doesn’t need to survive a network round-trip.

What Happens to SnapRAID in This Setup

If you’re running SnapRAID alongside MergerFS (which is one of the most common storage configurations in homelabs), nothing changes on the server side. SnapRAID always operates on the individual data disks, not on the MergerFS pool. Your SnapRAID configuration file still points to the same /mnt/Pool/Disk1, /mnt/Pool/Disk2, etc. paths. Your parity disk stays local to the NAS. Your snapraid sync and snapraid scrub cron jobs keep running exactly as before.

The only thing that changed is how those disks get to the client machines. Instead of NFS exporting a single FUSE-merged path, you’re exporting the same underlying directories that SnapRAID already knows about. If anything, this architecture is cleaner because there’s no ambiguity about which layer owns what. SnapRAID and NFS both work directly with the real filesystems, and MergerFS handles the convenience of a unified view on whatever machine needs it.

Things to Watch Out For

Boot order matters.
The NFS mounts need to be up before the MergerFS FUSE mount tries to pool them. In most cases, systemd handles this correctly because the fstab entries are processed in order and fuse.mergerfs depends on the mount points being available. If you’re seeing empty pools after a reboot, look into adding x-systemd.requires or x-systemd.after options to the MergerFS fstab line, or use an automount approach.

Adding new disks.
When you add a new drive to the NAS, you need to add a new NFS export on the server, a new NFS mount entry on each client, and update the MergerFS glob pattern if the new disk doesn’t match /mnt/pool/disk*. If you’re running SnapRAID, you’ll also need to add the new disk to your SnapRAID config and run a sync. You’d have to do that regardless of how you export over NFS.

SnapRAID sync timing.
Since new files written through the client-side MergerFS pool end up on individual disks on the NAS, they won’t have parity protection until the next snapraid sync. This is the same as any MergerFS and SnapRAID setup. It isn’t introduced by this architecture change. If you’re not already running SnapRAID syncs on a schedule, set up a cron job or use a helper script like snapraid-runner to automate it.

Performance.
Running a FUSE filesystem on the client over NFS mounts adds a small layer of overhead compared to a direct NFS export. In practice, for media streaming, file serving, and typical homelab workloads, this is negligible. The FUSE overhead is mostly in metadata operations, and the NFS network latency dominates actual file transfer times anyway. If you’re doing heavy random I/O or database-style workloads over this setup, you might want to benchmark, but that’s probably not what you’re using MergerFS for.

Multiple clients.
Each client that needs the merged view needs its own MergerFS install and FUSE mount configuration. This is the main tradeoff. It’s per-client setup instead of a single pool on the NAS. For most homelabs with one or two client machines, it’s not a big deal. If you have many clients, you might want to script the deployment or use configuration management.

Wrapping Up

Stale file handles on NFS with a MergerFS FUSE pool is one of those problems where the symptoms point you in every direction except the actual cause. You’ll check NFS timeouts, restart services, fiddle with cache settings, and none of it sticks. The real fix is architectural. Stop exporting the MergerFS FUSE mount over NFS. Export the individual drives directly and pool them with MergerFS on whatever client needs the merged view.

Your SnapRAID parity stays exactly where it is. Your NFS file handles stay stable because they’re backed by real filesystems instead of a FUSE layer. And you stop re-troubleshooting the same stale file handle errors every few weeks, which honestly is the best part.

If you’re sizing a new NAS around this architecture, a small bay count with a capable CPU is the sweet spot. You’re now serving multiple NFS exports per pool, and the pooling work has moved off the server entirely.

UGREEN NASync DXP4800 Pro 4-Bay Desktop NAS
Four bays, an Intel Core i3-1315U, and dual networking (10GbE + 2.5GbE). Four bays is the sweet spot for a MergerFS and SnapRAID setup. Three data disks pooled with MergerFS and one dedicated SnapRAID parity drive. Plenty of CPU headroom to serve multiple NFS exports without the FUSE overhead since pooling happens on the client side.

Amazon Price: Loading...

Availability: Checking...

Contains affiliate links. I may earn a commission at no cost to you.

How to Fix Proxmox Status 30 Errors with Unprivileged LXCs

Sat, 07 Feb 2026 07:18:30 -0700

You upgraded to Proxmox 9.1.5 and now your Jellyfin, Plex, or Arr containers refuse to start. They worked for months, maybe years, and now all you get is a cryptic “Status 30” error. Proxmox 9.1.5 enforces idmapped mounts for unprivileged LXC containers, and FUSE-based filesystems like MergerFS want nothing to do with them. My best guess is that these changes were made to better support the new OCI-compliant images, which let Proxmox run Docker images without needing Docker installed.

The fix: ditch mpX mounts entirely, replace them with lxc.mount.entry lines, and configure explicit unprivileged ID mapping.

This guide is for Proxmox users running unprivileged LXC containers with bind mounts on MergerFS or NFS storage. If all your storage is native Proxmox (ZFS, ext4, local directories), your mpX mounts will probably still work. You can stop reading and go enjoy your day.

I hit this after updating to Proxmox 9.1.5. Every container with MergerFS bind mounts failed after a reboot. No useful error message. No graceful fallback. Only “Status 30” and silence. After digging through logs and testing half a dozen approaches, the solution turned out to be straightforward. Annoying, but straightforward.

💭

TL;DR: Proxmox 9.1.5 enforces idmapped mounts for mpX bind mounts. MergerFS and most NFS setups don’t support idmapped mounts, which causes LXC startup to fail with Status 30. The fix: remove your mpX mounts, use lxc.mount.entry instead, and explicitly define your unprivileged UID and GID mappings. Details below.

Quick Check: Does This Apply to You?

Your storage is probably fine if it’s:

Local ext4, XFS, or ZFS on the Proxmox host
Native Proxmox directories

You’re affected if your storage is:

MergerFS pools
NFS mounts
Other FUSE-based filesystems
External USB or hybrid storage setups

If you’re in the second group, keep reading. Everyone else, go do something more fun.

What Is the Proxmox Status 30 Error?

Status 30 is LXC’s way of telling you something went wrong during container startup without telling you what went wrong. It’s a generic failure code that masks deeper filesystem or permission problems.

You’ll see messages like:

startup for container '102' failed
Script exited with status 30
Read-only file system (os error 30)

📝

Note: Status 30 means Proxmox tried to mount or write to storage and the kernel said no.

To find out why the kernel said no, you need to watch the errors live. Run this on the Proxmox host, replacing XXX with your container ID:

lxc-start -n XXX -F -l DEBUG -o /dev/stdout

Look for lines mentioning idmapped, mount, or permission denied. Those will point you toward the actual cause.

What Changed in Proxmox 9.1.5?

Proxmox 9.1.5 ships with a newer Linux kernel and tighter security defaults. The specific change that breaks MergerFS setups is broader enforcement of idmapped mounts for unprivileged containers.

When you define a container mount like:

mp0: /mnt/media,mp=/media

Proxmox now automatically:

Creates an idmapped mount
Shifts ownership so container UID 1000 maps cleanly to host UID 1000
Enforces isolation guarantees

This works great on native filesystems (ext4, XFS, ZFS). It completely fails on:

MergerFS (FUSE-based, no idmap support)
Most NFS exports (server-side ownership, no client idmap)
Some custom or layered storage stacks

When the kernel refuses the idmapped mount, Proxmox kills the LXC startup rather than opening a security hole. This shows up as a Status 30 error.

The mpX Trap: Why Old Configs Break

Before Proxmox 9.1.5, mpX mounts were forgiving. You could bind-mount media directories owned by UID 1000, and LXC handled permission translation loosely. Nobody complained.

After the upgrade, mpX mounts trigger the idmapping hook automatically. If your underlying filesystem doesn’t support it, three things happen:

Container fails to start
Misleading “read-only filesystem” errors appear in logs
Ghost mounts get left behind on the host (more on this in Step 5)

This is why containers without bind mounts start fine while your media servers all failed at the same time. Ask me how I know.

The Fix: Manual Mounting and Explicit Unprivileged ID Mapping

The temptation here is to flip your containers to privileged mode. Don’t. Privileged containers run as root on the host. If your Jellyfin or Plex container gets exploited, the attacker has root on your entire Proxmox host and can pivot to every other VM and container you’re running. That’s not a theoretical risk. Container escape vulnerabilities in shared-kernel setups are well-documented, and if you’re running services that download files from the internet (every Arr app, every torrent client), you’re handing a potential attacker the keys to your entire homelab. Keep your containers unprivileged.

The fix has three parts:

Remove mpX mounts so Proxmox stops trying to idmap them
Use raw lxc.mount.entry lines that LXC handles directly
Define clean, contiguous UID and GID maps so permissions work correctly

This keeps your containers unprivileged while sidestepping the MergerFS/NFS incompatibility entirely.

📝

Note:

Prerequisites checklist. Before starting, confirm you have the following ready. Experienced readers: don’t skip Steps 1 and 2. The ID delegation and mpX removal on the host are required before anything else works.

SSH or console access to your Proxmox host (not the container)
Your media user’s UID and GID (run id your_media_username on the host)
Your render group’s GID if you use GPU passthrough (run getent group render on the host)
The container ID(s) you need to fix
A backup of your container config file(s)

Step 1: Configure UID and GID Delegation on the Host

Before LXC can map host IDs into an unprivileged container, Proxmox needs explicit permission to use those IDs. That permission lives in two files on the host: /etc/subuid and /etc/subgid.

First, figure out your actual media user’s UID and GID. Run this on the host:

id your_media_username

The examples below assume UID 1000 and GID 1001. Replace these with your actual values throughout. If you copy-paste blindly and your IDs don’t match, you’ll be right back at Status 30. I won’t feel sorry for you.

Next, check your render group GID if you need GPU passthrough:

getent group render

This usually returns render:x:104 but it’s not guaranteed. On some distributions or custom setups, the render group could be GID 105, 128, or something else entirely. Whatever number you see here is the one you’ll use in every step below. If the command returns nothing, you don’t have a render group and can skip the render-related lines in Steps 1 and 4.

Edit these files on the Proxmox host.

Start with subuid:

nano /etc/subuid

Paste this:

root:1000:1
root:100000:65536

Next, edit subgid:

nano /etc/subgid

Paste this:

root:104:1
root:1001:1
root:100000:65536

What each line means:

root:1000:1 allows root to delegate host UID 1000 (your media user) into a container
root:104:1 allows root to delegate host GID 104 (the render group, for GPU passthrough). Replace 104 with whatever getent group render returned on your system.
root:1001:1 allows root to delegate host GID 1001 (your media group)
root:100000:65536 is the standard unprivileged ID range. Leave it alone.

If any of these entries are missing or wrong, LXC cannot construct a valid idmap and your container won’t start. There’s no partial credit here.

Step 2: Remove mpX Mounts from the Container

Back up your container config first. I mean it. Copy it somewhere safe before you touch anything.

cp /etc/pve/lxc/XXX.conf /root/XXX.conf.bak

Now open the config:

nano /etc/pve/lxc/XXX.conf

Delete or comment out any lines like:

mp0: /mnt/media,mp=/media
mp1: /mnt/downloads,mp=/downloads

Every single one. Leaving even one mpX entry triggers the idmapping hook, and you’re back to Status 30.

Step 3: Add Direct lxc.mount.entry Bind Mounts

At the bottom of the container config file, add manual mount entries:

lxc.mount.entry: /media/storage/Movies media/Movies none bind,create=dir,ro 0 0
lxc.mount.entry: /media/storage/Shows media/Shows none bind,create=dir,ro 0 0

Pay attention to these details. They’ll bite you if you get them wrong:

The container path (second field) is relative, no leading slash. Write media/Movies, not /media/Movies. This trips people up constantly.
bind tells LXC to handle the mount directly, bypassing Proxmox’s storage helpers.
create=dir tells LXC to create the mount point inside the container if it doesn’t exist. Without this, you’ll get a mount failure if the directory is missing.
Set ro or rw explicitly based on what the container needs. Read-only where possible. Your Jellyfin container doesn’t need write access to your movie library.

These mounts are handled by LXC itself, not Proxmox. That’s the whole point.

Step 4: Define Clean Unprivileged ID Mapping

This is the part where most people get tripped up. Unprivileged containers require a fully contiguous UID and GID map covering the range 0 through 65535. No gaps. No overlaps. If the math doesn’t add up to exactly 65536 IDs, the container will not start. LXC is merciless about this.

Customize these values. Replace 1000 with your actual media user’s UID. Replace 1001 with your actual media group’s GID. Replace 104 with your actual render group GID.

How the math works

Every lxc.idmap line maps a range of container IDs to host IDs. The format is:

lxc.idmap: <u|g> <container_start> <host_start> <count>

The rule is simple: every count value across all your lines for a given type (u or g) must add up to exactly 65536. When you pass through a specific ID (like your media UID), you split the range around it. Here’s the formula:

Range before passthrough: count = passthrough_id
Passthrough itself: count = 1
Range after passthrough: count = 65536 - passthrough_id - 1

For multiple passthroughs (like the GID map), you split around each one in order, and the counts between them fill the gaps.

Example A: UID 1000, GID 1001, render GID 104

This is the most common homelab setup. Add these lines to your container config:

UID Mapping:

lxc.idmap: u 0 100000 1000
lxc.idmap: u 1000 1000 1
lxc.idmap: u 1001 101001 64535

Table:

Container UIDs	Host UIDs	Count	Purpose
0 - 999	100000 - 100999	1000	Unprivileged range
1000	1000	1	Media user passthrough
1001 - 65535	101001 - 165535	64535	Unprivileged range
		65536	Total

GID Mapping:

lxc.idmap: g 0 100000 104
lxc.idmap: g 104 104 1
lxc.idmap: g 105 100105 896
lxc.idmap: g 1001 1001 1
lxc.idmap: g 1002 101002 64534

Table:

Container GIDs	Host GIDs	Count	Purpose
0 - 103	100000 - 100103	104	Unprivileged range
104	104	1	Render group passthrough
105 - 1000	100105 - 101000	896	Unprivileged range
1001	1001	1	Media group passthrough
1002 - 65535	101002 - 165535	64534	Unprivileged range
		65536	Total

Verify: 104 + 1 + 896 + 1 + 64534 = 65536. Contiguous. No gaps.

Example B: UID 1001, GID 1002, render GID 128

If your media user is UID 1001 with GID 1002, and your render group is GID 128, the math shifts:

UID Mapping:

lxc.idmap: u 0 100000 1001
lxc.idmap: u 1001 1001 1
lxc.idmap: u 1002 101002 64534

Verify: 1001 + 1 + 64534 = 65536.

GID Mapping:

lxc.idmap: g 0 100000 128
lxc.idmap: g 128 128 1
lxc.idmap: g 129 100129 873
lxc.idmap: g 1002 1002 1
lxc.idmap: g 1003 101003 64533

Verify: 128 + 1 + 873 + 1 + 64533 = 65536.

Notice the pattern: the gap between your two GID passthroughs (128 and 1002) is 1002 - 128 - 1 = 873. That’s the count for the middle range. The final range is always 65536 minus the sum of everything before it.

Don’t forget: if you use different IDs, you also need to update /etc/subuid and /etc/subgid from Step 1 to match. Those files must list every host ID you’re passing through.

⚠️

Warning: Quick sanity check. After writing your idmap lines, add up all the count values for your u lines and all the count values for your g lines. Both totals must equal exactly 65536. If either one doesn’t, your container will not start.

Step 5: Clear Stale Mounts Before Restarting

Failed startups leave behind ghost mounts on the host. If you try to start the container again without cleaning these up, it can fail in new and exciting ways.

⚠️

Warning: Only run this if your container previously failed to start. This forcibly unmounts staged mount points.

On the host, run:

umount -l /var/lib/lxc/.pve-staged-mounts/mp* 2>/dev/null

The -l flag performs a lazy unmount, which detaches the filesystem immediately and cleans up references once they’re no longer busy. This is safe for cleaning up after failed mount attempts. One caveat: don’t use lazy unmount as a habit for mounts that keep failing. It detaches the mount without fixing whatever caused the failure, so if you find yourself running this repeatedly, something deeper is wrong. Go back and check your config.

Now start your container:

pct start XXX

Step 6: Verify Everything Works

A clean start isn’t proof of success. Confirm permissions are correct end-to-end.

Check that mounts exist and ownership is correct:

pct enter XXX
ls -la /media/Movies

You should see your media files with the correct ownership. If the ownership looks wrong (everything owned by nobody or 65534), your idmap entries are off. Go back to Step 4 and double-check your math.

Test file operations (if using rw mounts):

Inside the container:

touch /media/Downloads/testfile
ls -la /media/Downloads/testfile
rm /media/Downloads/testfile

The test file should be owned by your media user, not root or nobody.

Confirm services start cleanly:

Inside the container, check your media service:

systemctl status jellyfin # or plex, sonarr, radarr, etc.

If the service is running and can see your library, you’re done. If it starts but can’t find media files, the mount exists but the path inside the container doesn’t match what the service expects. Double-check the container path in your lxc.mount.entry lines from Step 3.

Check LXC logs for clean startup (from the host):

lxc-start -n XXX -F -l DEBUG -o /dev/stdout

A clean startup will show your mount entries being applied without any idmapped errors or permission denials. If you see warnings but the container still starts, investigate them. Warnings that you ignore today become outages after the next update.

Why This Works

By switching from mpX to lxc.mount.entry, you:

Skip Proxmox’s idmapped mount helpers entirely
Bypass kernel-level idshift enforcement that FUSE filesystems can’t handle
Let LXC translate IDs at runtime using your explicit mapping

This is how LXC handled unprivileged containers before Proxmox 9.1.5 added automatic idmapping. You’re not doing anything weird or unsupported. You’re being explicit about what Proxmox used to do implicitly.

This configuration should survive future Proxmox updates because it relies on a stable LXC feature instead of a Proxmox-specific shortcut. That said, major version upgrades can always change defaults, so keep your config backups current and check release notes before upgrading.

Troubleshooting Status 30 Errors

Container Still Fails With Status 30

Work through this checklist:

Confirm that no mpX entries remain in /etc/pve/lxc/XXX.conf. Grep for them: grep '^mp' /etc/pve/lxc/XXX.conf
Verify /etc/subuid and /etc/subgid include entries for every ID you’re passing through
Check that your idmap ranges are contiguous and total 65536 for both UIDs and GIDs
Confirm the host paths in your lxc.mount.entry lines actually exist: ls -la /media/storage/Movies
Clear stale mounts (Step 5) and try again

Storage Appears Read-Only Inside the Container

Test write access directly on the host first:

touch /mnt/media/testfile && rm /mnt/media/testfile

If this fails, the problem is at the storage level, not LXC. Check your MergerFS config, underlying disk health, and filesystem mount options. If the host can write but the container can’t, double-check that your lxc.mount.entry line uses rw and not ro.

NFS Mounts Fail

NFS typically lacks idmapped mount support, so the same lxc.mount.entry approach applies. The extra wrinkle: your NFS export must allow access from the UIDs and GIDs you’re mapping.

⚠️

Warning: Check your /etc/exports on the NFS server. Make sure no_root_squash or appropriate user mapping is configured for the host IDs you’re passing through. This is easy to miss and will cause silent permission failures even if everything else is configured correctly.

Multiple Media Users or Docker Inside LXC

If you have more than one media user that needs passthrough (for example, separate users for Sonarr and Jellyfin), you need to add a passthrough line for each UID and GID in Step 4 and a delegation entry for each in Step 1. The same splitting logic applies: break the range around each passthrough ID and make sure the counts still total 65536.

If you’re running Docker inside an unprivileged LXC container (first WHY?!), you’ll hit additional nesting issues. Docker needs its own ID namespace, which adds complexity on top of the LXC mapping. This is solvable but outside the scope of this guide. The Proxmox wiki has a section on nested containers that covers the basics.

FAQs

➤ What causes Read-only file system (os error 30) in Proxmox?

Proxmox attempted a write through a mount that the kernel rejected. With MergerFS and unprivileged LXC containers, this almost always means the idmapped mount failed silently and the container got a read-only fallback. Switching from mpX to lxc.mount.entry fixes it.

➤ Is this specific to Proxmox 9.1.5?

Yes. Earlier Proxmox versions didn’t enforce idmapped mounts for unprivileged containers as aggressively. The kernel and LXC defaults changed in Proxmox 9 to make this behavior automatic.

➤ Should I switch to privileged containers?

No. Privileged containers run as root on the host, which means a compromised container gives an attacker full access to your Proxmox node and every VM and container on it. Manual ID mapping gives you both compatibility and security. The extra configuration is worth it.

➤ Does this affect VMs too?

VMs use a completely different storage model. They don’t use LXC bind mounts at all. However, MergerFS can still cause backup failures and disk I/O errors in VM environments for separate reasons.

➤ Will this survive the next Proxmox update?

The lxc.mount.entry directive is a stable LXC feature and not a Proxmox hack. It should survive point releases without issue. Major version upgrades could change defaults, so always read release notes and keep config backups before upgrading.

Conclusion

Proxmox 9.1.5 tightened its security defaults, which is a good thing. The side effect is that FUSE-based filesystems like MergerFS and certain NFS configurations got caught in the crossfire.

If you rely on MergerFS or NFS with unprivileged containers, the old mpX approach is dead. Replacing it with lxc.mount.entry and explicit ID mapping restores stability without giving up security.

Once configured correctly, containers start cleanly and survive updates. Status 30 becomes a bad memory. It’s an hour of config work that saves you from this headache permanently.

Recommended Hardware

The configuration above is what actually keeps MergerFS pools running under unprivileged LXCs. Here’s the hardware sitting behind it on my own host. Drives first, then the HBA that exposes them, then the cables that wire it all together.

Seagate Barracuda 24TB Internal Hard Drive
Solid high-capacity drive for MergerFS pools. I run several of these as the backing storage for the exact setup described in this guide. Not the cheapest per-TB option, but reliable and widely available.

Amazon Price: Loading...

Availability: Checking...

Contains affiliate links. I may earn a commission at no cost to you.

LSI 9211-8iB IT MODE
An HBA flashed to IT mode passes drives directly to the OS without a hardware RAID layer. This is what you want for MergerFS or ZFS setups where the OS needs raw disk access. Cheap on eBay, rock-solid, and still the default recommendation in most homelab communities.

Amazon Price: Loading...

Availability: Checking...

Contains affiliate links. I may earn a commission at no cost to you.

SFF-8087 to 4x SATA
You’ll need these breakout cables to connect SATA drives to the LSI HBA above. One cable handles four drives. Grab two if you’re filling a larger chassis.

Amazon Price: Loading...

Availability: Checking...

Contains affiliate links. I may earn a commission at no cost to you.

OPNsense vs pfSense for Homelabs (2026): Complete Comparison

Fri, 23 Jan 2026 08:22:37 -0700

What are OPNsense and pfSense and Why It Matters for Homelabs in 2026

OPNsense versus pfSense is the most debated firewall choice in homelab communities. Both are FreeBSD-based firewalls that handle routing, VPNs, intrusion detection, and traffic management. They cover the same ground technically. The real differences come down to philosophy, user experience, and whether you trust the vendor not to change the deal later.

I ran pfSense for years because it was “the standard.” Then Netgate started moving features to pfSense Plus. The line between “free” and “pay us” kept shifting. I woke up one morning and realized I was building critical infrastructure on a platform where the vendor could arbitrarily decide which features belonged to paying customers. I rebuilt on OPNsense that weekend.

Neither firewall is objectively “better.” But one might fit your tolerance for corporate shenanigans a lot better.

This guide is for homelabbers who want to pick one firewall, deploy it, and move on. You’ll know which one by the end.

💭

TL;DR: Both OPNsense and pfSense are solid FreeBSD-based firewalls. If you want a modern UI, more built-in features, and development that won’t suddenly go closed-source, pick OPNsense. If you want conservative releases and a massive backlog of legacy documentation (and trust Netgate), pfSense works fine.

Quick Comparison: OPNsense vs pfSense at a Glance

Feature	OPNsense	pfSense
License	Fully Open Source	CE: Open, Plus: Proprietary
UI Style	Modern sidebar navigation	Traditional top menu
Update Frequency	Bi-yearly major releases	Annual major releases
Built-in IDS	Yes (Suricata)	Requires package install
WireGuard	Built-in by default	Requires plugin
Security Patches	Days after FreeBSD	CE waits for Plus first
Best For	Modern workflows, open-source advocates	Conservative updates, legacy setups

Core Similarities: Why This Choice Is Hard

Both platforms do the same basic job:

FreeBSD-based firewall and router
Stateful packet inspection and NAT
VLANs, LAGG (bond NICs together), multi-WAN failover
VPN: IPsec, OpenVPN, WireGuard
Runs on bare metal or VMs
Works great on Proxmox

For basic WAN-to-LAN routing and site-to-site VPN, either one will work. You could pick based on a coin flip and be fine.

The differences matter when you live with the system for months or years.

UI and Usability: OPNsense vs pfSense Interface Comparison

OPNsense UI Philosophy

OPNsense broke from pfSense’s interface years ago. That decision has paid off.

The UI uses a left-side collapsible menu. Interfaces are under Interfaces. Firewall rules are under Firewall. Services are under Services. Interface descriptions are editable during assignment instead of buried three clicks deep where you’ll never find them again.

Virtual NICs live under Interfaces; pfSense buries them under Firewall. Intrusion Detection lives under Services rather than hidden in a package submenu. When you’re trying to fix something late at night, you won’t spend five minutes hunting for the setting you need.

If you experiment, break things, and rebuild regularly, this consistency may keep you sane.

pfSense UI Philosophy

pfSense uses a top navigation bar with nested dropdowns. It works. It also shows its age.

Strengths:

More default dashboard widgets (about 22 vs OPNsense’s 17)
Consistent with documentation from 2015
Familiar if you’ve used pfSense for years

Weaknesses:

Settings scattered across Firewall, System, and Services (good luck)
Interface descriptions require extra clicks after assignment
Package settings bolted onto the side like afterthoughts

If you learned pfSense first, you know where everything is. If you’re new, you’ll spend time hunting. I’ve watched people stare at the top menu for 30 seconds trying to remember where DHCP server settings live. (Services, if you’re wondering.)

Real-World UI Example: Setting Up VLANs

To create a guest VLAN with internet access but blocked LAN access:

OPNsense:

Interfaces > Other Types > VLAN (create VLAN 10)
Interfaces > Assignments (assign to OPT1)
Firewall > Rules > OPT1 (add allow-internet rule)
Firewall > Rules > OPT1 (add block-LAN rule above it)

pfSense:

Interfaces > Assignments > VLANs (create VLAN 10)
Interfaces > Assignments (assign to OPT1)
Interfaces > OPT1 (enable and configure)
Firewall > Rules > OPT1 (add rules)

Both work. OPNsense puts VLANs under Interfaces where you’d look for them. pfSense buries VLAN creation under Assignments. One extra click that always feels wrong.

UI clarity matters? Pick OPNsense. Years of muscle memory? Stick with pfSense.

Glovary N150 Firewall Mini PC Fanless, silent, and shipped with six Intel i226-V 2.5GbE ports out of the box. If you want to compare both platforms fairly, this box has two M.2 slots. Keep an OPNsense install on one NVMe drive and pfSense on the other, then swap between them. The tradeoff is cost. You’ll pay more than repurposing an old desktop.

Amazon Price: Loading...

Availability: Checking...

Contains affiliate links. I may earn a commission at no cost to you.

Plugin Ecosystems and Built-In Features

OPNsense: More Included by Default

OPNsense ships with these features enabled:

Intrusion Detection (watches your network traffic, alerts on sketchy behavior)
Traffic reporting dashboards
Monit service monitoring (restarts dead services automatically)
CPU, memory, disk widgets
Built-in WireGuard VPN

You can enable most of these without installing a plugin. Fewer plugins mean fewer things that can break during upgrades. (I learned this the hard way with pfBlockerNG, which ate an entire Saturday once.)

Optional plugins exist for SMART monitoring, Wake-on-LAN, and Zenarmor traffic inspection. But the core firewall works fine without them.

pfSense: Package-Driven Power

pfSense CE relies more on packages:

Suricata or Snort for intrusion detection
ntopng for traffic analysis (shows you what’s eating bandwidth)
SMART monitoring
Additional dashboards

The package manager is powerful. It’s also a maintenance risk. When pfSense updates the core system, packages sometimes lag. Sometimes they break. Sometimes they stop working entirely until the maintainer catches up.

There’s also the CE/Plus split:

pfSense CE: free, open-source (for now)
pfSense Plus: closed-source features, faster updates, tied to Netgate hardware or subscriptions

This matters if you care whether your firewall config depends on features that could disappear behind a paywall. I don’t want to wake up one day and find out the feature I rely on is Plus-only now.

Fewer plugins and more built-in functionality? OPNsense. Specific pfSense packages you can’t live without? pfSense.

The pfBlockerNG Lesson

I ran pfBlockerNG for ad blocking and threat feeds. Worked great for eight months. Then a pfSense core update hit. pfBlockerNG didn’t update in time. The firewall booted fine. DNS stopped working completely.

Spent three hours troubleshooting. Checked DNS forwarder settings. Verified upstream resolvers. Restarted services. Nothing. The logs showed DNS queries arriving but pfBlockerNG was silently dropping everything because its threat feed database was incompatible with the new pfSense version.

Removed pfBlockerNG. DNS came back instantly.

This is the package problem in miniature. When your ad blocker can take down your entire network and the logs don’t quite tell you why, you start questioning your architecture. That Saturday convinced me to rebuild on a platform with fewer external dependencies.

OPNsense vs pfSense Performance and Hardware Requirements

Hardware Requirements and Virtualization

For self-hosting, OPNsense hardware requirements match pfSense:

x86-64 CPU
4 GB RAM minimum, 8 GB recommended
2 NICs minimum (Intel NICs strongly recommended, Realtek will make you question your sanity)
SSD storage

Proxmox Deployment:

Both run well as VMs. Pass through physical NICs or use virtio adapters. Give it 2 vCPUs minimum, 4+ if you’re running IDS. Hardware offloading can cause weird issues with some hypervisors, test it. Back up your configs before hypervisor updates. (You do this already, right?)

I’ve run both on Proxmox with 4 vCPUs and 8GB RAM handling 500Mbps WAN without issues.

Real-World Performance

Both deliver similar throughput on identical hardware. The bottleneck is your NIC or CPU, not the firewall software.

On a quad-core i5 with Intel NICs, expect near line-rate for basic routing (900+ Mbps on gigabit). WireGuard pushes 600-800 Mbps. OpenVPN is CPU-bound, usually 200-400 Mbps. Turn on IDS and lose 10-30% depending on rulesets.

If your numbers are terrible, it’s probably hardware offloading or bad NIC drivers. (Realtek, I’m looking at you.)

Performance is a tie. Choose based on other factors.

Performance Benchmarks: Real Numbers

Tested on identical hardware (i5-8500, 16GB RAM, Intel i350-T4 NICs):

Routing Performance: OPNsense: 940 Mbps WAN-to-LAN (line rate) pfSense: 938 Mbps WAN-to-LAN (line rate)

WireGuard VPN: OPNsense: 720 Mbps pfSense: 710 Mbps

OpenVPN: OPNsense: 380 Mbps pfSense: 375 Mbps

With IDS Enabled (Suricata, 3 rulesets): OPNsense: 680 Mbps (-27%) pfSense: 670 Mbps (-28%)

Performance difference is negligible. Your hardware matters more than your platform.

📝

Note: These aren’t my numbers. A friend with a 1 Gbps line ran the tests. Made for easier math.

Update Philosophy: OPNsense vs pfSense Release Cycle

OPNsense Updates

OPNsense follows a predictable schedule:

Major releases twice yearly (January and July)
Security updates and patches as needed
Plugin updates independent of core system
Clear change logs and migration guides

The web UI shows pending updates with one-click installation. Rollback options exist if something breaks. Development is transparent. Community input matters.

Updates feel modern and reliable.

pfSense Updates

pfSense CE takes a more conservative approach:

Major releases roughly annually
Minor updates and security patches as needed
pfSense Plus gets updates first
CE trails behind (sometimes weeks)
Some features migrate to Plus-only

This frustrates people. CE users wait for security patches that Plus users already have. You’re constantly aware of what you’re missing. The free tier feels like a free tier.

For “set it and forget it” homelabs, pfSense’s slower pace could be a feature or a frustration. Depends on your perspective.

Mid-2026 check-in. The split isn’t one-directional. pfSense CE 2.8 (2025) actually pulled several previously Plus-only features back into the free edition, and as of June 2026 CE 2.8.1 is current while pfSense Plus hasn’t shipped a release since 24.11 in November 2024. The CE/Plus gap widens and narrows with Netgate’s priorities. This unpredictability is the real issue. OPNsense, by contrast, kept its clockwork pace: the 26.1 series landed in January 2026, with 26.7 due in July.

Regular updates and transparency? OPNsense. Conservative updates and slower pace? pfSense.

Whichever cadence you pick, you still need something to run it on. For a first homelab firewall on a budget, a used micro PC is hard to beat. Add a NIC and you’re done.

Dell OptiPlex 7070 Micro Cheap, quiet, and easy to repurpose as a pfSense or OPNsense box. Perfect first firewall hardware. The catch: it ships with a single NIC, so you’ll need to add a USB 2.5GbE adapter or a PCIe NIC (on the bigger SFF chassis) to handle WAN and LAN properly.

Amazon Price: Loading...

Availability: Checking...

Contains affiliate links. I may earn a commission at no cost to you.

Trust and Long-Term Viability

This is where it gets personal.

OPNsense:

Fully open-source, no proprietary split
Community-driven development
No vendor lock-in
Deciso B.V. sponsors but doesn’t control features

pfSense:

Netgate controls everything
CE is open, Plus is closed
CE feels like the free tier of a paid product
Netgate’s business goals don’t align with homelab users

I switched to OPNsense because I don’t want my firewall’s future tied to quarterly earnings calls. pfSense CE isn’t dying tomorrow. But I don’t like the trajectory.

When a company starts moving features behind paywalls, it doesn’t stop. It accelerates. I’ve seen this before.

Open-source purity matters? OPNsense. Netgate ecosystem matters more? pfSense.

My Migration Weekend: What Happened

I ran pfSense for four years before switching. The migration took six hours over one weekend.

Saturday - Setup and Config Migration

Spun up OPNsense VM on Proxmox. Exported pfSense config to XML, tried importing. It accepted the file but only 60% transferred cleanly.

What worked: Interface assignments, VLANs, basic firewall rules, DHCP scopes.

What broke: NAT rules needed manual recreation. VPN configs had to be rebuilt from scratch. DNS forwarder settings didn’t transfer.

WireGuard rebuild: 20 minutes.

Sunday - Testing and Cutover

Ran both firewalls in parallel for testing. Shut down pfSense, changed VLAN assignments on switch, updated DHCP gateway IPs.

Total downtime: about 20 minutes.

Kept pfSense VM around for two weeks as backup. Never needed it.

What I’d Do Differently

Export VPN client configs before starting. I had to message six people with new configs during the cutover.

Test VLAN isolation more thoroughly. Found a misconfigured rule Monday morning that let guest traffic reach management VLAN. Fixed in five minutes but should’ve caught it Sunday.

Been running OPNsense for 18 months now. No regrets.

When You Should Stay on pfSense

Don’t switch if:

You have complex pfBlockerNG configs you can’t easily recreate.
- Zenarmor exists on OPNsense but it’s not identical. If you’ve got custom threat feeds and DNSBL configs that took months to tune, migration pain might not be worth it.
Your network depends on pfSense-specific packages.
- Some packages don’t have OPNsense equivalents. Check before committing to migration.
You have working configs and no pain points.
- Migration has costs. If pfSense works, and you’re not frustrated, stay put. I switched because the CE/Plus split bothered me and I had a package break. If you don’t have these problems, you don’t need to solve them.

Practical Decision Guide for Homelab Firewalls

Ask yourself:

Modern UI that reduces mistakes? → OPNsense
Rely on specific pfSense packages? → pfSense
Care about open-source purity? → OPNsense
Want ultra-conservative updates? → pfSense
Run everything in Proxmox VMs? → Either works, OPNsense slightly easier
Need maximum plugin flexibility? → pfSense

If you’re undecided, install both in VMs. Spend an afternoon configuring VLANs and WireGuard. Your preference will become obvious. Don’t agonize over this for weeks. Spin them up, click around, pick one.

Decision Tree: Which Firewall Should You Pick?

Do you already run pfSense with no issues?
- YES → Stay on pfSense (don’t fix what isn’t broken).
- NO → Continue…
Do you rely on pfSense-specific packages?
- YES → Stay on pfSense (migration pain isn’t worth it).
- NO → Continue…
Does the CE/Plus split bother you?
- YES → Switch to OPNsense.
- NO → Continue…
Do you want a modern UI with better organization?
- YES → Switch to OPNsense.
- NO → Continue…
Do you want faster security updates?
- YES → Switch to OPNsense.
- NO → Stay on pfSense (conservative updates suit you).

If you end up at “Stay on pfSense” but still feel uncertain, that uncertainty is telling you something. Listen to it.

Common Mistakes That Will Bite You

Don’t Virtualize on Hardware You’re Using for Other Things

Your firewall VM needs dedicated hardware or a hypervisor that’s always on. I’ve watched people wonder why their network dies when they reboot their workstation to install updates. Because your firewall is on it. Obviously.

Run your firewall on a dedicated box, a separate hypervisor, or accept that rebooting your daily driver takes down your entire network. There’s no middle ground here.

Don’t Skip Backups Before Updates

Both platforms make this easy:

OPNsense: System > Configuration > Backups > Download configuration

pfSense: Diagnostics > Backup & Restore > Download configuration as XML

Save it locally with the date in the filename: firewall-backup-2026-01-31.xml

Do this before updates. Do this before changing anything important. Do this monthly even if you’re not changing anything. Store it somewhere that’s not the firewall. Your NAS, your workstation, cloud storage, doesn’t matter. Anywhere but the firewall itself.

When (not if) you need to restore, you’ll thank past-you for being paranoid.

Don’t Enable Every IDS Rule

More rules ≠ more security. You’ll kill performance and get flooded with false positives you’ll ignore.

Start with recommended rulesets. Monitor for a week. Add more only if you need them. I ran with three rulesets for 18 months before adding a fourth. You don’t need 47 different threat feeds.

Don’t Use Realtek NICs If You Can Avoid It

They work. They also cause weird throughput issues, driver headaches, and inexplicable packet loss under load.

Intel NICs cost $20 more used on eBay. Buy Intel. The i350-T2 and i350-T4 are solid choices. Your future self will appreciate it when you’re not troubleshooting phantom network issues on a deadline.

Don’t Trust Default Settings for Production

Both platforms ship with sensible defaults for home use. But “sensible defaults” means:

No firewall rules blocking RFC1918 (private IP addresses) traffic on WAN (fine for home, terrible for dual-WAN or VPS)
DNS resolver allowing queries from all interfaces (convenient but insecure)

Review the defaults. Adjust for your environment. Lock down access to the web UI. Enable stricter firewall rules. Don’t assume “default” means “secure.”

Minimum Viable Firewall Setup

Stop overthinking the initial config. Day one, you need:

WAN interface configured - DHCP from ISP or static IP, whichever your ISP provides
LAN interface with DHCP enabled - Both do this automatically during install
Default allow rule on LAN - Both create this automatically
DNS set to upstream resolvers - 1.1.1.1 and 8.8.8.8, or your preference

That’s it. Everything else is optional.

VLANs? Add them when you need device isolation. VPNs? Add them when you need remote access. IDS? Add it when you want visibility into traffic. Custom dashboards? Add them when the defaults feel limiting.

Start simple. Add complexity only when you have a specific need. Your firewall’s job is routing packets and blocking threats. It does not need to look impressive in screenshots.

Troubleshooting Common OPNsense and pfSense Issues

Internet Works, but Throughput Is Terrible

What you see: Slow speeds despite fast connection

The fix: Disable hardware offloading first. This is the most common culprit.

OPNsense: Interfaces > Settings > Disable “Hardware CRC”, “Hardware TSO”, “Hardware LRO” pfSense: System > Advanced > Networking > Disable all hardware checksum offloading

Reboot. Test again.

If that doesn’t fix it, check IDS rulesets. Too many active rules kills performance. System > Intrusion Detection > Download > verify only 2-3 rulesets are enabled.

Verify your NIC drivers are loaded correctly:

# SSH into firewall, check what driver your NIC is using
ifconfig -a | grep -A 4 "em0"

If you see “re0” (Realtek), you found your problem. Intel NICs use “em”, “igb”, or “ix” drivers. Realtek uses “re”. Replace the NIC.

If you’re seeing 100 Mbps on gigabit, the NIC negotiated wrong. Check System > Interfaces > [Interface] and verify it’s set to auto-negotiate or manually force 1000baseT full-duplex.

VPN Is Slow

What you see: WireGuard or OpenVPN performing poorly

The fix: Verify WireGuard is using kernel implementation (not userspace). Check VPN > WireGuard > Instances > verify “Type” shows kernel implementation.

Disable unnecessary logging (verbose logging kills performance). VPN > WireGuard > Advanced > set log level to “error” only.

Test without IDS. Suricata inspecting VPN traffic = very slow. Services > Intrusion Detection > disable temporarily, test VPN speed.

WireGuard should be fast. If it’s not, your config or hardware is wrong.

Upgrade Broke Something

What you see: Features missing or broken after update

The fix: Restore config backup (you made one, right?). System > Configuration > Backups > restore previous config.

Check package compatibility in changelogs. Before updating, read the release notes. They list package compatibility issues. Review deprecated features list. Sometimes features get removed. Check migration guides.

Test packages individually after core upgrade. Update core first, reboot, then update packages one at a time.

Restore your backup. Try again. Five minutes reading release notes can save an hour troubleshooting. (Yes, I have learned this the hard way.)

Security Differences That Matter

Both platforms are secure by default. The differences are operational, not architectural.

OPNsense Security Advantages

Two-factor authentication built-in. No plugin needed. System > Access > Users > [Select User] > Generate new secret. Works with Google Authenticator, Authy, or any TOTP app.

IDS integrated and easier to configure. Services > Intrusion Detection > Download tab. Select rulesets, enable IDS, done. No separate package installation or config files to manage.

Faster security patches. No CE/Plus delay. When a FreeBSD security advisory drops, OPNsense patches hit within days. pfSense CE users wait for Plus to get patched first.

More frequent security updates. Bi-yearly major releases plus security patches as needed. pfSense CE releases are annual with longer gaps between security updates.

pfSense Security Advantages

More mature IDS rulesets. Snort has been around longer than Suricata. More documentation, more tuned rules for specific scenarios. If you need very specific detection rules for niche attacks, pfSense’s Snort documentation is a deep rabbit hole.

More third-party security plugins. ntopng integration is tighter. More options for anomaly detection and traffic analysis. If you want to build a full security monitoring stack, pfSense has more plugin options.

More documented attack mitigation examples. Decade of forum posts, blog tutorials, and Stack Overflow answers. If you’re mitigating a specific attack, someone’s documented how to do it on pfSense.

What Matters

Neither platform has had a major security incident in recent years. Your security posture depends more on configuration than platform choice.

Common security mistakes I see:

Web UI exposed to WAN (don’t do this)
Default admin passwords (change them immediately)
No firewall rules blocking RFC1918 on WAN (matters for dual-WAN setups)
Permissive outbound rules on LAN (most people allow all, should be more restrictive)

Fix these regardless of platform. A misconfigured OPNsense box is less secure than a properly configured pfSense box, and vice versa.

What Surprised Me After Switching

OPNsense updates are faster. pfSense updates took 10-15 minutes and always required a reboot. OPNsense updates finish in 2-3 minutes. Most don’t need a reboot. The few that do reboot in under 60 seconds.

The documentation is different. pfSense has more forum posts and third-party tutorials dating back to 2008. Google any pfSense problem and you’ll find 47 blog posts about it. OPNsense has cleaner official docs but fewer community tutorials. Took me a few weeks to adjust to reading official docs instead of blog posts.

Built-in features I didn’t know I wanted. Monit caught a failing DNS resolver once and restarted it before I noticed. I woke up, checked logs, saw “unbound died, Monit restarted it 3 hours ago.” That alone justified the switch. On pfSense I would’ve woken up to “DNS is broken” messages from family.

The community is smaller but more active. pfSense has more users. OPNsense has more engaged users. Forum questions get answered faster on OPNsense because there are fewer “have you tried turning it off and on again” responses. People assume competence.

Plugin updates don’t break things. Because most features are built-in, there are fewer plugins to break during core updates. I haven’t had a plugin break in 18 months on OPNsense. On pfSense, I had plugin breakage every 3-4 months.

Quick Wins After Installation

First 30 minutes with either platform:

Change default admin password
Enable automatic config backups
Set up 2FA (OPNsense: built-in, pfSense: use package)
Configure DNS over TLS (prevents ISP snooping)
Enable basic IDS with recommended rulesets
Test failover to backup DNS resolver

Do these immediately. Everything else can wait.

What I Was Wrong About

I thought migration would take all weekend. Took six hours of actual work. Most of that was rebuilding OpenVPN configs because I didn’t export them properly first.

I thought I’d miss pfSense packages. Haven’t needed a single pfSense-specific package in 18 months. Everything I relied on either exists natively in OPNsense or has an equivalent plugin.

I thought OPNsense would be less stable. It’s been rock-solid. Only reboots are for updates. Uptime between reboots averages 6-8 weeks. On pfSense I was rebooting every 3-4 weeks when packages broke.

I thought the smaller community would be a problem. Smaller community means better signal-to-noise ratio. Questions get answered by people who actually know the codebase, not people guessing based on pfSense experience.

I thought performance would be identical. It is, mostly. But OPNsense’s update speed and reboot time makes maintenance faster. Shaving 10 minutes off update time doesn’t sound like much until you’re doing it monthly.

When Your Firewall Is Good Enough

Stop tweaking when:

WAN to LAN routing works at line rate
VPNs connect reliably and stay connected
You haven’t touched the config in a month
Uptime is measured in weeks, not hours
Family/roommates don’t complain about the network
You stop checking the dashboard daily

Your firewall’s job is to be invisible. Once it disappears into the background, you’ve won. Move on to other projects.

The best firewall is the one you forget about. If you’re thinking about your firewall daily, something’s wrong. Fix it or replace it.

If you ever decide you want a single box that can run the firewall plus a few other services, hardware with serious NIC density gives you room to grow without a second appliance.

MINISFORUM MS-A2 Nice to have but not required. With multiple 10GbE and 2.5GbE ports, this mini workstation gives you flexible, high-performance hardware for running OPNsense or pfSense as part of a multi-role homelab node. Overkill for a firewall-only setup.

Amazon Price: Loading...

Availability: Checking...

Contains affiliate links. I may earn a commission at no cost to you.

FAQs: OPNsense vs pfSense for Homelabs

➤ What's the easiest firewall for a homelab?

OPNsense. Better UI, fewer required plugins. You’ll spend less time hunting through menus.

➤ Does OPNsense run better on low-end hardware than pfSense?

No meaningful difference. Hardware quality matters more. A good Intel NIC beats a bad Realtek NIC regardless of firewall choice.

➤ Why do pfSense updates feel delayed?

pfSense CE trails pfSense Plus. Netgate prioritizes Plus for paying customers. CE gets updates eventually. You wait.

➤ How do I set up WireGuard without plugins?

pfSense requires installing the plugin. OPNsense ships with it by default.

➤ Is OPNsense's IDPS as good as pfSense + Suricata?

They both use Suricata. Same engine, same rules, same detection. OPNsense integrates it cleaner.

➤ pfSense menu is confusing, how does OPNsense compare?

OPNsense uses a left-side menu with clearer grouping. Things are where you’d expect them. Not revolutionary, but noticeably better.

➤ Can I trust Netgate long-term?

Netgate is a for-profit company. They need revenue. OPNsense is community-driven. If the CE/Plus split bothers you now, it’ll only get worse. Pick accordingly.

➤ Best plugins for homelab monitoring?

ntopng on pfSense for traffic analysis. Zenarmor on OPNsense for deep packet inspection. Both work well.

➤ How do I migrate from pfSense to OPNsense?

Export XML config, import selectively, manually verify interfaces and rules. Plan for manual reconfiguration. Not one-click, but doable in an afternoon. (Make a backup first. Obviously.)

Conclusion: Pick Your Homelab Firewall and Move On

In 2026, choosing between OPNsense and pfSense isn’t about raw capability. It’s about philosophy, workflow, and trust.

pfSense is powerful, stable, and widely documented. OPNsense feels more modern, more open, and more forgiving when you experiment.

I want my firewall to fade into the background. For me, that’s OPNsense. For you, it might be pfSense.

Pick one. Document your setup. Back up before upgrades. Get back to building the fun parts of your homelab.

Your firewall should be boring. That’s the whole point.

Sources

Official Documentation

Official Documentation

How to Install, Configure, and Migrate to a Consolidated PostgreSQL Server

Sat, 17 Jan 2026 06:48:12 -0700

If you’re running more than a couple of Docker stacks, chances are you’re also running more PostgreSQL containers than you want to admit. I hit my breaking point at six separate Postgres containers, each with its own volume, backup strategy, and maintenance quirks. Every time I ran: docker compose pull && docker compose up -d it felt risky.

Consolidating PostgreSQL databases into a single dedicated server eliminates scattered backups, reduces resource bloat, and makes future migrations trivial, which is exactly what you want from a database. In this guide, you’ll learn how to install PostgreSQL on Debian, configure remote database access, and migrate Docker PostgreSQL containers to a centralized VM without breaking your apps or losing data.

This PostgreSQL migration guide moves you from multiple Docker-based instances to one dedicated server running in a Debian 13 VM on Proxmox. Expected downtime: 10-30 minutes per app during migration. Risk level: Medium, but I’ll also cover recovery strategies.

This is written for users who already understand Docker, basic Linux administration, and Postgres fundamentals, but want a clean, repeatable way to consolidate databases.

💭

TL;DR: Create a Debian 13 VM in Proxmox, install PostgreSQL natively, enable secure remote access, migrate each Docker database using pg_dump, then update your Docker stacks to point at the new centralized server for simpler management and backups.

Why a Dedicated PostgreSQL VM Beats Multiple Containers

Before running any commands, let’s talk about why this is worth the effort.

When each Docker stack runs its own Postgres container, you’re dealing with:

Duplicated memory and CPU usage across every instance
Backups scattered across volumes (good luck finding the right one when you need it)
Version upgrades happening at different times (or not at all)
Monitoring and tuning that’s inconsistent at best

A single PostgreSQL server in a VM gives you:

One place to back up and restore, your future self will thank you
Centralized performance tuning that matters
Cleaner Docker stacks with fewer moving parts
Easier upgrades and security patching (do it once, not six times)

Here’s the thing: databases need to be treated as infrastructure, not app dependencies. Treating Postgres like shared infrastructure pays off quickly. I wish I’d done this years ago.

More details on why you should do this:

My post on why you should consolidate your PostgreSQL Docker Containers in to on consolidated VM

Prepare the Proxmox VM (Debian 13)

VM Sizing and Creation

In Proxmox, create a new VM with these baseline specs. These specs work well for 5 to 10 typical homelab apps:

OS: Debian 13 ISO
CPU: 2 to 4 cores
RAM: 4 to 8 GB
Disk: 20 to 50 GB SSD, VirtIO
Network: Bridge to your homelab subnet
Enable QEMU Guest Agent in VM options

PostgreSQL benefits more from RAM and fast storage than raw CPU. If you have the memory to spare, err on the side of more, you won’t regret it.

Install Debian 13 (Minimal)

During the Debian installer:

Choose a minimal install, no desktop environment (you don’t need it)
Assign a static IP, saves headaches later
Install openssh-server, so you can manage the VM remotely with SSH

After the first login, update the system and install the QEMU guest agent:

sudo apt update && sudo apt upgrade -y
sudo apt install -y qemu-guest-agent
sudo systemctl enable --now qemu-guest-agent

The guest agent improves shutdown handling, IP reporting, and backup consistency in Proxmox. It’s not required, but it’s one of those “install it now, appreciate it later” things.

MINISFORUM MS-A2
This compact mini-workstation offers powerful CPU options and serious I/O, making it ideal for running a consolidated PostgreSQL server in a Proxmox VM with room for future growth.

Amazon Price: Loading...

Availability: Checking...

Contains affiliate links. I may earn a commission at no cost to you.

Install PostgreSQL on Debian 13

Decision: Default Debian Repo or Official PostgreSQL Repo?

Alright, this is the first real fork in the road. Your choice here affects file paths and version numbers for the rest of the guide.

Option A: Debian default repository (RECOMMENDED)

Pros: simpler, stable, fewer surprises
Cons: version may lag behind upstream (Debian 13 uses PostgreSQL 17)
Install paths: /etc/postgresql/17/main/
Service name: postgresql

Install with:

sudo apt update
sudo apt install -y postgresql postgresql-contrib

Option B: Official PostgreSQL APT repository

Pros: access to PostgreSQL 18 or newer features
Cons: slightly more setup complexity, one more thing to maintain
Install paths: /etc/postgresql/18/main/
Service name: postgresql

If you want the latest features:

sudo apt install -y curl ca-certificates
sudo install -m 0755 -d /etc/apt/keyrings
curl -o /etc/apt/keyrings/pgdg.asc https://www.postgresql.org/media/keys/ACCC4CF8.asc
sudo chmod a+r /etc/apt/keyrings/pgdg.asc

echo "deb [signed-by=/etc/apt/keyrings/pgdg.asc] https://apt.postgresql.org/pub/repos/apt $(lsb_release -cs)-pgdg main" | sudo tee /etc/apt/sources.list.d/pgdg.list

sudo apt update
sudo apt install -y postgresql-18 postgresql-contrib-18

📝

Note: The rest of this guide assumes Debian 13’s default PostgreSQL 17. If you chose PGDG, replace /etc/postgresql/17/main/ with /etc/postgresql/18/main/ in all config file paths. I know, I know, it’s annoying, but that’s the price you pay for bleeding edge.

Verify the Service

PostgreSQL starts automatically after installation. Let’s make sure it’s actually running:

sudo systemctl status postgresql
sudo systemctl enable postgresql

If you see “active (running)”, you’re golden. Now access the admin shell:

sudo -i -u postgres psql

You should see the postgres=# prompt. Check your version with SELECT version();
Output should look like this:

postgres=# SELECT version();
 version
-------------------------------------------------------------------------------------------------------------------
 PostgreSQL 17.7 (Debian 17.7-0+deb13u1) on x86_64-pc-linux-gnu, compiled by gcc (Debian 14.2.0-19) 14.2.0, 64-bit

Then exit with \q.

MINISFORUM MS-01 Mini Workstation
Its multiple NVMe slots and dual 10G SFP+ networking make it a practical, quiet, and efficient choice for hosting a dedicated PostgreSQL server and handling VM workloads.

Amazon Price: Loading...

Availability: Checking...

Contains affiliate links. I may earn a commission at no cost to you.

Configure PostgreSQL for Remote Access

By default, PostgreSQL only listens on localhost. That’s good for security, but useless for Docker containers on other hosts. Let’s fix that.

Enable Network Listening

Edit postgresql.conf (adjust path for your version):

sudo nano /etc/postgresql/17/main/postgresql.conf

Find and set:

listen_addresses = '*'

This tells PostgreSQL to listen on all interfaces. Don’t panic. Access control is handled separately. You’re not opening the floodgates here.

Configure Client Authentication

Edit pg_hba.conf:

sudo nano /etc/postgresql/17/main/pg_hba.conf

Add a rule for your Docker subnet(s) and your LAN. For example:

# LAN Subnet
host all all 192.168.1.0/24 scram-sha-256
# Docker 1 Subnet
host all all 172.17.0.0/16 scram-sha-256
# Docker 2 Subnet
host all all 172.18.0.0/16 scram-sha-256

Use scram-sha-256 authentication instead of md5 where possible. It’s more secure and the modern default. Your Docker clients will handle it fine.

Restart PostgreSQL:

sudo systemctl restart postgresql

Firewall the Database

Never expose PostgreSQL to the internet. Don’t even think about it. Lock it down to your trusted subnets.

Using UFW:

sudo apt install -y ufw
sudo ufw allow 22/tcp
sudo ufw allow from 192.168.1.0/24 to any port 5432 proto tcp
sudo ufw allow from 172.17.0.0/16 to any port 5432 proto tcp
sudo ufw allow from 172.18.0.0/16 to any port 5432 proto tcp
sudo ufw enable

Verify it is working:

sudo ufw status

Adjust the subnets to match your LAN, Docker hosts, and Proxmox bridge. If you’re not sure what subnet to use, check your Docker network with docker network inspect bridge.

It should look like this when you are done:

Status: active

To Action From
-- ------ ----
5432/tcp ALLOW 192.168.1.0/24
22/tcp ALLOW Anywhere
5432/tcp ALLOW 172.18.0.0/16
5432/tcp ALLOW 172.17.0.0/16

Checkpoint:

From another host or container already running Postgres, test connectivity.

docker exec -it <container_name> /bin/bash

Run this to test if the firewall is allowing traffic on this subnet

psql -h <vm_ip> -U postgres

If it connects and asks for a password, you’re good.
Press ctrl-c to abort the connection and exit to leave the container.

If it fails, check logs with:

journalctl -u postgresql

Nine times out of ten, it’s either pg_hba.conf or the firewall. Double-check both.

Create Users and Databases for Docker Apps

Here’s where a lot of people mess up: they dump everything into a single database with a single superuser. Resist that urge.

Identify Existing Containers

On your Docker host(s):

docker ps | grep postgres

Make a list of containers, databases, and users. Seriously, write it down or put it in a text file. You’ll reference it constantly.

⚠️

Warning: I recommend that you DO NOT consolidate the Immich Postgres database. They use older versions of Postgres and Postgres extensions. I tried to do this and wasted quite a few hours, and then I realized that if I got it working it would be a pain to update in the future. Leave it in its docker container unless you REALLY know what you are doing.

Create a dedicated role and database per application. It makes troubleshooting and permissions way simpler later.

sudo -i -u postgres psql

Example:

CREATE ROLE ExampleUser WITH LOGIN PASSWORD 'StrongPasswordHere';
CREATE DATABASE example_db OWNER ExampleUser;

Repeat this for each former Docker-based Postgres instance. Yeah, it’s a bit tedious, but you only do it once.

Test access:

psql -h localhost -U ExampleUser -d example_db

If you see the example_db=> prompt, you’re set. Exit with \q.

💡

Tip: Matching users and database names to applications (like example and example_db) makes your life so much easier six months from now when you’re trying to remember which database belongs to what.

Migrate Docker PostgreSQL Databases to Dedicated Server

Alright, this is the heart of the PostgreSQL migration process. Take your time here, rushing this step is how you end up restoring from backups (You have backups right? RIGHT?).

Handle Extensions and Ownership Issues First

Before dumping, identify potential problems. This saves you from “why won’t it restore?” headaches later:

# Check for extensions
docker exec -it <container> psql -U <user> -d <db> -c "\dx"

# Check for custom roles
docker exec -it <container> psql -U <user> -c "\du"

Common issues you’ll hit:

Extensions like pg_trgm or uuid-ossp may need manual creation on the target server
```
CREATE EXTENSION IF NOT EXISTS "uuid-ossp";
```
Role ownership conflicts between different container dumps (especially if you’re using pg_dumpall)

Dump the Data

Decision point here:

Small homelab DBs (under a few GB): dumping while containers are running is usually fine
Larger or critical DBs: stop the app container first to guarantee consistency

For single database (recommended):

docker exec -it <container> pg_dump -h 127.0.0.1 -U postgres -d example_db --format=plain --no-owner --no-privileges > example_dump.sql

The --no-owner --no-privileges flags avoid role and ownership conflicts during restore. You’ll set ownership manually on the new server anyway.

For all databases and roles (advanced, usually overkill for homelabs):

docker exec -i <container> pg_dumpall -h 127.0.0.1 -U <user> > full_dump.sql

Watch the output. If you see errors about missing permissions or roles, that’s your cue to use --no-owner --no-privileges.

Transfer Dumps to the VM

Use scp or VSCode to download and upload to the new server:

scp db_dump.sql user@postgres-vm:/tmp/

If you’ve got multiple dumps, throw them all in /tmp/ on the VM. Remember to clean them up later.

Restore into the New Server

On the PostgreSQL VM:

psql -h localhost -U ExampleUser -d example_db -f /tmp/db_dump.sql

Repeat for each application. Yeah, it’s repetitive. Put on some music.

If you hit extension errors like “extension uuid-ossp does not exist”, install them manually:

CREATE EXTENSION IF NOT EXISTS "uuid-ossp";

Most common extensions you’ll need: uuid-ossp, pg_trgm, hstore. Install them as needed.

The Samsung 9100 PRO 2TB
Great choice for a PostgreSQL database because its very high IOPS and low latency keep reads and writes snappy under load, while the sustained throughput helps with WAL logging, indexes, and vacuum/maintenance jobs without the whole system feeling sluggish.

Amazon Price: Loading...

Availability: Checking...

Contains affiliate links. I may earn a commission at no cost to you.

Update Docker Stacks to Use the Central Database

This step removes PostgreSQL from your Docker stacks entirely. It’s weirdly satisfying.

In your docker-compose.yml:

Comment out the postgres service (Remove once you know it works)
Comment out volume definitions tied to Postgres (Remove once you know it works)
Update environment variables to point at the new server

Example:

environment:
 POSTGRES_HOST: <postgres_VM_IP>
 POSTGRES_DB: example_db
 POSTGRES_USER: ExampleUser
 POSTGRES_PASSWORD: StrongPasswordHere

Recreate the stack:

docker compose down
docker compose up -d

Your application should now connect to the centralized PostgreSQL server. Check the logs to make sure it’s connecting:

docker compose logs -f

If you see database connection errors, double-check your environment variables. Typos in the hostname or database name trip up 80% of people here.

Once you do this for one stack, the rest should be faster.

PostgreSQL Performance Tuning for Homelabs

Out of the box PostgreSQL settings are conservative. Here’s safe starting points for a homelab:

Edit postgresql.conf:

shared_buffers = 1GB
work_mem = 16MB
max_connections = 100

Why these settings matter:

shared_buffers: PostgreSQL’s main cache. Rule of thumb is 25% of system RAM, but too much can actually hurt performance on smaller systems. For a 4GB VM, 1GB is the sweet spot.
work_mem: Per-operation memory for sorts and joins. This multiplies by concurrent connections, so be conservative. 16MB is safe for most homelabs.
max_connections: Many apps hold idle connections. 100 is safe for most homelabs, you’re probably not hitting 50 concurrent connections anyway.

⚠️

Warning: Don’t blindly scale these up. A 4GB VM with work_mem = 64MB and 100 connections could theoretically use 6.4GB of RAM during heavy queries. This is how you OUT OF MEMORY (OOM) kill your databases.

Restart PostgreSQL after changes:

sudo systemctl restart postgresql

These settings work well for read-heavy media workloads. If you’re running something write-heavy, you’ll want to tune further, but this is a good baseline.

Troubleshooting PostgreSQL Migration Issues

Connection Refused from Docker Containers

This is the most common issue. Here’s the checklist:

Confirm PostgreSQL is listening: ss -lntp | grep 5432
Verify listen_addresses = '*' is set and not commented out
Check firewall rules with sudo ufw status
Double-check pg_hba.conf subnet and authentication method

If you’re still stuck, check the logs:

journalctl -u postgresql -n 50

Look for “connection refused” or “no pg_hba.conf entry” messages. They’ll tell you exactly what’s wrong.

pg_dump Fails with “Role Does Not Exist”

This usually means roles from the old container don’t exist yet on the new server.

Fix by either:

Creating the roles first with CREATE ROLE, or
Using --no-owner --no-privileges during dump and restore (recommended)

Using --no-owner --no-privileges is cleaner. You’re not trying to preserve complex permission structures. You want the data.

Authentication Errors After Migration

Frustrating, I know. Check these:

Ensure passwords match what’s in Docker environment variables (no trailing spaces)
Confirm scram-sha-256 is supported by your client library (it should be)
Check for copy-paste errors in passwords, seriously, this happens more than you’d think

If you’re still stuck, temporarily switch to md5 in pg_hba.conf to isolate the issue. If that works, it’s a scram-sha-256 compatibility problem.

Performance Worse Than Before

Wait, what? Yeah, this can happen. Here’s why:

Your containers may have been memory-starved without you realizing it, so they were “fast” because they weren’t doing much
The new server is doing proper caching and query planning
You need to increase VM RAM or revisit shared_buffers and work_mem

Run EXPLAIN ANALYZE on slow queries to see what’s happening. Usually it’s a matter of giving PostgreSQL more memory to work with.

Extension Errors During Restore

If you see “extension does not exist” errors, install them manually:

CREATE EXTENSION IF NOT EXISTS "uuid-ossp";
CREATE EXTENSION IF NOT EXISTS "pg_trgm";

Most homelab apps use a handful of common extensions. Install them once and you’re done.

FAQs

➤ How do I connect to PostgreSQL from Docker containers on a different host?

Expose PostgreSQL on the VM’s IP, allow the Docker subnet in pg_hba.conf, and ensure your firewall permits port 5432 only from trusted subnets. Never open it to the internet, really, don’t do it.

➤ What's the safest way to migrate a large Docker PostgreSQL database without downtime?

For homelabs, brief downtime is safest. Stop the app, run pg_dump, restore, then restart the app pointing at the new server. Trying to do zero-downtime migrations in a homelab is usually more trouble than it’s worth.

➤ Why can't I access PostgreSQL after install?

By default, PostgreSQL listens only on localhost. You must update listen_addresses and pg_hba.conf, then restart the service. This trips up everyone the first time.

➤ Should I use Debian repos or the official PostgreSQL repo?

Debian repos prioritize stability. Official repos give newer versions. For most homelabs, Debian’s version is the safer default. Unless you need a specific PostgreSQL 18 feature, stick with Debian’s package.

➤ How much RAM and CPU should I allocate to a PostgreSQL VM?

For 5 to 10 small apps, 2 to 4 CPU cores and 4 to 8 GB RAM is sufficient. PostgreSQL benefits more from RAM than CPU. If you’re running out of resources, add RAM first.

➤ Can I migrate Docker PostgreSQL databases while containers are running?

Yes, for small databases (under a few GB). For consistency, stopping the app container is safer. The downtime is usually under 10 minutes, your users might not even notice.

➤ What's the QEMU guest agent used for?

It improves Proxmox integration, clean shutdowns, and backup behavior. It’s not mandatory but recommended. Install it now, and thank yourself later when you’re doing VM backups.

Conclusion

Consolidating multiple Docker-based PostgreSQL instances into a single dedicated server is one of those changes that feels intimidating but pays off immediately. You reduce clutter, simplify backups, and gain real control over your data layer.

The key takeaways:

Use a dedicated Debian 13 VM for PostgreSQL, treat it as one of your most important VMs
Keep one user and database per application (makes troubleshooting way easier)
Migrate with pg_dump --no-owner --no-privileges, not filesystem copies
Lock down network access to trusted subnets only
Handle extensions and roles proactively during migration

If you’re tired of babysitting half a dozen Postgres containers like I was, this approach will make your homelab cleaner and more predictable.

Resources

PostgreSQL Official Documentation

Debian PostgreSQL Wiki

Proxmox VE Documentation

Fractal Design Define 7 XL
This full-tower case is useful if you want a quiet, storage-heavy homelab server for Proxmox, but may be overkill for smaller or more compact builds.

Amazon Price: Loading...

Availability: Checking...

Contains affiliate links. I may earn a commission at no cost to you.

Should You Consolidate PostgreSQL Databases In One VM

Fri, 16 Jan 2026 07:39:34 -0700

Why Consolidate Multiple PostgreSQL Databases Into One VM

If your homelab’s quietly accumulated half a dozen or more Postgres containers, one per Docker stack, you’re not alone. This is how it always starts: an app needs a database, the compose file spins one up, and you move on. Fast-forward a year or two, and you’re patching several Postgres containers, backing up all the separate volumes, and troubleshooting six or more slightly different configurations.

Move them onto a single Postgres VM and the operational tax drops fast. One backup job. One upgrade window. One place to tune. If you’re running 3+ Postgres databases across Home Assistant, Wiki.js, Immich, and a monitoring stack, that’s hours a month you stop spending on babysitting containers.

I hit that wall myself. Managing six separate PostgreSQL containers felt like busywork instead of actual homelabbing. Consolidating them into a single Postgres VM changed that overnight. Fewer moving parts, simpler backups, and one place to tune database performance.

Here’s the thing: consolidating your Postgres databases onto one VM is usually the better call for intermediate homelabs. I’ll walk through why it simplifies management and backups, and the cases where you absolutely shouldn’t do it.

Who should consolidate: Homelabbers running 3+ Postgres containers with low to moderate traffic workloads like Home Assistant, Wiki.js, and monitoring stacks.

Who should not: Those with high-write databases, strict isolation requirements, or apps that need different PostgreSQL versions.

💭

TL;DR: Running all your Postgres databases on one dedicated Postgres VM reduces sprawl, simplifies backups, and cuts management overhead, as long as your workloads are modest, and you plan for resource contention.

Why Consolidating PostgreSQL Databases Matters

The hidden cost of “one database per stack” isn’t CPU or RAM. It’s operational overhead.

Every Postgres container means:

Its own data volume
Its own backup job (or worse, no backup at all)
Its own upgrade and patch cycle

From an infrastructure perspective, this is wasteful. PostgreSQL’s shared buffer cache, background workers, and WAL processes all duplicate across instances. A single instance hosting multiple databases eliminates this duplication. In my own setup, memory usage dropped from 3.2GB across six containers to 1.8GB with one consolidated instance.

For a homelab where workloads are rarely extreme, consolidation’s usually a net win.

My post on how-to consolidate your PostgreSQL Docker Containers in to on consolidated VM.

My Story: Death by a Thousand Containers

At one point, I was running six separate PostgreSQL containers:

Home Assistant
Wiki.js
Immich
A monitoring stack
Two side projects I barely touched

Each had its own compose file and volume. When it came time to back them up, I had six cron jobs dumping databases in slightly different ways. When PostgreSQL 13 went end-of-life, I had to plan multiple upgrades.

After consolidating everything into one Postgres VM, backups became a single script, upgrades happened once, and adding a new database was a 30-second task instead of its own mini-project.

One Postgres VM vs One Postgres Container Per Stack

The Container-Per-App Model

This model’s popular because it’s easy to start with:

Drop a postgres: image into your compose file
Link it to your app
Forget about it

Pros:

Strong isolation boundaries
Easy to reason about for beginners
App and database lifecycles are tightly coupled

Cons:

Fragmented backups
Repeated configuration and tuning
Higher memory and disk overhead
More patching and monitoring work

This approach scales poorly as your homelab grows.

The Dedicated Postgres VM Model

In this model, you run one PostgreSQL instance on a dedicated Postgres VM. Each app gets its own database and role inside that instance.

Pros:

Centralized management and upgrades
One backup strategy for all databases
Better overall resource utilization
Easier monitoring and performance tuning

Cons:

Less isolation than separate containers
Risk of resource contention if poorly sized
Requires more up-front planning

For most intermediate homelabs, the pros outweigh the cons. You’re trading a bit of isolation for dramatically simpler operations.

MINISFORUM MS-A2 Must have for this build. Why it fits this post: Its high core count, fast networking (dual 10GbE), and flexible storage make it ideal for running a consolidated PostgreSQL VM with room for future database growth and multiple homelab workloads.

Amazon Price: Loading...

Availability: Checking...

Contains affiliate links. I may earn a commission at no cost to you.

Why a VM Instead of LXC or More Containers

Postgres VM vs LXC Container

Running PostgreSQL in LXC containers is tempting. They’re lightweight and fast. But for databases, the trade-offs matter.

VM advantages for PostgreSQL:

Better I/O isolation under load
Cleaner snapshot and backup integration with hypervisors like Proxmox
Fewer surprises from shared kernel behavior
Predictable fsync behavior with dedicated virtual disks

LXC advantages:

Lower RAM overhead (200-500MB saved)
Faster startup

Proxmox-specific considerations:

Use VirtIO SCSI with “Write back” cache for VM disk performance
If you’re on ZFS, disable sync writes for the VM dataset to avoid double-fsync
For LXC, unprivileged containers require proper UID/GID mapping for Postgres

Here’s the thing: PostgreSQL’s sensitive to disk latency and I/O jitter. A VM gives you more predictable behavior, especially when multiple databases share the same instance. For a dedicated Postgres VM, this predictability’s usually worth the small overhead.

How Consolidating PostgreSQL Databases Simplifies Backups

This is where consolidation really shines.

With multiple containers, backups often look like this:

Different schedules
Different dump formats
Different retention policies
That one database you forgot about entirely

With one Postgres VM, you can choose a single approach:

Logical backups using pg_dump for each database
Physical backups using pg_basebackup
Or a full-featured tool like Barman

PostgreSQL is designed to host multiple databases in one instance. Unified backups aren’t a hack. They’re the intended path.

Practical example:

#!/bin/bash
DATABASES=("homeassistant" "wikijs" "immich" "grafana")
for db in "${DATABASES[@]}"; do
 pg_dump -h localhost -U backup_user -d "$db" | gzip > "/backups/${db}_$(date +%Y%m%d).sql.gz"
done

Restores are simpler too. You restore one database, not an entire container volume. When you’re staring at a corrupted Wiki.js database, you’ll appreciate the difference.

Resource Utilization and Performance

Why One Instance Is Usually Faster

Every PostgreSQL instance has overhead:

Background workers (autovacuum, stats collector)
Shared buffers (typically 128MB default per instance)
WAL processes

When you run six instances, you pay that cost six times. A single instance with six databases shares those resources way more efficiently.

The Noisy Neighbor Problem

The main risk is one database hogging resources. We’ve all been there. Immich decides to index 10,000 photos while Home Assistant is trying to log sensor data, and suddenly your dashboards crawl.

Mitigations:

Separate roles per app
Per-database configuration settings
Connection pooling with PgBouncer
Monitoring query behavior

If one workload regularly exceeds 50% of available CPU or I/O, it might deserve its own instance. Consolidation’s not all-or-nothing.

GMKtec Mini PC i7-1185G7 Must have for this build. A quad-core i7 with 16 GB of DDR4 and a 1 TB SSD, which is enough headroom to host a dedicated PostgreSQL VM and still leave room for the other services you’re consolidating onto the same machine.

Amazon Price: Loading...

Availability: Checking...

Contains affiliate links. I may earn a commission at no cost to you.

Should You Consolidate Your PostgreSQL Databases?

Use this quick test:

If your databases are mostly low to medium traffic, consolidate.
If one database has heavy writes or constant load, consider isolating it.
If you value simplicity over maximum isolation, consolidate.
If uptime requirements differ wildly between apps, consider partial consolidation.

Many homelabs end up with a hybrid approach: one Postgres VM for most apps, and a separate instance for the outlier that’s constantly hammering the disk.

What Homelab Software Benefits Most

A dedicated Postgres VM works especially well for apps that already support external databases.

Common examples:

Home Assistant
Wiki.js
Immich
Monitoring stacks like Grafana
Internal tools and dashboards
n8n

These apps benefit from stable connections, predictable performance, and easy backups.

Media servers that use PostgreSQL for metadata also fit well, as long as write rates are reasonable.

High-Level Migration Strategy

At a high level, migration looks like this:

Inventory your existing databases
Build a dedicated Postgres VM
Dump each database
Restore into the new instance
Update app connection strings

This is usually downtime-friendly for homelabs, but you can also stage it database by database if you’re paranoid about breaking everything at once. (I don’t blame you.)

Basic Setup for a Postgres VM

For larger homelabs (5-10 databases):

4 to 8 CPU cores
16 to 32 GB RAM
SSD or NVMe storage
PostgreSQL 16 or newer

For smaller homelabs (3-5 databases):

2 to 4 CPU cores
8 to 16 GB RAM
SSD storage
PostgreSQL 16 or newer

Key configuration ideas:

shared_buffers around 25% of RAM
effective_cache_size around 75% of RAM
Conservative max_connections with PgBouncer in front

These defaults give you room to grow without constant tuning. You can always optimize later when you actually have data showing where the bottlenecks are.

Security Considerations

Consolidation reduces the number of exposed services, which is good. But isolation now happens at the database level instead of the container level.

Best practices:

One role per app
Strong passwords or certificates
Restrictive pg_hba.conf
No shared superuser credentials

Done right, this isn’t less secure than containers. But it does require discipline. Don’t get lazy and hand everything the postgres superuser account because “it’s only a homelab.”

MINISFORUM MS-01 Mini Workstation Nice to have but not required. Why it fits this post: Its compact size, multiple NVMe slots, and real homelab networking (dual 10G SFP+ plus 2.5GbE) make it a practical, quiet option for a PostgreSQL VM, though with slightly less raw power than the top picks.

Amazon Price: Loading...

Availability: Checking...

Contains affiliate links. I may earn a commission at no cost to you.

Troubleshooting Common PostgreSQL Consolidation Problems

One Database Is Slowing Everything Down

Symptoms:

High CPU or I/O usage
Other apps feel sluggish
Your spouse complains that Home Assistant’s not responding

Fixes:

Identify heavy queries with pg_stat_statements
Limit connections per app
Move the noisy database to its own instance if needed

Apps Cannot Connect After Migration

I know what you’re thinking: “I updated the connection string, why isn’t it working?”

Checklist:

Verify pg_hba.conf allows the Docker subnet
Check firewall rules
Test with pg_isready

That last one’s saved me more times than I can count. If pg_isready fails, your app’s not going to connect either.

Backups Take Too Long

Options:

Switch from logical to physical backups
Run dumps in parallel
Exclude rarely changed databases from daily dumps

Version Conflicts

You can’t mix PostgreSQL major versions in one instance. Period.

Solution:

Upgrade all databases together
Or run a second instance temporarily during migration

Yeah, this part’s finicky. Plan your upgrades carefully.

FAQs

➤ How do I prevent one database from starving others?

Use connection limits, PgBouncer, and per-database settings. Monitor resource usage and be ready to split workloads if necessary.

➤ What's the minimum VM size for 5 to 10 databases?

For typical homelab apps, 4 cores and 16GB RAM is a solid baseline. For smaller setups, 2 cores and 8GB works fine. Scale up if you see sustained load.

➤ Can I mix PostgreSQL versions in one instance?

No. One instance equals one major version. Plan upgrades accordingly.

➤ How does backup time change with consolidation?

Backups are usually faster and simpler because you avoid container overhead and duplicated jobs. One script instead of six.

➤ Is a VM really better than LXC?

For PostgreSQL, yes in most cases. VMs provide better I/O isolation and simpler snapshot workflows.

➤ What apps work best with a shared Postgres VM?

Apps with moderate workloads and good external database support, like Home Assistant, Wiki.js, and monitoring tools.

➤ How do I handle high-write workloads?

Tune WAL settings, use fast storage, and consider isolating that workload if it dominates the system.

➤ Does consolidation reduce Docker overhead?

Yes. You eliminate multiple Postgres images, volumes, and background processes.

➤ How can I migrate with minimal downtime?

Dump and restore during low-usage windows, or stage databases one at a time. For a homelab, a few minutes of downtime’s usually fine.

➤ What tools help monitor contention?

Prometheus with a Postgres exporter, pg_stat_statements, and log analyzers are all effective.

➤ Are there security risks?

The risk shifts from container boundaries to role and permission management. Follow least-privilege principles and you’ll be fine.

Resources

PostgreSQL Official Documentation

Conclusion

Consolidating all or some of your PostgreSQL databases into one dedicated Postgres VM is one of those changes that feels scary at first and obvious in hindsight. You trade a bit of isolation for dramatically simpler management, cleaner backups, and better resource utilization.

For my homelab, moving away from six separate containers was a relief. One upgrade, one backup strategy, one place to look when something goes wrong.

If you’re juggling multiple Postgres containers today, consider consolidation. Start small, monitor closely, and split workloads only when the data tells you to. Your future self, restoring a database in the middle of the night, will thank you.

Intel NUC 12 Pro (NUC12WSHi5) Nice to have but not required. Why it fits this post: This mini PC offers a balance of performance, quiet operation, and expandability for a PostgreSQL VM, but may be more limited for heavy multi-database or high-I/O scenarios compared to workstation-class options.

Amazon Price: Loading...

Availability: Checking...

Contains affiliate links. I may earn a commission at no cost to you.

Kodi vs Jellyfin (2026): Honest Comparison + Which to Pick

Sat, 10 Jan 2026 07:12:29 -0700

Jellyfin vs Kodi: which media server is better for you? If you’ve ever said “Kodi is awesome, but…” and then sighed, this post is for you.

Kodi was my media center for years. I loved the skins, the endless tweaks, and the feeling that I could make it do anything. But once it had to work for my wife, friends, and multiple TVs, Kodi stopped being a fun hobby and turned into an ongoing tech support job.

That’s when I finally ditched Kodi as my primary media player and moved to Jellyfin. Not Kodi with network shares. Not Kodi with a bunch of sync hacks. Not even Kodi with the Jellyfin plugin, which is good but still not the clean fix I wanted.

I switched to Jellyfin server and Jellyfin clients. It solved the three things that made Kodi painful: syncing watched status across devices, transcoding files that wouldn’t play, and sharing media remotely without being a tech support desk.

This article explains why, from the perspective of someone who’s run both for years.

💭

TL;DR: Kodi is a powerful front-end player, but Jellyfin is a true media server with simple clients. Jellyfin wins for transcoding, remote access, sharing with friends, and keeping watched status synced everywhere. For most households, that makes it the better choice.

Kodi vs Jellyfin: The Mental Model That Changes Everything

Before we get into features, you need to understand one core difference. This alone explains why Jellyfin feels easier once you switch.

Kodi: A Player First

Kodi is designed to run on the device connected to your TV. Each Kodi box:

Scans media itself
Maintains its own library database
Tracks watched status locally
Depends on the device’s hardware to play files

You point Kodi at local files or network shares, and it works great for that use case. But every device is effectively on its own unless you bolt on extra layers like a shared database or third-party services (Trakt, for example).

And look, setting up MySQL database sharing across Kodi instances? That’s a weekend project that’ll break in a few months. I could never keep my shared library alive longer than that.

Jellyfin: A Server With Clients

Jellyfin flips the model.

One Jellyfin server indexes your entire library
All metadata, artwork, and watched status live in one place
Every device connects as a client
The server decides whether to direct-play or transcode

For most people, one central server is simpler than maintaining multiple Kodi installations. You’re managing one thing instead of five.

Getting Started: What Jellyfin Setup Looks Like

You don’t need an enterprise server to run Jellyfin. Honestly, you probably have something lying around that’ll work.

Where Jellyfin Can Run

NAS systems like Unraid or TrueNAS
Mini PCs and Intel NUCs
Old desktops
Even Raspberry Pi for light use (though transcoding will not work well)

Beginner Setup Reality Check

Install Jellyfin server - Runs on almost any computer; it doesn’t need much
- Intel 8th Gen or newer if you want hardware transcoding
Point it at your media folders - Movies, TV Shows, Music
- Can be network storage like Unraid, OpenMediaVault, or a plain NAS share
Let it scan and download metadata - This takes a while the first time
Install the Jellyfin app on your streaming device
- NVIDIA Shield, Smart TV, or even some gaming consoles
Log in and start watching - That’s it.

The whole process takes maybe an hour if you already have media organized. Compare that to setting up Kodi on every TV in the house, then explaining to your spouse why the living room shows different watch progress from the bedroom.

Hardware Expectations

Here’s the thing: hardware matters, but not as much as you’d think.

Mostly direct play, one or two users: any old desktop works fine
Multiple remote users, lots of transcoding: Intel Quick Sync (Intel 8th Gen or newer) or a GPU helps massively
Weak CPU with no hardware acceleration: expect stuttering when transcoding

If you’re only watching locally and your files are already in formats your devices support, you can run Jellyfin on a potato. It’s when you start transcoding 4K movies for your friend’s phone that you need real hardware.

Why Jellyfin Beat Kodi in My House

Kodi was fine when it was only me. I could tinker, fix things, restart services. But once my wife started using it daily, the friction became obvious:

Different Kodi boxes had different watched statuses
One update broke a skin and suddenly nothing looked familiar
Some files played on one TV but not another
Explaining “back out and refresh the library” got old fast

I tried Kodi with the Jellyfin plugin, and while it helped with library sync, it still left me maintaining two layers: Jellyfin plus Kodi on every device. Every Kodi update was a potential disaster. Every new device meant configuring Kodi again.

Switching to native Jellyfin clients finally solved the problem. One app, consistent interface, no per-device configuration hell.

NVIDIA SHIELD Pro
A premium Android TV client, it offers excellent Jellyfin playback, smooth 4K HDR support, and broad codec compatibility, making it a top choice for users wanting a seamless living room experience with Jellyfin.

Amazon Price: Loading...

Availability: Checking...

Contains affiliate links. I may earn a commission at no cost to you.

Jellyfin Transcoding: Making Files Play Everywhere

Alright, this is where Jellyfin pulls ahead of Kodi for good.

Kodi plays files locally. If the device can’t decode the file, playback fails or stutters. Kodi has no server-side transcoding. Everything happens on the client.

Jellyfin includes a full transcoding engine based on FFmpeg. This means the server can:

Convert unsupported codecs on the fly
Downscale 4K video to 1080p for older TVs
Adjust bitrate for slow connections
Convert audio formats like TrueHD or DTS-HD to stereo

Translation: your phone can now play that 4K HDR movie because Jellyfin converts it to something your phone understands, in real time.

Your friend with the ancient Fire Stick? They can watch your 4K Blu-ray rips because Jellyfin handles the conversion. With Kodi, they’d get a black screen or a stuttering mess.

Hardware Acceleration Warning

Jellyfin supports hardware-accelerated transcoding on Intel Quick Sync, NVIDIA NVENC, and AMD VA-API. When it works, your server can handle multiple streams without maxing out the CPU.

When it doesn’t work: You get stuttering, buffering, or the server crashes under load.

I know what you’re thinking: “how hard can it be?” Well, driver issues on Linux are real. Wrong permissions for hardware devices will bite you. Codec support varies by GPU generation. Test hardware transcoding with one stream before depending on it, because finding out it doesn’t work when three people are trying to watch at once is not fun.

Jellyfin + Intel QuickSync - The Complete Guide
How to install and configure Jellyfin in an unprivileged LXC container with QuickSync.

Centralized Library and Watched Status Sync

Jellyfin tracks watched episodes, movies, and resume positions down to the second. Start a show on your living room TV, pause halfway through, and resume on your phone in bed. It works.

Kodi can sync watched status, but only if you set up a shared MySQL database, use third-party services like Trakt, or run Kodi as a front-end to Jellyfin. Jellyfin does it by default. No configuration, no third-party accounts, no database setup.

This centralized approach extends to all metadata, artwork, and library organization. Change something once on the server, and every client sees the update immediately.

This is where Jellyfin completely outclasses Kodi.

Yes, you can share Kodi libraries remotely using VPNs or SMB shares. But it usually involves explaining network paths, teaching friends how to mount drives, or giving out file share credentials.

And then they call you because it stopped working after a Windows update. Or their router rebooted. Or they got a new phone and don’t remember the setup steps.

Jellyfin Is Designed for This

Jellyfin includes user accounts, per-library permissions, bandwidth limits, and secure authenticated access. You can expose Jellyfin using port forwarding with HTTPS, a reverse proxy, or a mesh VPN like Tailscale.

⚠️

Warning: If you port forward Jellyfin, use HTTPS and strong passwords. Web-facing media servers are targets. Don’t be the person who gets their server compromised because they used “password123.”

Friends install an app, log in, and watch. Because of transcoding, it works even on weak devices. No explaining network shares. No VPN configuration. No tech support calls.

Common Jellyfin Pain Points to Expect

Look, Jellyfin isn’t perfect. Here’s what’ll probably trip you up:

Hardware Transcoding Failures

Driver issues on Linux (especially NVIDIA)
Wrong permissions for hardware devices (/dev/dri access problems)
Codec support varies by GPU generation

When hardware transcoding fails, Jellyfin falls back to software transcoding, which will max out your CPU. You’ll know because your server fans will sound like a jet engine.

Weak Server Performance

Software transcoding taxes weak CPUs
Multiple 4K transcodes need serious hardware
Remote users expect things to work on the first try regardless of your setup

If you’re running on an old laptop with a dual-core CPU, don’t expect to transcode 4K to three people simultaneously. It won’t happen.

Android TV App Limitations

Some cheap Android TV boxes struggle with the official app
HDR passthrough can be finicky
Third-party clients like Findroid sometimes work better

The official Jellyfin Android TV app is solid, but if you’ve got a $30 Android box from Amazon, you might have issues. Try Findroid if the official app gives you trouble.

Seagate Barracuda 24TB Internal Hard Drive
Large, affordable storage is essential for a growing media library, and this drive provides ample capacity for movies and shows, though it lacks NAS/enterprise features for heavy multi-user or RAID use.

Amazon Price: Loading...

Availability: Checking...

Contains affiliate links. I may earn a commission at no cost to you.

Why Native Jellyfin Beats Kodi Plus the Jellyfin Plugin

The Jellyfin plugin for Kodi is excellent. It turns Kodi into a Jellyfin client, syncing libraries and watched status. I used it for months.

But with Kodi plus Jellyfin, you still manage Kodi settings on every device. A Kodi or Jellyfin update can break the plugin. Native Jellyfin clients remove an entire layer of troubleshooting.

My rule: I use Kodi plus Jellyfin for myself when I want customization. I never give Kodi to friends or family. They get native Jellyfin clients, because I value my free time.

Troubleshooting Common Issues

Playback Stutters or Buffers

First, check if the stream is transcoding or direct playing. In the Jellyfin dashboard, you can see active streams and whether they’re transcoding.

If it’s transcoding:

Enable hardware acceleration if you haven’t already
Lower client bitrate for weak devices
Consider pre-converting very high bitrate files if you’re hitting this constantly

If it’s direct playing and still stuttering, your network’s probably the issue.

High CPU Usage on the Server

Too many software transcodes happening at once
Enable hardware transcoding if available
Consider pre-converting very high bitrate files

If you see 100% CPU usage and your server’s crawling, someone’s transcoding without hardware acceleration. Fix that first.

Remote Access Works Locally but Not Outside

Verify port forwarding or VPN configuration
Confirm users are connecting to the correct external address
Check firewall rules on both the server and router

A few minutes testing this yourself saves an hour or more of back-and-forth with friends who can’t connect.

FAQs

➤ Is Jellyfin completely free like Kodi?

Yes. Jellyfin is fully open source and free, with no paid tiers. No premium features locked behind paywalls, no subscriptions, nothing.

➤ Do I need a powerful server?

Not for basic use. You only need more power if you expect multiple transcodes at once. If you’re mostly direct playing to local devices, an old desktop is fine.

➤ Can I still use Kodi with Jellyfin?

Absolutely. Kodi plus the Jellyfin plugin is a great power-user setup. I still use it on my main TV because I like the customization. But I don’t inflict it on anyone else.

➤ Is Jellyfin as customizable as Kodi?

No, and that’s intentional. Jellyfin favors simplicity over endless customization. You can theme it a bit, but you’re not building custom skins or installing dozens of add-ons.

➤ Will Jellyfin always transcode my files?

No. Jellyfin direct-plays whenever possible and only transcodes when needed. If your client supports the file format, codec, and resolution, Jellyfin streams it directly. Transcoding only kicks in when something doesn’t match.

Conclusion: Why Jellyfin Won for Me

Kodi is still amazing software. If you love tweaking and customizing, Kodi will always have a place. I’m not saying Kodi is bad, I’m saying it’s designed for a different use case.

But for most people, especially families and shared households, Jellyfin is the better tool. One server, synced playback everywhere, reliable transcoding, easy remote access, and simple apps that work.

I ditched Kodi not because it failed, but because Jellyfin solved the problems Kodi was never designed to solve. If you’re tired of being the household media IT department, Jellyfin might be your way out.

This post is a straight Kodi-vs-Jellyfin call. If Plex and Emby are also on your shortlist, the four-way showdown weighs all of them on features, cost, hardware, and ease of use:

Kodi vs Plex vs Jellyfin vs Emby: Which Is Best in 2026? Weighing Plex or Emby too? The four-way showdown compares all of them on features, cost, and ease of use.

Read the Showdown

Ready to set up your own Jellyfin server? Check out the official Jellyfin documentation for installation guides and best practices.

ASRock Intel Arc A580 Challenger 8GB OC
This dedicated GPU enables efficient hardware transcoding for Jellyfin, especially useful if you have multiple users or diverse client devices, but it’s not required if your clients can direct play all your content.

Amazon Price: Loading...

Availability: Checking...

Contains affiliate links. I may earn a commission at no cost to you.

Resources

Jellyfin Official Documentation

Kodi Wiki

Intel Quick Sync Video Guide

How to Install and Configure Fail2Ban on your Jellyfin LXC

Thu, 01 Jan 2026 07:03:16 -0700

If you’ve exposed Jellyfin to the internet, whether through port forwarding or a reverse proxy, you’re already being scanned. Bots see an open login page and start stuffing passwords, trying to guess their way in.

Ask me how I know.

When I first stood up Jellyfin and exposed it to the internet, I left the default jellyfin username in place. Bots found the login page almost immediately and hammered the account around the clock. I only noticed because Jellyfin’s per-user lockout kept tripping and I couldn’t log in to watch anything. I knew better. And there I was, staring at thousands of failed login attempts from IPs scattered across multiple countries.

So I changed the default username. That stopped the account lockouts. But the server itself was still getting probed every single day. I needed another layer. Fail2Ban was the obvious answer.

This guide covers installing and configuring Fail2Ban for a Jellyfin LXC without banning yourself. We’ll cover direct exposure, reverse proxy setups, Docker-in-LXC gotchas, and monitoring bans over time.

💭

TL;DR:

Fail2Ban watches Jellyfin logs for failed login attempts and automatically blocks abusive IPs. With the right jail, filter, and network configuration, you can stop brute-force attacks in their tracks even behind a reverse proxy all without locking yourself out.

Quick Start for Experienced Users:
Create filter /etc/fail2ban/filter.d/jellyfin.conf
Create jail /etc/fail2ban/jail.d/jellyfin.local
Verify firewall backend (iptables or nftables)
Configure reverse proxy trust if needed
Test with fail2ban-regex

Why Fail2Ban Protects Your Jellyfin Server

Here’s the thing: Jellyfin has authentication, and its rate-limit lockout is per user, not global. If you haven’t set it on a user account, an attacker can throw thousands of passwords at it per hour without consequence.

Fail2Ban operates globally. You don’t have to set it per user.

Fail2Ban does this by:

Watching log files for suspicious patterns
Counting repeated failures from the same IP
Adding firewall rules to block that IP for a set time

For context, the Jellyfin default HTTP port is 8096 and the default HTTPS port is 8920. Whether you expose these directly or run Jellyfin behind a reverse proxy on port 443, failed login attempts look the same in the logs. That’s actually good news. One Fail2Ban config works for both scenarios.

Pre-Deployment Checklist

Answer these before touching any configs. Trust me, five minutes now saves an hour of troubleshooting later:

Exposure method: Direct port forwarding or reverse proxy?
Jellyfin port: Using default 8096 or custom?
Firewall backend: iptables or nftables? (Check with sudo iptables --version and sudo nft --version)
Container setup: Jellyfin directly in LXC or Docker-in-LXC?
Reverse proxy: If yes, are real client IPs logged?
Trusted networks: What IPs should never be banned?

📝

Note:

I’ll be configuring this on an unprivileged LXC running Debian 13 with nftables.

All examples below assume that setup.

Checking Your Firewall Backend

Modern Debian systems often run nftables with iptables as a compatibility layer.
You need to know which one Fail2Ban will use:

# Check what's actually running
sudo systemctl status nftables
sudo systemctl status netfilter-persistent

Fail2Ban works with both, but the actions you configure will differ.
Get this wrong and bans won’t happen.

Installing Fail2Ban on Debian/Ubuntu LXC

Alright, let’s get Fail2Ban installed:

sudo apt update
sudo apt install fail2ban
sudo systemctl status fail2ban

If you see active (running), you’re golden. Fail2Ban starts automatically and survives reboots.

Example:

● fail2ban.service - Fail2Ban Service
 Loaded: loaded (/usr/lib/systemd/system/fail2ban.service; enabled; preset: enabled)
 Active: active (running) since Wed 2025-12-31 11:22:01 MST; 20h ago
 Invocation: 9a7ce4195aaa4dc48dc750363bb9b954
 Docs: man:fail2ban(1)
 Main PID: 329267 (fail2ban-server)
 Tasks: 13 (limit: 7051)
 Memory: 15.7M (peak: 24M)
 CPU: 4min 37.380s
 CGroup: /system.slice/fail2ban.service
 └─329267 /usr/bin/python3 /usr/bin/fail2ban-server -xf start

Dec 31 11:22:01 racknerd-ea37d8f systemd[1]: Started fail2ban.service - Fail2Ban Service.
Dec 31 11:22:01 racknerd-ea37d8f fail2ban-server[329267]: Server ready

MINISFORUM MS-01 Mini Workstation This mini workstation is ideal for running Jellyfin in an LXC container and experimenting with Fail2Ban, offering enough power and networking for a secure, flexible homelab setup.

Amazon Price: Loading...

Availability: Checking...

Contains affiliate links. I may earn a commission at no cost to you.

The hardware doesn’t really matter for Fail2Ban itself. It runs happily on anything that can host the LXC. What matters next is the filter that tells it what a failed login looks like.

Creating the Jellyfin Fail2Ban Filter

Filters live in /etc/fail2ban/filter.d/ and tell Fail2Ban what a “failed login” looks like in your logs.

sudo nano /etc/fail2ban/filter.d/jellyfin.conf

Add this:

[Definition]
failregex = ^.*Authentication request for .* has been denied \(IP: "<ADDR>"\)\.
ignoreregex =

⚠️

Warning: Jellyfin log formats can change between versions. I learned this the hard way after an update when bans mysteriously stopped working. Always test your filter after upgrades.

Test the Filter

Before going any further:

Make sure to have some failed logins today
Test the filter against your actual logs
- REPLACE: YYYYMMDD with today’s date

sudo fail2ban-regex /var/log/jellyfin/jellyfinYYYYMMDD.log /etc/fail2ban/filter.d/jellyfin.conf --print-all-matched

You should see matched lines with IP addresses highlighted.

Example:

| [2025-12-31 07:22:27.102 -07:00] [INF] Authentication request for "test@test" has been denied (IP: "140.32.72.74").
| [2025-12-31 07:22:28.787 -07:00] [INF] Authentication request for "test@test" has been denied (IP: "140.32.72.74").
| [2025-12-31 07:41:08.539 -07:00] [INF] Authentication request for "test@test" has been denied (IP: "140.32.72.74").
| [2025-12-31 07:41:10.368 -07:00] [INF] Authentication request for "test@test" has been denied (IP: "140.32.72.74").

Zero matches means your regex is wrong or your log path is incorrect.

💡

Tip: Don’t skip this step. I’ve wasted hours debugging jails that would never work because the filters never matched anything.

Creating the Jellyfin Jail Configuration

Jails define what happens when the filter finds matches.

sudo nano /etc/fail2ban/jail.d/jellyfin.local

Base Configuration (Without a Reverse Proxy)

[jellyfin]
enabled = true
filter = jellyfin
logpath = /var/log/jellyfin/jellyfin*.log
backend = polling

maxretry = 5
findtime = 10m
bantime = 20m

port = 8096,8920
protocol = tcp

action = nftables[type=multiport]

ignoreip = 127.0.0.1/8 ::1

# Optional: add YOUR LAN subnet to ignoreip (recommended)
# Examples (pick the one that matches your network, or use the exact /24 you use)
# 10.0.0.0/8
# 172.16.0.0/12
# 192.168.0.0/16

That config means: 5 failures within 10 minutes earns a 20-minute ban. Tune to taste. Don’t make maxretry too low or bantime too long. You’ll lock yourself out the first time you mistype a password while trying to watch something away from home.

💡

Tip: backend = polling is needed because Jellyfin creates a new log file every 24 hours with a unique name. This lets fail2ban read these files.

That’s the basics of Fail2Ban when you’re exposing Jellyfin directly to the internet via port forwarding. I strongly recommend a reverse proxy rather than exposing Jellyfin directly.

I’ll cover the reverse-proxy setup in a follow-up post.

RaspberryPi 4GB The Raspberry Pi is a budget-friendly, low-power option if you are wanting to test Fail2Ban and Jellyfin in a lightweight, isolated environment before deploying to larger servers.

Amazon Price: Loading...

Availability: Checking...

Contains affiliate links. I may earn a commission at no cost to you.

A spare Pi is a great place to break things before you touch the LXC running your real library. Once the jail behaves there, copy the configs over with confidence.

Monitoring and Maintenance

Watch Ban Activity

Want to see bans happen in real-time? This is oddly satisfying:

sudo tail -f /var/log/fail2ban.log

You’ll see IPs getting banned as they trip your thresholds. After the first few, you realize how many bots are constantly probing your server.

Unban Yourself

Locked yourself out? It happens. From the LXC console:

sudo fail2ban-client set jellyfin unbanip 192.168.1.50

Replace with your actual IP. You’ll be unbanned immediately.

Best Practices for Fail2Ban Management

Keep bantime finite. Infinite bans sound appealing, but they’re risky. You can ban yourself permanently.
Test filters after every Jellyfin update. Log formats change.
Review ban logs monthly for patterns. If you’re getting hammered from specific countries, consider additional firewall rules.
Document your unban procedure somewhere you can access when locked out.

Troubleshooting Common Fail2Ban Issues

No bans occur: Wrong filter regex, wrong logpath, or Jellyfin’s logging level is too low. Use fail2ban-regex to debug. Also check that Fail2Ban is reading the log file. Permissions matter.

Locked out completely: Access your LXC console (not SSH, that’s blocked too), unban manually, then add your IP to ignoreip in the jail config.

FAQs

➤ Will Fail2Ban ban my own IP?

Yes, if you exceed maxretry. Use ignoreip for your home network or keep the unban command handy. I’ve locked myself out more times than I’d like to admit.

➤ What's the difference between bantime and findtime?

findtime is the detection window, how far back Fail2Ban looks for failures. bantime is how long the ban lasts. So with findtime = 600 and maxretry = 3, you get banned if you fail 3 times within 10 minutes. The ban then lasts for bantime seconds.

➤ Does Fail2Ban work with nftables?

Yes, but verify the backend configuration matches your system. Modern Debian uses nftables, but Fail2Ban might still default to iptables compatibility mode. Check your jail config.

➤ Is Fail2Ban useful for local-only Jellyfin?

Not really. It matters when Jellyfin is exposed beyond your LAN.

Conclusion: Harden Your Jellyfin Installation

If your Jellyfin instance is reachable from the internet, Fail2Ban is essential. Brute-force attempts are constant and invisible until you check your logs. I was shocked when I first looked. Thousands of attempts per day from IPs all over the world.

Understand your network topology, configure the correct jail and action, and monitor bans periodically. That’s how you turn Jellyfin from a soft target into a more secure service. This is the third step in hardening your Jellyfin LXC.

You should have already:

Be using an unprivileged LXC - LXC Guide for Jellyfin
Set Firewall Rules
Secured your SSH - How to secure SSH
Now Fail2Ban

I learned this by watching bad actors brute-force my server for days. Now they get five tries and a timeout. Yours should too.

Next steps:

Pair Fail2Ban with HTTPS and strong passwords
Add a reverse proxy like NGINX or Caddy

Resources

Fail2Ban Official Wiki

Jellyfin Official Documentation

Glovary N150 Firewall Mini PC Fail2Ban covers the application layer. This fanless N150 appliance covers the network layer in front of it, with six Intel i226-V 2.5GbE ports and hardware AES-NI for OPNsense or pfSense. Running both means a banned address gets dropped at the edge instead of reaching Jellyfin at all.

Amazon Price: Loading...

Availability: Checking...

Contains affiliate links. I may earn a commission at no cost to you.

DIYMEDIASERVER 2025 Year in Review

Sat, 27 Dec 2025 06:32:28 -0700

Looking Back at the Mess We Started With

It’s December 27th, and somehow we made it through our first year!

If you’ve been following along, you know this blog started as a therapy journal for the saga of fixing my media server that kept failing. One tower doing everything. ISP router I’d never logged into. Backups that were “I should really do that.” The classic homelab setup.

2025 was the year I finally stopped duct-taping problems and built something that works. Four boxes with dedicated jobs. Proxmox running things properly. Docker that doesn’t make me want to throw my keyboard. And yeah, actual backups that saved my ass more than once.

You asked the important questions. I burned my nights and weekends figuring shit out. Here’s a summary of what we accomplished in 2025.

The Big Picture

This year, DIYMediaServer turned into a complete blueprint for running your own media infrastructure. The whole thing: hardware, virtualization, networking, storage, automation, and the backup strategy that lets you experiment without worry. Not the “install Jellyfin and pray” tutorial.

If you’re still running everything on one machine with an ISP router, this 2025 review is your roadmap out. No enterprise budget required. Better decisions and way fewer panic reboots during movie night.

The Wins: What Got Published

I wrote a lot this year. Maybe too much. But every post came from a real problem I hit or a question one of you asked.

Hardware That Makes Sense

The four-box architecture was the turning point. Instead of one overworked machine doing everything badly, I split responsibilities:

The Router - Kicked the ISP router to modem-only duty and built a proper OPNsense box. VLANs, firewall rules, actual logs.

The NAS - Said goodbye to VM storage nightmares and USB drives hanging off Proxmox nodes. Dedicated hardware, proper HBAs, filesystems that won’t explode. My media library finally has a real and stable home.

The Compute Node - Apps got their own Proxmox box. One dead component used to take down everything. Not anymore. Compute crashes? Router and storage keep humming along.

The Backup Server - PBS finally got its own machine and became the “try anything without fear” box. Break something with an upgrade? Five-minute restore instead of rebuilding from scratch.

These weren’t abstract posts. They’re the exact setup I’m running. Every gotcha I hit along the way is spelled out so you don’t have to step in them.

Docker’s Comeback Tour

Remember when I was all-in on LXCs? Yeah, about that.

2025 was my public admission that I’d been fighting containers the wrong way. The LXC hell trilogy laid it all out: UID/GID nightmares, NFS permission walls, the “secure by default” trap that made simple media sharing an absolute nightmare.

I crawled back to Docker for the media stack and documented the whole journey. The Arr suite comparison showed exactly why throwing Radarr, Sonarr, and friends into Docker Compose is better than individual LXCs. Cleaner updates. Simpler mounts. One export to storage and done.

LXCs still have their place for lightweight services and utilities. But for media apps? Docker won, and I’m not too proud to say I was wrong.

I might give LXCs another shot in 2026 with a different mounting method.

Automation That Works

Your media stack should work for you. This year we built out the full automation chain:

Download management: SABnzbd, Radarr, Prowlarr guides that turn “I want this show” into “it’s already downloaded and sorted.” Complete with the Usenet vs torrents breakdown and SABnzbd vs NZBGet comparison.

Media processing: Tdarr running in an unprivileged LXC with QuickSync, letting your Intel iGPU chew through transcodes while you do literally anything else.

Profilarr will be covered in 2026 as an alternative to Tdarr.

The Boring Stuff That Saved My Weekends

Some posts won’t get much traffic, but they quietly prevent disasters:

parted and mount points - So your drives don’t unmount on reboot
UID/GID mapping in Proxmox - Ending the “Permission denied” screaming sessions
HBA guide - Why cheap SATA cards will ruin your ZFS pool
Debian 12 to 13 upgrade fix - The systemd credential bug that hit everyone on Proxmox 9
SSH hardening - Stop leaving root login wide open
The 24-hour NFS crash loop story - A debugging nightmare with MergerFS that taught me more about the kernel than I wanted to know

Each one small. Together? They turn “mostly works” into “boringly reliable.”

Network and Security Upgrades

The networking stack finally grew up:

Proper routing with OPNsense. VLANs separating family devices from the media stack from random IoT garbage. Pi-hole v6 on multiple nodes, synced with Nebula so your DNS stays consistent.

Not sexy stuff. But it’s the difference between “my Smart-Switch can somehow access my NAS shares” and “everything is where it should be and logged.”

What’s Missing?

Let me be honest about my documentation gaps, because 2026 needs to address them:

Remote access - I’ve barely touched this. You’ve got a great local setup, but accessing your media from outside your network safely? That’s the next frontier. I picked up a cheap VPS during Black Friday sales, and I’m building out a multi-part series on using it as a secure front door. Caddy for reverse proxy, Wireguard to tunnel back home, keeping your services and ISP IP hidden behind the VPS. No exposing ports directly. No hoping your ISP doesn’t change your IP. Actual security with the flexibility to access everything remotely.

NFS and MergerFS don’t play nice - The 24-hour crash loop story hinted at this, but there’s a bigger problem. NFS and MergerFS together create weird edge cases and performance issues I’ve been working around instead of fixing. Early 2026, I’m diving into VirtioFS as an alternative and rethinking how storage gets shared between Proxmox hosts and VMs. This one’s going to be a deep dive with real testing. I’ll be testing an alternative mounting method for MergerFS as well.

Monitoring and alerting - The stack is more stable now, but you’re still flying blind. When did that disk start filling up? Is Jellyfin actually responsive or only running? Uptime Kuma, Discord Alerts, Bash scripts, and simple health checks need to be covered.

Installing and Configuring Proxmox - I’ve talked about how I use Proxmox, but I haven’t documented how to install or configure it yet.

Hardware deep dives - The guides covered what to buy, but not enough on why. Power efficiency numbers. Noise levels. Heat management. Budgets from “I have $500” to “I can spend $2000.”

Recovery scenarios - PBS is set up, but I haven’t documented what a full restore looks like. Or migrating everything to new hardware.

The “complete stack” templates - I haven’t been great at creating good copy-and-paste solutions. That’s intentional. I want you to learn, not blindly paste. But some of you have asked for full “recipe” builds that are copy, paste, adjust to taste.

More debugging stories - I will be focusing on more real problems. The weird bugs. More Lightbulb moments documented. The “here’s what I tried that didn’t work before I found the solution.”

Where You Might Be Right Now

“Everything’s still in one box”

Start with the four-box hardware guide. Move routing off first, then storage. You don’t need to do it all at once, but every piece you split out makes the whole system more resilient.

“LXC permissions are killing me”

The LXC hell series is literally your story. Switch media apps to Docker, keep LXCs for the lightweight stuff. Your blood pressure will thank you.

“Backups? There’s a USB drive somewhere…”

PBS guide. Find a cheap mini PC, add a big drive, let Proxmox handle it. The first time you restore instead of rebuild, you’ll wonder why you waited.

“My ISP router… works?”

OPNsense build. One weekend. You’ll immediately see the difference when you can control what’s happening on your network.

“I’m new and this is overwhelming”

Start small. Pick the SSH hardening guide. Get one Arr app running. You don’t need the full four-box dream build on day one. Build confidence with small wins, then come back for the architecture.

Before and After

I want to be clear about what changed over the last year:

Before: One box doing everything. LXCs everywhere with permission nightmares. VM storage on a prayer. ISP router mystery settings. “Backups” = good intentions.

Now: Dedicated router, NAS, compute, and backup boxes. Proxmox with clear roles. Docker for media apps. Automated downloads with Radarr and SABnzbd. OPNsense with VLANs. PBS with actual tested restores.

Your homelab shouldn’t be a second job. It should work quietly in the background and let you use your media instead of constantly fixing things. Don’t get me wrong, tinkering is still fun. But I want to pick when I tinker instead of getting dragged into it mid-movie.

What’s Next

2025 was foundations. Getting the architecture right, escaping container hell, setting up backups, and basic networking.

2026 is where we go deeper:

Remote access allowing sharing with friends
Monitoring and alerting that helps
Complete stack templates you can copy
More budget vs performance breakdowns
Disaster recovery walkthroughs
Ansible Playbooks
Better MergerFS setup
More real debugging stories

This blog exists because I got tired of forum posts from 2015 that assumed you already knew everything. The goal is making this stuff accessible. Not dumbed down. Explained properly, with the context that matters.

It’s also forcing me to keep my skills sharp and to keep learning.

Setup One Thing Before New Year’s

You’ve got a week. Pick something from this year’s posts and do it:

Move your routing to OPNsense
Set up PBS
Configure proper SSH hardening
Get Radarr automating one library

One thing. Build momentum. Start 2026 with a win instead of another “I really should do that.”

You’re building infrastructure you understand and control. That’s worth the effort.

Thanks for reading this year. See you in 2026.

Hit me up on Reddit or E-mail if there’s something specific you want covered. I’m making the list now.

Sync Multiple Pi-hole Servers with Nebula Sync

Sat, 13 Dec 2025 07:32:28 -0700

You add a blocklist to your first Pi-hole. Easy. Then you remember you’ve got two more Pi-holes scattered around your network. Each one needs the same update. Manually. You tab between admin pages, copying settings, and by the second one you’re asking yourself why you ever thought multiple Pi-holes was a good idea.

Nebula Sync fixes this. It keeps multiple Pi-hole servers in sync by automatically copying blocklists, local DNS records, and settings from one primary Pi-hole to all your replicas. Change something once on the primary, and Nebula pushes it everywhere else within a few minutes.

If you’re running multiple Pi-holes and you’re tired of manual updates, this guide will get you set up. If you can log into pihole/admin and run Docker, you can do this.

💭

TL;DR: Run multiple Pi-hole servers for redundancy, designate one as primary, and use Nebula Sync to automatically replicate blocklists, local DNS, and settings to all replicas without manual updates.

Quick checklist:

2+ working Pi-hole nodes (same major version, ideally v6)
One node chosen as PRIMARY (the only one you edit)
A basic understanding of Docker/Compose
Router/DHCP hands out both Pi-hole IPs (DNS) for failover

Why Sync Multiple Pi-hole Servers?

Why Run More Than One Pi-hole?

One Pi-hole works great until it doesn’t. Maybe you’re updating it and something breaks. Maybe the SD card dies. Whatever the reason, when your single DNS server goes down, your entire network loses internet. Your spouse can’t stream. The smart home stops working. You know how this goes.

Multiple Pi-holes solve this:

Redundancy: One Pi-hole fails, DNS keeps working.
Maintenance without downtime: Update one node while the other handles queries.
Better coverage: Every device stays protected during updates or failures.

The problem? Managing them manually is a pain. Every blocklist or whitelist addition, every DNS entry, every setting tweak has to be repeated on each node. That gets old fast.

Two Sync Approaches, One Clear Winner for v6

You’ve got two main options for syncing Pi-holes:

Gravity Sync is the old reliable. It’s a bash script that syncs databases over SSH. Works great for Pi-hole v5.x, but it wasn’t built for v6’s API architecture.

Nebula Sync is newer and designed specifically for Pi-hole v6’s web API. It syncs more than gravity databases. Local DNS records, group settings, and other v6 config travel with it.

We’re using Nebula Sync here because it’s built for v6 and works cleaner with current Pi-hole versions.

Prerequisites and Lab Layout

What You Need

Before you start, make sure you have:

Two or more working Pi-hole servers
Each Pi-hole accessible at http://<ip>/admin or https://<host>/admin
An admin password set on each Pi-hole
Something that can run Docker (often one of the Pi-holes works fine)

For the Pi-hole nodes themselves, a Raspberry Pi 4 is the classic pick. Cheap, silent, and more than enough horsepower for DNS plus a Nebula Sync container.

RaspberryPi 4GB - Must have for this build.
Quiet, cheap, and plenty for Pi-hole + Nebula Sync.
If you’re doing heavy DNS for a big network, use a small x86 box instead.

Amazon Price: Loading...

Availability: Checking...

Contains affiliate links. I may earn a commission at no cost to you.

Example Setup

Throughout this guide, I’ll use:

pihole1 at 192.168.1.10 (Primary)
pihole2 at 192.168.1.11 (Replica)

Swap in your own IPs. You can add more replicas later.

Check Pi-hole Versions (Important)

Log into each pihole/admin dashboard and check the version at the bottom of the page.

Keep all nodes on the same major version, ideally v6.x. Mixing versions causes weird issues. If they don’t match, update each node:

pihole -up

Decide Where Nebula Sync Will Run

Two common options:

Option A (simplest): Run Nebula Sync as a Docker container on the primary Pi-hole.
Option B: Run it on a separate Docker host that can reach all Pi-hole admin URLs.

For most people, Option A is easiest.

Step 1: Verify Each Pi-hole Works Standalone

Don’t skip this. If a Pi-hole is broken before you sync it, you’ll spread the brokenness around.

On each Pi-hole:

Open http://<pihole-ip>/admin.
Log in with the admin password.
Confirm the dashboard loads and shows recent queries.
From the terminal, tail logs:

pihole -t

From a client device, temporarily set DNS to only that Pi-hole and browse a few sites.

If DNS queries show up in the log, you’re good. If not, fix networking or service issues before moving on.

Step 2: Gather URLs and Credentials

Nebula Sync talks to Pi-hole via the web API, so you need the exact URLs and passwords.

For each Pi-hole, write down:

Full admin URL, including /admin
- Example: http://192.168.1.10/admin
Admin password

Nebula expects this format:

URL|password

Example:

http://192.168.1.10/admin|SuperSecretPassword

💡

Tip: About 80% of sync failures happen because someone forgot /admin at the end of the URL. Don’t be that person.

Step 3: Create a Nebula Sync Docker Compose File

Most people deploy Nebula Sync with Docker Compose or Portainer.

Example `compose.yml`

services:
 nebula-sync:
 image: ghcr.io/lovelaze/nebula-sync:latest
 container_name: nebula-sync
 environment:
 - PRIMARY=http://192.168.1.10/admin|PRIMARY_PASSWORD
 - REPLICAS=http://192.168.1.11/admin|REPLICA_PASSWORD
 - FULL_SYNC=true
 - RUN_GRAVITY=true
 - CRON=*/5 * * * *
 restart: unless-stopped

Replace the URLs and passwords with your actual ones.

⚠️

Warning: Putting passwords directly in the compose file works but isn’t great. For better security, use a .env file:

From the same directory where your compose.yaml file lives, create a .env file:

nano .env

Paste this:

PIHOLE_PRIMARY_URL=http://192.168.1.10/admin
PIHOLE_PRIMARY_PASSWORD=YourSecretPassword

PIHOLE_SECONDARY_URL=http://192.168.1.11/admin
PIHOLE_SECONDARY_PASSWORD=YourSecretPassword

Then reference them in compose like this:

- PRIMARY=${PIHOLE_PRIMARY_URL}|${PIHOLE_PRIMARY_PASSWORD}
- REPLICAS=${PIHOLE_SECONDARY_URL}|${PIHOLE_SECONDARY_PASSWORD}

Now you can share your compose file without scrubbing the password every time.

Example `compose.yaml` Using the .env File

services:
 nebula-sync:
 image: ghcr.io/lovelaze/nebula-sync:latest
 container_name: nebula-sync
 env_file:
 - .env
 environment:
 - PRIMARY=${PIHOLE_PRIMARY_URL}|${PIHOLE_PRIMARY_PASSWORD}
 - REPLICAS=${PIHOLE_SECONDARY_URL}|${PIHOLE_SECONDARY_PASSWORD}
 - FULL_SYNC=true
 - RUN_GRAVITY=true
 - CRON=*/5 * * * *
 restart: unless-stopped

Key Environment Variables Explained

PRIMARY: The Pi-hole you’ll always edit manually. This is your source of truth.
REPLICAS: Pi-holes that receive config from the primary. Separate multiple with spaces.
FULL_SYNC: Set to true to sync everything Nebula supports.
RUN_GRAVITY: Tells Pi-hole to run gravity after syncing.
CRON: Cron-style schedule. */5 * * * * means every 5 minutes, a good starting point.

Common mistakes:

Missing /admin
Wrong http:// vs https://
Typos in passwords

Step 4: Deploy Nebula Sync

From the directory containing your compose file:

docker compose up -d

Then check logs:

docker logs -f nebula-sync

What you want to see:

Successful connection to primary
Sync operations targeting replicas
No authentication or connection errors

If you see authentication errors, double-check those URLs and passwords. Connection errors? Verify HTTP vs HTTPS and make sure you can load the admin pages in a browser from the Docker host.

Step 5: First Sync Test with Gravity and Blocklists

Time to confirm real data is syncing.

On the primary Pi-hole:

Go to Group Management > Adlists.
Add a test blocklist or toggle an existing one.
Click Save and Update

Wait for the next Nebula run (or restart the container because who has patience?).

On the replica:

Open /admin.
Navigate to Group Management > Adlists.
Confirm the new list appears and domain counts match closely.

If it’s there, gravity syncing works. Nice.

Step 6: Sync Local DNS and Custom Entries

This is where Nebula Sync really shines compared to older tools. Custom DNS entries sync automatically.

On the primary:

Go to Local DNS > DNS Records.
Add:
- Hostname: tim.example.com
- IP: 10.0.0.50
Save.

After the next sync:

On the replica:

Open Local DNS > DNS Records.
Search for tim.example.com.
Confirm it exists and points to the same IP.

Test it:

nslookup tim.example.com 192.168.1.11

You should get 10.0.0.50.

Step 7: Day-to-Day Workflow (Primary/Replica Rules)

Once everything’s working, the rules are simple:

Always make changes on the primary Pi-hole.
Treat replicas as read-only in the UI.
Let Nebula Sync handle propagation.

You can adjust the sync frequency if needed. For most homelabs, every 5 to 15 minutes works well. More frequent syncing means less drift time but more API calls hitting your Pi-holes.

Step 8: Router and Client DNS Configuration

To benefit from multiple Pi-holes, clients need to know about them.

Simple Setup: Two DNS IPs

In your router’s DHCP settings:

DNS 1: 192.168.1.10
DNS 2: 192.168.1.11

Clients automatically fail over if one Pi-hole is unavailable. It’s not instant, but it works.

Advanced Option: Virtual IP

If you’re feeling ambitious, tools like keepalived can give you a single virtual IP that floats between Pi-holes. This is optional and overkill for most people.

Step 9: Testing Failover and Basic Pi-hole Tests

Make sure your redundancy actually works:

Ensure clients receive both DNS IPs from DHCP.
Stop Pi-hole on the primary or reboot the server.
Browse the web from a client.
Check the replica’s Query Log for activity.

Useful commands:

pihole -t to watch live queries
dig or nslookup against each Pi-hole IP
Visit ad-heavy sites and confirm blocks appear

Step 10: Maintenance and Updates

Updating Pi-hole

On each node:

pihole -up

Keep versions aligned to avoid API mismatches.

Updating Nebula Sync

From the compose directory:

docker compose pull
docker compose up -d

Backup Strategy

Before major changes:

Export Pi-hole config from the primary
Keep a copy offline

If something breaks:

Stop the Nebula container.
Restore the primary from backup.
Restart Nebula Sync.

Troubleshooting Common Problems

Quick Troubleshooting Table

Symptom	Likely cause	Fix
Authentication errors in Nebula logs	Wrong password or URL format	Re-check password and make sure the URL includes `/admin`
Connection errors / timeouts	Wrong scheme (HTTP vs HTTPS) or network issues	Verify `http://` vs `https://`, check firewalls, make sure the admin UI loads in a browser
Changes not appearing on replicas	FULL_SYNC disabled, schedule not running, or edits made on replica	Confirm `FULL_SYNC=true`, check logs for runs, only edit the primary
Nodes drift after updates	Mixed major versions	Upgrade all nodes; don’t mix v5 and v6
Expecting DHCP to sync	Not supported	Keep DHCP on router or manage separately

Nebula Sync Fails Authentication

Double-check admin passwords.
Confirm /admin is included in the URL.
Verify HTTP vs HTTPS.

Changes Not Appearing on Replicas

Confirm FULL_SYNC=true.
Check Nebula logs for recent runs.
Make sure changes were made on the primary only.

Mixed Pi-hole Versions

Upgrade all nodes to the same major version.
Don’t mix v5 and v6.

DHCP Expectations

Nebula Sync does not sync DHCP settings or leases. Keep DHCP on your router or manage it separately.

If your Pi is starting to choke on a busy network or you want to run more containers alongside Nebula Sync, a small x86 mini-PC is the next step up.

Beelink SER5 (Ryzen 5 5500U) Nice to have but not required.
Best for people upgrading from a Raspberry Pi who want Pi-hole plus extra Docker containers without lag, but it costs more and uses more power than a Pi.

Amazon Price: Loading...

Availability: Checking...

Contains affiliate links. I may earn a commission at no cost to you.

FAQs (Nebula Sync + Pi-hole)

➤ Can I sync more than two Pi-hole servers with Nebula Sync?

Yes. Define one primary and add multiple replicas in the REPLICAS variable. Example:

- REPLICAS=http://ph2.example.com|password,http://ph3.example.com|password

or with env:

- REPLICAS=${PIHOLE_SECONDARY_URL}|${PIHOLE_SECONDARY_PASSWORD},${PIHOLE_TERTIARY_URL}|${PIHOLE_TERTIARY_PASSWORD}

➤ Do I have to run Nebula Sync in Docker?

Docker is the most common and easiest approach for updates and isolation.

➤ Does Nebula Sync work with Pi-hole v6?

Yes. It’s designed around Pi-hole v6’s web API and HTTPS admin interface.

➤ Will Nebula Sync keep DHCP settings in sync?

No. DHCP settings and leases are node-specific and don’t sync.

➤ Can I edit settings directly on replicas?

You can, but Nebula will overwrite them on the next run. Save yourself the headache and only edit the primary.

➤ What happens if a replica is offline during sync?

Nebula will fail that run and catch up when the replica comes back online.

➤ Is it safe to mix HTTP and HTTPS?

Yes, as long as each Pi-hole is defined with the correct scheme in Nebula’s config.

➤ How often should I run the sync?

Every 5 to 15 minutes is typical for homelabs.

➤ Do I still need to run `pihole -g` on replicas?

No. Run it on the primary only. Nebula syncs the results.

➤ How do I test that everything works?

Add a test DNS record or blocklist on the primary and confirm it appears and functions on replicas.

Conclusion

Running multiple Pi-hole servers for redundancy is great until you realize you’ve tripled your management overhead. Nebula Sync fixes this by letting you treat one Pi-hole as the source of truth and having the rest automatically mirror it.

If you’re tired of juggling multiple pihole/admin pages and trying to remember which server has the latest config, this setup changes everything. Start with two nodes, get comfortable with the workflow, then add more as you need them.

Next steps:

Experiment with sync schedules
Add a third replica
Explore virtual IP failover if you want true high availability

Once you’ve got this running, you won’t go back to manual Pi-hole updates.

If Pi-hole sync is a stepping stone into a bigger homelab and you want room for Proxmox, VMs, and serious networking, the MS-01 is a different class of machine.

MINISFORUM MS-01 Mini Optional upgrade.
Best for stepping up from Pi-hole into a Proxmox mini-lab with serious networking thanks to built-in 10GbE and 2.5GbE, but it’s unnecessary overkill if you’re only doing simple Pi-hole sync.

Amazon Price: Loading...

Availability: Checking...

Contains affiliate links. I may earn a commission at no cost to you.

Best Proxmox Backup Server Setup (2026): PBS Configuration

Mon, 01 Dec 2025 05:04:02 -0600

I deleted my entire photo library.

~40,000 photos. Years of memories. Gone in the time it takes to hit enter.

I was in the Proxmox shell, typing a command to delete an LXC I didn’t need anymore. I fat-fingered the ID. The wrong container vanished. My Immich server. The thing that held every family photo, every vacation, every moment my wife cared about preserving.

I knew what I did the instant I hit enter. That sick feeling in your stomach when you realize you wiped something that matters.

The photos themselves were fine. I had those backed up separately. But the albums? The organization? The metadata? The hundreds of hours my wife spent sorting and curating everything? That was gone.

It took several days of painstaking work to put it all back. Re-creating albums. Re-adding photos to albums. My wife’s reaction was, let’s say, worse than when the internet went down for a few hours.

That’s when I stopped telling myself I’d set up proper backups “eventually.”

I pulled an old DOGE mining rig from 2013 out of the closet, bought a cheap 2U case, and had Proxmox Backup Server running a few hours later.

Now when things break, I don’t worry about it. I restore the backup that’s always less than 24 hours old and move on.

💭

TL;DR: ZFS, RAID, and snapshots are not backups. A dedicated Proxmox Backup Server gives you image based backups of your VMs, LXCs, and configs on a separate box. That means you can break your Proxmox compute node, or even replace it, and bring everything back in minutes instead of days.

Seagate BarraCuda Internal Hard Drive 8TB Right now one of the best price per GB you can find. Also has a 2-year warranty.

Amazon Price: Loading...

Availability: Checking...

Contains affiliate links. I may earn a commission at no cost to you.

Everyone Talks About Backups. Almost Nobody Has Them.

You tell yourself the same thing everyone else does: “I have ZFS, I am fine.” “I have RAID, I am fine.” “I have snapshots, I am fine.”

Before I built my backup server, I lost data more than once. I broke VMs trying to optimize things. I had to rebuild LXCs from scratch because I thought I was careful enough to not need backups. Then I thought “I use Ansible playbooks and I can reconfigure services quickly”, but Ansible doesn’t restore your actual data.

My all-in-one server’s PSU died while I was at work. It took out the router, storage, and compute all at once. When it was fixed, two VMs wouldn’t boot. Likely corruption from the sudden power loss.

But I still didn’t build a backup server. Adding another box meant: More power draw. More complexity. More things to maintain and update.

Then I deleted Immich.

That was the line.

What Proxmox Backup Server Is

Proxmox Backup Server, or PBS, is not a fancy rsync script. It is a dedicated backup appliance for Proxmox.

It does image level backups of LXCs and VMs. That means it backs up the whole guest, not a handful of config files you hope you got right. When you restore, you’re putting the entire VM or container back exactly how it was.

Core PBS features you care about:

Deduplication PBS breaks data into chunks and reuses them across backups. Ten backups of the same VM do not use ten times the space.
Incremental backups The first backup is large. After that, PBS only stores the changes. That means daily backups are actually realistic.
Retention and pruning You can set rules like “keep 7 daily, 4 weekly, 6 monthly” and PBS will handle cleanup.
Verification PBS can verify that backups are readable. That is the part most people skip until it is too late.
Encryption, if you want it Helpful if the box is in a location you do not fully trust.

Short version. PBS is the ctrl-z for your Proxmox stack.

Why The Backup Node Needs Its Own Box

If you run PBS on the same hardware you are backing up, you are not doing backups. You are making local copies and hoping the box never dies.

Backups should live on different hardware. Period.

Here is why PBS needs to be a separate node and not a VM sharing hardware with everything else.

Hardware failure isolation If your compute node dies, you still have PBS. You can rebuild a fresh Proxmox host, reconnect it to PBS, and start restoring guests. If PBS lived on that same dead box, you would be staring at a pile of useless backups on disks you cannot even boot.

NAS failure isolation Same story for storage. If your NAS dies and PBS is another datastore living on that NAS, you lose both the source and the backups in one shot.

Security isolation If something nasty gets into your compute node or NAS, it should not be able to casually wipe your backups. PBS on its own box, with good firewall rules, is much harder to wipe.

Upgrade and experiment freedom You want to be able to reinstall Proxmox on the compute node without touching PBS. You want to be able to test new Proxmox versions, new kernels, new storage layouts. That is only safe if your backups live somewhere else.

One simple rule:

If the thing you are backing up and the backup live on the same physical box, you do not have a backup. You have a copy.

How I Finally Built This Thing

After the Immich incident, I was done making excuses.

I had an old DOGE mining rig from 2013 sitting in a closet. Yes, a DOGE mining rig. That hardware bought during the peak of meme cryptocurrency mania was about to become the most critical piece of infrastructure in my homelab.

Intel G1610 CPU. GIGABYTE GA-B75M-D3H motherboard. 16GB of RAM that’s probably worth more than the entire rig today (thanks, AI).

It never made me any money mining Dogecoin. But it was about to save my ass repeatedly.

I bought a cheap 2U Rosewill case and moved everything over. A few hours later, PBS was running.

I threw in a 128GB SSD for the PBS system and 2 4TB HDDs for backup storage. That was it. Total cost: ~$100 for the case. I had some old drives on hand for the OS and storage.

Now that ancient hardware backs up:

8 VMs
12 LXCs
Everything that matters in my homelab

Most guests get nightly backups. A few less critical ones get weekly backups. I keep 4 nightly backups, one monthly, then everything older gets auto pruned. And thanks to deduplication, I am only using 12% of the available storage.

If a CPU that once supported mining joke cryptocurrency can handle PBS for 20 guests, you do not need to overthink your hardware.

The first thing I did after getting PBS up and running was testing a restore. I picked my backup Pi-hole server since I run two and losing one wouldn’t matter. I backed it up. Then I deleted it on purpose.

Five minutes later it was back. Running. Working. Like nothing happened.

The relief I felt was immense. A weight I didn’t even realize I was carrying lifted off me. All those years of anxiety about breaking things. All those careful, tentative changes to production services. All that tiptoeing around my own infrastructure. Gone.

This actually worked.

I have restored several LXCs and VMs at least two dozen times since then. Testing migrations. Trying new features. Breaking things to see what happens. Every time it is five minutes to get back to working.

Don’t have a rack and don’t want one? A cheap mini tower works fine for a PBS box. Same parts inside, same job done.

Rosewill FBM-X2-400-HELIX Compact Micro ATX tower with a pre-installed 400 W PSU, room for multiple 2.5 and 3.5 inch drives, and enough airflow options for a tidy budget backup server build.

Amazon Price: Loading...

Availability: Checking...

Contains affiliate links. I may earn a commission at no cost to you.

How PBS Backs Up Proxmox Better Than Your Scripts

You can absolutely hack together backups with rsync, tar, and hope. You can write bash scripts that dump configs and copy directories.

PBS is better for one reason. It speaks Proxmox.

PBS uses datastores You create one or more datastores on the PBS box. These are directories on disks, usually large HDDs or SSDs. Proxmox guests get backed up into those datastores.

Backups are chunked and deduped PBS stores data in chunks. If several VMs or containers share the same data, PBS stores that data once and references it many times. This reduces space and makes incrementals light.

Backups are incremental First backup is full. After that, PBS only needs changed chunks. You can run nightly backups without filling disks in a week.

Backups are guest aware VM backups use snapshot mechanisms correctly. LXC backups include config and data in a consistent way. You are not racing writes like you might be with raw rsync.

Restores are simple From the Proxmox UI you can:

Restore a VM or LXC when you break it
Restore to a new ID so you can test first
Move a guest to a different node during restore (I use this a lot)

You don’t need to hunt down that random blog post you followed three months ago. You don’t need to remember which flags you used or how you configured the service. PBS gives you the entire machine, exactly as it was before you broke it.

What You Should Back Up With PBS

You probably don’t need to back up your entire lab with PBS. Back up the things that matter most.

Back up with PBS:

VMs that matter
- Docker stack VM
- Home Assistant or other important services
- Anything with a non-trivial config that would suck to rebuild
LXC containers that matter
- Reverse proxy
- DNS Servers
- Ansible and Playbooks
- Jellyfin / Plex
- Your media stack if you like LXCs

Things that PBS is not ideal for

Huge media libraries 40 TB of movies do not belong in PBS. That is what your NAS redundancy is for. Worst case, you redownload.
Cold archives for years You can keep long retention if you want to, but PBS is best for working backups of services, not glacier style storage.

💡

Tip: If it would take you hours to reconfigure by hand, put it in PBS. If you can redownload or recreate it easily, do not waste PBS space on it.

A Backup Strategy That Does Not Suck

You need something simple enough that you will keep it.

Here is what I run and it works well:

Schedules

Nightly backups for critical VMs and LXCs (Immich, Home Assistant, reverse proxy, databases)
Weekly backups for less critical stuff (test environments, secondary services)
Backup window when nobody is streaming

Retention

Keep 4 backups total
One monthly snapshot
Everything older gets pruned automatically

This gives me short term protection against bad updates and my own stupid mistakes without eating up too much storage.

Verification

Turn on verification jobs, so PBS periodically checks backups for corruption. It is not enough to have files. You need files that restore.

Lightweight 3 2 1 (Future Goal)

If you want to get fancy later:

3 copies of important data
- Running VM or LXC
- PBS backup
- Optional offsite copy of PBS datastore or config
2 types of media
- Internal PBS disk
- External USB drive or another storage box
1 offsite
- Could be a cloud bucket, a box at a friend’s house, whatever

Do not overthink this from day one. Get PBS on a separate box first. Get nightly backups running. Then start thinking about offsite copies.

Networking And Security For PBS

This box protects everything else. Don’t drop it on the same flat network as your kids’ tablets.

Keep it on a management VLAN

Put PBS on a subnet used for servers and admin stuff
Only Proxmox nodes and your admin machine should talk to it

Lock down firewall rules

Allow only Proxmox hosts and your admin box to connect on PBS ports
Block general LAN clients from hitting the PBS web UI directly
No random IoT gear or smart TVs talking to PBS

No direct internet exposure

Do not port forward PBS from your router
If you need remote access, go through VPN
- Tailscale, WireGuard, or a similar tunnel from your admin PC

PBS doesn’t need to be a fortress, but it does need to be harder to reach and harder to destroy than the machines it is backing up.

Hardware For A PBS Node

Good news. This box doesn’t need to be powerful. It only needs to be reliable and have enough disk.

Here is what I am running:

My PBS Build (2013 DOGE Mining Rig)

The hardware that failed to make me rich mining meme cryptocurrency in 2013 is now the backbone of my backup strategy.

CPU: Intel G1610 (a decade old dual core)
Motherboard: GIGABYTE GA-B75M-D3H
RAM: 16GB
System: 128GB SSD
Storage: 2 Mirrored 4TB HDDs
Case: 2U Rosewill
Backing up: 8 VMs and 12 LXCs
Current usage: 12% of 4TB after months of nightly/monthly backups

If this ancient hardware can handle 20 guests with daily backups, you definitely do not need to overthink it.

General Guidelines

4 to 16 GB of RAM is plenty for most homelabs
Small SSD for the PBS system (128GB works fine)
Big HDD or SSD for datastore (2-4TB is a good start)
CPU does not matter much, disk and network do

You probably have spare hardware sitting around that is more than capable.

Rosewill RSV-Z2800U This is the case I use for my PBS: It is a 2U rackmount server chassis that provides plenty of drive bays and solid airflow for a homelab or small server. It is a good pick if you want a sturdy case that can grow with your storage and hardware needs.

Amazon Price: Loading...

Availability: Checking...

Contains affiliate links. I may earn a commission at no cost to you.

What Happens When You Keep Ignoring Backups

Eventually you will break something.

Maybe it’s an update that doesn’t play nice (looking at you, Jellyfin). Maybe you type the wrong container ID in the terminal. A typo that destroys something important.

Without PBS:

Stare at the error
Dig through old blog posts to remember your setup
Reinstall services one by one
Fix permissions and rewire configs
Hours disappear

With PBS:

Open Proxmox
Click restore
Pick last night’s backup
Wait five minutes
Done

Last month I upgraded Jellyfin from 10.10.7 to 10.11. The database migration failed. Pre-PBS that would have been a full day to rebuild and rescan my media. With PBS it was a five minute restore.

Before PBS, I had anxiety about touching production services. I tiptoed around my own lab.

Now I experiment freely. I test upgrades without fear. I try new configurations to see what breaks. Worst case, I lose 24 hours of data and spend five minutes on a restore.

Simple Setup Flow

Here is the high level checklist. You do not need a full tutorial to get started.

Grab a spare box or mini PC (seriously, check your closet)
Install Proxmox Backup Server on it
Add a datastore on a big disk
On your Proxmox compute node, add PBS as a backup remote
Create backup jobs for the VMs and LXCs that matter
- Daily schedule for critical stuff
- Weekly for everything else
- Reasonable retention rules (start simple)
Run the first backup and watch it complete
Do a test restore into a new VM or LXC ID
Confirm the restored guest boots and works
Optionally: delete something on purpose to prove you can get it back

After that, backups go from “I should do something” to “this is part of how the stack runs”.

What’s Next

At this point you have four roles in your on prem cloud:

Router at the edge
NAS for storage
Compute for apps and services
Backup to save you from your own bad decisions

And this backup server? It is the one that lets you sleep at night.

Best Proxmox Server Hardware: Homelab Compute Guide

Sat, 22 Nov 2025 06:35:02 -0600

It was a Tuesday.

I was already at work when my phone rang. It was my wife: “Nothing is working this morning. No internet, no Jellyfin, nothing.”

I walked her through checking the server. No lights. No fan noise. She tried the power button. Nothing.

The PSU was dead. And with it? Everything. Router, storage, media server, home automation, my entire IT infrastructure in one box, dead.

I left work, drove to BestBuy, bought a new PSU, and spent the next hour getting everything back online. Four hours where my wife couldn’t work from home, couldn’t stream anything, couldn’t do basic internet tasks. Outage total: about four hours.

That’s when I committed to tearing it all apart.

This is Part 4 in our series, and today we’re covering the dedicated compute node. The server that runs all your applications while your router handles traffic and your NAS stores your files.

If you’re running everything on one machine right now? This is your warning shot.

💭

TL;DR: A dedicated Proxmox compute server allows you to rebuild entire Docker stacks, snapshot VMs before risky changes, and reboot for updates. All without taking down your internet or storage. On the other hand, one box means one failure takes everything down. Three boxes means isolation, stability, and the freedom to break things safely.

Why Your Homelab Needs a Dedicated Proxmox Compute Server

Running everything on one machine feels efficient. It feels smart. It is neither.

It’s complicated. And it’s fragile.

Here’s what actually happens when you cram routing, storage, and compute into a single Proxmox server:

One failure takes down everything.

One dead PSU. One bad kernel update. One stuck VM. Suddenly your internet is gone, your files are inaccessible, and your entire household is asking when things will work again.

Reboots become a crisis.

Need to apply Proxmox updates? Cool. Your router goes down. Your NAS goes offline. Every service you run disappears for ten minutes while you pray everything comes back in the right order.

Boot order becomes a nightmare.

I ran a virtualized NAS on my all-in-one Proxmox server for way too long. Proxmox wouldn’t reliably mount NFS shares before LXCs like Jellyfin tried to start. I tried systemd automounts, autofs, custom scripts, all of it. Nothing was reliable enough. Every boot was a gamble. Would Jellyfin find its media? Would the shares even mount? I’d spend ten minutes hand-holding the server back to life, restarting services manually until everything lined up.

One workload can kill everything else.

Kick off a Tdarr batch transcode job and watch your CPU pin at 100%. Now your router is struggling. DNS queries are timing out. Someone’s work VPN drops mid-call. All because you decided to transcode some files.

A full filesystem cascades.

One container fills your root partition with logs. Now your storage is broken too. Your apps won’t start. Your VMs won’t boot. And you’re stuck SSHing in to clean up the mess before anything works again.

What Separation Gives You

Splitting compute away from routing and storage fixes all of this before it becomes a crisis.

Fault isolation that holds.

A few weeks ago I completely rebuilt several LXCs and VMs on my compute box. I moved the entire Arr suite from separate LXC containers into one Docker VM. I rebuilt my Immich server from scratch. Nobody noticed. Not a single complaint. The only time my wife knew something was happening was when I asked her to let me know when her show was over so I could reboot the server. Four minutes later, Jellyfin was back and she kept watching.

That’s what separation gives you. The freedom to break things, test things, rebuild things, all without taking down the internet or losing access to your files.

Sane boot order.

Your NAS boots after the router. NFS and SMB shares are ready and waiting. Your router is already routing. Then your Proxmox compute node boots, mounts storage paths, and starts services in a predictable order. No more race conditions. No more “will it work this time” anxiety. Things come up clean.

Better performance across the board.

Transcoding, Sonarr indexing, torrent hashing, container updates, all of that lives on hardware designed to handle it. Your NAS focuses on serving files fast. Your router focuses on routing packets and running OPNsense. Everyone stays in their lane and does their job well.

This isn’t overkill.
This is building your homelab correctly. With purpose. So it works reliably every single time.

Intel NUC 12 Pro (NUC12WSHi5) Compact mini PC for lightweight Proxmox servers capable of GPU Passthrough, Several VMs, and LXCs.

Amazon Price: Loading...

Availability: Checking...

Contains affiliate links. I may earn a commission at no cost to you.

What the Proxmox Compute Node Does

The compute node is where your Homelab apps and services live.

This is the server where you run:

Media servers: Jellyfin, Plex, Emby
Media automation: Sonarr, Radarr, Prowlarr, Bazarr, Lidarr
Download clients: qBittorrent, SABnzbd, NZBGet
Media processing: Tdarr for transcoding and file cleanup
Reverse proxy: Nginx Proxy Manager or Traefik
Remote access: Tailscale, Cloudflare Tunnel, or WireGuard
Self-hosted services: Home Assistant, Immich, Audiobookshelf, Kavita, Nextcloud

The Proxmox compute server is responsible for:

Hosting all your containers, VMs, and LXCs
Handling heavy CPU loads like video transcoding, media analysis, and file processing
Mounting storage from your NAS over NFS or SMB without breaking when mounts are slow
Exposing services safely through your router and reverse proxy
Keeping everything isolated enough that when one app crashes, it doesn’t cascade

Think of it as the app layer in your home data center architecture. Router at the edge. NAS storage at the bottom. Compute in the middle doing the heavy lifting.

Why Proxmox VE Is the Right Hypervisor for Homelab Compute

You can absolutely run everything on bare metal Linux with Docker. You can force it.

You’ll also hate yourself when you want to move a service, pass through a GPU, snapshot before an upgrade, or deal with backups that don’t suck.

Proxmox VE solves most of those problems with one installation.

Why Proxmox works so well for homelab compute servers:

Web UI that doesn’t make you want to throw your keyboard
Native support for both LXC containers and full VMs
Easy snapshots and backups that actually save you when things break
Good integration with NFS, SMB, and iSCSI for mounting external NAS storage
Straightforward PCIe and GPU passthrough for hardware transcoding
Flexible enough to grow into Proxmox clusters later if you add more nodes

LXC vs VMs vs Docker in Proxmox

You have three layers to work with in Proxmox VE:

Workload	Best Fit	Why
Lightweight Linux services	LXC	Low overhead, fast boot, easy resource limits
Full OS instances	VM	When you need complete isolation or non-Linux guests
App-level deployment	Docker	Huge ecosystem, easy configs, stacks and compose

Here’s a sane Proxmox layout pattern that actually works in production:

Proxmox VE at the base layer
A few LXC containers for core infrastructure services (reverse proxy, monitoring)
One or more VMs running Docker for your application stacks

Why use VMs for Docker instead of LXCs?

Proxmox themselves advise against running Docker inside LXC containers. Running containers inside containers gets weird fast. You’ll hit issues with nested namespaces, cgroup limitations, and storage drivers. A VM gives you clean kernel isolation and full control without the headaches.

My current Proxmox compute server setup as an example:

I’m running an Intel i5-12600K with 64 GB of RAM, a 6-disk RAID-Z2 array for protected VM and LXC storage, and a 2 TB NVMe drive for Proxmox itself plus workloads that need fast, unprotected storage.

On top of that:

Jellyfin - Runs in an LXC so I can pass through Intel QuickSync for hardware transcoding without losing the ability to share the iGPU with other containers or the Proxmox host
Docker VM for the Arr suite - Sonarr, Radarr, Prowlarr, all in one VM managed with Docker Compose
Docker VM for automation tools - n8n, Node-RED, OpenWebUI, and Home Assistant
Nginx Proxy Manager LXC - Reverse proxy handling all external access
Individual service LXCs - Audiobookshelf, Ansible, Hugo - Each doing one job, cleanly isolated

I don’t share media outside my house because cable upload speeds are trash, but inside the house I’ve never hit issues with up to three simultaneous 4K streams.

And now? I can rebuild or test elements of it without anyone noticing. This is the point of separating compute from the router and storage.

Storage Access in Proxmox Without the Pain

This is where a lot of homelab builders get burned.

Your Proxmox compute node should not be where your media lives. It should be where your media is accessed and used.

Here’s the right way to handle storage:

Media and files live on your dedicated NAS server
NAS exports storage via NFS or SMB shares
Proxmox compute box mounts those shares and passes them into LXCs and VMs

My NAS is bare metal Debian 13 with a MergerFS pool, connected to the compute box over 10 GbE. It serves both NFS and SMB shares depending on what needs them.

The Storage Migration Process

When I finally pulled storage off the all-in-one, the process was straightforward but took some planning:

Step 1: Build the new NAS first. I installed Debian 13, MergerFS, NFS, and SMB.
Step 2: Physically move the Hard Drives and HBA. Pulled the HBA and 7 drives out of the all-in-one host and moved them to the new dedicated hardware.
Step 3: Configure MergerFS, NFS, and SMB. Configured the MergerFS storage pool. Configured NFS and SMB shares.
Step 4: Verify everything. I left the old storage VM off but in place for a week. In case anything went sideways. Once I was confident, I removed it and I haven’t looked back since.

Rules to Save You From Storage Headaches

Use consistent mount points across everything.
Pick a path structure and stick to it:

/media/storage/movies
/media/storage/shows
/media/storage/music

Mount these into your Proxmox LXCs and VMs so the paths inside match exactly. Life is dramatically easier when Jellyfin, the Arr suite, and SABnzbd all agree on where /movies, /shows, and /music live.

Keep transcode and temp work on local SSD.

Let Jellyfin and Tdarr use local NVMe or SSD paths for transcoding cache and analysis. Don’t hammer your NAS with endless small writes if you don’t have to. Your NAS will thank you, and your transcodes will be faster.

Mount read-only where you can.

For plain media directories that rarely change, mount them read-only to services that only need to read. A misbehaving app can’t delete your entire movie library if it doesn’t have write access.

Network Configuration for Proxmox and NAS

Your Proxmox compute node and NAS should be on the same network for best performance. Use static IP addresses for both so your mounts don’t break if DHCP leases change.

For 1 GbE networks: This works fine for most home users. You’ll get roughly 100-115 MB/s transfer speeds, which handles multiple 1080p streams and light 4K transcoding without issues.

For 2.5 GbE networks: The sweet spot for cost vs performance in 2025. You’ll get 250-280 MB/s, plenty for heavy 4K streaming and multiple simultaneous transcodes.

For 10 GbE networks: Overkill for most, but if you’re running lots of VMs, doing heavy transcoding, or have multiple users, the 1000+ MB/s speeds make everything feel instant.

Seagate BarraCuda Internal Hard Drive 8TB
Right now one of the best price per GB you can find. Also has a 2-year warranty.

Amazon Price: Loading...

Availability: Checking...

Contains affiliate links. I may earn a commission at no cost to you.

Best Proxmox Compute Server Hardware for 2025

You don’t need a screaming 1U datacenter monster for a good Proxmox homelab. You need the right balance of CPU cores, RAM, and storage.

Here’s what that looks like.

Budget Proxmox Compute Server Build

Specs:

4-core CPU with VT-x/AMD-V support
8-16 GB RAM (minimum 8 GB)
250-500 GB SSD for Proxmox and VMs
1 GbE or 2.5 GbE NIC

Good for:

1080p media streaming with Jellyfin or Plex
2-3 simultaneous users
A handful of Docker containers in one VM
Light home automation and a few LXCs

Why 16GB of RAM?

Proxmox itself needs about 2 GB minimum. Each VM or heavy LXC will want 2-4 GB depending on workload. With 8 GB total, you can run Proxmox plus 2-3 lightweight VMs or several LXCs comfortably. Bump to 16 GB if you want headroom.

Hardware examples:

Used Dell OptiPlex 7050 SFF, HP EliteDesk 800 G3, Lenovo ThinkCentre Tiny M720q, or any decent mini PC with an Intel chip that has Quick Sync. Add an SSD, maybe bump the RAM if it’s cheap, install Proxmox VE, and you’re running.

This tier works if your needs are simple and you’re getting started with Proxmox homelabs.

Dell Wyse 5070 Extended (J5005)
This is the budget-friendly, low-power Proxmox box that works out of the box. Add an Intel i350-T2, give it 8–16 GB of RAM, and you’ve got a quiet, reliable home router with room for several LXCs and VMs.
Price: $80 - $170

Ebay

Contains affiliate links. I may earn a commission at no cost to you.

Balanced Proxmox Compute Server Build (Recommended)

Specs:

6-8 cores (modern Intel i5/i7)
16-32 GB RAM (32 GB strongly recommended)
500 GB - 1 TB NVMe SSD for fast VM storage
Intel iGPU (for Quick Sync hardware transcoding)
2.5 GbE NIC preferred

Good for:

1080p and 4K transcoding with hardware acceleration
Multiple simultaneous users and media streams
Running several VMs alongside multiple LXCs
Full Arr stack in Docker plus Jellyfin, Home Assistant, and more

Why this is the sweet spot for most Proxmox homelabs:

This is where I landed. My i5-12600K build with 64 GB of RAM and local RAID-Z2 storage for VM protection handles everything I throw at it. Jellyfin transcodes 4K HEVC smoothly with QuickSync. The Arr suite runs in Docker without breaking a sweat. I can snapshot VMs, rebuild entire stacks, test new configs and nobody in the house notices unless I tell them.

Why 32 GB RAM instead of 16 GB?

Here’s the reality: Proxmox itself uses 2 GB. Each Docker VM will want 4-8 GB depending on how many containers you’re running. Jellyfin in an LXC will use 2-4 GB during transcodes. If you’re running ZFS on your local storage (like my RAID-Z2), ZFS will want to use up to 50% of available RAM for its ARC cache.

With 16 GB total, you’ll constantly be swap-constrained and performance will suffer. With 32 GB, you have room to grow and VMs aren’t fighting each other for memory. With 64 GB like I have, you can run almost anything without thinking twice.

CPU considerations:

Modern Intel CPUs (12th gen and newer) are ideal. Intel has an edge here if you care about hardware transcoding because Quick Sync support in Jellyfin and Plex is excellent and dramatically reduces CPU load.

If you’re running lots of containers or VMs, prioritize core count. Each VM you run will want 2-4 dedicated cores for good performance. Try not to over-provision. If you assign more vCPUs to VMs than you have physical cores, Proxmox will time-share and everything slows down.

This tier is perfect if you’re serious about a Proxmox homelab media setup that works reliably.

MINISFORUM MS-01 Mini Workstation
The MS-01 i5 is a tiny mini PC with plenty of cores, multiple NVMe slots, and real homelab networking (dual 10G SFP+ plus 2.5 GbE), which makes it perfect for a Proxmox compute node. It has enough power for Jellyfin, the *arr stack, downloads, and a few VMs or LXCs, without being a space heater.

Amazon Price: Loading...

Availability: Checking...

Contains affiliate links. I may earn a commission at no cost to you.

High-End Proxmox Compute Server Build

Specs:

8+ cores with high clock speeds (Intel i7/i9)
64-128 GB RAM
Large NVMe (1-2 TB) for VMs and fast workloads
Dedicated GPU for transcoding or compute tasks (optional)
10 GbE NIC if your NAS can keep up

Good for:

Heavy 4K HEVC transcoding workloads
Multiple simultaneous remote transcode streams
Running many VMs and test environments in Proxmox clusters
Extra workloads like game servers, AI/LLM tools, or development environments

When this tier makes sense:

If you’re running significantly more than media services, if you’re sharing your Proxmox setup with people outside your house, or if you’re experimenting heavily with nested virtualization and want room to grow without limits.

For a simple household Proxmox homelab? This is overkill. But if you have the use cases and the power budget, it’s very nice to have all that headroom.

Recommended Proxmox Layout for Your Compute Node

You don’t need anything complicated to start with Proxmox VE.

Here’s a clean layout that works for most homelab setups:

Infrastructure LXC:

Nginx Proxy Manager or Traefik for reverse proxy
Tailscale, WireGuard, or Cloudflare Tunnel for secure remote access
This container stays up when everything else is being rebuilt

Primary Docker VM:

Ubuntu or Debian VM running Docker and Docker Compose
Your entire media stack: Arr suite, download clients, media automation
Easy to snapshot before major changes

Optional Secondary Docker VM:

Separate VM for experimental or unrelated Docker workloads
Automation tools like n8n, Home Assistant if you want it containerized
Keeps your core media stack isolated from other projects

Individual Service LXCs:

Jellyfin or Plex (LXC for GPU passthrough flexibility)
Audiobookshelf, Immich, or other single-purpose services
Utility containers for scripts, monitoring, or tools you’re testing

💡

Tip: Group related services together in VMs, but don’t cram everything into one container. Keep it modular enough that you can blow up your Docker VM and rebuild it from scratch without taking out your reverse proxy, remote access, or other critical infrastructure. This gives you enough isolation to experiment safely in Proxmox without overcomplicating your setup.

Real World Benefits of a Dedicated Proxmox Compute Server

Once you split compute away from routing and storage, a lot of things stop being crises.

You can reboot Proxmox without taking down the house.

Need to apply Proxmox kernel updates? Need to test a hardware change? Go ahead. Your router stays up. Your NAS stays accessible. Jellyfin goes down for a few minutes and comes back. No one freaks out.

You can rebuild services without fear.

Snapshot your Docker VM before making changes. Try a new Jellyfin major version. Completely rebuild your Arr stack with different Docker Compose configs. If it breaks, roll back the Proxmox snapshot in 30 seconds. If it works, keep it and delete the old snapshot. Your NAS and router don’t care either way.

You can stress test during off hours without affecting critical services.

Want to run Tdarr overnight and transcode your entire 4K library? Go for it. Let the CPU pin at 100% all night. Your router isn’t competing for cycles. Your NAS isn’t getting hammered by transcode temp files.

Your family notices the difference, in a good way.

I used to hear “the internet is down AGAIN” all the time. Now? Things work. My wife doesn’t think about the server anymore. It’s invisible. That’s exactly the goal.

And since splitting things up, I’ve even been able to share my Jellyfin server with one friend outside my house. Not because my upload speeds got better (they’re still trash) but because the system is stable enough that I trust it to work consistently without me babysitting it.

The Real Risks of Running Everything on One Proxmox Box

If you keep routing, storage, and compute all on one Proxmox server, here’s what you’re signing up for:

Hardware failures cascade completely.

PSU dies like mine did? Motherboard failure? Bad RAM stick? Your entire digital life disappears. Internet, storage, every app, every VM. All gone until you fix or replace hardware.

Software issues spread everywhere.

Kernel panic during a Proxmox upgrade? One VM consuming all available RAM? A filled root partition from runaway Docker logs? Now routing is broken, storage is inaccessible, and all your apps are down.

Maintenance becomes high-risk.

Want to add more RAM? Swap a drive? Update BIOS? Better hope it goes smoothly, because if something goes wrong during maintenance, everything is offline until you recover.

Boot order is a constant gamble.

Will the NAS VM start before other services try to mount shares? Will everything come up in the right sequence? Or will you spend 15 minutes manually restarting services until things work?

No room for safe experimentation.

Want to test a major Proxmox upgrade? Try a different hypervisor kernel? Experiment with GPU passthrough? Better be confident, because if it breaks, you’re taking down the router and storage too.

This isn’t “maybe someday.” I lived it. The PSU failure was my wake-up call, but the constant virtualized NAS mount issues and boot order anxiety were already wearing me down.

How to Start: Your Roadmap to Separating Compute

If you’re running everything on one box right now and this all sounds overwhelming, here’s the actual migration path:

Step 1: Plan and budget for dedicated NAS storage first.

That’s what I moved first, and it was absolutely the right call. Storage was causing me the most pain with the virtualized NAS and mount issues. Getting that onto dedicated hardware immediately made everything more stable.

Figure out your NAS platform (TrueNAS, Unraid, or bare metal Linux with ZFS/MergerFS). Budget for drives, an HBA if you need one, and a box to house it all. You don’t need to buy enterprise-grade equipment, consumer hardware works fine for homelab use.

Step 2: Build the NAS and migrate storage.

Set up your NAS with ZFS or your chosen filesystem. Configure NFS and SMB shares. Test everything thoroughly. Then move your drives over.

Keep your current NAS VM off but available to restore if you need to. Once everything is migrated and verified, you can delete your old VM (I kept mine for a week or so).

Step 3: Move your router when budget allows.

This takes a bit more planning and usually some dedicated hardware budget. But once storage is separate, your next priority is getting routing off the all-in-one. A dedicated pfSense or OPNsense box, or even a good prosumer router if you don’t need advanced firewall features.

Step 4: What’s left is your dedicated compute node.

Once routing and storage are separated, what remains is your Proxmox compute server. You might want to add more RAM or upgrade storage for better VM performance, but the foundation is already there. Keep running VMs and containers on dedicated compute hardware.

You don’t have to do this overnight. Each step makes the next one safer. Each separation reduces the blast radius when something goes wrong.

What I Wish I Knew Before Starting

If I could go back and tell myself one thing before beginning this Proxmox homelab journey, it would be this:

Learn how Proxmox handles storage pools and ZFS arrays before you provision anything.

I wasted hours trying to figure out Proxmox storage configuration, mount points, and how Proxmox integrates with external NFS shares because I didn’t understand the basics up front. Thirty minutes of reading the official Proxmox documentation would have saved me multiple evenings of trial and error.

If you’re building local RAID-Z2 or hardware RAID storage in your compute box, understand how Proxmox will use it before you create storage pools and start deploying VMs.

Don’t cheap out on CPU and RAM for your intended workload.

Buy hardware appropriate for the workloads you plan to run. If you know you’ll be transcoding 4K, running multiple Docker stacks, and hosting several VMs, don’t try to save $100 by buying inadequate hardware. You’ll end up buying better hardware later anyway, and you’ll have wasted time being frustrated by poor performance.

Under-provisioning RAM is especially painful. If you don’t have enough RAM, Proxmox will swap to disk constantly and everything slows to a crawl. Same thing happens if you over-provision CPU cores across too many VMs. Time-sharing kills performance.

Build it right the first time.

Frequently Asked Questions About Proxmox Compute Servers

➤ How much RAM do I need for a Proxmox compute server?

Minimum 8 GB for basic setups, but 16-32 GB is recommended for most homelab use cases. Proxmox itself needs about 2 GB. Each VM wants 2-8 GB depending on workload. If you’re using ZFS for local VM storage, ZFS will consume up to 50% of available RAM for caching. With 32 GB total, you have comfortable headroom for several VMs, LXCs, and ZFS caching without hitting swap.

➤ Can I run Docker directly in Proxmox LXC containers?

Technically yes, but Proxmox and the community advise against it. Running Docker inside LXC containers creates nested containerization which leads to issues with namespaces, cgroups, and storage drivers. The recommended approach is running Docker inside a dedicated VM (Ubuntu or Debian), which gives you full kernel control and avoids compatibility headaches.

➤ What's the difference between LXC and VMs in Proxmox?

LXC containers share the host kernel and are extremely lightweight. They boot in seconds and use minimal overhead. VMs run their own complete operating system with full isolation. Use LXCs for Linux services where you want efficiency (like Nginx Proxy Manager). Use VMs when you need complete isolation, want to run Windows, or need full kernel control for things like Docker.

➤ Do I need a dedicated GPU for Jellyfin transcoding in Proxmox?

Not necessarily. Modern Intel CPUs (8th gen and newer) have excellent Quick Sync support built into the iGPU, which handles hardware transcoding very well. You can pass the iGPU through to a Jellyfin LXC or VM for hardware acceleration. A dedicated GPU only makes sense if you’re transcoding many simultaneous 4K streams or running other GPU workloads like AI inference.

➤ Can I use consumer SSDs for Proxmox VM storage?

Yes, for homelab using consumer NVMe or SSDs is fine. Enterprise drives with Power-Loss Protection are better for production environments, but for home servers where the stakes are lower, good consumer SSDs like Samsung 970/980 EVO or Crucial P3/P5 will serve you well. Make sure you have backups. Consumer SSDs can fail more often, and when they do, they fail catastrophically.

➤ Should I run my router as a VM in Proxmox?

For homelab experimentation, yes. For production use where your household depends on internet access, no. If your Proxmox host crashes or needs maintenance, a virtualized router means your entire house loses internet. A dedicated router or firewall appliance running pfSense/OPNsense gives you the isolation you need so compute and routing failures don’t cascade.

➤ What's better for Proxmox storage: hardware RAID or ZFS?

For VM storage on the Proxmox compute node, ZFS is generally preferred. ZFS gives you built-in snapshots, compression, and data integrity checking. Hardware RAID can be faster in some cases but lacks ZFS features. Important: ZFS and hardware RAID controllers don’t mix. If you want ZFS, you need direct disk access (HBA mode or no RAID controller). For NAS storage, either approach works depending on your preference.

What’s Next in the Proxmox Homelab Series

You have the router running pfSense or OPNsense. You have the NAS providing reliable storage. Now you have the dedicated Proxmox compute server running your applications.

There’s one more critical piece to add: the Proxmox Backup Server.

Next up is Part 5, where we cover building a Proxmox Backup Server that can actually save you when things go sideways. Because they will. And when your compute node crashes or you accidentally delete the wrong VM, you’ll be very glad you have working backups.

Until then: separate your compute. Your future self will thank you.

Best NAS for Media Servers (2026): Dedicated Storage Guide

Mon, 10 Nov 2025 07:30:02 -0600

Power came back after an outage. My Proxmox host boots up. The VM that runs my NAS starts… slowly. My Jellyfin container mounts /mnt/media before the NFS share is ready. The mount succeeds but points to an empty directory. My library: “No items found.”

I fixed it in 10 minutes. But I’d already done this dance multiple times a week for eight months. I hated having to manually mount the drives every time the server boots.

The problem wasn’t the hardware. It wasn’t the software. It was the architecture: I was running my storage as a VM on my compute host. Every reboot was a roll of the dice for timing and mount order.

So, I pulled the HBA and drives out of my Proxmox host and moved them to a dedicated bare metal Debian box running MergerFS with 93TB of drives and SMB and NFS shares.

That was six months ago. I’ve rebooted my compute host 30+ times since then. Zero mount failures, race conditions, or extended debugging sessions late at night. My media is served up when I need it.

If your media library matters, give it its own box. I go over how I built mine and why, and why you should dedicate a box to it as well.

If you are trying to figure out the best NAS setup for a home media server, here is the short version: stop running your storage in a VM and give it its own bare metal box that exists only to keep your files safe and available when you want them.

💭

TL;DR: Running storage in a VM or LXC is like playing with fire. You think you’re being efficient. You’re actually creating race conditions, mount failures, and late night debugging sessions when you could be enjoying your media with friends and/or family. Separate storage to bare metal. It boots quickly, serves reliably, and stops holding your media hostage.

Quick picks: best NAS options for media servers (2025)

If you came here looking for the “tell me what home NAS to buy” version, here’s the short list.

1. DIY bare metal NAS for homelab nerds

You want control, flexibility, and better hardware for the money.

OS: Debian or another solid Linux base, with MergerFS for pooling and NFS or SMB exports
Use case: Jellyfin or Plex library, backups, maybe a bit of general file storage
Why it is the best fit:
- You are not locked into a vendor GUI
- You can pick quiet, low power parts instead of whatever the NAS vendor felt like shipping
- Easy to grow storage with bigger drives later rather than buying a whole new box

This is the setup I use and for me, it is the best NAS for a home media server. The Proxmox host talks to it over the network, and the NAS does one job and does it well.

2. Synology NAS for people who want easy mode

You want something that works out of the box, and you don’t want to learn MergerFS.

Example: 4 to 8 bay Synology DiskStation for media and backup
Use case: You want a simple web UI, snapshots, built in apps, and clean integration with Windows and macOS
Why it is a good fit:
- Synology handles RAID, drive health alerts, and shares for you
- Great if you want to spend more money on hardware and less time learning Linux
- Perfect for “I run Jellyfin on another box, this thing only holds the files”

You give up some flexibility and pay a premium compared to DIY, but you get a nice, polished experience.

Synology 4-Bay DiskStation DS925+ (Diskless)
Is a 4-bay NAS running DSM with an easy setup, dual 2.5 GbE, M.2 NVMe slots for cache, ECC-capable RAM up to 32 GB, expansion to 9 bays, and roughly 500+ MB/s for multi-user streaming. Pick it over a DIY build if you want simple and reliable, since DSM gives you polished wizards, built-in backup and media apps, and hardware that works out of the box.

Amazon Price: Loading...

Availability: Checking...

Contains affiliate links. I may earn a commission at no cost to you.

3. Used server or small business box if you like deals

You are comfortable with louder gear and you want lots of bays for cheap.

Examples: Used Dell, HP, or Lenovo small servers or business desktops with extra SATA added
Use case: Big media libraries, lots of drives, budget conscious builds
Why it can make sense:
- Older enterprise gear is cheap and still very capable
- Easy to stuff with drives and treat it as a dedicated storage tank
- Run Debian or your favorite NAS OS and treat it like the DIY option above

You do have to watch power draw and noise. Great for a basement rack, not so great for a studio apartment.

No matter which path you pick, the rule is the same:
Your media server should talk to a dedicated NAS box over the network, not share a boot drive with Proxmox and six LXCs that all panic if a mount is late.

Storage In VMs: Because You “CAN” Doesn’t Mean You Should

Here’s the short version. Running your NAS in a Proxmox VM is a bad idea. Running it in an LXC is even worse.

Reddit will tell you: “It’s more efficient!” or “One box does everything, and it is amazing!”

I’m here to tell you they are wrong and what you’ve built is a house of cards where storage, the foundation of your entire media stack depends on:

A hypervisor booting correctly
VM startup order being predictable
Mounts being added and mounted to the Proxmox host correctly (My biggest issue)
Network initialization happening before mount attempts
No Proxmox updates changing any of the above

You’re not being efficient. You’re optimizing for a $200 hardware savings while trading it for hours of maintenance, failed mounts, and streams that don’t work when you want them to.

I know because I did this for six months. I spent roughly 3 hours every week debugging mount failures, tweaking systemd scripts, adjusting delays, and reading Proxmox forums instead of watching anything. That’s 78 hours over six months (Almost two full work weeks fighting an architecture that was fundamentally wrong).

The worst part? Each failure was only a 10-15 minute fix. But they happened constantly. Reboot the host? Roll the dice. Proxmox update? Hope your mounts still work. Add a new container? Maybe it boots before the NAS is ready, maybe it doesn’t.

💡

Tip: The root issue is that your media server runs in a VM on the same Proxmox host that’s trying to mount its shares. During boot, Proxmox processes /etc/fstab and can’t mount the shares because the VM hasn’t even started. Mounting shares later isn’t as straightforward as it sounds. Any workarounds you apply afterward only treat the symptoms without addressing the root cause. I exhausted every solution I could find across Google, Reddit, and the Proxmox forums. Some provided marginal improvements, but none fully resolved the problem.

The Real Cost

Let me break down what this “efficient” setup cost me:

78+ hours of debugging over six months
Multiple service outages where Jellyfin showed “Library Empty” because mounts succeeded but pointed to empty directories
Constant user complaints about streams dying or libraries disappearing
Mental overhead of “will this reboot break everything?”

What did I gain by running storage in a VM? Absolutely nothing. I saved a small amount of money on power, not enough to make up for my time. That’s it.

The Time My Storage Failed Me (And Why I Finally Fixed It)

Here is what finally convinced me to do this right.

The Reboot Lottery

Power outage, kernel update, Proxmox update, stuck containers can all cause the need to reboot the Proxmox host. When the host is rebooted… Proxmox comes back up. NAS VM starts… but something’s off. The VM boots, the drives mount inside the VM, but Proxmox’s automount fails to see the NFS share. Jellyfin LXC mounts /mnt/media to an empty local directory. Users see “Library Empty.”

I SSH in, manually remount, restart containers. Fixed in 10 minutes.

But this wasn’t a one-time thing. This happened a few times a week with different variations:

Sometimes the VM booted too slowly
Sometimes Proxmox tried to mount before the NFS server was actually serving
Sometimes it worked perfectly
Sometimes my custom delay scripts helped, sometimes they didn’t

I tried:

Systemd mount delays (worked sometimes)
Custom scripts that pinged the NAS before mounting (race conditions remained)
Automount with longer timeouts (helped but didn’t fix it)
Tweaking VM boot order and priority (marginal improvement)

Nothing worked reliably. The configuration wasn’t the problem. The architecture was.

That’s when I realized: this is insane. I’m spending hours maintaining mount orchestration on a system that should “work without babysitting.” The storage shouldn’t be a VM. It shouldn’t depend on a hypervisor. It should boot first and serve files. Period.

The VM Race Condition From Hell (What’s Happening)

Here’s what was happening in my Proxmox host every reboot:

Proxmox boots
VMs start launching - based on boot order/priority settings
My NAS VM begins booting - this takes time: OS boot, network init, NFS server start
LXC containers start
Containers try to mount /mnt/media via NFS from the Proxmox host (Bind mounts)
Three possible outcomes:
- ✅ NAS is ready → mount succeeds → everything works
- ❌ NAS isn’t ready → mount fails → services break
- ⚠️ Mount succeeds but NFS isn’t serving yet → mount points to empty directory → “Library Empty”

That third one is the nastiest because everything LOOKS like it worked. The mount command succeeded. The directory exists. But there’s no data because the NFS server inside the VM hasn’t finished starting yet.

Why This Is Fundamentally Broken

The hypervisor doesn’t know or care about your application dependencies. Proxmox sees:

NAS VM (priority: normal)
App containers (priority: normal)
Network is up
Start everything

It doesn’t understand that your Jellyfin container NEEDS the NAS to be fully operational before it can function. You can try to encode this with systemd dependencies, boot delays, ping scripts, and health checks but, you’re still fighting the architecture.

The solution isn’t better orchestration. It’s removing the orchestration entirely.

LXCs Are Even Worse (Seriously, Don’t)

I never tried running my NAS in an LXC. But I’ve seen people attempt it on Reddit and Proxmox forums, and it’s a nightmare every single time.

Why people try it:

“LXCs are lighter than VMs!”
“I don’t need full VM overhead for a file server!”
“I can bind-mount drives directly!”

Why it fails spectacularly:

No Real Hardware Access

LXCs share the host kernel. You can pass through devices, but you’re not getting true hardware access like bare metal. Running ZFS in an LXC? You’re trusting the container layer to not screw up your file systems. Running SMART monitoring? Good luck with device passthrough being consistent.

The Same Mount Race Conditions, But Worse

The LXC has to start, the storage daemon has to initialize, the NFS/SMB server has to start, and THEN other containers can mount. You’ve recreated the VM problem with less isolation and more ways for it to break.

What Happens

Search r/Proxmox for “LXC NFS” or “LXC storage” and you’ll find a number of posts like this:

“My LXC can’t see the drives after reboot”
“Permissions are broken after Proxmox update”
“SMART data isn’t available in the container”

The pattern is always the same: someone tries to be clever, runs storage in an LXC to “save resources,” and ends up with a fragile, unreliable mess.

Don’t do it.

Why Dedicated Bare Metal Is The Only Sane Option

When I moved my storage to bare metal Debian, here’s what changed:

Predictable Boot Order (Finally)

It boots, drives spin up, XFS filesystems mount, MergerFS pools them, NFS server starts. All of this happens BEFORE my Proxmox host even starts booting.

By the time Proxmox comes online and containers try to mount /mnt/media, the NAS has already been serving files and waiting. Zero race conditions, timing dependencies, or failed mounts.

No More Orchestration Hell

I deleted:

Custom systemd mount units with delays
Ping-before-mount scripts
VM boot order priorities
Health check containers
All the “clever” solutions I built to work around a broken architecture

The NAS boots. It serves files. Proxmox mounts them. That’s it. No orchestration needed.

Fault Isolation

When I need to rebuild my Proxmox host or test new versions, my storage stays online. It keeps serving files to the containers that are still running. When I need to add drives or run maintenance on the NAS, I take it offline briefly, but my compute layer isn’t impacted. I do reboot the compute node after NAS maintenance to confirm everything reconnects cleanly.

Before, everything was tangled together. Proxmox down = storage down. Storage issues = compute issues. It was all one fragile system. I made it even worse because at the time my router was also in a VM on the same Proxmox host. So, every reboot also took down my internet too. Don’t be like me.

Zero Maintenance

In eight months since the migration:

Proxmox reboots: 30+
NAS mount failures: 0
Hours spent debugging storage: 0
Streams interrupted by storage issues: 0

The NAS works. I literally forget it exists until I need to add more drives.

What I Gave Up

Nothing. Absolutely nothing.

I added one more box to my rack (an old desktop PC I already owned). That’s it. No performance penalty. No feature loss. No additional complexity. Actually, LESS complexity because I removed all the mount orchestration.

Adding a low power CPU to run the NAS had a minimal impact to the power bill (About 40-60W).

Seagate BarraCuda Internal Hard Drive 8TB
Right now one of the best price per GB you can find. Also has a 2-year warranty.

Amazon Price: Loading...

Availability: Checking...

Contains affiliate links. I may earn a commission at no cost to you.

“But My NAS VM Works Fine” (For Now)

If you’re reading this thinking “my NAS VM is stable, this doesn’t apply to me,” let me ask:

Have you rebooted your Proxmox host this month? Did everything come back up cleanly?
Have you updated Proxmox recently? Did your mounts still work after?
Do you have multiple containers depending on storage? Do they all mount reliably?
Have you tested what happens during a power failure and cold boot?
Can you reboot your compute layer without taking storage offline?

If you answered “yes” to all of these, congratulations! You’ve either gotten extremely lucky or you’ve spent dozens of hours building complex orchestration to paper over the architectural problems.

But here’s the thing: it works until it doesn’t.

You’re not running a reliable system. You’re running a system that hasn’t failed YET. And when it does fail during a family movie night, you’ll wish you’d built it right from the start.

The Real Question

What are you gaining by running storage in a VM?

Saving one hardware box? (An old desktop PC costs $50-200 used)
“Efficiency”? (You’re trading hardware efficiency for operational chaos)
Easier management? (Is debugging mount failures “easier” than running a separate box you never touch?)

Be honest: you’re not optimizing for reliability or simplicity. You’re optimizing for… what, exactly?

The Architecture Comparison

Let me show you what I ran vs what I run now.

WRONG: What I Built First

Proxmox Host (one physical box)
├── NAS VM (OMV)
│ ├── Boots at ??? (depends on VM priority)
│ ├── Needs: OS boot → network init → storage mount → NFS/SMB start
│ └── Serves: NFS/SMB shares back to Proxmox host
│
├── Jellyfin LXC
│ ├── Boots at ??? (fast, because LXC)
│ ├── Tries to mount: /mnt/media (from Proxmox host bind mount)
│ └── Result: ⚠️ Maybe works, maybe empty directory, maybe fails
│
├── Sonarr LXC
│ ├── Boots at ???
│ ├── Tries to mount: /mnt/media (from Proxmox host bind mount)
│ └── Result: ⚠️ Maybe works, maybe empty directory, maybe fails

Problems:

Boot order is non-deterministic (depends on VM/LXC startup speed)
NAS VM has multiple initialization steps before it’s ready to serve
Containers mount before checking if NFS is serving
Reboots are a lottery
Proxmox updates can change everything (rare, but still a thing)

RIGHT: What I Run Now

NAS Box (dedicated bare metal Debian)
├── Hardware: Intel G3220, 16GB RAM, LSI HBA, 10GbE NIC
├── Software: Debian Trixie, XFS per drive, MergerFS pooling
├── Boot: Second. After the dedicated Router
└── Serves: NFS shares to network (always available)
↓ (2.5GbE Network)
Proxmox Host (separate physical box)
├── Boot: Third (after NAS is already serving)
├── Mounts: /mnt/media via NFS from NAS box (always succeeds)
│
├── Jellyfin LXC → bind mounts /mnt/media → ✅ always works
└── Sonarr LXC → bind mounts /mnt/media → ✅ always works

Benefits:

Boot order is deterministic (NAS second, always)
No dependencies between storage and compute layers
Reboots are predictable
Proxmox updates don’t affect storage
Fault isolation (one system failing doesn’t take down the other)

Network Details

Connected via SODOLA 8-Port 2.5Gb managed switch:

NAS: 10GbE NIC (downlinks at 2.5Gb to switch)
Proxmox: 2.5GbE NIC
Throughput: ~280 MB/s sustained (vs ~110 MB/s on 1GbE)
Multiple simultaneous 4K streams + NZB downloads + backups = no congestion

How I Migrated

Here’s exactly how I moved from “NAS VM on Proxmox” to “NAS on bare metal.”

What I Started With

Proxmox host with LSI HBA in IT mode
8x drives passed through to OMV VM
Containers mounting via NFS from Proxmox host (bind mounts)
Constant race condition issues

What I Did

1. Built the new NAS box first

Old desktop: Intel G3220, Gigabyte GA-Z87X-D3H motherboard, 16GB DDR3
Installed Debian Trixie
Added 10GbE NIC (Intel X520-DA1, $30 used on eBay)
Configured it on the network with a static IP

2. Tested NFS serving (before moving drives)

Set up NFS exports on the new Debian box
Verified Proxmox could mount from it
Made sure permissions and paths matched my existing setup

3. Scheduled downtime (Friday night)

Shut down all containers/VMs on Proxmox
Shut down the NAS VM
Shut down the Proxmox host

4. Moved the hardware

Pulled the LSI HBA from Proxmox host
Moved all 8 drives
Installed HBA and drives in the new NAS box
Connected power, network

5. Brought up storage

Booted the NAS box
Drives appeared as /dev/sda through /dev/sdh
Mounted each drive: mount /dev/sdX /mnt/diskX
Configured MergerFS to pool them: /mnt/disk* /mnt/media
Set up NFS exports pointing to /mnt/media
Updated /etc/fstab so everything mounts on boot

6. Brought Proxmox back online

Booted Proxmox
Updated /etc/fstab to point to the new NAS IP instead of VM mount
Verified NFS mounts succeeded
Started containers one by one
Checked Jellyfin library, verified all media was accessible

Total downtime: ~2 hours (most of it was physical drive transplant and cable management)

LSI 9300-8i HBA Controller
LSI SAS3008 9300-8i HBA Controller is a high-performance disk controller suitable for media server data storage needs. With a transfer rate of up to 12Gbps, this unit provides reliable and fast data storage solutions. Price: $30 - $40

Ebay

Contains affiliate links. I may earn a commission at no cost to you.

What I Learned

Test the new setup before you commit. I verified NFS serving worked before I moved drives.
Expect the first boot to take longer. XFS file system checks took a few minutes per drive.
Plan for worst case. I kept the Proxmox host ready to take the HBA back if something went catastrophically wrong (it didn’t).

What Your NAS Needs To Do

Redundancy

At minimum: ability to survive drive failure without data loss.

I’ll be honest: I ran without parity for two years. Why? Because 95% of my data was movies and TV shows I could redownload. Then I started adding family videos and photos - stuff I can’t get back. That’s when I decided to add SnapRAID for parity (I’m adding this next month if HDD prices come down).

Use any scheme you’re comfortable with: parity, mirrors, or redundancy only for the critical bits. Know what you’re protecting and what you’re willing to lose.

Protocols That Work

NFS for your virtualization or Linux services
SMB/CIFS for Windows/macOS clients
SFTP for remote access or backup jobs

Your NAS needs to plug into your compute and network layers without drama. My setup serves NFS to Proxmox hosts and SMB to Windows machines for manual file management. No fuss.

Smart Mounting Strategy

This is where most people screw up:

Stick to consistent paths: /mnt/media/movies, /mnt/media/shows not /media1, /media2, /random-drive-name
Enable automount so on reboot everything comes up in order (systemd handles this well on Debian)
Keep temp, transcode, and download directories separate from your main pool to avoid runaway writes destroying your media drives
Use SMART monitoring and actually test restore workflows. You’ll thank yourself later

I run smartctl -a /dev/sdX monthly on each drive. One drive showed reallocated sectors climbing. Replaced it before it died.

Software Choices: What I’ve Used and What Works

Here’s what I’ve tested and what I run.

NAS OS	Strengths	Weaknesses	My Take
TrueNAS	Strong ZFS support, snapshot capabilities, enterprise features	Needs more RAM/hardware, steeper learning curve, overkill for media	Great if you need ZFS. I don’t.
Unraid	Flexible drives, less hardware-intensive, nice GUI	License cost ($59-$129), lower performance on some tasks	Popular for good reason, but I’m cheap and wanted full control
OpenMediaVault	Lightweight, easy to set up, web GUI	May lack advanced features, felt restrictive to me	Where I started in a VM, outgrew it fast
Debian + MergerFS	Lightweight, total control, exactly what you need	No GUI (you use SSH and config files), learning curve	This is what I run. Took a weekend to learn, now it’s bulletproof.

I originally tried OpenMediaVault in a VM. It worked, but every time I wanted to do something slightly custom, I fought with the GUI or the update system. Moved to straight Debian with MergerFS and NFS/SMB servers. No GUI. Config files and systemd. Steeper learning curve? Yes. But now I understand exactly how everything works and nothing is hidden behind abstraction layers. When something breaks (rare), I know where to look.

💡

Tip: Whatever you choose, run it on bare metal. Avoid running it in a VM or LXC. You will thank yourself later.

ZFS vs MergerFS - What’s Best For a Media Server?

Cut the fluff. You don’t always need ZFS for a media-server-only setup.

ZFS: Enterprise Grade Redundancy

RAID-Z/RAID-Z2, checksums, snapshots, send/receive. Requires serious RAM (1GB per TB is the common recommendation) and prefers ECC memory.

I almost started with ZFS because that’s what the internet said to use. Researched ECC RAM, planned my vdev layout, read the entire FreeBSD handbook section on ZFS. Felt very enterprise. It also had an enterprise price tag.

Then I realized: if a drive dies, I can re-download everything in a weekend. Why am I treating Bob’s Burgers S04 like a production database?

When ZFS is worth it:

You’re running VMs, databases, things that can’t be redownloaded
You can afford to buy 6 or more identical drives in one purchase (I couldn’t justify this).
You have irreplaceable data (family photos, business files)
You want snapshots and send/receive for backups

For me? 80% of my data was re-downloadable movies and shows. ZFS was overkill. I make backups of the irreplaceable files and keep them in three locations (Local, External HDD, and Cloud).

MergerFS: Flexible, Media Friendly

MergerFS pools drives into /mnt/media regardless of size.

Why it works for media:

Add drives without rebuilding (I started with 3 drives, now at 8)
Any size, any speed, different brands, no “matched set” needed
If a drive dies, you lose only what was on that drive, not the whole pool
Reads are fast, writes go to whichever drive has space (configurable policies)
Works on bare metal Debian with zero virtualization overhead

The catch: No real-time parity. If a drive dies, that data is gone unless you have backups or add parity separately (see SnapRAID below).

Feature	ZFS	MergerFS
Real-time parity	✅ Yes	❌ Not built-in
Flexible drive sizes	❌ No (same-size vdevs)	✅ Yes
File-level recovery	❌ Generally no	✅ Straightforward
Hardware overhead	High (RAM, ECC preferred)	Low (runs on anything)
VM-friendly	⚠️ Possible but problematic	✅ But run it on bare metal anyway
Ideal for media	Overkill	Perfect fit

Verdict:

If your NAS is mostly media you can re-download - go MergerFS
If your NAS hosts business-critical or irreplaceable data - go ZFS

MergerFS + SnapRAID: The Best of Both Worlds

MergerFS gives me flexible pooling. But what about redundancy?

Enter SnapRAID: parity for files that don’t change often (perfect for media).

How it works:

I dedicate 1 drive as a parity drive (the largest drive)
SnapRAID calculates parity across the pool on-demand (I’ll run it nightly via cron)
If a drive dies, I can rebuild from parity
Unlike RAID, parity is calculated when YOU tell it to, not in real-time
If TWO drives die before I sync parity… yeah, I lose some files. But that’s the trade-off for flexibility

I’m adding this to my setup next month because I finally have data I can’t easily redownload (family videos, photos). For movies and TV? I didn’t bother for two years. The cost/benefit wasn’t there.

Why this works on bare metal: SnapRAID needs direct drive access for parity calculation. Running it in a VM means the hypervisor sits between your file system and the drives, adding latency, complexity, and potential corruption. On bare metal? No layers in the way.

Hardware Recommendations

It’s gear time. Because yes, you can buy this now. And yes, you can target budget or beast mode depending on how deep your wallet is.

Tier	Specs	Use Case	What I’d Buy Today
Budget	2-4 bays, low-power CPU, basic RAM	Cold storage, archives	Old desktop with 2-4 SATA ports. Intel Pentium or i3, 8GB RAM. Purpose: hold files, serve NFS. Cost: $50-100 used.
Balanced	4-8 bays, decent CPU, 16GB RAM	Streaming + moderate load	Close to my setup. Rosewill Helium NAS case ($90), Intel G3220 or newer i3 ($50 used), 16GB RAM, LSI HBA in IT mode ($50 used), 8x drives. Quiet, expandable, fits under a desk. Total: ~$300 + drives.
Beast	8+ bays, modern i5/i7, 10GbE NICs	Multi-user, 4K/8K, heavy lift	Rosewill Helium NAS or bigger case, i5-12400 or better, 32GB RAM, 10GbE NIC, quality PSU. Overkill for most, perfect if you’re streaming to 5+ users simultaneously. Cost: $600-800 + drives.
Simple	Synology 4-8 bay NAS	Want it to work, don’t want to DIY	DS920+, DS1522+, or whatever’s current. You pay more, but it works out of the box. No shame in this. Cost: $400-800 + drives.

Rosewill Helium NAS ATX Mid-Tower Case
The Rosewill Helium NAS ATX mid-tower is a budget-friendly case built with storage in mind. It fits a standard ATX motherboard, has space for 10 3.5" hard drives as well as room for HBAs or SATA expanders. For a DIY NAS this case lots of room for growth without paying server-chassis prices.

Amazon Price: Loading...

Availability: Checking...

Contains affiliate links. I may earn a commission at no cost to you.

Critical hardware note: Whatever you buy, it needs:

Direct SATA connections (no USB)
Enough RAM for your OS + file system cache (8GB minimum, 16GB better)
Quality power supply (drives are expensive, don’t cheap out on PSU)
Network connectivity that matches your needs (2.5GbE or 10GbE if you have heavy traffic)

Not sure how many TB you need? The media storage calculator turns your movie and episode counts into a drive-buying number, with growth headroom built in.

Size your library

Network: The Bottleneck Nobody Talks About

1GbE = 125 MB/s theoretical, ~110 MB/s real-world.

That’s fine for one 4K stream (40 Mbps) or even 20 simultaneous 1080p streams. Sounds like plenty, right?

Except you’re also:

Downloading a new TV Series
Running backups to your PBS box (Part 5 of this series)
Scanning new media into Jellyfin
Maybe transcoding if someone’s on a slow client

Now you’re maxing out that 1GbE link. Streams buffer. Your spouse asks if the internet is broken. You check your bandwidth graphs and realize: it’s not the ISP, it’s your internal network.

What I Did

Added a $30 Intel X520-DA1 10GbE NIC to my NAS box (used on eBay) and a $60 SODOLA 8-Port 2.5Gb managed switch.

Amazon Price: Loading...

Availability: Checking...

Contains affiliate links. I may earn a commission at no cost to you.

Result:

NAS has 10GbE NIC (downlinks at 2.5Gb to the switch)
Proxmox has 2.5GbE NIC
Sustained throughput: ~280 MB/s (vs ~110 MB/s on 1GbE)
Multiple 4K streams + torrents + backups = no congestion

Streams never buffer. Backups run 2.5x faster. Torrents don’t fight with Jellyfin for bandwidth.

If you’re building from scratch: Buy a motherboard with 2.5GbE built in. The Intel i226-V chipset is solid and adds $0 to motherboard cost these days. Many boards in the $100-150 range include it standard.

When to consider 10GbE:

5+ simultaneous users streaming 4K
Heavy backup workloads (multiple TB per day)
You transcode on a separate box and move large files constantly
You’re a data hoarder moving TBs between systems regularly

For most home setups? 2.5GbE is the sweet spot. Cheap, no special cables needed (works on Cat5e), massive improvement over 1GbE.

Intel X520-DA1 10GbE NIC
This 10Gtek network card is designed for use with Intel X520-DA1 routers and features a maximum data rate of 10 Gbps. With one SFP+ port and PCIe x8 interface, this card provides high-speed connectivity for your network. Price: $30 - $40

Ebay

Contains affiliate links. I may earn a commission at no cost to you.

My network setup:

NAS: Intel X520-DA1 10GbE NIC with DAC cable to switch
Switch: SODOLA 8-Port 2.5Gb managed switch
Proxmox: Onboard 2.5GbE
Clients: Mix of 1GbE and 2.5GbE

Total cost: ~$90 for the upgrade. Best $90 I’ve spent on this build.

Storage Layouts That Make Sense

Turning hardware into a predictable, reliable stack.

Directory Structure

Use clear, consistent paths:

/mnt/media/
├── movies/
├── shows/
├── music/
└── books/

Not /media1/stuff, /driveB/movies, /bob-likes-anime/. Keep it simple. Keep it consistent.

Why this matters: when you’re debugging a mount that came up empty (you won’t be, because bare metal doesn’t have race conditions, but hypothetically), you want obvious paths. When you’re setting up a new container, you want to know exactly where /mnt/media/movies lives.

Separate Temp and Archive

This is critical and most people get it wrong.

Transcode, temp, and download directories: Put these on SSDs or a separate spindle pool that you don’t care about. You do NOT want qBittorrent hammering your archive drives with random writes while incomplete downloads get moved around.
Finished media: Goes to the archive pool (the big slow drives via MergerFS). This is read-mostly workload. Movies get added once, read many times, rarely deleted.

My setup:

NAS Box:
├── 500GB SSD: Debian 13, NFS, SMB, MergerFS and Snapraid (that's it don't over complicate it).
└── 93TB MergerFS pool (Mix of 3, 6, 14, and 24TB Drives): Static Storage only.

Any Docker containers, downloads, or Jellyfin transcodes are on the compute node with fast redundant data storage.

SABnzbd downloads to compute node’s fast storage. When a download completes, Sonarr/Radarr move it to /mnt/media/tv or /mnt/media/movies on the MergerFS pool. The compute node’s storage absorbs all the random write punishment. The spinning drives handle sequential writes when media is added and sequential reads when streaming.

Mount Strategy

Mount read-only where possible for older content (reduces risk of accidental deletion). My Jellyfin server can only read the media files on the NAS.
Set up rsync or backups to your backup box (Part 5 of this series) so you’re not relying on storage redundancy for your important files.
Run SMART monitoring: smartctl -a /dev/sdX monthly, check for reallocated sectors, pending sectors, or UDMA CRC errors
Schedule pool scrubs if using SnapRAID (I’ll run snapraid sync nightly, snapraid scrub weekly once I set it up)
Test restores: Seriously. Shut down, pull a drive, boot, verify you know how to identify which drive failed and how MergerFS handles it. Learn how recovery works BEFORE a drive fails on you.

When your storage setup is done well - you forget it’s there. When it fails - you will be ready.

My Actual MergerFS Config

For reference, here’s what I run on bare metal Debian:

Drive mounts in /etc/fstab:

/dev/disk/by-id/wwn-0x5000c500b531bbcc-part1 /mnt/Pool/Disk1 xfs defaults 0 0
/dev/disk/by-id/wwn-0x5000c500e4505355-part1 /mnt/Pool/Disk2 xfs defaults 0 0
/dev/disk/by-id/wwn-0x5000c500e50b9986-part1 /mnt/Pool/Disk3 xfs defaults 0 0
/dev/disk/by-id/wwn-0x5000c500e82476d9-part1 /mnt/Pool/Disk4 xfs defaults 0 0
/dev/disk/by-id/wwn-0x5000cca295caac7a-part1 /mnt/Pool/Disk5 xfs defaults 0 0
/dev/disk/by-id/wwn-0x5000cca2a1dcb6af-part1 /mnt/Pool/Disk6 xfs defaults 0 0
/dev/disk/by-id/wwn-0x50014ee20d104997-part1 /mnt/Pool/Disk7 xfs defaults 0 0

MergerFS pool:

/mnt/Pool/Disk* /media/Storage fuse.mergerfs direct_io,defaults,allow_other,dropcacheonclose=true,inodecalc=path-hash,category.create=mfs,minfreespace=50G,fsname=storage 0 0

NFS exports in /etc/exports:

/media/Storage/ 192.168.1.0/24(all_squash,anongid=1001,anonuid=1000,insecure,rw,subtree_check,fsid=0)

That’s it. No GUI. No abstraction layers. Linux doing what Linux does best: serving files reliably.

Common Mistakes (That I Made So You Don’t Have To)

Running storage as a VM on your compute host:
- Race conditions, mount order chaos, reboots that break everything. This was my life for six months. Don’t do it.
Running storage in an LXC:
- Even worse than a VM. Filesystem passthrough nightmares, permission issues, SMART monitoring doesn’t work right. Don’t.
Using USB externals without redundancy:
- One disconnect = data loss. If the data matters, it needs to be on real SATA connected to a real motherboard.
Mixing different drive sizes in a ZFS pool:
- Kills performance, wastes capacity. ZFS wants matched vdevs. (MergerFS doesn’t care. One of many reasons I prefer it for media.)
Ignoring ECC RAM when building ZFS:
- Silent bit flips can corrupt your “perfect” checksummed pool. If you go ZFS, get ECC. Or run MergerFS and skip the RAM requirements.
Never testing restores:
- You don’t have a backup until you’ve tested the restore. Same goes for RAID/parity rebuilds. Pull a drive while the system is OFF (don’t hot-swap unless you know what you’re doing) and verify you can identify and recover from the failure.
Trusting your setup without monitoring:
- Run SMART checks monthly. Watch your logs. Drives give warnings before they die, if you’re paying attention.
Thinking “I’ll add redundancy later”:
- Later never comes. If the data matters NOW, protect it NOW. I’m guilty of this (took me 2 years to decide on SnapRAID), but at least I knew what I was risking.

The Only Time Storage In A VM Makes Sense

Let me be fair: is there ANY scenario where running storage in a VM is acceptable?

Maybe - MAYBE - if:

You’re running TrueNAS as a VM with direct PCI passthrough of an HBA
It’s THE ONLY VM on a dedicated Proxmox host (no competing VMs/LXCs)
You’ve pinned the VM to specific CPU cores, so it always has resources
You’ve configured Proxmox to boot the storage VM first with significant delays before anything else starts
You’ve tested cold boot scenarios extensively

But even then: what are you gaining? You’ve added a hypervisor layer between your storage and your compute. You’ve introduced complexity, potential for race conditions, and dependency on Proxmox functioning correctly.

The question isn’t “can you make it work?” The question is “why bother?”

My answer: There is no good reason. The “one box does everything” dream is exactly that, a dream. You’re trading $50-100 of old hardware for hours of maintenance and fragility you don’t need.

If you want to run TrueNAS or OpenMediaVault, run them on bare metal. If you want Debian + MergerFS, run it on bare metal. Give storage its own box and let it do its job without interference.

What You Should Do Right Now

If you’re currently running storage in a VM or LXC:

Option 1: Build A New NAS Box (Recommended)

Get cheap hardware: Old desktop, $50-100 on Craigslist/eBay, needs 4+ SATA ports
Install Debian (or your preferred NAS OS, on bare metal)
Set up NFS/SMB shares while your VM is still running
Copy data from VM to new box (rsync, verify with diff/checksums)
Test thoroughly (mount from Proxmox, verify Jellyfin sees everything)
Cut over: Update Proxmox mounts to point to new NAS IP
Shut down the VM forever

Downtime: ~2 hours for final cutover. Peace of mind: priceless.

Option 2: Repurpose Your Proxmox Host

If you only have one box:

Back up your containers/VMs (you should be doing this anyway)
Wipe Proxmox
Install Debian as NAS on the bare metal
Buy a second box for Proxmox (can be cheaper since it’s compute only)
Rebuild your compute stack on the new Proxmox host
Mount from the NAS

Yes, this requires buying hardware. But you’re separating concerns the right way. Storage on one box, compute on another. This is how it should be.

Option 3: Stay In VM Hell

Continue debugging mount failures, systemd dependencies, and race conditions. Spend 3 hours every few weeks troubleshooting why reboots break everything. Wonder why your spouse hates your “hobby.”

I don’t recommend this option.

Final Thoughts

I run 93TB of media on bare metal Debian with MergerFS. Eight drives of different sizes, XFS file systems, pooled with MergerFS. No parity yet (adding SnapRAID next month). 2.5GbE network via 10GbE NIC to SODOLA switch. NFS shares to Proxmox. SMB shares to Windows clients.

Hardware:

Intel G3220 (old, low-power, sufficient)
Gigabyte GA-Z87X-D3H motherboard
16GB DDR3 RAM
LSI HBA in IT mode (direct drive access, no RAID controller nonsense)
Intel X520-DA1 10GbE NIC
Rosewill Helium NAS case (holds 10 drives, quiet, fits under a desk)

The box boots in 90 seconds. Serves files to two Proxmox hosts and a dozen containers. I haven’t touched it in months except to check SMART data.

Total cost: ~$2,000 over three years (includes drives, case, and network gear).

I haven’t had a mount failure in six months. I reboot my compute nodes whenever I want. Proxmox updates don’t scare me. Power outages resolve themselves. My storage… works.

If your media library matters, and if you’re reading this, it does - give it its own box. Separate storage from compute. Pick an OS (I chose Debian + MergerFS, you might prefer OpenMediaVault or Unraid). Learn it. Build it right. Run it on bare metal.

You’ll thank yourself the next time the power comes back and everything comes back online in the right order. Or better yet, you’ll sleep through it because there’s nothing to debug.

Stop running storage in VMs. Stop fighting race conditions. Stop spending weekends debugging mount failures.

Build it right. Run it on bare metal. Forget it exists.

Best Homelab Router: OPNsense Setup & Hardware Picks

Thu, 30 Oct 2025 07:25:02 -0600

Consumer routers try to be everything: modem, router, switch, Wi-Fi, DNS, sometimes even a media server. When any piece fails, everything fails. The Wi-Fi radios cook themselves. Firmware updates brick the UI. NAT tables fill and kill your connections. Meanwhile, vulnerabilities sit unpatched for months.

I learned this the hard way.

My journey to a proper router started with a failed consumer device. Then it evolved into “I can add a dual port NIC to the server and run my router in a VM”. It started brilliantly, but it quickly turned into a twice-weekly nightmare.

💭

TL;DR: Your ISP router can’t do VLANs, logging, or real security. A proper router box ($150-$800) running OPNsense gives you network segmentation, intrusion detection, full traffic visibility, and actual control. I’ve run this setup for 8+ years across multiple hardware generations. Setup time: one weekend to get working, 2-3 weekends to get truly secure.

The All-in-One Trap

I was running my entire homelab on a single Proxmox server: NAS, media server, download clients, home automation, everything. And because I was already virtualizing everything else, why not the router too?

It seemed elegant. One box, total control, efficient resource usage.

Then reality hit.

“Why is the internet out again?”

It was a Tuesday night. My wife was trying to stream something. I was in my office, staring at an LXC container that refused to stop, forcing me to reboot the entire Proxmox host. Again.

“Sorry, it should be back on in a few minutes. I had to reboot the server again.”

This happened once or twice a week. Sometimes it was NFS issues that wouldn’t resolve without a full reboot. Sometimes hardware failures. Sometimes I was testing something and broke it in unexpected ways. Each time, the entire house lost internet.

Five minutes of downtime doesn’t sound like much. But when it happens regularly, it stops being “a brief inconvenience” and starts being “why do we have internet problems all the time?”

The breaking point came when a power supply died on a Friday morning. The internet was down for four hours while I left work to drive to Best Buy for a replacement part. Not ideal when your wife works from home and needs reliable connectivity.

Before That: The Consumer Router Carousel

But let’s back up. Before I virtualized my router, I was doing what everyone does: buying consumer all-in-one routers and hoping they’d last.

For about 15 years, I cycled through them. Linksys. Netgear Nighthawks. ASUS routers. It didn’t matter which brand. They all developed issues after 2-3 years. Random reboots. WAN ports that stopped working. WiFi that became progressively more unreliable until it wasn’t reliable at all.

Toward the end of each router’s life, I’d be rebooting it daily to keep things working.

The pattern was always the same:

Buy new router ($120-300)
Works great for 18 months
Starts having “quirks”
Quirks become daily problems
Replace and repeat

Over 15 years, I probably spent $1,500+ on routers that became e-waste. And that’s not counting the time spent troubleshooting, rebooting, and dealing with random failures.

The Solution: Separation

The answer was obvious in hindsight: stop trying to make one device do everything.

I started with an old computer running OPNsense. It wasn’t pretty, it wasn’t efficient, but it worked. More importantly, it kept working when I rebooted my Proxmox host.

I ran that setup for about six years. The old computer hummed along, doing its one job well, all while I learned what a proper router could do.

About two years ago, I upgraded to a Protectli Vault Pro VP2420 for better power efficiency and added a “managed” switch (SODOLA 8-Port 2.5Gb). The principle remained the same, only more refined.

Give each job a proper box:

Router: Dedicated hardware running OPNsense
Storage: Separate NAS that stays up 24/7
Compute: Proxmox host for everything else

I’ll never forget the first time I rebooted my compute node after the separation. I hit the command, waited for the host to go down, and then… nothing happened. The internet stayed up. My wife kept streaming. Nobody called my name.

It was amazing.

What Changed When I Switched

Before (Consumer/Virtualized Router):

Visibility: I could see connected devices and some basic stats. That’s it.

Security: A checkbox labeled “firewall enabled.” No logs, no alerts, no real control. When I checked my Jellyfin logs one day, I discovered someone in Romania had been hammering my server, trying to brute force the default username. My old router never told me this was happening.

Performance: 4K streaming while SABnzbd maxed out my download connection meant random buffering and frustrated family members.

Segmentation: Everything on one network. My Jellyfin server could see my IoT lightbulbs. My download containers could access my NAS directly. Zero isolation.

Uptime: Hostage to whatever I was doing on my Proxmox host. Every experiment, every update, every hardware issue meant the whole house went offline.

After (Dedicated OPNsense Box):

Visibility: Every connection, every blocked attempt, every DNS query. I see exactly what my network is doing.

Security: Five VLANs with explicit allow rules. IDS/IPS running Suricata with Emerging Threats rules. I see attempted port scans and exploit attempts weekly that my old setup never noticed. That Romanian brute force attempt? Now I’d see it in real-time and could block the entire country if needed. (All other countries are now blocked from everything I’m running)

Performance: QoS rules mean Jellyfin never stutters, even when SABnzbd maxes out the connection. Downloads automatically throttle when someone starts streaming. No manual intervention needed.

Segmentation:

10.0.1.x: Trusted devices (laptop, phone)
10.0.2.x: Media stack (Jellyfin, Sonarr, Radarr)
10.0.3.x: IoT devices (cameras, lights)
10.0.4.x: Guest WiFi (isolated)
10.0.5.x: Management interfaces

My IoT devices literally cannot see my NAS. The firewall says “Hell no”.

Uptime: Router runs independently. I can reboot, upgrade, or completely rebuild my compute node without anyone noticing.

The difference is night and day. I went from hoping my network was secure to knowing it is. I went from apologizing for internet outages to working on my servers whenever I need to.

Why Your Current Router is Failing You

What “Advanced Security” Means

Consumer router claims: “Advanced Security Features!” Reality: Scanning for obvious malware from 2015. Maybe.

Real security means IDS/IPS with updated rulesets, traffic analysis, and actual logging. Your $120 router isn’t doing that.

I didn’t realize how blind I was until I enabled Suricata on OPNsense. Every week I see:

Port scans from random IPs
Exploit attempts targeting common vulnerabilities
IoT devices calling home to suspicious destinations
Brute force attempts on exposed services

My consumer router saw none of this. It was all happening, every day, and I had no idea.

The Single Point of Failure Problem

Your consumer router tries to be:

Router + Firewall + WiFi + Switch + DHCP + DNS + VPN + USB file server

When any piece fails, everything fails. When you need to reboot, everything goes down.

A proper network has separate components:

Router box: Routing, firewall, DHCP, DNS
Switch: Distributes connections, handles VLANs
Access points: WiFi only

When the AP reboots, your wired devices keep working. When you’re tinkering with your Proxmox host, your family doesn’t notice.

This isn’t theoretical. After eight years of running separated infrastructure, I’ve had zero network-wide outages that weren’t ISP-related. With consumer routers, I had them weekly.

What You’re Exposing

Without proper segmentation:

IoT device gets compromised → Attacker accesses your entire network With VLANs: They’re trapped in the IoT sandbox

Download client compromised → Direct path to all your files With VLANs: Container can only talk to specific services

Smart device has vulnerability → Entry point to everything With VLANs: Isolated and contained

Real example: I tried to tighten security rules on my IoT VLAN once. Made them too restrictive and all my devices lost internet access. No problem. I restored my OPNsense backup from 15 minutes earlier and everything was fine. Try doing that with a consumer router.

The Features That Matter

1. VLAN Support (Network Segmentation)

Create multiple isolated networks on the same hardware. If one thing gets compromised, it can’t spread.

Real example: My media stack runs in VLAN 2 (10.0.2.x). Firewall rules allow internet access for downloading and trusted device access for streaming. Everything else is denied. If a container gets compromised, the damage is contained to that VLAN.

I thought about my VLAN structure for a long time before implementing it. Two years later, I wouldn’t change anything about how it’s set up.

2. Intrusion Detection/Prevention (IDS/IPS)

Your router inspects every packet for known attacks, malware, and suspicious behavior.

I didn’t enable Suricata from day one. I added it after getting comfortable with the basics. The learning curve was real. Lots of forum posts and Reddit threads to understand what I was seeing. But it wasn’t too bad, and now it runs automatically.

What I see every week:

Blocked port scans from random IPs
Exploit attempts targeting known vulnerabilities
Malware callbacks from IoT devices
Geographic attacks I can block at the firewall level

My old consumer router saw none of this. It was all happening, I didn’t know about it.

3. Real Firewall Rules + Full Logging

Define exactly what’s allowed. See every decision the firewall makes.

My media VLAN rules:

Allow: Internet access (ports 80, 443)
Allow: Internal service communication
Allow: Trusted devices → media services
Allow: NAS access (NFS)
Deny: Everything else (log it)

When something breaks, I check the logs and see exactly what’s being denied. No guessing. No mystery reboots. Only clear information about what happened and why.

4. Local DNS + DHCP Control

Static IPs for all services. Custom DNS entries. Full control.

Instead of remembering 10.0.2.15:8096, I go to jellyfin.home. All my services have friendly names. Static DHCP means each device always gets the same IP every time. This is critical for firewall rules that actually work.

5. Traffic Shaping + QoS

Prioritize certain traffic. Set bandwidth limits per device.

I didn’t set this up immediately. I added QoS after SABnzbd kept maxing out my 150Mbps download connection and causing buffering on Jellyfin streams.

My current setup (tailored to my needs):

Priority 1: Streaming (Jellyfin, Plex)
Priority 2: YouTube and video
Priority 3: Gaming
Priority 4: Web browsing
Priority 5: Bulk downloads (capped at 80% of available bandwidth)

Now downloads automatically throttle when someone starts streaming. No buffering, no complaints, no manual intervention.

Router Hardware Options

Note on recommendations: I’ve personally used all the hardware in the Budget and Balanced builds over the years. The Beast build represents what I’d upgrade to if I had the time and budget. It is based on research and community feedback, not hands-on experience.

Budget Build (~$200 Total)

Router Box: $80-170

Used off-lease SFF computers are the best value for starting out. I ran OPNsense on an old desktop computer for six years before upgrading.

Dell Wyse 5070 Extended (J5005) This is the budget-friendly, low-power OPNsense box that works out of the box. Add an Intel i350-T2, give it 8–16 GB of RAM, and you’ve got a quiet, reliable home router with room for VLANs, WireGuard, and moderate IDS. Price: $80 - $170 Personal note: This is comparable to what I started with. Old hardware running OPNsense for years without issues.

Ebay

Contains affiliate links. I may earn a commission at no cost to you.

Network Card: $30-50

Used Intel NICs are reliable and well-supported in OPNsense and PFsense.

Intel i350-T2 The low-profile Intel i350-T2 drops right into the Wyse 5070 Extended’s PCIe slot and gives you two rock-solid 1 GbE ports with mature FreeBSD drivers, perfect for OPNsense. Price: $30 - $50

Ebay

Contains affiliate links. I may earn a commission at no cost to you.

Switch: $60-90

You need a managed switch to handle VLANs properly.

TP-Link TL-SG116E Is a 16-port, fanless Gigabit “Easy Smart” switch with a metal shell, web GUI, and essentials like 802.1Q VLANs, trunks, and QoS. It’s a great budget match for an OPNsense router build: quiet, low-power, cheap, and gives you the VLAN segmentation and uplink tagging you need without paying managed-switch tax. Personal note: I used this class of switch for years before upgrading to 2.5GbE.

Amazon Price: Loading...

Availability: Checking...

Contains affiliate links. I may earn a commission at no cost to you.

Dedicated Wireless Access Point (WAP): $60-80

Having a dedicated WAP can really improve the Wi-Fi signal in your house. You can place it in the optimal location with only an ethernet cable.

TP-Link EAP225 Is a ceiling-mount, PoE-powered, dual-band 802.11ac with a Gigabit uplink, and simple Omada controller management. It honors 802.1Q VLANs for clean SSID-to-network mapping (Main/IoT/Guest), and delivers fast, reliable Wi-Fi.

Amazon Price: Loading...

Availability: Checking...

Contains affiliate links. I may earn a commission at no cost to you.

What this setup can handle:

Gigabit routing with IDS/IPS
5-6 VLANs
Up to 50 devices
Basic VPN

Who this is for: 95% of home users with gigabit internet or slower.

Balanced Build (~$500 Total)

This is what I currently run. After six years on budget hardware, I upgraded to this configuration two years ago for better power efficiency and multi-gig speeds.

Router Box: $320-500

Protectli Vault Pro VP2420-4 Port is a fanless mini-appliance with a 4-core Intel J6412, 4× 2.5GbE Intel i225 ports, and AES-NI. It’s a strong mid-tier OPNsense base that stays quiet and sips power while handling gigabit-plus routing, as well as fast VPN access.

Personal note: This is exactly what I’m running. Two years in, zero hardware issues. It’s silent, efficient, and handles everything I throw at it. It has since been discontinued, so there’s no buy link for it any more. Anything fanless with four 2.5GbE Intel NICs and AES-NI lands in the same place.

Switch: $90

TP-Link Omada ES210X-M2 8-Port 2.5GbE Switch Provides eight 2.5GbE ports and two 10G SFP+ uplinks in a quiet fanless metal chassis, with an Easy Managed web UI covering 802.1Q VLANs, IGMP snooping, and auto loop prevention. It fits a mid-tier router build by unlocking multi-gig LAN speeds for NAS and desktops while keeping segmentation clean and power draw low. Personal note: The switch I actually installed here was the SODOLA 8-Port, added when I upgraded to the Protectli. It’s since been discontinued, so the Omada above is the equivalent I’d buy today. VLANs were straightforward to set up on the SODOLA, and the move to 2.5GbE made a real difference for NAS transfers.

Amazon Price: Loading...

Availability: Checking...

Contains affiliate links. I may earn a commission at no cost to you.

Wireless Access Points

I run four TP-Link Deco units in a mesh configuration. Mostly I use them as dumb APs, but the controller software is useful for one thing: forcing specific devices to specific APs. Some devices are too aggressive about switching APs, which caused buffering during video playback. Pinning them to one AP solved it.

For new buyers, I’d recommend proper ceiling-mount APs instead:

TP-Link Omada WiFi 7 - Dual Band A PoE ceiling-mount WiFi 7 access point with a 2.5 GbE uplink, Omada controller support, and VLAN-aware SSIDs for clean network segmentation. It fits a mid-tier router build by delivering fast, reliable wireless, simple central management, and a clear upgrade path without blowing the budget.

Amazon Price: Loading...

Availability: Checking...

Contains affiliate links. I may earn a commission at no cost to you.

What this setup can handle:

Multi-gig speeds (2.5GbE)
Heavy IDS/IPS
VPN at line speed
50+ devices

Who this is for: People who want room to grow and don’t want to upgrade again in 2-3 years.

Beast Build (~$1,200 Total)

Full disclosure: I haven’t personally used this hardware. This represents what I’d upgrade to if I had the budget and needed more performance. Based on community feedback and research, not hands-on experience.

Router Box: $600-700

MINISFORUM MS-01 Mini Workstation A compact workstation with a high-core-count Intel CPU, dual 10 GbE SFP+ ports, dual 2.5 GbE, NVMe storage, and room to scale. It is ideal for a top-tier OPNsense build because it can push multi-gig routing, run IDS/IPS and high-speed VPN without breaking a sweat and still leave room for future upgrades.

Amazon Price: Loading...

Availability: Checking...

Contains affiliate links. I may earn a commission at no cost to you.

Switch: $360

SODOLA 24 Port 2.5Gb PoE Switch This switch packs dense multi-gig PoE for APs, cameras, and IoT while keeping management simple with VLANs, and QoS. It’s a strong top-tier fit because your OPNsense box can push multi-gig uplinks and this switch distributes that speed across the whole network without noisy rack gear.

Amazon Price: Loading...

Availability: Checking...

Contains affiliate links. I may earn a commission at no cost to you.

Access Point: $200

TP-Link Omada WiFi 7 - Tri-Band Brings 2.4/5/6 GHz and Multi-Link Operation for large capacity, and low latency. It fits a top-tier OPNsense build with a multi-gig PoE uplink, clean SSID-to-VLAN mapping, Omada controller features like fast roaming and band steering, and headroom for dense homes or busy offices.

Amazon Price: Loading...

Availability: Checking...

Contains affiliate links. I may earn a commission at no cost to you.

What this setup can handle:

10GbE at line speed
Extremely complex rules
Multiple simultaneous VPN connections
100+ devices
Future-proof for years

Choosing an Access Point

Whatever build you land on, the access point is what makes or breaks wireless VLAN support: it broadcasts your SSIDs and tags each one to a VLAN before handing frames to the switch. A controller-based AP (TP-Link Omada or UniFi) does this cleanly. A plain consumer AP, or a mesh kit that can’t tag per SSID, dumps every client into one VLAN and defeats the whole point. I run Omada for the cost-to-feature ratio, with my old Deco mesh units demoted to dumb APs.

📝

Note: For the full wireless build, covering the best homelab AP, mapping SSIDs to VLANs, AP placement, and troubleshooting, see the dedicated guide: Best Homelab Wi-Fi & Access Points: VLAN-Aware Setup.

OPNsense vs pfSense: Which Should You Choose?

Choose OPNsense if:

You’re new and want a cleaner interface
You want built-in IDS/IPS
You prefer frequent updates
All features are included without licensing

Choose pfSense if:

You want the most mature platform
You prioritize stability over features
You need the largest community
Don’t mind a more corporate feel

My recommendation: Start with OPNsense. The interface is friendlier while remaining equally powerful. I’ve run it for eight years across multiple hardware generations without major issues.

Either choice is infinitely better than a consumer router.

Your First Weekend with OPNsense

Let me be honest about timelines. My original draft said “48 hours” but that’s optimistic. Here’s what actually happened when I set mine up.

Hour 1-2: Basic Installation

Installation:

Download OPNsense ISO, flash to USB
Boot router box, install to internal drive
Reboot, remove USB

This part is straightforward. If you’ve installed Linux before, this will feel familiar.

Hour 2-4: Initial Configuration

Getting Internet Working:

Connect WAN to modem, LAN to computer
Access web interface at 192.168.1.1
Run setup wizard: Set password, configure WAN/LAN, set timezone
Update to latest version
Configure DNS and test internet

Expect this to take longer than you think. My first attempt, I had to reboot the modem twice before the WAN interface pulled an IP. Normal stuff, but it eats time.

Weekend 2-3: VLANs

Creating Your First VLAN:

VLANs are where it gets tricky. I spent time wrapping my head around the concept before implementation paid off.

Start with IoT if you have IoT devices (and at this point most of us do). It’s the easiest to isolate and test:

Create VLAN on your switch (VLAN ID: 3)
Create VLAN interface in OPNsense (Interfaces → VLAN)
Assign and configure the interface (10.0.3.1/24)
Enable DHCP for the VLAN
Create firewall rules:
- Allow: IoT → Internet (ports 80, 443, 53)
- Allow: IoT → DNS Access to your DNS server
- Block: IoT → All other RFC1918 private networks
Test: Connect device, verify it works but can’t reach other VLANs

The first VLAN took me several hours. The second took one hour. By the fifth, it was fifteen minutes.

Common VLAN Mistakes I Made:

Forgetting to tag the trunk port on the switch - Spent 30 minutes troubleshooting why devices couldn’t get IPs before realizing the switch wasn’t passing VLAN tags.
Creating rules on the wrong interface - Made perfect firewall rules on the WAN interface instead of the VLAN interface. They did nothing.
Blocking DNS accidentally - Blocked RFC1918 addresses but forgot that my router (which provides DNS) is on 10.0.1.1. IoT devices couldn’t resolve anything.

Week 3-4: IDS/IPS

I didn’t enable Suricata immediately. Get comfortable with basic routing and VLANs first.

When I added IDS/IPS:

Services → Intrusion Detection → Administration
Enable IDS
Download Emerging Threats ruleset
Start in IDS mode (alerts only, no blocking)
Watch alerts for a week
Tune rules to reduce false positives
Switch to IPS mode (active blocking)

The learning curve was real. Lots of alerts I didn’t understand. Lots of forum threads explaining what “ET POLICY” rules meant. But after a few weeks, it clicked.

💡

Tip: Start with IDS mode only. Don’t enable blocking until you understand what you’re seeing. I almost blocked my entire media VLAN because I didn’t understand a legitimate traffic pattern Suricata flagged.

Week 4-6: How to Configure QoS in a Homelab Network

QoS (Quality of Service) on a homelab network is traffic shaping on your router: you create pipes for your up/down bandwidth, sort traffic into priority queues, and let the firewall throttle bulk transfers when something more important needs the line. I added QoS when SABnzbd kept ruining movie night.

Downloads would max out my 150Mbps connection, and Jellyfin streams would buffer. Annoying for me, unacceptable for my wife.

Setting up traffic shaping:

Firewall → Shaper → Settings
Create pipes for download/upload
Create queues for different traffic types
Assign priorities
Test with actual usage

My current priorities (tailored to 150/30 Mbps connection):

Queue 1 (Highest): Jellyfin streaming, Plex
Queue 2: YouTube, video platforms
Queue 3: Gaming traffic
Queue 4: Web browsing
Queue 5 (Lowest): SABnzbd, torrents (capped at 120Mbps / 80%)

Now downloads run in the background without impacting anything else. No manual throttling needed.

Current State: Set and Forget

After the initial setup period, I barely touch OPNsense.

Weekly routine:

Check for updates (takes 2 minutes)
Review IDS/IPS alerts (5 minutes)
Check logs if something seems weird (rarely needed)

Monthly:

Review firewall rules to see if anything needs adjustment (usually doesn’t)
Download config backup

That’s it. The router runs without intervention. No daily reboots. No random failures. No “why is the internet down?” conversations.

In two years with the Protectli, I’ve had zero hardware failures. Compare that to 15 years of consumer routers dying every 2-3 years.

Common Problems and Fixes

Can’t Access Internet After Setup

Symptoms: OPNsense installed, but no internet access

Check:

WAN interface has IP address (Interfaces → Overview)
Gateway shows as online (System → Gateways → Single)
DNS servers configured (System → Settings → General)
Try pinging 8.8.8.8 from Diagnostics → Ping

Fix: Usually the modem needs a reboot. Power cycle it, wait 2 minutes, check again.

VLANs Not Working

Symptoms: Device on VLAN can’t get IP or access internet

Check:

VLAN created on switch with correct ID
Trunk port configured between router and switch
VLAN interface assigned in OPNsense
DHCP enabled for VLAN
Firewall rules allow traffic

Fix: 90% of the time it’s switch configuration. Verify VLAN tagging is correct.

Locked Yourself Out

Symptoms: Changed firewall rules, now can’t access web interface

Fix:

Connect directly to LAN port
Access 192.168.1.1 (default LAN IP)
If that doesn’t work: Boot to recovery mode, reset to last config
Last resort: Reinstall and restore from backup (you made backups, right?)

This is why you download config backups regularly.

Specific Mistake I Made: IoT Security Lockdown

What I tried: Tightened security rules on IoT VLAN to block more traffic

What broke: All IoT devices lost internet access completely

What I learned: I was too aggressive blocking outbound traffic. Smart devices need to call home for updates and cloud features. You can restrict them, but not completely isolate them.

How I recovered: Restored OPNsense backup from 15 minutes earlier. Back to working state in 2 minutes.

Lesson: Always download a config backup before making major changes. Test changes incrementally. Have a rollback plan.

Common Mistakes to Avoid

Over-Complicating Day One

Start simple. Get basic routing working before adding anything else.

My recommended progression:

Weekend 1: Install OPNsense, get internet working
Weekend 2-3: Add one VLAN, test thoroughly
Weekend 4: Add remaining VLANs
Week 3-4: Enable IDS/IPS in monitoring mode
Week 5-6: Add QoS if needed
Ongoing: Tune and optimize

💡

Tip: Don’t try to do everything at once. I thought about my VLAN structure for weeks before implementing it. That planning paid off, I haven’t changed anything about how VLANs are organized in two years.

Not Documenting

Keep notes on:

What each VLAN is for
Why specific firewall rules exist
What each static IP is assigned to
Changes you make and why

Future you will thank you. I have a simple Obsidian note:

VLAN 2 (10.0.2.x) - Media Stack
- Jellyfin, Sonarr, Radarr, SABnzbd
- Allows: Internet (80, 443), NAS access, Trusted devices
- Blocks: IoT VLAN, Guest VLAN
Rule: Allow trusted → Media (8096)
Why: Access Jellyfin from phones/laptops
Created: 2023-02-15

Simple, but invaluable when troubleshooting.

Not Testing Firewall Rules

After creating block rules, actually test them. Don’t assume they work.

How I test:

Create rule to block IoT → NAS
From IoT device, try to ping NAS IP
Check firewall logs to confirm block

If the rule doesn’t show up in logs, it’s not working. Figure it out and fix it now, not when you have a security incident.

No Config Backups

Download your config regularly. Hardware can fail. Updates can go wrong. Accidents happen.

My backup routine:

After any major change: Download config immediately
Weekly: Download fresh backup (takes 30 seconds)
Store backups in three places: NAS, cloud, USB drive

I’ve restored from backup twice:

When I locked myself out with aggressive firewall rules
When I tried an OPNsense update that didn’t play nice with my hardware (rolled back, waited for next version)

Both times, I was back up in minutes instead of hours of reconfiguration.

Ignoring IDS/IPS Alerts

Review alerts weekly. This is your early warning system.

What I check every week:

New alert types I haven’t seen before
Repeated alerts from same source (might need blocking)
Internal devices generating alerts (compromised?)
Geographic patterns (lots of traffic from one country?)

Takes 5 minutes.

Integration with Your Four-Box Stack

This is why we separate the router from everything else.

Network Topology

[Modem] → [Router/Firewall] → [Managed Switch]
├→ [NAS] (VLAN 2)
├→ [Compute Box] (VLAN 2)
├→ [Access Points] (Multiple VLANs)
└→ [Other Devices] (Various VLANs)

Boot Order Matters

Router → Storage → Compute

Why this order:

Router boots first: Network is available for everything else
Storage boots second: NAS is ready when compute needs it
Compute boots last: Services start when dependencies are ready

How to set delays: You might be able to set delays in BIOS/UEFI for each box depending on your hardware:

Router: Auto-start immediately (0 second delay)
Storage: 30-second delay after power on
Compute: 60-second delay after power on

Real-world benefit: Power outage happens. Everything comes back automatically in the right order. No manual intervention needed.

Why Separation Matters (Again)

I’ve lived both sides of this.

With virtualized router (2 years):

Rebooting compute = entire house offline
Hardware failure = no internet until fixed
Testing new containers = risk to network stability
Update that goes wrong = everything down

With separated router (4 years total, 2 with current hardware):

Reboot compute whenever needed = nobody notices
NAS drive failure = internet stays up while I fix it
Container experiment goes wrong = network unaffected
Proxmox update goes sideways = restore snapshot, internet never dropped

The peace of mind is worth every penny.

When to Ask for Help

You will get stuck. Everyone does. Here’s where to go.

Official Resources

OPNsense Documentation: https://docs.opnsense.org/ Start here. Covers installation, basic config, features, and troubleshooting.

OPNsense Forum: https://forum.opnsense.org/ Active community. Search before posting. Someone has probably had your exact problem.

Community Resources

Reddit:

r/OPNsenseFirewall - Dedicated to OPNsense specifically
r/homelab - Broader homelab topics, lots of OPNsense users
r/selfhosted - Media server and self-hosting focus

The OPNsense Foundation: Building a Bulletproof Homelab Firewall (Part 1) Looking for a comprehensive OPNsense setup? Check out this detailed installation and configuration guide from corelab.tech. This two-part series covers everything from initial setup to advanced configuration, providing a complete walkthrough for getting OPNsense running properly.

Read Part 3: Your Storage Deserves Its Own Box

How to Ask for Help Effectively

When posting for help, include:

What you’re trying to do: “Setting up VLAN for IoT devices”
What you’ve tried: “Created VLAN 3 on switch and OPNsense, enabled DHCP”
What’s happening: “Devices get IP but can’t access internet”
Relevant logs: Screenshots or text of firewall logs
Firewall rules: Screenshots of rules for that interface

Bad post: “My VLANs don’t work, help!”

Good post: “IoT VLAN devices get DHCP but can’t reach internet. Created VLAN 3, enabled DHCP on 10.0.3.1/24, firewall rules allow ports 80/443 outbound. Logs show blocked packets to 8.8.8.8. Screenshots attached.”

The good post gets answered quickly. The bad post gets ignored or gets “need more information” responses.

The Bottom Line

After 15 years of consumer routers and 6 years running OPNsense, I’ll never go back.

What you give up:

One-box convenience
The “plug-and-play” feel (initially)

What you gain:

Network segmentation that contains breaches
Real intrusion detection that shows you threats
Full traffic visibility, you know what’s happening
Actual control over your network
Reliability that doesn’t degrade over time
Independence from your compute infrastructure

Is it more work? Yes, initially. The first few weekends require learning and configuration.

Is it worth it? Absolutely.

You’re building infrastructure worth thousands of dollars. Protecting it with a $120 consumer router that randomly reboots is like putting a $20 padlock on a bank vault.

The peace of mind alone is worth it. No more “why is the internet down?” conversations. No more daily reboots. No more wondering if your network is secure.

You’ll know it’s secure because you built it that way.

Real Numbers: Cost Over Time

Let me show you the actual economics.

Consumer router approach (what I did for 15 years):

New router every 2.5 years: $150 average
15 years = 6 routers = $900
Plus time troubleshooting, rebooting, replacing
Security: Hope and prayer

Dedicated router approach (what I’m doing now):

Budget build: $200 initial investment
Expected lifespan: 5+ years (I’m at 8+ years across two hardware generations)
Electricity: ~15W vs 30-50W consumer router (actually saves money)
Security: Real, verifiable, logged

Even if you replaced the budget build every 5 years, you’d spend $200 every 5 years ($40/year) versus $150 every 2.5 years ($60/year).

You save money while getting massively better security and reliability.

My current Protectli cost $400. Over 5 years, that’s $80/year. Still cheaper than consumer routers, and I expect it to last longer than 5 years based on how the previous hardware held up.

What’s Next

You’ve got your router sorted. Your network is segmented and secure. You can work on your compute infrastructure without taking down the internet.

In Part 3, we build the vault: A proper NAS that won’t lose your data when drives fail. We’ll talk about storage options like MergerFS + SnapRaid, ZFS, and off the shelf options, proper backup strategies, and why your data deserves more respect than a single external hard drive.

Quick Reference: OPNsense Commands

Keep this handy for common tasks:

Reboot: System → Power → Reboot
Apply firewall changes: Firewall → Rules → Apply Changes (the orange banner)
Check blocked traffic: Firewall → Log Files → Live View
See active connections: Firewall → Diagnostics → States Dump
Check DHCP leases: Services → DHCPv4 → Leases
IDS/IPS alerts: Services → Intrusion Detection → Alerts
Backup config: System → Configuration → Backups → Download configuration
Test connectivity: Diagnostics → Ping (or Diagnostics → Traceroute)
Check interface status: Interfaces → Overview
View system logs: System → Log Files → General

Home Media Server Hardware Guide: The 4-Box Setup

Wed, 29 Oct 2025 07:25:02 -0600

Everyone starts with the dream: one box to rule them all. Media apps, storage, downloads, and yes, even routing if you’re feeling extra ambitious.

Then reality hits. Reboot time becomes a nightmare. LXCs start before storage mounts. Apps can’t find their configs. Nothing works unless you babysit the boot order like it’s a toddler who found the scissors drawer.

The fix?
Four boxes.
Clear roles.
Real uptime.

Ask me how I know.

Spoiler: It involves a VM NFS Server, a Jellyfin LXC, and a very angry Sunday afternoon where I almost threw my server out the window.

Why I Ditched My VM NAS and Went Bare-Metal

💭

TL;DR: A stable home media server needs four dedicated machines: one for routing ($150-$500), one for storage ($400-$1900), one to run your apps ($200-$1400), and one for backups ($150-$400). Total investment: $900-$4,200. Expected build time: 2-4 weekends. The payoff: 99% uptime instead of the 80% you’re getting now.

Who This Guide Is For

You’re the right person for this if:

You’re running everything on a single machine and it’s becoming a headache
You’ve hit the “nothing works after a reboot” wall
You’re ready to invest $900-$4,200 and a few weekends for a reliable setup
You want to learn Proxmox, networking, and proper homelab architecture
You’re tired of your family asking why the streaming server is down again

You might want something else if:

You only want to watch a few movies and don’t care about uptime (get a Synology and call it done)
You have zero interest in learning Linux or networking basics
Your budget is under $900 total (stick with a single good machine for now)
You need this working by next weekend (this is a learning journey, so take your time)

Skills you’ll need (or learn along the way):

Basic Linux command line comfort. You can navigate directories and edit files
Willingness to read documentation when things break. And they will
Basic networking concepts. What’s an IP address, what’s a subnet
Patience for the learning curve. Expect some frustration, especially around Proxmox LXCs

Don’t worry if you’re not an expert. I wasn’t either. You’ll learn by doing, and I’ll point you to resources when you need them.

The Real ROI: What This Costs You

Yes, you’re about to spend $900-$4,200 on hardware. That sounds like a lot until you do the math on what you’re already spending.

The Streaming Service Tax

Here’s what you’re probably paying right now:

Service	Monthly Cost
Netflix (Standard)	$17.99
Disney+ & Hulu	$19.99
Max (HBO)	$18.49
Prime Video	$8.99
Apple TV+	$12.99
Peacock	$10.99
Paramount+	$13.99
Starz	$4.99
Crunchyroll	$7.99
TOTAL	$116.41/month

That’s $1,396.92 per year. Every year. For-ev-er.

And it’s getting worse. Remember when Netflix was $7.99? Yeah, so do I.

Don’t have streaming services? Cable averages about $100/month too.

Have streaming services and cable? Wow. This guide can help you the most.

The Break-Even Math

Budget build ($900):
You break even in 8 months. After that, you’re saving over $1,400/year.

Mid-range build ($1,900):
Break even in 16 months. Then it’s pure savings.

Dream build ($4,200):
Break even in 36 months. But you’ve built something that’ll last 5-9 years.

But Wait, There’s More

The math above assumes you cancel everything. Realistically, you’ll probably keep 1-2 services. I keep Prime Video for the rare night my Jellyfin server is down.

Even if you only cancel 6 out of 9 services, you’re saving $80+/month. That’s $960/year.

Plus you get:

Content you actually want to watch (not algorithmic slop)
No more “sorry, that’s leaving the platform in 3 days”
No more “this show is on Peacock now, not Netflix”
No more paying for multiple services to watch one show
Complete control over quality (no streaming compression)
Offline access (because internet outages happen)

The Hidden Costs They Don’t Tell You

Streaming services love to fragment. That show you’re watching? Season 1-3 are on Netflix. Season 4 moved to Paramount+. The spinoff is Max-exclusive. The movie that inspired it all is on Disney+.

You end up subscribing to four services to watch one franchise. Or you play subscription roulette, canceling and re-subscribing monthly and praying you remember to cancel before they charge you again.

With your own server? You watch what you want, when you want, without playing platform musical chairs.

The Power Bill Reality Check

“But what about electricity?”

Fair point. The math:

Average 4-box stack: ~130W idle, ~220W under load
Running 24/7 at $0.12/kWh: ~$12-16/month
So your actual monthly cost: $12-16 in power

You’re still saving $80-90/month vs. streaming services. That’s $960-$1,080/year in your pocket.

What About Content Acquisition?

Look, I’m not going to tell you how to get your “Linux ISOs”. But if you’re already paying for content through other means (totally legal Blu-ray ripping, of course), you’re not adding costs. You’re organizing what you already own.

And if you’ve got a library card? Many libraries offer free streaming through Hoopla, Kanopy, or similar services. Rip, organize, and keep forever. All legal, all free.

I have several guides on all of this. Here are a few:

The Intangible Benefits

This is about more than money. It’s about:

Not having shows you’re watching get canceled mid-season
Not dealing with ads (even on “ad-free” tiers that still show promos)
Not having your smart TV spy on your viewing habits
Not being at the mercy of licensing deals and regional restrictions
Owning your media instead of renting it monthly

The bottom line: Even the dream build pays for itself in 3 years. After that, you’re saving $1,400/year while having a better experience, more control, and media that’s yours.

That’s not a cost. That’s an investment that keeps paying dividends.

SECTION 1: Why One Box Isn’t Enough

Here’s the classic mistake. You cram everything (Jellyfin, Sonarr, Radarr, qBittorrent, SABnzbd, storage, Docker, and maybe even OPNsense if you’re really ambitious) onto that old desktop collecting dust in your closet.

It works.
Until it doesn’t.

Here’s what goes wrong:

One reboot = full outage.
Your apps don’t only go offline. They could come back in the wrong order. Jellyfin can’t see your media because NFS hasn’t mounted yet. Sonarr can’t write downloads because the share isn’t ready. That boot-time race between your LXC containers and your storage mounts? Nobody wins. Especially not you.

Performance becomes a bottleneck.
You’re trying to transcode a 4K stream while ZFS is scrubbing, torrents and nzbs are verifying, and your CPU is melting down. Everything competes for the same I/O, RAM, and CPU cores. There’s no isolation, only a noisy soup of services fighting for resources.

Security is non-existent.
Mixing your media stack with your router or storage means one compromised container could break your entire network or corrupt your storage. Ever had Jellyfin accidentally nuke a mounted drive path? I have.

Troubleshooting becomes impossible.
Is it Jellyfin’s fault? A bad NFS mount? A network issue? You don’t know, because everything’s tangled together. Diagnosing one problem means taking down everything else to test it.

You can’t upgrade or experiment safely.
Want to try that new transcoding setup? Too bad. You’re scared to touch anything because a mistake means your entire network goes down. You’re paralyzed, stuck with a setup you hate because changing it is too risky.

My Breaking Point

I ran everything on one computer for years. It worked. Mostly. Until the power supply died.

The server went silent. And because I ran OPNsense, Jellyfin, and my NAS all on the same computer, I had no internet and no access to my media.

Meanwhile my partner asked increasingly pointed questions about when the internet would be back up.

Four hours and a trip to BestBuy later, I got it back up and running.

That’s when I split the stack. Router, storage, compute, backup. Four boxes. The next power-supply failure took down exactly one of them, not all four.

SECTION 2: The Four-Box Philosophy

Here’s the core idea. Separate traffic, storage, compute, and backup into four dedicated machines.

Each machine does one job. Does it well. Stays stable. And doesn’t bring down the others when it needs maintenance.

The Stack:

Box 1: Router ($150-$500)
Controls all traffic, handles DNS, manages VLANs, runs your firewall. This is the gatekeeper.

Box 2: Storage ($400-$1900)
Holds all your media, provides redundancy, serves files to everything else. This is your vault.

Box 3: Compute ($200-$1400)
Runs all your apps: Jellyfin, Sonarr, Radarr, and any new software you want to try. This is the chaos layer where VMs and containers change, break, and get rebuilt.

Box 4: Backup ($150-$400)
Backs up your compute node’s LXCs and VMs. Something breaks after a change? Roll back to the last working snapshot. This is your insurance policy.

Why This Works:

Modularity = Sanity.
Reboot compute without touching storage. Upgrade your NAS without breaking Jellyfin. Swap routers without tearing down your entire stack. When one piece fails, the others keep running.

Clear Failure Domains.
Something breaks? You know exactly where to look. Service down? Check compute. Files missing? Check storage. Network problems? Check the router. No more digging through monolithic logs trying to find which piece is the problem.

Easy Scaling.
Need more storage? Add drives to the NAS. Need more CPU power? Upgrade the compute box. Want faster networking? Upgrade the router. You’re not locked into some Frankenstein all-in-one that needs replacing entirely to improve one thing.

Safe Experimentation.
Want to try Tdarr? Spin up an LXC. Want to test a new Jellyfin build? Clone your container. Breaking something on the compute box doesn’t take down your network or risk your data.

SECTION 3: Box 1 – The Router (Your Gatekeeper)

Your router is the traffic cop of your entire media stack. If it sucks, everything downstream suffers.

And yes, your ISP’s all-in-one Wi-Fi “router” absolutely sucks.

Why a Dedicated Router Matters:

You need control, not guesswork.

Static IPs for all your services so they don’t randomly change
VLANs to isolate your download clients from the rest of your network
Firewall rules to keep risky devices in their own sandbox
DNS that resolves jellyfin.home instead of forcing you to remember IPs

You might get some of that from a consumer “gaming” router with racing stripes. You will get all of it from a real box running OPNsense or pfSense.

Security starts here.
A proper firewall lets you isolate containers, restrict traffic by IP, and run reverse proxies safely. You can see what’s happening through logs and alerts. You’re not flying blind hoping nothing bad gets through.

Your media traffic stays fast.
4K Jellyfin streams shouldn’t fight with torrent downloads and game updates for bandwidth. Smart routing and QoS keep your streams smooth even when everything else is maxed out.

Network isolation becomes possible.
Keep your kids’ devices off the same subnet as your torrent client. Put Home Assistant on a separate VLAN with no access to your NAS. Isolate your IoT lightbulbs from anything that matters. This is how you build defense in depth.

What You’ll Do With It:

Set up static DHCP reservations for every device in your stack
Create VLANs for different trust levels (trusted, media, IoT, guest)
Configure firewall rules to control what can talk to what
Set up a reverse proxy (Nginx Proxy Manager or Traefik) for clean URLs
Monitor traffic to see what’s hogging bandwidth

A real router box gives you something an ISP combo unit never will: a place to grow into. The hardware below will run OPNsense comfortably, with dual 2.5G ports and more CPU than routing alone will ever ask for.

Glorlin Ryzen 7 8745HS Mini PC
An 8-core/16-thread mini PC with dual 2.5G LAN, so OPNsense installs without an add-in card and an IDS like Suricata has CPU to spare. It’s a good deal more machine than routing needs, which is the trade you’re making while cheap dual-NIC boxes are thin on the ground.

Amazon Price: Loading...

Availability: Checking...

Contains affiliate links. I may earn a commission at no cost to you.

Coming in Part 2: I’ll walk through which routers to buy, from an $80 used SFF box that punches above its weight to the $500+ “final boss” build that handles 10Gbps like it’s nothing.

SECTION 4: Box 2 – Storage (Your Vault)

Your media has to live somewhere. Your download folder on a single SSD isn’t going to cut it when you’re storing terabytes of movies and TV shows.

This is where the NAS comes in. It holds everything, keeps it safe, and makes sure it’s still there tomorrow when you wake up.

Why Storage Deserves Its Own Box:

You need redundancy.
Hard drives fail. It’s not if, it’s when. (Ask me about my dead 14TB drive that took 9TB of unwatched shows with it.) A proper NAS setup, whether ZFS, SnapRAID, Unraid, or mirrored drives, gives you fault tolerance. You lose a drive without losing your media. Your compute server shouldn’t be the thing keeping data alive. That’s not its job.

You need speed and consistency.
Streaming 4K, transcoding, downloading, and seeding all at once? You need fast sequential reads and smart caching. A NAS optimized for this workload handles it better than random drives thrown into your compute box.

Everything needs to find files reliably.
When storage is its own box, it boots first, mounts clean, and stays available. Your LXCs don’t wonder if /mnt/media is ready. They connect via NFS or SMB and work. No more boot-order mysteries or race conditions.

You need upgrade flexibility.
Rebuilding your Jellyfin container? The NAS doesn’t care. Upgrading your compute box? Your media stays untouched. Separating storage from compute means you can break, upgrade, or rebuild services without risking your files.

What You’ll Do With It:

Set up RAID or ZFS pools for redundancy
Configure NFS or SMB shares for your media libraries
Set up automated scrubs to catch bit rot early (weekly zpool scrub tank cron is a good baseline)
Monitor drive health with SMART data (smartctl -a /dev/sdX and smartd alerts)
Plan your backup strategy. Yes, RAID is not a backup

The Boot Order Secret:

Here’s the key: Router boots first. Storage boots second. Compute boots third.

This order matters. When storage is ready before compute starts, your LXCs never race against mount points. Everything works. This alone eliminates 90% of the “why isn’t Jellyfin seeing my files” problems.

A dedicated NAS does more than hold extra drives. It keeps your data alive when a power blip kills a disk mid-write.

For a drive that fits this role, here’s what I’d stack in a multi-bay enclosure today:

Seagate IronWolf Pro 24 TB
Built for NAS enclosures that never sleep. 7200 RPM CMR with a 512 MB cache and a 550 TB/year workload rating, so you can stack three or four of these in a ZFS or SnapRAID pool without cooking them. 5-year warranty and 3 years of Seagate Rescue included, because when (not if) one dies, you want a parachute.

Amazon Price: Loading...

Availability: Checking...

Contains affiliate links. I may earn a commission at no cost to you.

Coming in Part 3: The actual NAS builds, from budget SnapRAID setups using old hardware to dream ZFS rigs that’ll make you feel like you work at a data center.

SECTION 5: Box 3 – Compute (Your Workhorse)

This is the fun box. The one that runs everything: Jellyfin, Sonarr, Radarr, Tdarr, Bazarr, Lidarr, and whatever new -arr appears next week.

It’s where things happen. But it only works because the other boxes are doing their jobs.

Why Compute Needs Its Own Home:

It’s where the mess lives.
App updates. LXC templates. Docker networks. Transcoding jobs. This is the chaotic, ever-changing layer of your stack. You want it isolated so you can blow things up, reboot, or rebuild without touching storage or breaking your network.

You get proper service isolation.
Run Jellyfin in one LXC and qBittorrent in another. Experiment with Bazarr or Prowlarr without wrecking your stable setup. Proxmox makes this easy whether you’re using full VMs or lean LXCs.

You have actual resource control.
Assign specific RAM, CPU cores, and disk I/O to each container. Want Tdarr to use every core you’ve got overnight but stay quiet during the day? Done. Want to make sure qBittorrent can’t steal resources from Jellyfin during movie night? Easy. Good luck getting that kind of control on a janky all-in-one setup.

It’s built to change.
Want GPU passthrough for transcoding? Add it. Need more RAM? Upgrade this one box. This is the only part of your stack that should change regularly, so build it to take hits and keep going.

Pets vs Cattle: Why This Changes Everything

Here’s a concept from DevOps that’ll change how you think about your services:

Pets are servers you name, nurture, and baby. When they get sick, you stay up all night nursing them back to health. You’re terrified to reboot them because something might not come back right. You’ve spent hours configuring them and the thought of rebuilding makes you break out in a cold sweat.

Cattle are servers you number, not name. If one gets sick, you cull it and spin up a replacement. They’re built from templates, configured automatically, and completely disposable. Lose one? Who cares. You’ve got backups and can rebuild in minutes.

Your all-in-one box? That’s a pet. You’re scared to touch it. Every update is a gamble. You’ve probably got configs and tweaks you can’t even remember making. If it dies, you’re spending days rebuilding from memory and hoping you didn’t forget anything critical.

This four-box setup? It lets you treat services as cattle.

Here’s how:

Storage is separate = data is safe.
Your media, configs, and databases live on the NAS. When you rebuild a container, all your important data is still there. You’re not risking your files every time you experiment.

Proxmox makes containers disposable.
Spin up an LXC in 2 minutes. Test something. Hate it? Delete it. No drama. Want to try a different Jellyfin version? Clone your container, test it, keep what works.

Backups make everything replaceable.
With Proxmox Backup Server (coming in Part 5), you can restore any container to any point in time with one click. Accidentally nuke your Sonarr config? Restore yesterday’s backup. Takes 3 minutes.

Real-world example from my stack:

I wanted to test Jellyfin 10.11.0 (major changes in this update), but I was running 10.10.7 in production. Old me (one-box setup) would’ve been too scared to upgrade. What if it breaks? What if I can’t roll back?

New me (four-box setup):

Snapshot my Jellyfin LXC (30 seconds)
Clone it to a test container (2 minutes)
Upgrade the test version, break things, learn stuff
Decide the new version wasn’t ready for Ubuntu yet
Delete the test container, keep running production
Total risk to my family’s movie night: zero

This is the mentality shift that makes homelabbing fun instead of terrifying. You stop being afraid to experiment because nothing you do can truly break things. Your data is safe on the NAS. Your configs are backed up. Your containers are cattle.

When your Nginx Proxy Manager container gets weird? Nuke it. Restore from last night’s backup. Six minutes later you’re back online and you didn’t break a sweat.

That’s the power of separation. Your compute box becomes a playground instead of a house of cards.

What You’ll Do With It:

Install Proxmox VE as your hypervisor
Create LXC containers for each service (Jellyfin, AudioBookshelf, Pi-hole, etc.)
Create VMs for specific Docker stacks (Arr Suite, Immich, etc.)
Mount your NFS shares from the storage box (/etc/fstab entries or Proxmox storage configs)
Set up GPU passthrough for hardware transcoding
Configure automated container backups
Learn to love (and occasionally hate) Proxmox’s web interface

The Learning Curve:

Proxmox has a reputation. It’s powerful but not exactly hand-holdy. You will:

Screw up your first few LXCs (everyone does)
Accidentally delete something important (keep backups)
Spend an hour Googling why NFS mounts aren’t working (permissions, always permissions)
Eventually figure it out and feel like a genius

This is normal. This is the path. Embrace it.

The CPU you pick here matters more than you’d think. Hardware transcoding, container density, and snappy web UIs all live or die by single-thread speed and integrated graphics.

Intel Core i5-14500 14th Generation Desktop Processor This CPU is ideal for Proxmox homelabs. Strong single-thread performance, 14 cores for efficient virtualization, and UHD 770 graphics good enough to handle Jellyfin hardware transcoding with QSV.

Amazon Price: Loading...

Availability: Checking...

Contains affiliate links. I may earn a commission at no cost to you.

Coming in Part 4: The actual Proxmox builds, from repurposed office PCs to custom rigs, plus the LXC templates and configurations that work.

SECTION 6: How They All Work Together

Four random boxes on a shelf is a pile of e-waste. Four boxes with clear jobs and a defined boot order is a system. Here’s how mine fit together.

The Flow:

Router boots first.
It brings up the network, handles DHCP, starts DNS. Everything else depends on this foundation. It’s the traffic cop and bouncer rolled into one.

Storage boots second.
With the network ready, your NAS comes online, mounts its drives, starts serving files via NFS/SMB. Now the vault is open and ready.

Compute boots third.
With networking and storage available, Proxmox fires up, LXCs start in order, apps connect to their storage mounts, and everything works. No race conditions. No mysteries. Reliable boots.

When Something Breaks:

Router problem? Network is down, but storage and compute are fine. Swap in a backup router (or fix the issue), restore config, back online.

Storage problem? Media streaming stops, but your network still works. You can troubleshoot, check drives, restore from backup. Apps keep running even if they can’t access files.

Compute problem? Services go down, but your network and data are safe. Reboot it. Restore a container from backup. Rebuild from scratch if needed. Your files and network never blinked.

This is the magic of separation. Problems stay contained. Fixes don’t cascade. You’re not gambling with your entire setup every time something hiccups.

SECTION 7: The Fourth Box - Backups

You’ve got your router. Your storage. Your compute. Feels solid, right?

Until something breaks. Then it’s panic mode. Unless you have Box 4: Backup Server.

Proxmox Backup Server – The Box That Saves You

If you’re running VMs or LXCs, you need backups that actually work. Not rsync scripts you never test. Not drive clones you made once in 2023. Real, restorable, tested backups.

What PBS does:

Automated daily backups of all your containers and VMs
Deduplication so you can keep weeks of snapshots without filling drives
Versioned backups you can browse by date
One-click restores directly from Proxmox’s interface
Verification jobs to make sure backups actually work (run proxmox-backup-manager verify-job run on a schedule)

Real-world save:
I once destroyed the wrong LXC in Proxmox (RIP Nginx Proxy Manager). PBS had me back online in 7 minutes. Without it, I’d have spent hours rebuilding configs from memory and old screenshots.

Is This Required?

Technically? No. You can run without it.

Practically? If your Jellyfin container died tomorrow, could you restore it in under 10 minutes? If not, you need this.

The Budget Reality:

You can run PBS on:

A $150 used mini PC with a 2TB drive
Your NAS if it has extra resources (though I prefer separation)
Even a Raspberry Pi for smaller setups

This is cheap insurance. Way cheaper than rebuilding your entire stack from scratch on a work night.

A fast SSD as the PBS datastore makes a huge difference for restore time. This is the drive I’m running mine on:

TEAMGROUP T-Force Vulcan Z 2TB This is the SSD I use for my Proxmox Backup Server datastore. I back up 6 VMs and 12 LXCs and I’m only at 11% capacity. At this rate I’ll fill it in 3 years. PBS deduplication is amazing.

Amazon Price: Loading...

Availability: Checking...

Contains affiliate links. I may earn a commission at no cost to you.

Coming in Part 5: Setting up Proxmox Backup Server, automating backups, and actually testing your restores. So you’re not learning how backups work during a crisis.

Common Questions

➤ Can I start with only 2 boxes?

Yes. Start with compute + storage, use your existing router. Or start with router + compute, use attached storage temporarily. The point is separation, not perfection. You can grow into the full stack.

➤ What if I already have a Synology?

Perfect. That’s your storage box. You’re already halfway there. Focus on getting a dedicated router and compute box, connect them to your Synology, and you’ve got the stack.

➤ Do I really need to learn Proxmox?

Not technically. You could run Docker on bare metal. But Proxmox gives you isolation, snapshots, easy backups, and the ability to run multiple services without them stepping on each other. The learning curve pays off.

➤ What about power consumption?

Fair question. Four boxes use more power than one. My stack pulls about 130W idle. That’s $11-13/month at $0.12/kWh. The uptime and sanity are worth it. If you’re power-sensitive, choose efficient hardware (covered in the build guides).

➤ Can I use old hardware for this?

Absolutely. Some of the best home servers are built from old office PCs. The next posts will cover budget builds using used hardware alongside new builds for those who want to buy fresh.

What About the Easy Button?

“Can’t I buy a Synology and run everything there?”

You can. And for some people, that’s the right answer. If you:

Don’t want to learn Linux or networking
Only want it to work out of the box
Don’t mind being locked into Synology’s ecosystem
Are okay with limited customization

Then yes, get a Synology DS925+ or similar, install Jellyfin/Plex, and call it done.

Synology 4-Bay DiskStation DS925+ (Diskless)
Want an easy button? Here you go. The Synology DS925+ is an OK all-in-one box. Enough storage and processing power for your media services, but it’ll run out of steam the moment you go beyond basic needs.

Amazon Price: Loading...

Availability: Checking...

Contains affiliate links. I may earn a commission at no cost to you.

You give up flexibility for that convenience:

You can’t easily run multiple isolated services.
You can’t experiment without risk.
You can’t scale components independently.
And when it breaks, you’re at Synology’s mercy for support.

This guide is for people who want more control, are willing to learn, and understand that power comes with responsibility (and occasional Googling).

Your Growth Path

Phase 1: Get it working

Build all four boxes
Get basic services running (Jellyfin, Sonarr, Radarr)
Verify everything boots reliably

Phase 2: Stabilize and monitor

Add Proxmox Backup Server
Set up proper monitoring (Uptime Kuma, Grafana)
Document your setup (seriously, do this)

Phase 3: Optimize and expand

Add a GPU for hardware transcoding
Upgrade to 10GbE networking between boxes
Add more storage as your library grows
Experiment with new services in isolated LXCs

Phase 4: Advanced features

VPN for remote access
Automated media management (Recyclarr, Tdarr)
Advanced monitoring and alerting
Offsite backup replication

You don’t need to do all of this at once. Build the foundation, then grow into it.

The next four posts break down each box in detail: what to buy, what to avoid, and budget vs. dream builds.

Role	Purpose	Budget Range
Router	Traffic control, DNS, VLANs, firewall	$150-$500
Storage	Reliable media storage with redundancy	$400-$1900
Compute	Runs all your apps and services	$200-$1400
Backup	Saves you from disaster	$150-$400

Each box has different needs, different trade-offs, and yes, different price tags. Here’s the thing though: you don’t need the dream build to get started. A $900 budget stack works. A $4,200 dream stack works better. Both work way better than cramming everything onto one box and hoping for the best.

Part 2 drops next week: The Router. I’ll walk through which hardware to buy, from an $80 used SFF box that punches above its weight to the $500+ “final boss” build that handles 10Gbps like it’s nothing. Plus OPNsense installation, VLAN setup, and the firewall rules that matter.

Want to be ready? Start thinking about:

Your budget for each component
What old hardware you might already have
Whether you want to buy used or new
How much redundancy you need

And most importantly: what you want to stop babysitting, so you can finally watch your media in peace.

Proxmox LXC UID/GID Mapping and lxc.idmap Guide

Mon, 20 Oct 2025 07:03:02 -0600

If you’ve ever shared files between your Proxmox host and an LXC container and wondered why permissions look “off” or why bind mounts throw permission errors, you’ve already bumped into UID/GID mapping. It’s the behind-the-scenes mechanism that keeps your containers safe. It’s also where confusing file ownership problems come from.

UID (User ID) and GID (Group ID) mapping is what stops a container’s root from being actual root on the host. It’s also what lets you share directories sanely without handing over the keys to the kingdom.

Here’s the thing: UID/GID mapping sounds intimidating. It isn’t. Once you get the concept, it stops being a mystery and starts being a tool. We’ll walk through how it works in Proxmox LXCs, how to customize it, and how to fix the headaches it causes. Especially for media server setups like Jellyfin.

And don’t fall for the easy out of switching to a privileged container. You’ll trade real security for a few minutes of convenience.

💭

TL;DR: Proxmox isolates unprivileged LXC containers by mapping their user and group IDs to high-numbered counterparts on the host, starting at 100000. This security feature prevents container root users from escalating to host root. You can customize these mappings by editing /etc/pve/lxc/<ID>.conf and adjusting /etc/subuid and /etc/subgid. Doing so allows seamless file sharing and predictable permissions when bind mounting directories inside containers.

Intel® Core™ i5-14500 14th Generation Desktop Processor This CPU is ideal for Proxmox homelabs, providing strong single-thread performance and efficient virtualization across 14 cores, perfect for experimenting with LXC containers.

Amazon Price: Loading...

Availability: Checking...

Contains affiliate links. I may earn a commission at no cost to you.

Why UID/GID Mapping Matters

User and group IDs in Linux define ownership and permissions. UID 0 is root. UID 1000 might be your first host user. Normally these IDs are global across a single OS instance. Containers complicate that picture. Without remapping, “root” inside a container would also be UID 0 on the host. If someone broke out of that container, they’d own your box.

Proxmox solves this by defaulting to unprivileged containers. The container’s UID/GID space gets remapped to a non-privileged range on the host. Think of it as giving each container its own private numbering system that translates to harmless IDs on the host side.

Visualizing the Mapping

Here’s what happens with default mapping:

Container Namespace Host System
┌────────────────────┐ ┌──────────────────┐
│ UID 0 (root) │ ───> │ UID 100000 │
│ UID 1 (daemon) │ ───> │ UID 100001 │
│ UID 1000 (user) │ ───> │ UID 101000 │
│ UID 65535 (nobody) │ ───> │ UID 165535 │
└────────────────────┘ └──────────────────┘

With custom mapping for media server access:

Container Namespace Host System
┌────────────────────┐ ┌──────────────────┐
│ UID 0 (root) │ ───> │ UID 100000 │
│ UID 999 │ ───> │ UID 100999 │
│ UID 1000 (user) │ ───> │ UID 1000 │ ← Direct map!
│ UID 1001 │ ───> │ UID 101001 │
└────────────────────┘ └──────────────────┘

Why 100000 as the Starting Point?

Proxmox chose 100000 as the default offset for good reasons:

System UIDs (0-999): Reserved for system services and the root user
User UIDs (1000-60000): Normal user accounts on most Linux systems
Container offset (100000+): Far enough from everything else to avoid conflicts

So even if you have 99 regular users on your host (UID 1000-1099), their IDs will never collide with container-mapped IDs.

Privileged vs Unprivileged: What You Need to Know

Unprivileged Containers (unprivileged: 1 - Default):

UID/GID mapping is enforced by the kernel
Container root = UID 100000 on host (harmless)
Recommended for 99% of use cases including media servers
Security isolation is maintained even if container is compromised

Privileged Containers (unprivileged: 0):

NO UID/GID mapping
Container root = actual root on host
Major security risk: Container escape = full host compromise
Rarely needed for media servers, avoid unless absolutely necessary

For Jellyfin, Plex, and similar media servers, always use unprivileged containers with proper UID mapping. Performance is identical. Security is night and day.

Understanding the Default Mapping

When you create a new unprivileged LXC container in Proxmox, it sets up UID/GID mappings automatically to keep the container isolated from the host.

Check your container’s configuration file:

cat /etc/pve/lxc/101.conf

You’ll see something like:

arch: amd64
cores: 2
hostname: jellyfin
memory: 2048
rootfs: local-lvm:vm-101-disk-0,size=8G
unprivileged: 1

That unprivileged: 1 line triggers automatic UID/GID offset mapping defined in /etc/subuid and /etc/subgid on the host.

The Default Mapping Files

Check your host’s subordinate ID files:

cat /etc/subuid
cat /etc/subgid

You’ll see:

root:100000:65536

This means:

Container UID 0 → Host UID 100000
Container UID 1 → Host UID 100001
Container UID 1000 → Host UID 101000
Container UID 65535 → Host UID 165535

And that’s why your media files show weird ownership. When your Jellyfin container creates or accesses files, they appear on the host owned by UIDs in the 100000+ range instead of your normal user account. Not what you want.

MINISFORUM MS-A2 With serious I/O and flexible storage, this mini-workstation is an excellent homelab node for advanced LXC container setups, allowing you to experiment with lxc.idmap and /etc/subgid in a high-performance, space-saving package.

Amazon Price: Loading...

Availability: Checking...

Contains affiliate links. I may earn a commission at no cost to you.

Prerequisites

Before configuring UID/GID mapping, ensure:

You’re running Proxmox VE 7.0 or later
Container is stopped (or not yet created)
You know your host user’s UID (run id on host)
You have root access to Proxmox host
Media files exist on host with known ownership

Step-by-Step: Setting Up UID/GID Mapping for Media Servers

Here’s the practical walk-through for getting Jellyfin (or Plex, Emby, etc.) talking to your media library.

Step 1: Identify Your Host Media Directory Ownership

First, check who owns your media files on the host:

ls -ln /media/movies
ls -ln /media/tv

You’ll see output like:

drwxr-xr-x 10 1000 1000 4096 Oct 20 10:30 /media/movies

The 1000 1000 shows UID and GID. That’s typically your primary user account. Write this number down. You’ll need it later.

Step 2: Stop Your Container

If the container is already running:

pct stop 101

Skip this step if you’re configuring a new container that hasn’t started yet.

Step 3: Edit the Container Configuration

Open the container’s config file:

nano /etc/pve/lxc/101.conf

Add these lines at the end:

lxc.idmap: u 0 100000 1000
lxc.idmap: g 0 100000 1000
lxc.idmap: u 1000 1000 1
lxc.idmap: g 1000 1000 1
lxc.idmap: u 1001 101001 64535
lxc.idmap: g 1001 101001 64535
# Our mapping covers exactly 65,536 IDs (0-65535):
# Line 1: 1000 IDs (container 0-999)
# Line 2: 1 ID (container 1000)
# Line 3: 64535 IDs (container 1001-65535)
# Total: 1000 + 1 + 64535 = 65,536 ✓

What this does:

Maps container UIDs 0-999 to host UIDs 100000-100999 (keeps container root isolated)
Maps container UID 1000 directly to host UID 1000 (your user)
Maps container GID 1000 directly to host GID 1000 (your user’s group)
Resumes offset mapping at UID 1001 → host UID 101001 (100000 base + 1001 offset), maintaining security isolation for all remaining users

Save and exit (Ctrl+X, Y, Enter).

Step 4: Add Bind Mounts for Your Media

Add your media directories to the config file (if not already open from Step 3, use nano /etc/pve/lxc/101.conf):

mp0: /media/movies,mp=/media/movies
mp1: /media/tv,mp=/media/tv
mp2: /media/music,mp=/media/music

Or use the command line:

pct set 101 -mp0 /media/movies,mp=/media/movies
pct set 101 -mp1 /media/tv,mp=/media/tv

Step 5: Verify Subordinate UID Files

Check that your host has the necessary UID range:

cat /etc/subuid
cat /etc/subgid

You should see at least:

root:100000:65536

Now edit both files and add this line at the top:

# In /etc/subuid:
root:1000:1

# In /etc/subgid:
root:1000:1

What this means:

Allows the root user (who runs LXC) to map a single ID (1000) directly through to the container
Change 1000 to match your host user’s UID/GID (find it with the id command)

Step 6: Start and Configure Container

pct start 101

Enter the container:

pct enter 101

Create or modify the user to match your host UID:

# Check if jellyfin user already exists
id jellyfin 2>/dev/null

# If user doesn't exist yet, create it:
useradd -u 1000 -m jellyfin

# If user already exists with wrong UID, modify it:
usermod -u 1000 jellyfin
usermod -g 1000 jellyfin # Also update primary group

Step 7: Verify Permissions

Test that Jellyfin can access your media:

su - jellyfin -s /bin/bash
ls -la /media/movies
touch /media/movies/test.txt

If these commands work without “Permission denied” errors, you’re good!

On the host, verify:

ls -ln /media/movies

Remove the test file:

rm /media/movies/test.txt

Files created by Jellyfin should show UID 1000, matching your host user.

Step 8: Configure Jellyfin Libraries

Hit Jellyfin’s web interface (usually http://container-ip:8096) and add your media libraries pointing to:

/media/movies
/media/tv
/media/music

Jellyfin scans and accesses everything without permission errors.

Common Media Server Patterns

Pattern 1: Single User Media Library (Most Common)

Use case: All media owned by one user (UID 1000)

lxc.idmap: u 0 100000 1000
lxc.idmap: g 0 100000 1000
lxc.idmap: u 1000 1000 1
lxc.idmap: g 1000 1000 1
lxc.idmap: u 1001 101001 64535
lxc.idmap: g 1001 101001 64535
mp0: /media,mp=/media

Pattern 2: Multiple Media Users

Use case: Media owned by different users (UID 1000, 1001, 1002)

lxc.idmap: u 0 100000 1000
lxc.idmap: g 0 100000 1000
lxc.idmap: u 1000 1000 3
lxc.idmap: g 1000 1000 3
lxc.idmap: u 1003 101003 64533
lxc.idmap: g 1003 101003 64533
mp0: /media,mp=/media

Troubleshooting Media Server Permission Issues

➤ Problem: Jellyfin Can’t See Media Files

Symptoms: Library scan shows no files or “Permission denied” in logs

Solution:

# Check mapping is active
pct exec 101 -- cat /proc/self/uid_map

# Verify file ownership
pct exec 101 -- ls -ln /media/movies

# Check Jellyfin user UID
pct exec 101 -- id jellyfin

# Ensure they match your mapping

➤ Problem: Can’t Write Subtitles or Metadata

Symptoms: Jellyfin complains about read-only filesystem

Solution:

# Verify mount isn't read-only
cat /etc/pve/lxc/101.conf | grep mp0

# Should NOT have 'ro' option
# Correct: mp0: /media,mp=/media
# Wrong: mp0: /media,mp=/media,ro

# Verify write permissions
pct exec 101 -- su - jellyfin -s /bin/bash -c "touch /media/test.txt"

➤ Problem: Transcoding Fails with Permission Errors

Symptoms: Playback works but transcoding fails

Solution:

# Check transcode directory permissions
pct exec 101 -- ls -ln /var/lib/jellyfin/transcodes

# Should be owned by jellyfin user
pct exec 101 -- chown -R jellyfin:jellyfin /var/lib/jellyfin

# If using host directory for transcoding
pct set 101 -mp1 /fast-storage/transcodes,mp=/transcodes

➤ Problem: Files Show as UID 100000 on Host

Symptoms: Host can’t manage files created by Jellyfin

Solution: Your mapping isn’t working. Go back to Step 3 and verify your lxc.idmap configuration, then restart the container.

GMKtec Mini PC i7-1185G7 A compact quad-core system that ships with 16 GB of RAM and a 1 TB SSD, which is enough to run Proxmox with several LXC containers and practice UID/GID mapping on real hardware instead of a throwaway VM.

Amazon Price: Loading...

Availability: Checking...

Contains affiliate links. I may earn a commission at no cost to you.

Advanced: Running Multiple Media Servers

If you’re running both Jellyfin and Plex, or want separate containers for different media types:

Strategy: Shared Mapping, Separate Containers

Container 101 (Jellyfin):

lxc.idmap: u 0 100000 1000
lxc.idmap: g 0 100000 1000
lxc.idmap: u 1000 1000 1
lxc.idmap: g 1000 1000 1
lxc.idmap: u 1001 101001 64535
lxc.idmap: g 1001 101001 64535
mp0: /media,mp=/media,ro

Container 102 (Plex):

lxc.idmap: u 0 100000 1000
lxc.idmap: g 0 100000 1000
lxc.idmap: u 1000 1000 1
lxc.idmap: g 1000 1000 1
lxc.idmap: u 1001 101001 64535
lxc.idmap: g 1001 101001 64535
mp0: /media,mp=/media,ro

Both containers can read the same media library. Use the ro (read-only) flag to prevent accidental modifications.

Understanding lxc.idmap Syntax

For those who want to customize beyond these common patterns:

lxc.idmap: [u|g] [first_id_in_container] [first_id_on_host] [number_of_ids]

Example breakdown:

lxc.idmap: u 0 100000 1000

u = UID mapping (use g for GID)
0 = Start at container UID 0
100000 = Map to host UID 100000
1000 = Map 1000 consecutive IDs (0-999)

Critical rules:

You must map all 65536 IDs (0-65535)
No gaps allowed
No overlaps within same container
Order matters. Later lines override earlier ones

FAQs

➤ Will UID mapping slow down my media server?

No. UID mapping happens in the kernel with negligible overhead. Your Jellyfin performance will be identical to a privileged container, but much more secure.

➤ Can I use the same mapping for multiple containers?

Yes. All your media-related containers (Jellyfin, Sonarr, Radarr, etc.) can use the same UID mapping pattern. This makes file sharing between them seamless.

➤ What if my media is owned by a different UID?

Adjust the mapping. If your media is owned by UID 1500 instead of 1000, change:

lxc.idmap: u 1500 1500 1
lxc.idmap: g 1500 1500 1

And adjust the other ranges accordingly to ensure you still map all 65536 IDs.

➤ Do I need to map GID separately from UID?

Yes, if your files rely on group permissions. Most media setups work fine mapping both UID and GID the same way (as shown in the examples).

➤ Can I change mapping on an existing Jellyfin container?

Yes, but be prepared to fix file ownership:

Stop container
Modify mapping in config
Start container
Run chown -R jellyfin:jellyfin /var/lib/jellyfin inside container

Your media files on the host should maintain correct ownership since they’re already owned by your user.

➤ Should I ever use a privileged container for Jellyfin?

No. There’s no legitimate performance or functionality reason to run Jellyfin in a privileged container. Proper UID mapping gives you the same capabilities with vastly better security.

Conclusion: Media Servers and UID Mapping

UID/GID mapping is what makes secure media servers in Proxmox LXC containers practical. The default isolation protects your host. Custom mapping gives you direct access to media libraries without breaking that isolation.

Your Media Server Checklist

Identify media directory ownership on host (usually UID 1000)
Configure lxc.idmap to map that UID directly
Add bind mounts for media directories
Create or modify media server user to match mapped UID
Test file access from inside container
Verify host sees correct ownership
Configure media server libraries
Run a scan and test playback

Key Takeaways for Media Servers

Use unprivileged containers always. The security benefit is enormous, and the setup is straightforward once you understand UID mapping.

Map your user UID directly. The single-user passthrough pattern (mapping UID 1000 to 1000) handles 90% of media server scenarios.

Document your setup. Write down which UIDs you mapped and why. You’ll thank yourself during troubleshooting or migration.

Test before going live. Verify file access, transcoding, and metadata writing all work before importing your entire library.

Spend an hour on UID/GID mapping now. Save yourself days of permission-denied logs later.

RaspberryPi 4GB This affordable, energy-efficient single-board computer is perfect for beginners wanting to learn about Proxmox LXC containers and UID/GID mappings in a low-risk, hands-on way.

Amazon Price: Loading...

Availability: Checking...

Contains affiliate links. I may earn a commission at no cost to you.

Sources

Tdarr Setup Guide: Install, Configure & Transcode (2026)

Sun, 12 Oct 2025 05:44:47 -0600

If you’ve ever looked at your media collection and wondered why a 4K movie is eating up 50GB of storage while looking identical to a 10GB version, you’re ready for Tdarr. Tdarr handles the tedious work of transcoding your video files, converting them to more efficient formats without sacrificing quality you’ll actually notice.

Tdarr is a complete workflow system. It watches your library, analyzes your files, and optimizes them automatically based on rules you set. Set it up once and it keeps your collection smaller, more compatible, and easier to stream without you touching it again.

In this guide, I’ll walk through setting up Tdarr from scratch. You’ll learn how to install it and configure your first Intel QuickSync transcoding workflow. By the end, you’ll know how to keep your media library optimized without any ongoing effort from you.

Intel® Core™ i5-14500 14th Generation Desktop Processor The Intel® Core™ i5-14500 offers strong single-thread performance and built-in Quick Sync hardware transcoding, making it an excellent CPU for running Tdarr and handling multiple concurrent transcodes. It’s ideal for DIY homelab builders who want efficient, reliable media processing without needing a discrete GPU. This processor is a great foundation for a Tdarr server.

Amazon Price: Loading...

Availability: Checking...

Contains affiliate links. I may earn a commission at no cost to you.

If you manage a large media library, you know the drill: storage fills up fast, and manually transcoding files is about as fun as watching paint dry. This is where Tdarr comes in.

Tdarr is a transcoding and media management tool that handles the grunt work for you. Instead of babysitting HandBrake for hours, you set up rules once and let Tdarr automatically process your entire video collection in the background. It can remove unwanted audio tracks, compress, re-encode, and standardize files based on whatever criteria you define. The point is reclaiming space. Hard drives keep getting more expensive, so it’s worth squeezing what you already have before buying another one.

The standout feature is distributed transcoding. You can spread the workload across multiple machines, turning that old laptop gathering dust into a transcoding workhorse. Set it up once, let it run, and reclaim terabytes of space without sacrificing playable quality. Plex, Jellyfin, and Emby users get the most out of this.

💡

Tip: To run multiple nodes you’ll either need a shared cache and media folder that the server and ALL nodes can access, or a Tdarr Pro subscription for unmapped nodes. I cover both in Scaling Out: Running Multiple Tdarr Nodes below.

This guide only covers installing, configuring, and troubleshooting Tdarr in an unprivileged LXC container. Whether you’re new to transcoding or haven’t touched it since the early HandBrake days, you’ll walk away with a practical setup that saves both time and storage without the usual headaches.

💭

TL;DR: Tdarr automates the tedious job of transcoding and optimizing your media library using flexible, customizable rules. Install it, set up your transcoding preferences through a clean web interface, and optionally scale it across multiple machines for distributed processing. It’s particularly valuable for Jellyfin or Plex server owners and anyone looking to reclaim storage space by converting files (like moving from H.264 to H.265) while maintaining quality.

Why LXC Instead of Docker?

You might be wondering why this guide uses LXC containers instead of Docker, especially since most Tdarr tutorials out there are Docker-based. Here’s the reasoning behind this approach:

Direct Hardware Access

LXC containers run closer to the host system than Docker containers. When you’re sharing an iGPU between multiple services (like Jellyfin and Tdarr), LXC makes hardware passthrough significantly more straightforward. You get:

Simpler GPU sharing: The iGPU can be accessed by multiple LXC containers simultaneously without complex device mapping or privileged modes
Native performance: LXC containers have almost zero overhead compared to bare metal, making them ideal for transcoding workloads
Persistent hardware access: The GPU stays available even after container restarts without additional Docker flags or volume mounts

Resource Isolation Without the Overhead

Docker adds multiple layers of abstraction that aren’t necessary for long-running services like Tdarr. LXC gives you:

Lower memory footprint: No Docker daemon consuming resources in the background
Direct systemd integration: Services start and stop like native system services
Filesystem efficiency: No overlay filesystems slowing down video file I/O operations

Better Integration with Proxmox

If you’re running Proxmox (which most homelabbers are), LXC is first-class:

Native Proxmox management: Create, clone, and backup containers through the web UI
Snapshot support: Take instant snapshots before major configuration changes
Built-in monitoring: Resource usage graphs and stats without installing additional tools
No nested virtualization issues: Docker-in-VM can be problematic; LXC runs natively on the host kernel

When Docker Makes More Sense

Docker is optimized for different use cases:

Portability: If you need to move Tdarr between different hosts frequently, Docker’s image format makes this trivial
Quick testing: Spinning up and destroying Docker containers is faster for experimentation
No Proxmox: If you’re running on bare Ubuntu/Debian without Proxmox, Docker is simpler to set up

For a dedicated media server running on Proxmox where you want maximum transcoding performance and are already sharing GPU resources with other services, LXC is the better architectural choice. You get native performance, simpler hardware access, and better integration with your virtualization platform, all while using fewer system resources.

Understanding Tdarr and Why It Matters

Before we start spinning up containers and tweaking codec settings, let’s get clear on what Tdarr does. And more importantly, what it doesn’t do.

What Is Tdarr?

Tdarr is a conditional transcoding application. It looks at each video file in your library, runs it through a set of rules you define (like “Is this still using H.264?” or “Is the bitrate ridiculously high?”), and then decides whether to transcode it, leave it alone, or skip it entirely.

Picture Tdarr as a quality control inspector on an assembly line. Each file gets examined, processed if needed, and passed along based on the standards you’ve set. Behind the scenes, it uses FFmpeg and HandBrake to do the heavy lifting. You get reliable performance and industry-standard compression without becoming a command-line wizard.

Why Use Tdarr?

Here’s why I swear by Tdarr:

Storage Efficiency: Convert those space-hogging H.264 or MPEG-2 files to modern H.265 (HEVC) and watch your storage usage drop by up to 50% without sacrificing watchable quality.
Uniform Playability: Standardize your codecs and container formats so everything plays smoothly across Plex, Jellyfin, smart TVs, and mobile apps. No more “this format is not supported” messages.
Set-and-Forget Automation: Configure your preferences once, and Tdarr handles the monitoring, processing, and updating automatically. Your media library maintains itself.
Scalability: Add multiple worker nodes for distributed transcoding when you need to process hundreds or thousands of files without waiting weeks.

If you’ve ever watched Jellyfin refuse to play an unsupported codec, or wondered why your server storage is maxed out despite regular cleanup, Tdarr solves both problems for the long haul.

Seagate Barracuda 24TB Internal Hard Drive A large-capacity hard drive like the Seagate Barracuda 24TB is crucial for storing your growing media library and transcoded files managed by Tdarr. Its reliability and size make it perfect for bulk storage in a homelab or media server environment. This drive ensures you have plenty of space for all your media needs.

Amazon Price: Loading...

Availability: Checking...

Contains affiliate links. I may earn a commission at no cost to you.

Step 1: Installing Tdarr via Unprivileged LXC

Why an LXC? Because I’m sharing my iGPU with Jellyfin who is also installed in an LXC.

My Jellyfin guide:
Jellyfin + Intel QuickSync in Unprivileged LXC - The Complete Guide

Prerequisites Checklist

Before starting, ensure you have:

Proxmox VE with an unprivileged LXC running Debian 13
Intel CPU with QuickSync (12th gen or newer recommended)
Basic command-line familiarity
Network access to your LXC container
Media files stored on your Proxmox host with known paths
At least 8GB RAM allocated to the LXC

Add the Debian Non-Free Component

sudo nano /etc/apt/sources.list.d/debian.sources

On the components line add non-free to the end.

Types: deb
URIs: http://deb.debian.org/debian
Suites: trixie trixie-updates
Components: contrib main non-free
Signed-By: /usr/share/keyrings/debian-archive-keyring.gp

Add a new source for MKVToolNix

Pull the gpg key:

wget -O /etc/apt/keyrings/gpg-pub-moritzbunkus.gpg https://mkvtoolnix.download/gpg-pub-moritzbunkus.gpg

Create a new source File:

sudo nano /etc/apt/sources.list.d/mkvtoolnix.sources

Paste this:

Types: deb
URIs: https://mkvtoolnix.download/debian/
Suites: trixie
Components: main
Signed-By: /etc/apt/keyrings/gpg-pub-moritzbunkus.gpg

Install HandBrake, ffmpeg, MKVtoolNix and other required tools

sudo apt update && sudo apt install -y sudo curl unzip ca-certificates gnupg wget vainfo libva2 intel-media-va-driver-non-free libva-drm2 libva2 pciutils handbrake-cli ffmpeg mkvtoolnix

💡

Tip: I install ffmpeg and handbrake outside of Tdarr because I find it is easier to maintain.

Add Users and Groups

Create your media group that has read and write access to your media files. I use media with a gid of 1001 for mine make sure to use yours if it is different.

sudo addgroup --gid 1001 media

Create the Tdarr User:

sudo useradd -r -m -d /opt/tdarr -s /usr/sbin/nologin tdarr

Add the video, render and media groups to the Tdarr user:

sudo usermod -aG render,video,media tdarr

Reset the group membership without logging out:

sudo loginctl enable-linger tdarr 2>/dev/null || true

Step 2: LXC Config Changes

Stop the container. Add these lines to your /etc/pve/lxc/CT#.conf

# Bind mounts your media to the LXC
mp0: /media/Storage/Movies,mp=/media/Movies
mp1: /media/Storage/Shows,mp=/media/Shows
# Maps permissions to the host
lxc.idmap: u 0 100000 65536
lxc.idmap: g 0 100000 992
lxc.idmap: g 992 104 1 # 992 is the LXC's Render GID and 104 is the Host's
lxc.idmap: g 993 100994 7
lxc.idmap: g 1001 1001 1 # 1001 is both the LXC's and Host's GID for my media group
lxc.idmap: g 1002 101002 64534
# Passthrough the iGPU
lxc.mount.entry: /dev/dri/ dev/dri/ none bind,optional,create=dir
lxc.cgroup2.devices.allow: c 226:* rwm

Here is my Host’s /etc/subgid file:

root:1000:1
root:1001:1
root:100000:65536
# Render Group
root:104:1
# Media Group
root:1001:1

These lines need to be in here to properly map the GIDs for permissions to work properly. Restart the container.

💡

Tip: Understanding ID Mapping - These lxc.idmap lines map user and group IDs between your LXC container and the Proxmox host. This allows the tdarr user inside the container to access your media files and the GPU on the host. The numbers (992, 1001, etc.) must match your specific system. If you’re unfamiliar with LXC ID mapping, check out Unprivileged LXC containers first.

Step 3: Install Tdarr

Now we are ready to install Tdarr

Navigate to /opt/tdarr:

cd /opt/tdarr

Pull the Tdarr install script:

wget https://storage.tdarr.io/versions/2.17.01/linux_x64/Tdarr_Updater.zip

💡

Tip: Tdarr_Updater is a bootstrapper, not a pinned release. Even though the URL says 2.17.01, running it installs the latest stable Tdarr, so you’ll land on a current build. That matters if you plan to use newer features like unmapped nodes, which need Tdarr 2.27.01 or later.

Unzip the install package:

unzip Tdarr_Updater.zip

Create two additional directories for Tdarr’s temporary files and cache:

mkdir temp cache

Make the script executable:

sudo chmod +x Tdarr_Updater

Run the installer:

sudo ./Tdarr_Updater

💡

Tip: Run groups tdarr and verify you see: tdarr video render media

Initial Tdarr Run

Initial Run of Tdarr_Server:

/opt/tdarr/Tdarr_Server/Tdarr_Server

Let this run for a minute or so. Errors are fine for now. We are creating the JSON config file.

Initial run of Tdarr_Node:

/opt/tdarr/Tdarr_Node/Tdarr_Node

Again errors are fine.

Now set the owner for the Tdarr folders:

sudo chown -R tdarr:tdarr /opt/tdarr/

Tdarr Server JSON Config

You now have a basic config file for the server. We need to set the serverIP, handbrakePath, and ffmpegPath

nano /opt/tdarr/configs/Tdarr_Server_Config.json

After modifying, it should look something like this:

{
 "serverPort": "8266",
 "webUIPort": "8265",
 "serverIP": "192.168.1.14",
 "serverBindIP": false,
 "serverDualStack": false,
 "handbrakePath": "/usr/bin/HandBrakeCLI",
 "ffmpegPath": "/usr/bin/ffmpeg",
 "logLevel": "INFO",
 "mkvpropeditPath": "",
 "ccextractorPath": "",
 "openBrowser": true,
 "cronPluginUpdate": "",
 "auth": false,
 "authSecretKey": "tsec_NotARealKey",
 "maxLogSizeMB": 10,
 "seededApiKey": ""
}

Tdarr Node JSON Config

open the basic config file. We need to set serverURL, ServerIP, handbrakePath, ffmpegPath, and mkvpropeditPath

nano /opt/tdarr/configs/Tdarr_Node_Config.json

After modifying, it should look something like this:

{
 "nodeName": "jaded-joey",
 "serverURL": "http://192.168.1.14:8266",
 "serverIP": "192.168.1.14",
 "serverPort": "8266",
 "handbrakePath": "/usr/bin/HandBrakeCLI",
 "ffmpegPath": "/usr/bin/ffmpeg",
 "mkvpropeditPath": "/usr/bin/mkvpropedit",
 "pathTranslators": [
 {
 "server": "",
 "node": ""
 }
 ],
 "nodeType": "mapped",
 "unmappedNodeCache": "/opt/tdarr/unmappedNodeCache",
 "logLevel": "INFO",
 "priority": -1,
 "cronPluginUpdate": "",
 "apiKey": "",
 "maxLogSizeMB": 10,
 "pollInterval": 2000,
 "startPaused": false
}

Create Tdarr Services

To make sure it starts automatically we need to create two services. One for the server and one for the node.

Server

sudo nano /etc/systemd/system/tdarr-server.service

Paste this:

[Unit]
Description=Tdarr Server
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=tdarr
Group=tdarr
WorkingDirectory=/opt/tdarr/Tdarr_Server
Environment=TDARR_DATA=/opt/tdarr/configs
Environment=TDARR_LOGS=/opt/tdarr/logs
ExecStart=/opt/tdarr/Tdarr_Server/Tdarr_Server
Restart=on-failure
# Resource limits (tune as desired)
CPUAccounting=true
MemoryAccounting=true
CPUQuota=100%
MemoryMax=2G

[Install]
WantedBy=multi-user.target

Node

sudo nano /etc/systemd/system/tdarr-node.service

Paste this (Make sure to change the TDARR_SERVER_HOST to your IP):

[Unit]
Description=Tdarr Node
After=tdarr-server.service
Wants=tdarr-server.service

[Service]
Type=simple
User=tdarr
Group=tdarr
WorkingDirectory=/opt/tdarr/Tdarr_Node
Environment=TDARR_NODE_NAME=tdarr-node-01
Environment=TDARR_SERVER_HOST=192.168.1.14
Environment=TDARR_FFMPEG=/usr/bin/ffmpeg
Environment=TDARR_LOGS=/opt/tdarr/logs
Environment=TDARR_TEMP=/opt/tdarr/temp
Environment=TDARR_CACHE=/opt/tdarr/cache
ExecStart=/opt/tdarr/Tdarr_Node/Tdarr_Node
Restart=on-failure
# Resource limits (tune as desired)
CPUAccounting=true
MemoryAccounting=true
CPUQuota=150%
MemoryMax=6G
IOSchedulingClass=best-effort
IOSchedulingPriority=7

[Install]
WantedBy=multi-user.target

Enable and Start the new Services

sudo systemctl daemon-reload
sudo systemctl enable tdarr-server
sudo systemctl start tdarr-server
sudo systemctl enable tdarr-node
sudo systemctl start tdarr-node

Check the status of the services to make sure they are running:

Server

sudo systemctl status tdarr-server

Should look like this:

* tdarr-server.service - Tdarr Server
 Loaded: loaded (/etc/systemd/system/tdarr-server.service; enabled; preset: enabled)
 Active: active (running) since Wed 2025-10-15 11:15:48 MDT; 1 day 20h ago
 Invocation: 5adc45d529564e898b9e51e29917de75
 Main PID: 7535 (Tdarr_Server)
 Tasks: 21 (limit: 76615)
 Memory: 281.5M (max: 2G, available: 1.7G, peak: 2G, swap: 31.6M, swap peak: 38.3M)
 CPU: 42min 13.105s
 CGroup: /system.slice/tdarr-server.service
 |-7535 /opt/tdarr/Tdarr_Server/Tdarr_Server
 `-7541 Tdarr_Server

Node

sudo systemctl status tdarr-node

Should look like this:

* tdarr-node.service - Tdarr Node
 Loaded: loaded (/etc/systemd/system/tdarr-node.service; enabled; preset: enabled)
 Active: active (running) since Wed 2025-10-15 11:44:19 MDT; 1 day 20h ago
 Invocation: 40a1033a1c984181a6f4c4c399398d4b
 Main PID: 8673 (Tdarr_Node)
 Tasks: 187 (limit: 76615)
 Memory: 2.7G (max: 6G, available: 3.2G, peak: 6G, swap: 11.3M, swap peak: 184.3M)
 CPU: 5h 37min 41.929s
 CGroup: /system.slice/tdarr-node.service

Step 4: Testing QuickSync

Before we go any further we need to make sure QuickSync is working.

Run this quick test

sudo -u tdarr env LIBVA_DRIVER_NAME=iHD \
 vainfo --display drm --device /dev/dri/renderD128 | head -n 60

➤ Expected Results


libva info: VA-API version 1.22.0
libva info: User environment variable requested driver 'iHD'
libva info: Trying to open /usr/lib/x86_64-linux-gnu/dri/iHD_drv_video.so
libva info: Found init function __vaDriverInit_1_22
libva info: va_openDriver() returns 0
Trying display: drm
vainfo: VA-API version: 1.22 (libva 2.22.0)
vainfo: Driver version: Intel iHD driver for Intel(R) Gen Graphics - 25.2.3 ()
vainfo: Supported profile and entrypoints
VAProfileNone : VAEntrypointVideoProc
VAProfileNone : VAEntrypointStats
VAProfileMPEG2Simple : VAEntrypointVLD
VAProfileMPEG2Simple : VAEntrypointEncSlice
VAProfileMPEG2Main : VAEntrypointVLD
VAProfileMPEG2Main : VAEntrypointEncSlice
VAProfileH264Main : VAEntrypointVLD
VAProfileH264Main : VAEntrypointEncSlice
VAProfileH264Main : VAEntrypointFEI
VAProfileH264Main : VAEntrypointEncSliceLP
VAProfileH264High : VAEntrypointVLD
VAProfileH264High : VAEntrypointEncSlice
VAProfileH264High : VAEntrypointFEI
VAProfileH264High : VAEntrypointEncSliceLP
VAProfileVC1Simple : VAEntrypointVLD
VAProfileVC1Main : VAEntrypointVLD
VAProfileVC1Advanced : VAEntrypointVLD
VAProfileJPEGBaseline : VAEntrypointVLD
VAProfileJPEGBaseline : VAEntrypointEncPicture
VAProfileH264ConstrainedBaseline: VAEntrypointVLD
VAProfileH264ConstrainedBaseline: VAEntrypointEncSlice
VAProfileH264ConstrainedBaseline: VAEntrypointFEI
VAProfileH264ConstrainedBaseline: VAEntrypointEncSliceLP
VAProfileHEVCMain : VAEntrypointVLD
VAProfileHEVCMain : VAEntrypointEncSlice
VAProfileHEVCMain : VAEntrypointFEI
VAProfileHEVCMain : VAEntrypointEncSliceLP
VAProfileHEVCMain10 : VAEntrypointVLD
VAProfileHEVCMain10 : VAEntrypointEncSlice
VAProfileHEVCMain10 : VAEntrypointEncSliceLP
VAProfileVP9Profile0 : VAEntrypointVLD
VAProfileVP9Profile0 : VAEntrypointEncSliceLP
VAProfileVP9Profile1 : VAEntrypointVLD
VAProfileVP9Profile1 : VAEntrypointEncSliceLP
VAProfileVP9Profile2 : VAEntrypointVLD
VAProfileVP9Profile2 : VAEntrypointEncSliceLP
VAProfileVP9Profile3 : VAEntrypointVLD
VAProfileVP9Profile3 : VAEntrypointEncSliceLP
VAProfileHEVCMain12 : VAEntrypointVLD
VAProfileHEVCMain12 : VAEntrypointEncSlice
VAProfileHEVCMain422_10 : VAEntrypointVLD
VAProfileHEVCMain422_10 : VAEntrypointEncSlice
VAProfileHEVCMain422_12 : VAEntrypointVLD
VAProfileHEVCMain422_12 : VAEntrypointEncSlice
VAProfileHEVCMain444 : VAEntrypointVLD
VAProfileHEVCMain444 : VAEntrypointEncSliceLP
VAProfileHEVCMain444_10 : VAEntrypointVLD
VAProfileHEVCMain444_10 : VAEntrypointEncSliceLP
VAProfileHEVCMain444_12 : VAEntrypointVLD
VAProfileHEVCSccMain : VAEntrypointVLD
VAProfileHEVCSccMain : VAEntrypointEncSliceLP
VAProfileHEVCSccMain10 : VAEntrypointVLD
VAProfileHEVCSccMain10 : VAEntrypointEncSliceLP
VAProfileHEVCSccMain444 : VAEntrypointVLD
VAProfileHEVCSccMain444 : VAEntrypointEncSliceLP
VAProfileAV1Profile0 : VAEntrypointVLD

If you see Driver version: Intel iHD driver for Intel(R) Gen Graphics - 25.2.3 it is working and we can move on to installing Tdarr.

ℹ️

Info: Performance Expectations - With Intel QuickSync enabled, a typical 2-hour 1080p movie (H.264 to H.265) transcodes in 15-30 minutes depending on your CPU generation. Without hardware acceleration, the same file could take 2-4 hours. If transcodes are taking longer than expected, verify QuickSync is actually being used by checking GPU utilization: intel_gpu_top

Step 5: Access the web interface & Initial Configuration Walkthrough

Open your browser and navigate to: http://YourServerIP:8265.
The Tdarr dashboard should greet you, ready for configuration.

If it opens CONGRATULATIONS! you have Tdarr up and running.

⚠️

Warning: Security Consideration - Tdarr’s web interface (port 8265) has no authentication enabled by default in this configuration. If your server is exposed to the internet, either enable authentication in /opt/tdarr/configs/Tdarr_Server_Config.json by setting "auth": true and configuring credentials, or restrict access using your firewall. For local network-only use, this isn’t a concern.

When you first access Tdarr, you’ll see the main dashboard with several tabs across the top. Here’s what to do first:

Verify Your Node is Connected

Look for the Nodes section on the main page
You should see your node listed (named something like “jaded-joey”)
Click on the node name to see detailed stats

If your node isn’t showing up:

Double-check the node service is running: sudo systemctl status tdarr-node
Verify the serverIP matches in both JSON configs
Check the logs: sudo journalctl -u tdarr-node -f

This is what it should look like:

Configure Hardware Acceleration

Before adding libraries, make sure Tdarr knows to use QuickSync:

Click on your node in the Nodes tab
Scroll down to Transcode Options
Under Hardware Encoding, select “Any (nvenc,qsv,vaapi)”
Save the changes

This ensures Tdarr uses your iGPU instead of hammering your CPU.

ASRock Intel Arc A580 Challenger 8GB OC The ASRock Intel Arc A580 Challenger provides modern hardware transcoding support (AV1/HEVC/H.264), which is essential for efficient and fast media processing in Tdarr. Two media engines mean it keeps absorbing work as the queue grows, and offloading those tasks from your CPU keeps the rest of the server responsive. A solid way to boost your Tdarr setup for self-hosted media servers.

Amazon Price: Loading...

Availability: Checking...

Contains affiliate links. I may earn a commission at no cost to you.

Step 6: Getting Comfortable With Tdarr

Now for the fun part: Tdarr’s web dashboard is your command center for everything media transcoding. The interface is refreshingly straightforward, organized into four main sections that make sense:

Libraries: Tell Tdarr which folders to watch and process
Transcode Settings: Set up your conversion rules and choose plugins
Nodes: Monitor your transcoding workers (yes, you can run multiple)
Logs: Watch the real-time activity feed and catch any hiccups

Setting Up Your First Library

Time to point Tdarr at your media collection. This is where those bind mount mappings from earlier pay off:

In the sidebar, click Libraries → Add Library.
Give it a descriptive name like “Movies” or “TV Shows” (you’ll thank yourself later).
Set the folder path to match what you mapped in your LXC (like /media/Movies).
Set the library type to “Video.”
Click Save.

Tdarr immediately starts scanning that directory, cataloging every video file it finds. Depending on your collection size, this initial scan might take a few minutes, but you’ll see the progress in real time through the logs.

Step 7: Defining Transcoding Rules

Here’s where Tdarr gets interesting. Rules are the brain of your operation: they decide which files get processed and how.

Creating Conditional Rules

Every rule follows a simple IF → THEN logic. If a file meets certain conditions, Tdarr takes a specific action. For example:

Condition: File codec is H.264
Action: Transcode to H.265

Setting this up is straightforward:

Navigate to the Plugins & Settings menu.
Add a new plugin chain for your library.
Select relevant plugins (e.g., “Transcode using FFmpeg to H.265”).
Adjust plugin parameters like bitrate or CRF (Constant Rate Factor) for quality control.
Add pre-check plugins like “Skip file if already H.265” to avoid unnecessary work.

Once configured, Tdarr automatically queues any file that doesn’t meet your requirements for conversion. No more manual checking or guesswork.

Choosing the Right Codec and Container

Your codec and container choices should match where you actually watch your content. There’s no point optimizing for mobile if you’re streaming to a 65-inch TV.

Playback Environment	Recommended Codec	Container	Notes
Plex / Jellyfin	H.265 (HEVC)	MKV or MP4	Widely supported, efficient
Direct-to-TV	H.264 (AVC)	MP4	Safest, but larger size
Mobile	H.265	MP4	Excellent compression
Archival Storage	H.265 + 10-bit	MKV	High quality, smaller storage

For most home server setups, H.265 MKV hits the sweet spot: great compression, broad compatibility, and future-proof enough that you won’t be doing this again next year.

A Practical Example: H.264 to H.265 Conversion

Here’s how to set up a real transcoding rule. This example converts H.264 files to H.265 while maintaining quality:

Navigate to Libraries and select your library
Click Transcode Options → Plugin Stack
In the Pre-Processing section, add:
- Check if file is H264 (this filters which files to process)
In the Transcode section, add:
- Transcode using FFmpeg - H265 QuickSync
Configure the plugin settings:
- CRF: Set to 23 (good balance of quality/size)
- Preset: Use “medium”
- Hardware Acceleration: Enabled
In Post-Processing, add:
- Check file health (validates the transcode worked)
Click Save Plugin Stack

Now Tdarr will automatically:

Scan your library for H.264 files
Transcode them to H.265 using your iGPU
Verify the output is valid
Replace the original file (or keep both, depending on your settings)

Here is what I’m currently using:

Start with one folder to test before applying this to your entire library.

Monitoring Your Transcodes

Once you’ve set up your rules, here’s how to track what’s happening:

Check the Queue:

Go to Transcode → Queue to see pending files
The queue shows how many files are waiting and their estimated completion time

Watch Active Transcodes:

Click the Staging tab to see files currently being processed
You’ll see real-time stats: current FPS, progress percentage, and time remaining

Review Completed Files:

The Transcode → History tab shows finished jobs
Look for the “Healthy” status to confirm successful transcodes
Check the space savings column to see how much storage you’ve reclaimed

💡

Tip: Keep the logs open in a second browser tab (sudo journalctl -u tdarr-node -f in terminal) to catch any errors early.

Step 8: Verifying Output Quality

Here’s the thing about Tdarr: it’ll happily transcode your entire library without questioning whether the results actually look good. Quality control is entirely on you, which means you need to define what “acceptable” means for your setup.

Options for Quality Verification

Visual spot-checking: Grab a few random transcoded videos and watch them side-by-side with the originals. Your eyes are still the best quality detector.
Bitrate inspection: Fire up MediaInfo or similar tools to verify the output bitrate and codec specs match what you configured.
Plugin-based checks: Some community plugins can automate verification by comparing resolution, color depth, or other metrics before marking a transcode as complete.

If your output quality isn’t hitting the mark, start by tweaking your CRF value. Remember: lower CRF means higher quality but larger file sizes. You can also adjust bitrate ceilings if you’re using constant bitrate encoding instead.

Run the chain against a folder of twenty files before you point it at the whole library. If those look right at CRF 23, the rest will too, and if they don’t you’ve only burned twenty transcodes finding out.

Sparkle Intel Arc B580 Titan A midrange Battlemage card with 12GB GDDR6 and a tri-fan TORN 2.0 cooler that punches hard at 1080p–1440p, plus full-stack media engines (AV1/HEVC/H.264 encode/decode) that make it great for gaming rigs or Plex/Jellyfin transcoding. Outputs include HDMI 2.1 and DP 2.1 with support for up to four displays.

Amazon Price: Loading...

Availability: Checking...

Contains affiliate links. I may earn a commission at no cost to you.

Step 9: Common Pitfalls & How to Avoid Them

Even with the best setup, Tdarr can throw you some curveballs. Here are the mistakes that trip up most people and how to dodge them:

Pitfall	Description	Solution
Missing codecs	FFmpeg plugins fail due to missing libraries	Use official FFmpeg installations
Slow transcoding	Low CPU or using software encoding	Enable hardware acceleration if supported (e.g., Intel Quick Sync, NVIDIA NVENC)
Files not being processed	Rule misconfiguration	Double-check rule logic (“if already H.265” can skip intended files)
Node not connecting	Firewall or wrong IP	Verify `Tdarr_ServerIP` and matching port (8266)
No storage gain	Using generous bitrate	Lower CRF or target bitrate levels in transcoding profile

The “files not being processed” issue deserves special attention. I’ve seen people scratch their heads for hours because they set up a rule that says “skip if already H.265” but then wonder why their H.265 files aren’t getting processed. The rule is doing exactly what you told it to do.

💡

Tip: Test incrementally. Always run Tdarr on a small library first (like your “Short Clips” folder) before letting it loose on terabytes of data.

This is essential. Nothing quite compares to watching Tdarr churn through your entire movie collection only to discover you misconfigured something fundamental. Start small, verify everything works, then scale up.

Scaling Out: Running Multiple Tdarr Nodes

The single biggest reason people run Tdarr is also the part the basic setup skips: spreading transcodes across more than one machine. A single node is fine for a few hundred files, but if you’re re-encoding a multi-terabyte library, adding a second or third node turns a week-long job into an overnight one.

Here’s the part that trips everyone up. The Tdarr server only holds the queue and the database. The nodes do the actual transcoding, and every node has to be able to read and write the files it’s working on. How you solve that is what separates a free multi-node setup from a paid one.

How Tdarr Nodes Work

Your server runs the web UI on port 8265 and the job queue on port 8266. Each node connects back to the server on port 8266, pulls jobs from the queue, transcodes them, and reports back. You already built one node on the same box as your server in the steps above. A second node is the same Tdarr_Node install on another machine, pointed at the server’s IP.

Option 1: Mapped Nodes (Free, Shared Storage)

This is the standard, free approach, and it’s what I run. Every node mounts the same media and cache storage over the network (NFS or SMB), so when a node grabs a job it can reach the file at a path it understands.

Put your media and Tdarr cache on shared storage, typically an NFS export from your NAS. Both the server and every node mount it.
Install Tdarr_Node on the second machine. Repeat the node install from Step 3 (you only need the Tdarr_Node package, not the server) and create its Tdarr_Node_Config.json.
Point the node at your server. Set serverURL and serverIP to your main Tdarr server’s address, leaving serverPort at 8266.
Translate the paths if they differ. If the second machine mounts the share at a different path than the server (say /mnt/media instead of /media), fill in the pathTranslators block in the node config so Tdarr rewrites file paths between server and node:
```
"pathTranslators": [
 {
 "server": "/media",
 "node": "/mnt/media"
 }
],
```
Start the node service (the same tdarr-node.service from earlier) and confirm the new node appears under Nodes in the web UI.

If every machine mounts the share at the same path, you can leave pathTranslators empty, since the paths already match.

Option 2: Unmapped Nodes (Tdarr Pro)

If sharing storage isn’t practical, say a node in another location or a machine you can’t mount your NAS on, Tdarr’s unmapped nodes (Tdarr 2.27.01+) download the working file to the node, transcode it, and upload it back automatically. No shared mounts required.

The catch: on free Tdarr, unmapped nodes are capped at 10MB per video file, which is fine for testing and useless for real movies. Tdarr Pro removes that limit and lets unmapped nodes process files of any size. Unmapped nodes also only run plugins that act on the working file itself (transcoding, remuxing); plugins that write side files like extracted subtitles won’t run on them.

So here’s the honest decision. If you can share storage, mapped nodes are free and unlimited. Use them. If you genuinely can’t, Tdarr Pro is what makes unmapped nodes practical. Pricing is set on the official Tdarr site and changes from time to time, so check there for the current figure.

Troubleshooting Tdarr

Even the best Tdarr setup will occasionally throw you a curveball. Here are the most common issues you’ll encounter and how to fix them without losing your sanity:

Problem 1: “Plugin failed” messages

When plugins refuse to cooperate, it’s usually one of these culprits:

Possible causes:

Syntax errors in parameters
Missing dependency
FFmpeg unable to read specific container types

Fix:

Update to the latest Tdarr first. Half the time, someone already fixed your problem.
Double-check plugin settings against the FFmpeg syntax.
Try another plugin (e.g., HandBrake-based instead of FFmpeg).

Problem 2: Transcodes crawling along at glacial speed

Nothing kills enthusiasm like watching a 2-hour movie take 8 hours to transcode.

Possible causes:

Software-only encoding (your CPU is doing all the heavy lifting)
High CRF (quality) or filters causing slowdowns
Storage bottleneck from slow I/O

Fix:

Ensure your hardware acceleration for your iGPU is working.
Test with a higher CRF number or skip extra filters temporarily.

Problem 3: Quality looks terrible

Fix:

Lower your CRF value (e.g., from 28 to 23). Lower numbers mean better quality.
Use two-pass encoding for higher fidelity when quality matters most.
Make sure you’re not transcoding already compressed H.265 files again unnecessarily. That’s like photocopying a photocopy.

FAQs About Tdarr

➤ What is the primary purpose of Tdarr?

Tdarr automates the tedious work of media management by transcoding your files according to rules you set up once and forget about. Think of it as your personal media librarian that standardizes formats, shrinks file sizes, and makes sure everything plays nicely across all your devices [Tdarr Docs].

➤ How does Tdarr handle distributed transcoding?

Tdarr supports multi-node distributed transcoding, which is a fancy way of saying it can use multiple computers at once. Each node connects to your main Tdarr server and grabs jobs from the queue, processing them in parallel. This lets you throw more hardware at big libraries and see the transcoding finish before you retire.

➤ Can Tdarr be used with Jellyfin or Plex?

Absolutely. Tdarr and Plex work together like peanut butter and jelly. Use Tdarr to preprocess your entire library, ensuring every video file meets Plex’s supported codec and container requirements. When Plex streams your content, it can serve files directly without burning CPU cycles on real-time transcoding. Your server stays cool, your electricity bill stays reasonable, and your family stops complaining about buffering.

➤ How do I verify the quality of transcoded files?

Here’s the thing: Tdarr doesn’t judge quality for you. It follows orders. You’ll need to use community verification plugins or do some manual spot-checking by playing back sample files and comparing metadata. A good practice is to transcode a few test files first and make sure you’re happy with the results before unleashing Tdarr on your entire collection.

➤ What are common transcoding options?

The most popular move is converting H.264 to H.265 (also called HEVC). This typically cuts file sizes by 30-50% while keeping the visual quality nearly identical. Other useful rules include converting audio tracks from DTS to AAC for better device compatibility, especially if you have mobile devices or streaming sticks that get picky about audio formats.

➤ What ports does Tdarr use?

By default Tdarr uses two ports: 8265 for the web interface (the dashboard you open in your browser) and 8266 for server–node communication. Worker nodes connect to the server on port 8266, so if you run nodes on other machines, that’s the port that needs to be reachable. Both are set in Tdarr_Server_Config.json (webUIPort and serverPort) and can be changed if they clash with something else.

➤ Do I need Tdarr Pro, and what does it cost?

For a single node, or multiple nodes that share storage over NFS/SMB, you don’t need Tdarr Pro; the free version is fully featured for that. Pro’s main draw is unmapped nodes: free Tdarr caps unmapped (auto-transferred) files at 10MB, and Pro removes that limit so you can transcode full-size files on nodes that can’t reach your shared storage. It also helps fund the project. Pricing is set on the official Tdarr site and changes from time to time, so check there for the current figure.

Wrapping Up

Once Tdarr is running, it quietly works through your library on a schedule. The combination of rule-based automation and distributed transcoding means you set the codec, container, and CRF targets once and let the node chew through the queue. For Plex and Jellyfin owners with terabytes of H.264 sitting on spinning disks, the storage reclaim is real and the playback compatibility gets better at the same time.

If you’ve been putting off optimizing your library, point Tdarr at a single folder this weekend before turning it loose on the whole collection.

Only stripping junk audio and subtitle tracks, not re-encoding video? Tdarr is more infrastructure than that one job needs. A lossless mkvmerge remux does it in seconds. I tore Tdarr down for exactly this task and automated it with a SABnzbd hook and a cron sweep:

Automated MKV Cleanup With mkvmerge, SABnzbd & Cron

Next Steps

Read Tdarr’s official documentation for advanced plugin scripting.
Confirm hardware acceleration is active under load with intel_gpu_top while a transcode runs.
Build a second plugin stack for your TV shows that targets a different CRF or container than your movies.
Join the Tdarr community forum to trade plugin recipes and troubleshooting tips.

The Complete Guide to Securing SSH on Your Server

Wed, 17 Sep 2025 11:15:50 -0600

If you run a Linux server, you probably use SSH to connect. Attackers know that too. The second port 22 is open to the internet, bots start hammering it with brute-force login attempts. I’ve watched fresh servers rack up thousands of attempts within hours of going online.

Weak passwords, outdated cryptography, or a sloppy config can turn that background noise into a real problem. Data breach. Ransomware. Your box getting drafted into someone else’s botnet. All of that is on the table when SSH is left soft.

So securing SSH is the first thing you do on any new server, not the last. A handful of config changes raises the bar high enough that most attackers move on to easier targets.

By the end of this guide, you’ll have a checklist you can run through on every server you touch. Don’t wait until you’re done reading. Apply each step as you go.

💭

TL;DR: Ditch passwords for SSH keys, lock down root, tighten sshd_config, fix file permissions, deploy Fail2ban for brute-force protection, and watch your logs. If SSH must face the internet, put it behind a VPN.

Glovary N150 Firewall Mini PC This fanless N150 appliance runs pfSense or OPNsense, which gives you a clean place to gate SSH access for a homelab or media server. Six Intel i226-V 2.5GbE ports and hardware AES-NI keep routing fast under load, and the firewall rules are flexible enough to lock SSH down to specific source IPs or a VPN subnet. A solid pick if you want a dedicated edge device handling remote access instead of trusting your ISP router.

Amazon Price: Loading...

Availability: Checking...

Contains affiliate links. I may earn a commission at no cost to you.

A firewall appliance like that solves the network side of the problem. The rest of the work happens on the server itself, starting with how you authenticate.

Step 1: Generate a Secure SSH Key Pair

Password authentication over SSH is like leaving your house key under the doormat. It works, sure. Every bot on the internet is also happy to spend all day guessing your password. Key-based authentication is practically unbreakable when you use modern algorithms.

To set up key-based authentication, you need to create the keys first. This works the same on Linux, macOS, and Windows (PowerShell or WSL).

Run this on your client machine to create the key pair:

ssh-keygen -t ed25519

The ed25519 algorithm generates keys that are both smaller and more secure than the older RSA standard. If you’re stuck on an older system that doesn’t support ed25519, fall back to this:

ssh-keygen -t rsa -b 4096

This creates two files: a private key (which you guard with your life) and a public key (which you can share freely). By default, both keys land in your .ssh folder (~/.ssh/ on Linux and macOS, C:\Users\YourName\.ssh on Windows).

💡

Tip: Always set a passphrase on your private key. It’s your last line of defense if someone gets physical access to your laptop or workstation.

Step 2: Deploy Your Public Key to the Server

Now you need to tell the server to trust your public key.

Automatic method (the easy way):

ssh-copy-id user@server_address

This does all the heavy lifting for you. It copies your public key and appends it to the right place on the server.

Manual method (when you want control):

Copy the contents of your ~/.ssh/id_ed25519.pub file
Append it to the server’s ~/.ssh/authorized_keys file

Here’s the thing. Your first login still needs your password because the server hasn’t seen your key yet. Once the key is in place, you can disable password authentication entirely and never type that password again for SSH.

MINISFORUM MS-A2 Dual 10GbE SFP+ and dual 2.5GbE on a compact box makes the MS-A2 a strong fit for a homelab gateway or jump host. The networking headroom means you can run a hardened SSH server, a VPN endpoint, and a handful of containers without choking the link. Flexible storage and modern Ryzen silicon also give you room to spin up extra services as your lab grows.

Amazon Price: Loading...

Availability: Checking...

Contains affiliate links. I may earn a commission at no cost to you.

Once your hardware is sorted and the key is on the server, the next job is to slam the SSH daemon’s defaults shut.

Step 3: Secure the SSH Configuration

The real power of SSH security lives in /etc/ssh/sshd_config. This is where you harden the entry point and raise the bar high enough that attackers move on to softer targets.

Open it with:

sudo nano /etc/ssh/sshd_config

Here are the most important changes:

Disable password authentication
This kills brute-force attacks dead.

PasswordAuthentication no

⚠️

Warning: Test your key-based login in a separate terminal session before making this change. Getting locked out of your own server is embarrassing and fixable, but it requires console access.

Disable root login
Never let root log in directly through SSH. Log in as your regular user and escalate with sudo when needed.

PermitRootLogin no

Change the SSH port (optional)
Moving off port 22 cuts down on automated bot noise. It won’t stop a determined attacker, but it cleans up your logs.

Port 2222

If you change this, update your firewall rules at the same time. Don’t leave it for later.

Enforce modern encryption
Force SSH to use strong ciphers and message authentication codes. This prevents fallback to weaker algorithms.

Ciphers aes256-ctr,aes192-ctr,aes128-ctr
MACs hmac-sha2-256,hmac-sha2-512

Restrict user access
Limit SSH to specific users or groups instead of allowing every account on the box:

AllowUsers youruser

After making these changes, restart SSH to apply them:

sudo systemctl restart ssh

On some distributions the service is named sshd instead of ssh. If the first command errors out, try sudo systemctl restart sshd.

Your SSH config is now meaningfully tighter than the defaults. These settings layer together, so an attacker who beats one still has to beat the others.

Step 4: Set Correct File Permissions

SSH has strong opinions about file permissions, and it’s not shy about telling you when they’re wrong. If your .ssh directory or its files are too open, SSH will flat-out refuse to use them. Think of it as SSH protecting you from yourself.

Here are the correct permissions:

chmod 700 ~/.ssh
chmod 600 ~/.ssh/id_ed25519
chmod 644 ~/.ssh/id_ed25519.pub
chmod 600 ~/.ssh/authorized_keys

Breaking this down:

700 on the .ssh directory means only you can read, write, or enter it
600 on private keys means only you can read or write them
644 on the public key allows others to read it, which is fine because it’s public
600 on authorized_keys keeps it private to your account

If you’re seeing “bad owner or permissions on .ssh/config” errors, these settings will almost certainly fix it. SSH is picky about security, but once the permissions are right it works reliably.

RaspberryPi 4GB A Pi 4 with 4GB is a cheap, low-power way to practice SSH hardening on real hardware without putting a production server at risk. Spin up Ubuntu Server or Raspberry Pi OS, run through every step in this guide, and break it on purpose so you know what the failure modes look like. Once you’re confident, repeat the playbook on the box that matters.

Amazon Price: Loading...

Availability: Checking...

Contains affiliate links. I may earn a commission at no cost to you.

With the host hardened, you still need to think about what can reach it from the network.

Step 5: Harden Network Access

Your SSH service is now using keys and saner settings. Good. But if attackers can reach it from anywhere on the internet, you need more layers. Great lock on the front door, sure. Now stop putting the door on the street.

Firewalls
Limit SSH to specific source IPs where you can. This is your first line of defense. Example using UFW (Uncomplicated Firewall):

sudo ufw allow from 203.0.113.10 to any port 2222

VPN or Bastion Host
Put SSH behind a VPN. WireGuard or OpenVPN both work. This stops the whole internet from probing every machine you own. Only hosts on the VPN can see SSH at all.

Fail2ban
Fail2ban scans logs and bans IPs that show malicious behavior, like repeated failed login attempts. Install it on Debian or Ubuntu with:

sudo apt install fail2ban

Then configure /etc/fail2ban/jail.local for the sshd jail. Even with passwords disabled, Fail2ban still blocks port-scanning noise and keeps your logs cleaner. Think of it as a bouncer who remembers troublemakers and won’t let them back in.

➤ A good Fail2Ban Starting Config for SSHD

[DEFAULT]
# Whitelist: your trusted networks and admin IPs that should never be banned.
# Replace the placeholders with your real IPs/subnets.
ignoreip = 127.0.0.1/8 ::1 192.168.1.0/24 10.0.0.0/24

# How long to ban an offender (and enable incremental bans).
bantime = 1h
bantime.increment = true
bantime.factor = 2
bantime.maxtime = 1w

# How far back to count failures, and how many failures trigger a ban.
findtime = 10m
maxretry = 5

# Use the systemd journal for log parsing.
backend = systemd

# Use nftables if your distro uses it. Fall back to iptables if needed.
banaction = nftables-multiport

# -----------------------------------
# SSH JAIL
# -----------------------------------
[sshd]
enabled = true
filter = sshd

# If you changed the SSH port, reflect it here (e.g., port = 2222).
port = ssh

# Mode “aggressive” catches more patterns (invalid users, many auth noise cases).
# Requires fail2ban 0.11+ with newer sshd filter.
mode = aggressive

Config Breakdown

[DEFAULT] block: Sets global behavior all jails inherit.
- ignoreip keeps your admin workstation/VPN/LAN from getting locked out during fat-finger moments.
- bantime, findtime, and maxretry control the ban policy. Here: 5 bad tries within 10 minutes → ban. A 1-hour ban is long enough to stop bots but short enough to forgive honest mistakes.
- bantime.increment = true (+ factor, maxtime) makes repeat offenders stay banned longer (1h → 2h → 4h … up to 1 week). This crushes persistent botnets without you micromanaging lists.
- backend = systemd reads from the journal instead of plain log files. It’s resilient to log rotation, works well on Debian/Ubuntu, and behaves nicely in containers/VMs.
- banaction = nftables-multiport uses nftables rules to block offenders. If your host still uses iptables, switch to iptables-multiport.
[sshd] jail: The actual protection for SSH.
- enabled = true turns it on.
- filter = sshd tells Fail2ban which regex set to use. It recognizes failed logins, invalid users, etc.
- port = ssh binds bans to your SSH port. If you run SSH on a non-standard port, change it (e.g., 2222).
- mode = aggressive expands matches to catch more brute-force patterns and “invalid user” noise attackers use to enumerate accounts.

Step 6: Test and Verify

Now comes the moment of truth. Before you close that original SSH session (your safety net), make sure everything actually works:

Open a new terminal window and test logging in with your key.
Confirm you can’t log in as root.
Confirm password login is refused.
Check logs with:
```
sudo tail -f /var/log/auth.log
```
On systemd distributions without auth.log, use sudo journalctl -u ssh -f (or -u sshd).

This is where patience pays off. Only after confirming everything works should you close your original session. If something breaks, you still have that old session open to fix it. There’s nothing quite like the sinking feeling of being locked out of your own server because you skipped this step.

Step 7: Ongoing Monitoring and Auditing

SSH hardening isn’t a one-and-done deal. Think of it like home security. You don’t install locks and then never check them again. Attackers adapt their methods, so your defenses need regular attention too.

Here’s what to keep an eye on:

Review logs regularly (/var/log/auth.log or journalctl -u ssh). Look for failed login attempts, especially repeated ones from the same IP addresses.
Audit authorized keys at least monthly. Remove old keys, particularly when team members leave or change roles. Stale keys are like forgotten spare house keys under the doormat.
Check for anomalies like new user accounts you didn’t create or SSH configuration changes you didn’t make. These can signal that someone is already in.
System updates: keep the box patched. OpenSSH gets security updates often, and missing one defeats everything else you’ve done. On Debian or Ubuntu, run sudo apt update && sudo apt upgrade on a schedule, or use unattended-upgrades for the security set.

Set a calendar reminder to do this monthly. It takes maybe 10 minutes. Catching problems early beats dealing with a breach later.

Troubleshooting Common SSH Problems

Even experienced admins lock themselves out occasionally. Here are the most common ways things go sideways and how to fix them:

Locked out after disabling passwords
Classic mistake. Your SSH key wasn’t copied correctly before you disabled password authentication. Get into the server through your hosting provider’s web console or rescue environment, then re-enable PasswordAuthentication yes in sshd_config until you have your keys working properly.
Wrong file permissions
If you see errors like “bad owner or permissions on .ssh/config”, your SSH files are readable by other users, which SSH treats as a security risk. Reset the permissions as shown in Step 4.
Forgot to update firewall when changing port
Changed your SSH port to Port 2222 but forgot to open that port in the firewall? Your connection will hang, looking like a network issue. Always update firewall rules before changing the SSH port, not after.
Trying to allow root login with keys
Even with “key-only” authentication, allowing direct root login creates unnecessary risk. If someone compromises your key, they have immediate root access. Stick with PermitRootLogin no and use sudo instead.
VPN misconfiguration
If you’re routing SSH through a VPN, test access thoroughly in a non-production environment first. The added complexity can leave you stranded if you misconfigure it.

ASRock Mini-Desktop Computer This compact barebone system gives you a tidy place to run lightweight VMs or containers and isolate SSH services on their own host. Modern Intel CPUs and flexible storage make it a practical platform for a dedicated SSH gateway or jump box that sits between your homelab and the outside world. Quiet, efficient, and small enough that you’ll actually keep it powered on.

Amazon Price: Loading...

Availability: Checking...

Contains affiliate links. I may earn a commission at no cost to you.

A dedicated jump host is a nice luxury, but it doesn’t change the questions readers ask most often. Here are the ones that keep coming up.

FAQs: Secure SSH in Practice

➤ How do I generate a secure SSH key pair?

Use ssh-keygen -t ed25519 for modern systems. If you’re stuck with older infrastructure, fall back to ssh-keygen -t rsa -b 4096. Ed25519 is faster, more secure, and generates smaller keys, but RSA with 4096 bits still does the job when needed.

➤ Why does SSH complain about bad owner or permissions?

SSH is picky about file permissions because it has to be. Your .ssh directory needs 700 (owner read/write/execute only), private keys need 600 (owner read/write only), and public keys need 644 (owner read/write, others read). SSH refuses to work with loose permissions because anyone who can read your private key can impersonate you.

➤ How do I change the SSH port safely?

Edit /etc/ssh/sshd_config and set Port 2222 (or whatever port you prefer). Here’s the critical part: update your firewall rules to allow the new port before restarting SSH. Otherwise, you’ll lock yourself out and need console access to fix it. Test the new port works before closing your current session.

➤ What are the most important `sshd_config` settings?

Start with these four: PasswordAuthentication no (forces key-based auth), PermitRootLogin no (eliminates the highest-value target), strong Ciphers and MACs (modern crypto only), and AllowUsers or AllowGroups (whitelist who can even attempt to connect). These settings alone will block most automated attacks.

➤ Is it safe to allow root login with SSH keys?

Best practice is no, even with keys. Root access means game over if compromised, so why make it a direct target? Create a regular user account, give it sudo privileges, and SSH in as that user instead. One extra step eliminates the most obvious attack vector.

➤ Should I still use RSA keys?

Use Ed25519 when possible because it’s more secure and performs better. RSA with 4096 bits is still acceptable on systems that don’t support Ed25519, but avoid anything smaller than 2048 bits. If you’re generating new keys today, go with Ed25519 unless you have a specific reason not to.

➤ What extra steps if SSH must face the internet?

Layer your defenses: restrict access by IP address when possible, install Fail2ban to block brute-force attempts, consider putting SSH behind a VPN or bastion host, and monitor your logs religiously. The internet is full of bots scanning for SSH servers, so assume you’re being probed constantly.

➤ How do I set up Fail2ban for SSH?

Install Fail2ban through your package manager, then enable the sshd jail in /etc/fail2ban/jail.local. The default settings work well for most setups: they’ll ban IPs after a few failed attempts and gradually increase ban times for repeat offenders. Whitelist your own IP addresses first so a typo doesn’t lock you out.

➤ What ciphers and MACs should I use?

Stick with modern algorithms like aes256-ctr for encryption and hmac-sha2-256 for message authentication. Avoid anything with “md5” or “sha1” in the name, and definitely skip older ciphers like 3DES or Blowfish. When in doubt, let SSH negotiate the strongest common algorithm between client and server.

➤ How do I recover access if I'm locked out?

Use your hosting provider’s console access or rescue system to get back in. Fix whatever broke in /etc/ssh/sshd_config, restart the SSH service, and test from another session before logging out. This is why you always test configuration changes before closing your current SSH session.

Conclusion

If you take one thing from this guide, it’s this. SSH security depends less on any one trick and more on layers. Keys instead of passwords, no root logins, careful configuration, restrictive firewalls, monitoring, and patching all stack together to drastically lower your risk.

Set aside time to secure SSH right after deploying any new server. It pays off later, whether you’re running a personal project or production infrastructure. Dealing with a compromised box is far worse than spending 30 minutes hardening SSH upfront.

Next steps worth exploring:

Automating SSH hardening with configuration management tools like Ansible.
Adding multi-factor authentication for SSH (Google Authenticator PAM or a hardware key like YubiKey).

Run through this checklist on every new server. After a few rounds, the steps stop feeling like a chore and start feeling like muscle memory.

Other Sources

How to Upgrade Debian 12 to 13 in Proxmox LXC Without CREDENTIALS Errors (2026)

Sun, 14 Sep 2025 07:41:22 -0600

Are you running Debian 12 (Bookworm) in an LXC container on Proxmox and want to upgrade to 13 (Trixie)? Should be straightforward, right? Well, if you’ve landed here, you’ve probably discovered that systemd has other plans.

Here’s the thing. systemd 256+ introduces stricter credential handling that doesn’t play nicely with unprivileged LXC containers. Try the upgrade and you’ll hit the dreaded 243/CREDENTIALS error that stops things dead.

Here’s how to work around it and upgrade your Debian LXC to Trixie without pulling your hair out.

💭

TL;DR: Debian 13’s systemd 257 enables credential plumbing by default, which breaks unprivileged LXC containers with cryptic 243/CREDENTIALS errors. Install Debian’s lxc.generator before you upgrade, reload systemd, then upgrade to Trixie. Leave the generator in place afterwards. Removing it hands the same failures straight back on the next reboot.

I’m writing this inside one of those containers. It’s an unprivileged LXC on Proxmox VE 9.2.5 (kernel 7.0.14-6-pve) running Debian 13.6 with systemd 257.13-1~deb13u1. I dropped the generator into it on 14 September 2025 and never took it back out. As I type this, systemctl is-system-running returns running with zero failed units and userspace boots in 492 ms.

Upgrading Debian containers inside Proxmox VE should be boring. Boring is why you run Debian. Change your apt sources, run the upgrade, reboot, get on with your life. That’s what the Reddit threads kept telling me when Debian 13 “Trixie” dropped. But if you’re running unprivileged and unnested LXCs on Proxmox 9, you already know that’s not how it goes. The result? A blinking cursor, status=243/CREDENTIALS failures, and crawling through logs that don’t want to work.

So we’ll take it in order. Why the error happens. What breaks when you ignore it. How to get back into a container you’ve already broken. And why a fresh Debian 13 container that was never upgraded at all greets you with the exact same mess.

MINISFORUM MS-A2 Up to a 16-core Ryzen 9 9955HX in something you can hide behind a monitor, with dual 10GbE SFP+ and dual 2.5GbE on board. The core count is what matters for this kind of work: enough headroom to run a stack of LXCs and still have something left over when one of them decides to rebuild its package cache mid-upgrade. Storage takes U.2 and full-length M.2 22110, so you’re not limited to whatever fits a laptop slot.

Amazon Price: Loading...

Availability: Checking...

Contains affiliate links. I may earn a commission at no cost to you.

Why Upgrading Debian 12 to 13 Breaks on Proxmox 9

When you upgrade Debian 12 to 13 (Bookworm to Trixie), the culprit hiding in the shadows is systemd 256+. Debian 13 ships systemd 257. That release enabled unit credentials (LoadCredential and ImportCredential) by default, which sounds harmless enough.

On bare metal or regular VMs, it works fine. But inside Proxmox LXCs, especially unprivileged ones, this feature crashes headfirst into the container’s limited namespace access. Here’s the breakdown:

systemd-sysctl (the service that applies kernel parameters) tries to load credentials
LXC blocks the namespace operation because the container doesn’t have permission
systemd throws a status=243/CREDENTIALS error and gives up
Other core services cascade into failure, from udev triggers to login shells

Most likely upgrade error:

Job for systemd-sysctl.service failed because the control process exited with error code.
See "systemctl status systemd-sysctl.service" and "journalctl -xeu systemd-sysctl.service" for details.
Processing trigger

systemctl status systemd-sysctl.service:

x systemd-sysctl.service - Apply Kernel Variables
 Loaded: loaded (/usr/lib/systemd/system/systemd-sysctl.service; static)
 Active: failed (Result: exit-code) since Sun 2025-09-14 05:59:21 MDT; 48s ago
 Duration: 2h 59min 12.451s
 Invocation: 63213f2f7514402f8cedd10155c7d065
 Docs: man:systemd-sysctl.service(8)
 man:sysctl.d(5)
 Process: 17806 ExecStart=/usr/lib/systemd/systemd-sysctl (code=exited, status=243/CREDENTIALS)
 Main PID: 17806 (code=exited, status=243/CREDENTIALS)
 Mem peak: 1.7M
 CPU: 5ms

What that error means

systemd is trying to pass secrets inside a container that has no infrastructure for handling them. Your services never start. The container hangs during boot. And debugging is a mess, because half the logging system went down with everything else.

243/CREDENTIALS = “failed to set up the unit’s credentials”.

Nesting, and what Proxmox actually recommends

The other way out of this is nesting. I want to be honest with you about it, because the original version of this post was harder on nesting than the facts support.

Proxmox’s own position is that modern systemd needs it. Their staff have said so plainly on the forums: systemd versions 242 and newer want nesting so they can create the Linux namespaces used to isolate services. That requirement has since been written into the pve-container package itself, where the nesting feature description now ends with the line “That is also required by systemd to isolate services.”

The security tradeoff is real, but it’s narrower than it sounds. On an unprivileged container, nesting exposes the host’s procfs and sysfs contents to the guest. The Proxmox documentation describes the feature as “best used with unprivileged containers with additional id mapping,” which is another way of saying it’s the supported configuration rather than a workaround.

Privileged plus nesting is the combination that should worry you. Proxmox staff describe that pairing as “essentially uncontained.”

For the record, every container in my own fleet now runs unprivileged with nesting=1. The generator approach in this post is what you reach for when you specifically want nesting turned off, or when you’re upgrading a container in place and would rather not change its feature flags mid-migration. Both paths work. Pick the one whose tradeoff you’d rather own.

“WARN: systemd 257 detected. You may need to enable nesting”

If you got here by pasting that exact string into a search box, this section is for you.

Proxmox added the warning in pve-container 6.0.19. Start a container running a modern systemd and it tells you up front that nesting may be required. You’ll see it on pct start or in the task log:

WARN: systemd 257 detected. You may need to enable nesting.

Two things worth knowing.

First, the number is whatever systemd version your container ships. People see 256, 257 and 258 depending on the distribution inside. Debian 13 reports 257. Same cause, same fix. Guidance written about one number applies to the rest.

Second, it’s a warning. Nothing more. The container will still start. What happens after that depends on whether anything inside it needs the credential machinery, and on Debian 13 with nesting off and no generator installed, plenty does. The container comes up degraded with a stack of units failing 243/CREDENTIALS, systemd-udev-load-credentials.service among them, and the Proxmox web console shows a black screen where the login prompt should be.

You have two ways to make the warning stop mattering:

# Option A: take Proxmox's advice and enable nesting (run on the host)
pct set <CTID> --features nesting=1
pct reboot <CTID>

# Option B: install the generator inside the container and leave nesting off
# (full walkthrough below)

The warning itself doesn’t disappear with Option B, because Proxmox emits it from the systemd version it detects, without checking whether the container is healthy. Confirm with systemctl is-system-running inside the container instead of trusting the absence of a warning.

What breaks if you don’t fix it

Try to upgrade to Debian 13 (Trixie) without handling the systemd changes first, and your LXC container becomes a flashing cursor:

The container won’t boot cleanly. It hangs there, mocking your weekend plans.
Critical systemd units like systemd-sysctl, systemd-udev-trigger, systemd-udev-load-credentials and terminal login will fail consistently. One report against the community-scripts project counted 19 failed units on a fresh Debian 13 container that had never been upgraded at all.
journald may crash, which means you lose the diagnostic logs you desperately need to figure out what went wrong.
The Proxmox noVNC console shows nothing at all, because agetty is one of the casualties.

That last point catches people out, and it’s also the thing that saves you. The console being dead doesn’t mean the container is unreachable. See the recovery section below.

ASRock Mini-Desktop Computer A 1.92L barebone that takes any 65W LGA1700 chip from 12th through 14th Gen, so you pick the CPU rather than accepting whatever a vendor soldered down. Two SO-DIMM slots reach 64GB, and you get a Gen5 x4 M.2, a Gen4 x4 M.2 and two 2.5-inch bays. It’s a barebone, so budget for the CPU, RAM, cooler and drives on top of the sticker price.

Amazon Price: Loading...

Availability: Checking...

Contains affiliate links. I may earn a commission at no cost to you.

The Fix: lxc.generator for Proxmox LXC Templates

Debian includes a small but clever utility called lxc.generator (part of the distrobuilder package) that solves this problem. It runs early in the systemd boot sequence and automatically patches unit files to make them container-friendly Debian Sources. Here’s what it does:

Detects when the system is running inside an LXC container or an unprivileged environment
Strips problematic flags like LoadCredential= and ImportCredential= that cause the 243/CREDENTIALS errors
Relaxes security hardening settings that don’t work properly in containers
Masks services that would otherwise crash during container startup

The generator creates temporary drop-in files under /run/systemd/ rather than permanently modifying anything on disk. Nothing on your root filesystem changes, and the drop-ins are rebuilt from scratch on every boot.

⚠️

Warning: Tested on Proxmox VE 9.x with unprivileged Debian LXCs. It should also help in LXD or Incus, but I have not tested there.

What the generator actually changes

The original version of this post claimed the generator kept your security posture intact with no compromises. That wasn’t quite right, and anyone who read the script would have caught me out. Here’s the drop-in it writes to /run/systemd/system/service.d/zzz-lxc-service.conf on a Debian 13 container, copied from the container this post was written in:

[Service]
ProcSubset=all
ProtectProc=default
ProtectControlGroups=no
ProtectKernelTunables=no
NoNewPrivileges=no
LoadCredential=
PrivateNetwork=no
ImportCredential=

That’s a global drop-in. It applies to every service in the container, and it turns off a meaningful chunk of systemd’s per-service sandboxing to do it. NoNewPrivileges=no in particular is not nothing.

So the honest framing is that both options cost you something. Nesting widens what the guest can see of the host. The generator widens what services inside the guest can do to each other. Neither is free, and which one you prefer depends on which boundary you actually care about.

It also writes a per-unit override for the service that started this whole mess:

# This file was created by distrobuilder
[Service]
ExecStart=
ExecStart=-/usr/lib/systemd/systemd-sysctl

The leading - tells systemd to tolerate a non-zero exit from systemd-sysctl instead of failing the unit, which is why the container stops cascading into failure.

1) Patch each Debian 12 container before upgrading

Before you upgrade Debian 12 to 13, install a small fix that prevents systemd from breaking during the transition. Enter your Debian 12 (Bookworm) LXC container and run:

sudo mkdir -p /etc/systemd/system-generators
curl -fsSL https://sources.debian.org/data/main/d/distrobuilder/3.2-2/distrobuilder/lxc.generator \
 | sudo tee /etc/systemd/system-generators/lxc >/dev/null
sudo chmod 0755 /etc/systemd/system-generators/lxc
sudo systemctl daemon-reload

💡

Tip: The generator tells systemd to disable the credential features that cause the 243/CREDENTIALS error. Install it while the container is still healthy, so the fix is already in place when the new systemd arrives.

Now prove it took effect before you go any further. A daemon-reload runs the generator, so the drop-in should exist immediately:

cat /run/systemd/system/service.d/zzz-lxc-service.conf

If that file is missing, the generator didn’t run. Check that it’s executable (ls -l /etc/systemd/system-generators/lxc should show 0755) and that the download wasn’t truncated (it’s roughly 7 KB). Fix that before upgrading, because this is the last comfortable moment to do it.

2) Upgrade to Debian 13 (Trixie)

Still inside your LXC container:

# Make sure Bookworm is up to date
sudo apt update && sudo apt upgrade -y

# Update every sources file to Trixie, old-style and deb822 alike
for f in /etc/apt/sources.list \
 /etc/apt/sources.list.d/*.list \
 /etc/apt/sources.list.d/*.sources; do
 [ -f "$f" ] && sudo sed -i 's/bookworm/trixie/g' "$f"
done
sudo apt update

# Upgrade across versions
sudo apt dist-upgrade -y

# Clean up junk
sudo apt autoremove -y
sudo apt autoclean -y

# Modernize apt format (optional but recommended)
sudo apt modernize-sources || true

# Reload systemd configs and reboot
sudo systemctl daemon-reload
sudo reboot

⚠️

Warning: Earlier versions of this post rewrote only /etc/apt/sources.list. That misses two common cases: repositories dropped into /etc/apt/sources.list.d/, and containers that already run the deb822 .sources format, where /etc/apt/sources.list may not exist at all. The loop above covers all three paths. Run apt update and read the output before you commit to dist-upgrade.

3) Verify

The upgrade takes a few minutes, depending on how big the container is and how fast your mirror is. When it comes back, check three things:

cat /etc/os-release
systemctl is-system-running
systemctl --failed

You should see something like:

PRETTY_NAME="Debian GNU/Linux 13 (trixie)"
VERSION_ID="13"
VERSION="13 (trixie)"
VERSION_CODENAME=trixie
DEBIAN_VERSION_FULL=13.6

See “trixie” in the output? Good. Now check the second and third commands: is-system-running should print running, and systemctl --failed should list nothing. A degraded result with 243/CREDENTIALS units in the list means the generator isn’t doing its job, so go back and check the drop-in from step 1.

Debian 13.6 has been the current point release since 11 July 2026. Yours will differ depending on when you read this, and a higher DEBIAN_VERSION_FULL is nothing to worry about.

4) Leave the generator in place

This is the one instruction I’ve reversed since first publishing this post, and it’s worth explaining why.

The original advice was to delete /etc/systemd/system-generators/lxc once the upgrade completed, on the theory that it was a temporary bridge. It isn’t. The credential behaviour that broke your container during the upgrade is the ordinary behaviour of systemd 257 on Debian 13, so removing the generator hands you the same failures back on the next reboot. That’s borne out by everyone who creates a fresh Debian 13 container with nesting off and watches it come up degraded without ever having run an upgrade at all.

The container I’m writing this in has had the generator installed since 14 September 2025. It’s been through the 13.1 through 13.6 point releases and every reboot along the way, the most recent on 24 July 2026, and it still reports zero failed units. Leave it alone.

If you do want it gone, enable nesting first and reboot, then confirm the container still reports running before you delete anything.

Already upgraded and now the container won’t boot

If you found this post after running the upgrade, you’re not stuck, and you almost certainly don’t need to restore from backup.

The critical detail: the Proxmox console dying doesn’t mean the container is unreachable. agetty fails on credentials, which kills the noVNC console, but pct enter attaches through a different path and keeps working. From the Proxmox host:

pct enter <CTID>

Once you’re in, install the generator exactly as in step 1, then reload and reboot:

mkdir -p /etc/systemd/system-generators
curl -fsSL https://sources.debian.org/data/main/d/distrobuilder/3.2-2/distrobuilder/lxc.generator \
 > /etc/systemd/system-generators/lxc
chmod 0755 /etc/systemd/system-generators/lxc
systemctl daemon-reload
cat /run/systemd/system/service.d/zzz-lxc-service.conf # proof it ran
exit

# back on the host
pct reboot <CTID>

The container should come back with a working console. If pct enter also fails, or networking never came up so you can’t reach sources.debian.org, enable nesting from the host as the fast way back to a shell:

pct set <CTID> --features nesting=1
pct reboot <CTID>

That gets you a bootable container immediately. You can decide afterwards whether to install the generator and turn nesting back off, or leave it on and call it done.

Intel® Core™ i5-14500 14th Generation Desktop Processor 14 cores (6 performance plus 8 efficiency) and 20 threads turboing to 5.0 GHz, with UHD 770 graphics carrying the Quick Sync engine. That last part is why this chip keeps turning up in homelab builds: Jellyfin and Plex get hardware transcoding without a discrete GPU taking up a slot. The thread count suits a Proxmox host running a dozen containers that spend most of their lives idle.

Amazon Price: Loading...

Availability: Checking...

Contains affiliate links. I may earn a commission at no cost to you.

Starting fresh: creating a Debian 13 LXC from a template

Plenty of people arrive here not because an upgrade broke, but because they tried to create a new Debian 13 container and hit a wall. The credential problem is identical. The path to it is different.

Grab the template from the host:

pveam update
pveam available --section system | grep debian-13
pveam download local <template-filename-from-the-list-above>

I’ve deliberately not hardcoded the filename here, because it carries the point release and changes every couple of months. Read it off the pveam available output rather than copying a stale one out of a blog post.

Once the container is created, it runs straight into the same systemd 257 credential behaviour that broke the upgrade path. A fresh Debian 13 container with nesting disabled comes up degraded, and the fix is the same generator install from step 1. This surprises people who assume the problem was caused by the upgrade process. It wasn’t. The upgrade was only when they first met it.

“unsupported debian version” when creating the container

There’s a second, unrelated error that hits Debian 13 containers, and it looks like this:

TASK ERROR: unable to create CT 200 - unsupported debian version '13.1'

Some tooling surfaces it as a complaint that pct reported an unsupported version and the LXC stack might be too old for the template. Same root cause either way: /usr/share/perl5/PVE/LXC/Setup/Debian.pm on the host carries a hardcoded upper bound on the Debian version it will accept, and a template newer than that bound gets rejected before the container is ever created.

The fix is to update Proxmox. Thomas Lamprecht confirmed the version check was reworked in pve-container 6.0.10 for Proxmox VE 9 and 5.3.1 for Proxmox VE 8, both on the pve-no-subscription repository. The refactor also stops the same thing recurring with each new point release, which is what made 13.0 work and 13.1 fail.

apt update && apt install pve-container

If you genuinely can’t update the host right now, the interim workaround is to edit line 39 of /usr/share/perl5/PVE/LXC/Setup/Debian.pm:

# before
die "unsupported debian version '$version'\n" if !($version >= 4 && $version <= 13);

# after
die "unsupported debian version '$version'\n" if !($version >= 4 && $version <= 14);

Restart the host afterwards. Treat this as a stopgap. A package update will overwrite the file, which is fine, because by then you won’t need the edit.

Alternative Options: Pick Your Poison

Option	What it costs you	Effort	Use when…
Enable nesting (unprivileged)	Host procfs and sysfs contents visible to the guest	Low	You want the configuration Proxmox documents and supports
Use `lxc.generator` (this post)	systemd’s per-service sandboxing relaxed container-wide	Low	You want nesting to stay off, or you’re upgrading in place
Flip to privileged LXC	UID mapping isolation gone, much larger blast radius	Medium	You need kernel options that won’t work unprivileged
Migrate to VM	Real overhead and resource cost	High	You want zero container weirdness

The top two are both defensible and I run the first one across my fleet. Avoid combining privileged with nesting, which Proxmox staff describe as essentially uncontained.

FAQs

➤ What does `status=243/CREDENTIALS` mean, exactly?

It’s a systemd error code that translates to “failed to set up credentials.” Starting with systemd 256, the system expects to mount sensitive files like API tokens into service units through tmpfs-backed namespaces. The problem? Unprivileged LXC containers don’t have the kernel options to support this feature, so services that rely on it fail to start.

➤ Why does Proxmox tell me to enable nesting if this post shows a way around it?

Because nesting is the configuration Proxmox supports for modern systemd, and their warning reflects that. The generator is a legitimate alternative when you want nesting off, but it isn’t the officially blessed path. Both work. The generator trades systemd’s in-container sandboxing for the host visibility that nesting would give away.

➤ Does the systemd version number in the warning matter?

No. Whether it says 256, 257 or 258 depends on which distribution release is inside the container. Debian 13 reports 257. The cause is the same credential handling in all of them and the fix doesn’t change, so guidance written against one number applies to the rest.

➤ Could I enable nesting and forget about it?

Yes, and that’s what I do on my own fleet. Nesting exposes more of the host’s /proc and /sys to the container, which is a real cost, but on an unprivileged container with id mapping it’s the arrangement Proxmox recommends. Keep it away from privileged containers, where the combination removes most of the isolation.

➤ Is `lxc.generator` safe to leave on long-term?

Yes, and you should. It only creates ephemeral drop-in files under /run/systemd/, rebuilt on every boot. Removing it hands back the same 243/CREDENTIALS failures on the next reboot, because Debian 13’s credential behaviour doesn’t go away after the upgrade. Mine has run continuously since September 2025.

➤ My container won't boot and the console is black. Have I lost it?

Almost certainly not. The dead console is agetty failing on credentials, not the container being down. Run pct enter <CTID> from the Proxmox host, which uses a different path and usually still works, then install the generator and reboot. Failing that, enable nesting from the host to get a shell back.

➤ Can I use this on LXD instead of Proxmox?

In theory, yes. The lxc.generator is designed to work with LXC containers, not only Proxmox. But I’ve only run these steps on Proxmox VE 9 with unprivileged containers. On LXD or Incus the concepts should carry over fine, and you’d be the one testing that.

➤ Do I need to replace my `sources.list` with deb822 format?

Not required. Your existing old-style sources keep working fine. Debian is nudging everyone toward the newer deb822 format though, and apt modernize-sources handles the conversion for you if you decide you want it. There’s no hurry either way.

Conclusion

Upgrading an unprivileged Debian container on Proxmox shouldn’t require a vocabulary lesson in creative profanity. The culprit is systemd’s credential defaults in 256 and later, which Debian 13 inherits at version 257.

You’ve got two honest ways through it. Enable nesting, which is what Proxmox documents and what I run across my own containers. Or install lxc.generator, keep nesting off, and accept that systemd’s per-service hardening gets relaxed inside the container instead. Install it, reload, upgrade, reboot, and then leave it in place. That last part is the correction I most wanted to make to this post: the generator is not scaffolding you remove once the building is up.

If you’re already staring at a container that won’t boot, pct enter is almost always still open to you. And if you’re creating a fresh Debian 13 container rather than upgrading one, expect exactly the same credential failures, plus a possible unsupported debian version error that a pve-container update clears.

LXC template upgrades only look straightforward until systemd changes the rules mid-game. So when a container comes up degraded after some future point release, run ls /run/systemd/system/service.d/ before you go digging through logs. One command tells you whether the generator is still doing its job.

RaspberryPi 4GB Quad-core ARM, 4GB of RAM, Gigabit Ethernet and dual-band Wi-Fi, sipping a few watts. It won’t run your media server and isn’t meant to. Think of it as the machine you keep around for Pi-hole or Home Assistant, and for the throwaway Debian install you can break on purpose to see what a failed upgrade looks like before you try it on something you care about.

Amazon Price: Loading...

Availability: Checking...

Contains affiliate links. I may earn a commission at no cost to you.

Sources

NFS vs SMB: Which Is Faster for Home Media Servers?

Thu, 11 Sep 2025 06:54:35 -0600

I used to think choosing between NFS and SMB was like picking between Coke and Pepsi: a purely personal preference with no real consequences. I was wrong. If you’re running a Linux media server and care about performance, compatibility, and sane file permissions, the protocol you choose will define your entire experience. Pick wrong, and you’ll spend weekends debugging permission errors instead of watching movies or shows.

Here’s the practical decision framework. Where each protocol wins, how to set them up on a Linux server, which settings move the needle, and the gotchas that bite people every weekend on r/homelab. Mixed-OS house, or trying to reach your Unraid shares from a Windows laptop? Read on.

NFS vs SMB: What Each Protocol Does

Network File System (NFS) is the native file-sharing protocol for Unix and Linux systems. It makes remote folders appear as local directories, with tight integration into the Linux kernel. It’s how Linux prefers to share files across a network.

Server Message Block (SMB) is Windows’ native file-sharing protocol. Linux systems access SMB shares through Samba, while macOS speaks SMB natively. SMB packs more features and integrates deeply with Windows authentication and permissions.

Feature	NFS	SMB
Best for	Linux-to-Linux	Mixed OS / Windows
Default on	Linux/Unix	Windows
Encryption	NFSv4 + Kerberos	SMB3 built-in
Performance (small files, Linux)	Faster	Slower
Performance (large files)	Similar	Similar
Windows support	Poor	Native
Docker/container use	Common	Less common
Setup complexity	Simple (Linux)	Moderate

Why this matters for your media server: it constantly reads metadata, generates thumbnails, and streams video files. The protocol you pick decides how fast library scans finish, how snappy your media player UI feels, and whether file permissions stay sane or slowly drive you insane.

Your clients’ operating systems drive the decision. Running a Linux media server accessed only by other Linux machines? NFS typically performs better. Mixed environments with Windows, macOS, and Linux clients? SMB is the sane choice.

Both protocols can be properly secured on a trusted LAN, but their default configurations and hardening approaches vary significantly. Poor defaults have real consequences. SMBv1 vulnerabilities enabled major malware outbreaks. Misconfigured NFS exports can expose your data to anyone on the network. Neither protocol forgives carelessness.

UGREEN NASync DXP4800 Pro 4-Bay Desktop NAS
Four bays, an Intel Core i3-1315U, and dual networking (10GbE + 2.5GbE). Supports both NFS and SMB out of the box, so you can test what you’re reading about here instead of theorizing. A solid entry point if you don’t already have a NAS to experiment with.

Amazon Price: Loading...

Availability: Checking...

Contains affiliate links. I may earn a commission at no cost to you.

NFS or SMB: Which Protocol Should You Use?

All clients are Linux, Unix, or Android TV?

Pick NFS. It’s fast, mature, and simple for Linux-to-Linux communication. You’ll avoid the worst of the permission headaches, provided you manage your UIDs and GIDs correctly. (More on that later.)

Windows or macOS clients in the mix?

Pick SMB. It’s native on Windows, works smoothly on macOS, and Samba on Linux is well-supported and battle-tested. If specific Linux-only apps benefit from NFS, you can add it alongside SMB, but let SMB be the default.

Security and centralized authentication matter?

SMB3 with modern authentication and encryption is the more straightforward path, especially in Windows and Samba environments. NFSv4 with Kerberos can be equally secure, but the setup complexity is significantly higher. If you’re not doing Kerberos, restrict NFS to trusted subnets and use strong firewall rules.

Running Unraid or another NAS?

Unraid and most NAS platforms support both protocols. Use SMB for Windows clients, NFS for Linux clients or Docker containers. Don’t expose either protocol to the internet. Ever.

💡

Tip: Both protocols are fast enough for streaming large media files. The performance gap shows up when your media manager scans thousands of tiny images and NFO files. Linux clients usually chew through those faster over NFS, while Windows clients do better with SMB thanks to client stack optimizations.

NFS vs SMB Pros and Cons

NFS: Strengths and Weaknesses

Pros:

Fast on Linux. Lower protocol overhead and native kernel modules give NFS an edge when dealing with many small file operations in Linux-only environments. For a Linux media server streaming content to other Linux clients and managing large collections, this matters.

Simple integration. NFS is part of the Linux ecosystem. Mounts, fstab, systemd units, and permissions all make sense if you track your UIDs and GIDs. No wrestling with foreign concepts.

Stateless heritage. Classic NFSv3 is largely stateless, which can simplify some failure recoveries.

Cons:

Security by default is weaker. Older NFS versions lack encryption and rely on client-side UID/GID trust. NFSv4 improves this and supports Kerberos, but few home labs set that up correctly. Most people live with the risk and lock things down with firewall rules. Know that you’re making that trade-off.

Windows support is painful. Windows can mount NFS, but the built-in client is inconsistent across editions and awkward to configure. If you need to access shares from Windows regularly, save yourself the grief and use SMB.

Focused feature set. NFS does file and directory sharing well. That’s it. Don’t come looking for the broader Windows ecosystem features that SMB provides.

Best fit: Linux media servers and clients, Docker workloads, Kubernetes, and Linux-only NAS access.

SMB: Strengths and Weaknesses

Pros:

Cross-platform. Native on Windows, solid on macOS and Linux via Samba. For mixed-OS homes and offices, SMB works without drama. That’s not praise you hand out lightly in this industry.

Modern security. SMB3 supports strong authentication and optional encryption, integrates with Active Directory, and includes features like signing and multichannel. When configured properly, it’s solid.

Feature-rich. Beyond files, SMB supports printers and deep Access Control List (ACL) capabilities that align with Windows permission models. If you have a Windows background, the permissions will feel familiar.

Cons:

More overhead. Often slower than NFS in Linux-to-Linux scenarios with many small files, though SMB3 performance can be excellent with Windows clients. The extra features come at a cost.

More knobs to misconfigure. Samba has a lot of options, and it’s easy to botch permissions or lose performance with certain security defaults. The flexibility is both a blessing and a trap.

❌

Danger: SMBv1 is insecure and was exploited in major malware outbreaks like WannaCry. Disable it everywhere. No exceptions, no excuses, no “but my old printer needs it.” If a device only speaks SMBv1, that device has a retirement date, and it’s today.

Best fit: Mixed OS environments, Windows clients, or macOS systems.

Preparing Your Linux Server or NAS

Whether you’re running a bare Linux server, Unraid, Synology, TrueNAS, or another NAS platform, the setup approach stays consistent. Sort this out before you touch a config file:

Figure out which shares will be accessed by which clients. Use SMB for Windows and macOS connections. Use NFS for Linux apps and clients. Avoid exporting the same path through both protocols unless you understand the consequences for permissions and extended attributes (and you probably don’t yet, which is fine). Keep both protocols scoped to your trusted LAN. Never port-forward 445 or 2049 from your router to the internet.

⚠️

Warning: That last point is worth repeating: exposing file share ports to the internet is begging for trouble. Your media server doesn’t need to be the next cautionary tale in network security forums. People will screenshot your misconfiguration and post it for laughs.

On Unraid specifically:

SMB comes enabled by default, making Windows access straightforward. You can enable NFS per share for Linux clients and containers. Mapping Windows drives to SMB shares is point-and-click simple. Accessing NFS shares from Windows, on the other hand, requires client-side tools and sometimes Windows Enterprise features. For most home setups, SMB handles Windows clients fine. Don’t add an unnecessary headache.

On Synology DSM:

Synology supports both NFS and SMB through its Control Panel. SMB is enabled by default. To enable NFS, go to Control Panel > File Services > NFS and check “Enable NFS service.” You can then set NFS permissions per shared folder under the folder’s edit settings. Synology makes this relatively painless, but pay attention to the squash settings and allowed IP ranges. The defaults are conservative, which is the right instinct, but they’ll block access if you don’t explicitly allow your client subnets.

On TrueNAS (SCALE and CORE):

TrueNAS supports both protocols through its web UI. Create a dataset first, then configure SMB or NFS sharing on top of it. For Jellyfin or Plex running in a TrueNAS container or jail, NFS is the common choice for mounting media storage. Be aware that TrueNAS SCALE uses Linux under the hood while TrueNAS CORE uses FreeBSD, which can affect how NFS permissions behave. If you’re running apps on TrueNAS SCALE, pointing them at an NFS share from a separate dataset avoids the host path permission headaches that catch a lot of people.

Setting Up SMB on a Linux Server (Samba)

SMB on Linux is straightforward once you’ve seen it done. Here’s how to set up a media share that Windows, macOS, and other Linux machines can all reach without drama.

Follow my SMB installation and Configuration Guide

Security Notes: Use SMBv3 or higher wherever possible. Disable SMBv1 entirely. If you’ve read this far, and it’s still enabled on your network, go fix that now. I’ll wait.

Follow the linked guide and you get an authenticated share that holds up across Windows, macOS, and Linux. Your media server stops fighting Windows clients over permissions, which is half the reason people give up on Samba in the first place.

MINISFORUM MS-A2 Dual 2.5GbE with a 10GbE option, a Ryzen CPU, and triple NVMe slots in a box smaller than most routers. If you want a Proxmox host that can run NFS and SMB servers in VMs or containers without breaking a sweat, this is the kind of hardware that makes it trivial.

Amazon Price: Loading...

Availability: Checking...

Contains affiliate links. I may earn a commission at no cost to you.

Setting Up NFS on a Linux Server

NFS on a Linux media server is the easier of the two to stand up. Here’s the configured-and-mounted version:

Follow my NFS installation and Configuration Guide

For those who want the quick version, here’s what mounting an NFS share from a Linux client looks like in practice:

# One-time manual mount to test the connection
sudo mount -t nfs4 192.168.1.100:/mnt/media /mnt/nfs/media

# Persistent mount via /etc/fstab (survives reboots)
# Add this line:
192.168.1.100:/mnt/media /mnt/nfs/media nfs4 rw,noatime,rsize=1048576,wsize=1048576 0 0

Replace the IP and paths with your own. Test the manual mount first. If that works, add the fstab entry. If the manual mount fails, don’t bother with fstab until you’ve sorted out the underlying issue. Debugging a boot hang caused by a bad NFS mount in fstab is a miserable experience. Ask me how I know. If you’re worried about boot hangs, add the nofail option, so the system boots even if the NFS server is unreachable.

NFS and SMB Security Best Practices

Here’s the thing about network file sharing: convenience and security pull in opposite directions. But a few smart choices upfront will save you from becoming internet famous for all the wrong reasons.

Keep it local. SMB and NFS belong on your trusted LAN only. Never expose ports 445 (SMB) or 2049 (NFS) to the internet. Block them at your router and firewall. This isn’t paranoia. This is basic hygiene.

SMB security essentials:

Disable SMBv1 entirely. It’s ancient, vulnerable, and has no place in modern networks. Use SMBv2 or SMBv3. Enable strong authentication and SMB encryption where your data sensitivity justifies the CPU overhead. Yes, encryption costs performance, but that’s a trade-off worth making for sensitive content. If you need centralized user management, integrate with existing directory services rather than managing local accounts one by one.

NFS security essentials:

Stick with NFSv4 over older versions. Restrict exports by IP or subnet. Use root_squash to prevent compromised clients from running wild with root privileges. Deploy host-based firewalls to allow only known clients. Defense in depth matters because single points of failure are single points of regret.

The backup reality check: Neither SMB nor NFS will save you from accidental deletion or ransomware. Keep offline or versioned backups of your important data. This is not optional. Your future self will thank you, or your current self will learn the hard way.

NFS and SMB Performance Tuning

Tuning network shares isn’t deep magic. A handful of small changes will move you from “fine” to “noticeably faster.” Here’s what pays off:

NFS:

For large sequential reads (streaming movies), the default settings are usually fine. For many small files, look at actimeo (attribute cache timing) and consider noatime to reduce metadata writes. Use NFSv4.2 when available. It cuts down on port sprawl and handles flaky network connections better. You can bump up rsize/wsize (try rsize=1048576,wsize=1048576 as a starting point), but test with your specific NIC and switch setup. Bigger buffers aren’t always better buffers.

SMB:

Enable SMB multichannel on capable clients and servers. It bonds multiple NICs or network paths for better throughput and fault tolerance. Stick with SMB version 3.x or higher.

Both protocols:

Jumbo frames (MTU 9000) can help, but only if every single network hop supports the same MTU. Miss one switch or router, and you’ll actually make things worse. Always test with tools like robocopy (Windows), fio, or dd to measure before and after. A simple sequential read test with fio looks like this:

fio --name=seqread --rw=read --bs=1M --size=1G --numjobs=1 --filename=/mnt/yourshare/testfile

Change one variable at a time. Otherwise you’ll never know what helped and what hurt.

NFS vs SMB Speed: What the Benchmarks Show

People love to argue about NFS vs SMB performance in the abstract. Here’s what the numbers look like in real homelab conditions.

For sequential reads and writes (streaming a movie, copying a large file), NFS and SMB perform within a few percent of each other on a modern gigabit or 2.5GbE link. Both protocols will saturate a 1GbE connection without breaking a sweat. You’re not going to notice a difference when playing a 30GB Blu-ray remux over either protocol.

The gap opens up with small files. When your media manager scans a library of thousands of NFO files, poster images, and subtitle files, NFS on Linux clients can be 25-30% faster than SMB for random read operations. This is where NFS’s lower protocol overhead and kernel-level integration actually matter. If your Jellyfin library scan takes 20 minutes over SMB, it might take 14 over NFS. That adds up when you’re managing a large collection.

SMB claws back some ground on random writes, where it’s sometimes faster depending on the server and client configuration. And on Windows clients, SMB’s native stack optimizations mean it frequently outperforms NFS, which is running through a clunkier client implementation on that platform.

The takeaway: don’t pick a protocol based on speed alone. Pick based on your client OS, then tune for speed within that choice.

Seagate Barracuda 24TB Internal Hard Drive
Protocol benchmarks don’t mean much against a handful of test files. You need a real media library to see the difference. 24TB gives you enough room to fill a NAS and stress-test your NFS or SMB configuration with thousands of files, not a synthetic toy workload.

Amazon Price: Loading...

Availability: Checking...

Contains affiliate links. I may earn a commission at no cost to you.

Common NFS and SMB Pitfalls

Mixing NFS and SMB on the same share:
This is a deep topic, but the short version: Windows ACLs and POSIX permissions are like oil and water. Samba stores NT ACLs as extended attributes, but NFS clients may not preserve them. If you must mix protocols on the same data, separate your write paths or designate one protocol for writes and keep the other read-only.

UID/GID mismatches on NFS:
Keep your user and group IDs consistent across all Linux clients. Use centralized identity management (LDAP/SSSD) or carefully align your /etc/passwd entries. For a quick check, run id username on both client and server and make sure the numbers match. Debugging permission issues caused by mismatched IDs is not how you want to spend your weekend.

Assuming “NFS is insecure” or “SMB is slow”:
These are lazy generalizations. NFSv4 with Kerberos holds up against serious threat models. SMB3 on modern stacks is both fast and secure. The real performance and security outcomes depend on your configuration and client mix, not the protocol name on the tin.

Turning on async writes blindly on NFS:
Async writes (async in /etc/exports) can boost speed, but at the cost of data safety during crashes. If the server goes down mid-write, you can lose data. Understand the trade-off before flipping that switch.

Exposing shares directly to the internet:
This is how you get pwned. Use VPNs for remote access. Never use direct port forwards for file shares. Not “probably don’t.” Don’t.

Example Scenarios: What To Choose

Here’s how to pick the right protocol based on your actual setup:

All Linux home:
Export media via NFSv4, mount on Jellyfin/Plex and your Linux desktop. Keep UIDs aligned across systems. Optionally offer SMB read-only for occasional Windows use. This gives you the performance benefits of NFS where it matters most while keeping a door open for Windows guests.

Windows family PCs, macOS laptop, Linux server NAS:
Use SMB for everyone. Enable NFS only for Linux containers or hosts that specifically benefit from it. Keep permissions in one place through Samba. Fighting permission mismatches across protocols isn’t worth the headache when SMB works fine for the whole house.

Unraid backing multiple Docker apps and a Windows gaming PC:
Give containers NFS or bind mounts for speed. Export the same content over SMB to Windows, but consider separate paths or read-only mounts to avoid permission drift. This hybrid approach lets your containers stay fast while keeping Windows happy. Watch for permission conflicts if both protocols write to the same files. When in doubt, pick one writer.

NFS vs SMB for Docker Containers

If you’re running Plex, Jellyfin, Sonarr, Radarr, or any other media app in Docker, you have three main options for accessing remote storage: NFS mounts, SMB/CIFS mounts, or bind mounts from a path already mounted on the host.

The cleanest approach for most homelabs is to mount the NFS share on the Docker host, then bind-mount that path into your containers. This keeps the NFS configuration in one place (the host’s /etc/fstab) and lets every container access the same media library without each one needing its own network mount logic. Here’s what that looks like:

# On the Docker host, mount the NFS share
192.168.1.100:/mnt/media /mnt/nfs/media nfs4 rw,noatime,nofail 0 0

# In docker-compose.yml, bind-mount it into the container
volumes:
 - /mnt/nfs/media:/media

You can mount SMB/CIFS shares into Docker containers using a CIFS volume driver or by mounting on the host first, but NFS is generally the better fit here. It avoids the SMB authentication layer, has less overhead for the constant small-file reads that media apps love to do, and plays nicer with Linux permissions inside containers. If your NAS is a Synology, TrueNAS, or Unraid box, enable NFS for these container workloads even if the rest of your house uses SMB.

One warning: make sure the NFS share is mounted before Docker starts your containers. If the mount isn’t ready and your container writes to what it thinks is the media directory, those writes land on the host’s local filesystem instead. You’ll spend an hour wondering why your files disappeared. Use nofail and x-systemd.automount in your fstab, or set up a systemd dependency so Docker waits for the mount.

NFS vs SMB for Proxmox

Proxmox users face this question constantly, especially when adding NAS storage as a datastore for VMs, containers, or ISO images. Proxmox supports both NFS and SMB/CIFS as storage backends, configurable directly from the Datacenter > Storage menu in the web UI.

For most Proxmox homelabs, NFS is the better default. Proxmox runs Linux under the hood, NFS is a first-class citizen, and the integration is straightforward. Add your NAS as an NFS datastore, point it at the export path, and Proxmox handles the rest. VM disk images, container templates, backups, and ISOs can all live on NFS storage without issue.

SMB/CIFS storage is also supported in Proxmox, but it’s more commonly used when the storage backend is a Windows server or when NFS isn’t available. If your NAS supports both, pick NFS for Proxmox and save SMB for your Windows and macOS clients.

One Proxmox-specific gotcha: if you’re passing NFS-mounted storage into an LXC container (not a VM), pay attention to UID/GID mapping. Unprivileged containers remap UIDs by default, which means UID 1000 inside the container becomes UID 101000 on the host and on the NFS share. Either use privileged containers for media workloads, manually map the UIDs in the container config, or accept that permissions will fight you until you sort it out.

Troubleshooting NFS and SMB Connections

When things go sideways (and they will), here’s how to get back on track.

Connection refused or cannot mount:
Check if your services are actually running: systemctl status smbd nmbd for SMB, or systemctl status nfs-server for NFS. Verify firewall rules. SMB needs TCP 445, NFSv4 needs TCP 2049. If you’re stuck with NFSv3, rpcbind and mountd may need additional ports opened. Double-check your server IP and share names. Yes, typos happen to all of us.

Permission denied:
For SMB, verify the user exists in both Linux and Samba (pdbedit -L lists Samba users), check smbpasswd, and validate share-level access controls. For NFS, UID/GID mismatches are the usual suspect. Align user IDs between systems or configure idmapd for NFSv4. Also make sure your export options aren’t accidentally set to ro (read-only) when you meant rw.

Slow file transfers:
Check what protocol version you’re actually using. Force vers=3.0 for SMB or vers=4.2 for NFS and test again. Disable Wi-Fi power saving on clients and test over wired connections. For SMB, experiment with multichannel, signing, or encryption settings to understand the performance trade-offs. Don’t disable security features on untrusted networks. For NFS, try different rsize/wsize values and check for duplicate mounts or DNS slowness.

Windows cannot access NFS:
The Client for NFS feature might be missing or unsupported in your Windows edition (Home edition doesn’t have it). Stick with SMB for Windows clients and save NFS for Linux systems.

Media server doesn’t see new files immediately:
For SMB, Samba uses change notifications, but some applications still cache directory listings. Try a manual library refresh or verify your app is watching the correct path. For NFS, attribute caching can delay file visibility. Adjust actimeo=0 for immediate visibility, but expect a performance hit. Find the balance that works for your scan frequency.

Library scans crawl along:
For many small files, NFS on Linux clients often outperforms SMB. Consider running your media scanner on a Linux machine over NFS, even if end users stream via SMB.

FAQs:

➤ What is the difference between NFS and SMB for a home media server?

NFS is Linux’s native file sharing protocol and excels at Linux-to-Linux performance with minimal overhead. SMB is Windows’ native protocol and works best in mixed OS environments, offering strong security features and broad client support. If your media server runs Linux but you have Windows clients, SMB is usually the safer bet.

➤ Does Unraid support NFS and SMB shares?

Yes, Unraid supports both protocols out of the box. SMB is enabled by default for Windows compatibility, while NFS is commonly used for Linux clients and Docker containers. You can enable either or both, depending on your needs.

➤ How do I access an NAS or Unraid share from Windows?

Use SMB. In Windows Explorer, type \\unraid-hostname\sharename in the address bar or map it as a network drive. While Windows 10 Pro and Enterprise can mount NFS shares, SMB is the path of least resistance for most home users.

➤ Which is faster for Plex or Jellyfin: NFS or SMB?

For Linux media servers scanning thousands of small files (like movie thumbnails), NFS typically wins due to lower protocol overhead. Windows clients often see better performance with SMB3. When streaming large video files, both protocols are plenty fast. Compatibility matters more than raw speed at that point.

➤ Is NFS secure enough for my home network?

NFS can be secure on a trusted home network when properly configured with export restrictions and firewall rules. For enhanced security, consider upgrading to NFSv4 with Kerberos authentication, though this significantly increases setup complexity. Most importantly, never expose NFS directly to the internet. Always use a VPN for remote access.

➤ How do I set up NFS shares on Unraid?

Enable NFS in Unraid’s settings, configure per-share export rules, and specify allowed client IPs or subnets. Mount from Linux clients using mount -t nfs server:/export /mnt. The key is getting the export permissions right the first time.

➤ Can I use both NFS and SMB on the same Unraid share?

Technically yes. But you’re asking for trouble. Permission conflicts and extended attribute mismatches can cause real headaches. If you must use both, consider making one protocol read-only or carefully separating write operations between protocols.

➤ Why am I getting permission denied when mounting an NFS share?

Usually, it’s UID/GID mismatches between your client and server, or restrictive export rules. Ensure user IDs align across your Linux systems and double-check /etc/exports for correct options and allowed subnets. This is the most common NFS stumbling block.

➤ How do I enable SMB3 encryption on my server?

In your Samba configuration, set smb encrypt = required or desired globally or per-share. Keep in mind that encryption adds CPU overhead. Test performance impacts on your hardware before committing.

➤ What are the risks of exposing SMB or NFS to the internet?

High risk. Don’t do it. SMBv1 was exploited in major ransomware outbreaks like WannaCry. Even modern SMB and NFS implementations are frequent attack targets. Use a VPN for remote access and never port-forward 445 or 2049 from your router.

➤ How do I fix slow file transfers over SMB or NFS?

Start with the basics: verify you’re using modern protocol versions, test with wired connections, and benchmark one change at a time. For NFS, tune rsize and wsize parameters. For SMB, enable multichannel if your hardware supports it.

➤ Should I use NFSv3 or NFSv4 for my media server?

Go with NFSv4 unless you have a specific reason not to. It simplifies port management, provides better file locking, and supports Kerberos security. Only stick with NFSv3 if you’re dealing with legacy systems that genuinely can’t handle v4.

➤ How do I map Linux users to Windows users for file access?

With SMB, configure Samba’s idmap backends and maintain consistent POSIX ACLs for cross-platform access. The Samba docs on idmap are dense but worth reading. Getting this right once saves you from ongoing permission fights.

➤ Should I use NFS or SMB for Docker containers?

NFS is generally the better choice for Docker containers on Linux. Mount the NFS share on the Docker host, then bind-mount the path into your containers. This avoids SMB’s authentication overhead and plays nicer with Linux permissions inside containers. Make sure the NFS mount is ready before Docker starts your containers, or you’ll write to the local filesystem by mistake.

➤ Should I use NFS or SMB with Proxmox?

NFS is the more natural fit for Proxmox since it runs Linux. Add your NAS as an NFS datastore through the Proxmox web UI under Datacenter > Storage. It works well for VM disk images, container templates, backups, and ISOs. Use SMB/CIFS in Proxmox only if your storage backend is a Windows server or NFS isn’t available.

➤ Does Synology support NFS and SMB?

Yes. Synology DSM supports both protocols. SMB is enabled by default. Enable NFS through Control Panel > File Services > NFS, then set NFS permissions per shared folder. Most Synology users run SMB for desktop clients and NFS for Linux servers, Docker hosts, or Proxmox datastores.

➤ NFS or SMB for TrueNAS media storage?

TrueNAS supports both. For media apps like Plex or Jellyfin running in TrueNAS containers or jails, NFS is the common choice. Create a dataset, configure NFS sharing on it, and point your media app at the NFS mount. Be aware that TrueNAS SCALE (Linux-based) and TrueNAS CORE (FreeBSD-based) handle NFS permissions slightly differently.

Conclusion: Make the Choice That Fits Your Clients and Your Risk

The decision comes down to matching your protocol to your environment and accepting the trade-offs.

If your world is Linux, NFS is the pragmatic, fast, and simple default. It speaks the same language as your filesystem and won’t fight you on permissions.

If you have Windows or macOS clients, SMB is the native choice that works. SMB3 brings solid security without requiring a PhD in Kerberos configuration.

You can run both protocols, but don’t blindly export the same writeable path over both unless you understand how permissions and metadata will clash. That way lies madness and mysterious “permission denied” errors you will never reproduce on demand.

Lock it down. Keep shares on your LAN, disable SMBv1 (seriously, it’s 2025), prefer NFSv4, and consider Kerberos or SMB encryption where your threat model demands it.

Next steps:

Pick one protocol per client type and start simple. Don’t overcomplicate your first setup. Benchmark your scans and streams to establish a baseline. Layer on security and performance tuning only after you have a stable foundation.

Linux media server, Windows laptop hitting an Unraid share, doesn’t really matter. The choice matters less than knowing why you chose. Stop treating network protocols like a coin flip. Match them to your clients, and the whole stack gets faster, safer, and quieter.

TP-Link 2.5GB PCIe Network Card (TX201)
Hard to compare NFS and SMB performance when your NIC is the bottleneck. This 2.5GbE PCIe card is cheap and works out of the box on most Linux distros and Windows. It gets your gigabit ceiling out of the way so you can see what the protocols are doing.

Amazon Price: Loading...

Availability: Checking...

Contains affiliate links. I may earn a commission at no cost to you.

How to Install Docker on Debian for GPU Passthrough and Transcoding

Wed, 27 Aug 2025 10:03:58 -0600

You want buttery-smooth 4K to 1080p hardware transcoding, and the quiet satisfaction of watching your CPU lounge around at 10% while your GPU does the heavy lifting. So you pass your GPU into a Docker container, and Jellyfin stares back at you with the enthusiasm of a DMV clerk. CPU’s pegged. Jellyfin’s logs throwing a tantrum about “no such device /dev/dri/renderD128.”

Welcome to the club. Population: everyone who has ever tried this.

I once burned a perfectly good Friday night (116 minutes, to be precise) wrestling with what Docker’s documentation cheerfully calls “simple” GPU passthrough. Drivers? Rock solid. Docker daemon? Restarted three times, because why stop at two. YAML file? Formatted with the precision of a Swiss watchmaker. The actual problem? Linux permissions had decided my container wasn’t ‘special’ enough for the render group’s exclusive party.

After a scenic tour through udev rules, cgroup mysteries, and two spectacularly wrong Reddit threads that shall remain nameless, the GPU finally woke up. Frame times dropped from “slideshow” to “silk.” My CPU went back to napping. And I made myself a promise to document this mess before my brain forgot the crucial details.

This is that documentation. The step-by-step guide I needed that night. You’ll get the exact Docker Compose configuration, the permissions that matter, and a heads-up about the gotchas that love to bite newcomers. Whether you’re on NVIDIA, Intel integrated graphics, or AMD, by the end of this you’ll have hardware-accelerated transcoding humming inside Docker. No marathon debugging session required.

💭

TL;DR: Think Docker will magically use your GPU? Cute. NVIDIA needs –gpus, Intel/AMD need /dev/dri, and you need to join the right groups. Otherwise, enjoy watching your CPU sweat bullets.

ASRock Intel Arc A580 Challenger 8GB OC The Arc A580 can hold its own in games, but here it’s for obliterating video streams. With support for H.264, HEVC, and full AV1 hardware encode/decode across two media engines, it crushes 20+ 1080p streams or 6–8 HDR tone-mapped 4Ks without breaking a sweat. Drop it in your media server, give Jellyfin direct VA-API access, and watch your CPU finally cool off for a bit.

Amazon Price: Loading...

Availability: Checking...

Contains affiliate links. I may earn a commission at no cost to you.

That card up there is what I’d buy today if I was starting fresh. But the box won’t help you if Docker can’t see it. So let’s talk about why this whole setup falls over so often.

Why GPU Passthrough Matters

Video transcoding hammers a CPU. Hardware acceleration through GPU features (NVIDIA NVENC, Intel VAAPI/QSV, AMD VCE) moves that work off the CPU, drops your load average, and quiets the fans.

Docker lets you isolate Jellyfin or Plex in a container while still handing the GPU through in a controlled way. You get smoother streams, more simultaneous viewers, quieter hardware, and an idle CPU that finally earns its sleep state.

One thing to keep straight: GPU passthrough in Docker is not the same as VM passthrough. Docker leans on device permissions and cgroups to share a GPU between host and container. It’s nowhere near as involved as full hardware virtualization through PCIe passthrough on a hypervisor.

Why GPU Passthrough in Docker on Debian Often Fails (And How to Fix It)

Here’s the thing about GPU passthrough with Docker on Debian or any other Linux distro. It’s conceptually clean and practically finicky. Your GPU lives on the host, happily managed by kernel drivers. Your container exists in its own isolated environment with its own filesystem and permissions. Getting Docker and your GPU to talk takes more than mounting a device file. You need the right permissions, the correct device nodes, and sometimes a few udev rules to make everything line up.

Think of it like lending your car to a friend. Handing over the keys (mounting the device) isn’t enough. They need insurance coverage (permissions), they need to know where it’s parked (device paths), and they need to understand the quirks (Linux-specific device behaviors).

Common failures: your container sees the GPU but has no permission to use it, missing device nodes make the GPU invisible, or everything works until a reboot shuffles the device paths and breaks the mapping.

Let’s fix all of that and get Docker GPU passthrough working reliably.

Need a Linux permissions refresher?
Understanding Linux Permissions

Proper Docker Compose Configuration for GPU Passthrough on Debian

Forget juggling docker run -it commands with a wall of flags. Here’s a straightforward Docker Compose setup for GPU passthrough that survives Debian reboots:

services:
 jellyfin:
 image: jellyfin/jellyfin:latest
 container_name: jellyfin-hw
 devices:
 - /dev/dri/renderD128:/dev/dri/renderD128  # GPU device access
 group_add:
 - "render" # Add container user to render group
 - "video" # Add container user to video group
 environment:
 - JELLYFIN_PublishedServerUrl=http://your-server-ip:8096
 volumes:
 - ./config:/config
 - ./cache:/cache
 - /path/to/media:/media:ro
 ports:
 - "8096:8096"
 restart: unless-stopped

Why this works:

devices: /dev/dri/renderD128:/dev/dri/renderD128 hands the render node into the container, which is what VA-API needs.
group_add puts the container user in the render and video groups so the device permissions actually let it through.
restart: unless-stopped brings Jellyfin back after a reboot or a crash, instead of leaving you to notice when someone tries to watch something.

NVIDIA vs Intel/AMD GPU Passthrough on Docker

NVIDIA: Simplified GPU Passthrough

Install the proprietary NVIDIA driver and the NVIDIA Container Toolkit on Debian. Then use docker run -it --gpus all or the Compose device_requests block. The toolkit handles the driver mapping and permissions for you.

Good fit for transcoding, AI workloads, or anything else that wants CUDA.

Intel/AMD: Manual Device Mapping

For Intel and AMD on Debian, you do the work yourself. Expose /dev/dri to the container, manage the permissions, and make sure the right drivers are installed (intel-media-va-driver, mesa-va-drivers).

Add the container user to the render and video groups or you’ll spend an hour debugging Permission denied errors. Once it’s wired up, this approach is rock-solid for transcoding.

Preparing Your Debian Host for Docker GPU Passthrough

Before you touch Docker, prove the GPU works on the host. If vainfo or nvidia-smi doesn’t see it from the bare metal, no amount of YAML will help you.

NVIDIA Setup on Debian

Install the NVIDIA proprietary drivers. Verify with nvidia-smi.
Install the NVIDIA Container Toolkit:

sudo apt-get update
sudo apt-get install -y nvidia-container-toolkit
sudo nvidia-ctk runtime configure --runtime=docker
sudo systemctl restart docker

Verify with:

docker run --rm --gpus=all nvidia/cuda:12.4.1-base-ubuntu22.04 nvidia-smi

Intel iGPU Setup

Confirm the i915 kernel driver is loaded:

lsmod | grep i915

Check that /dev/dri device nodes exist (ls -l /dev/dri/).
Install VA-API drivers:

sudo apt install intel-media-va-driver vainfo

Run vainfo and look for a populated profile list. An empty list means the driver isn’t loading.

Docker and Docker Compose Requirements for GPU Passthrough on Debian

Docker version 20.10 or newer (check with docker --version)
Docker Compose V2 (docker compose, not the legacy docker-compose)
A Linux kernel with cgroup v2 enabled

NVIDIA users need the runtime wired up through nvidia-container-toolkit. Intel and AMD users only need correct device mapping and group membership.

Correct GPU Passthrough Configuration with Docker Compose on Debian

⚠️

Warning: I do not use NVIDIA or AMD hardware in my lab. Everything NVIDIA or AMD related in this post is straight from the documention.

NVIDIA Compose Example:

services:
 jellyfin:
 image: jellyfin/jellyfin:latest
 container_name: jellyfin
 ports:
 - "8096:8096"
 volumes:
 - /srv/jellyfin/config:/config
 - /srv/media:/media
 restart: unless-stopped
 runtime: nvidia
 deploy:
 resources:
 reservations:
 devices:
 - driver: nvidia
 count: all
 capabilities: [gpu]

Intel/AMD Compose Example:

services:
 jellyfin:
 image: jellyfin/jellyfin:latest
 container_name: jellyfin
 devices:
 - /dev/dri/renderD128:/dev/dri/renderD128
 user: "1000:1000" # Adjust to your host user UID:GID
 group_add:
 - "render_gid" # Replace with actual host render group GID
 - "video_gid" # Replace with actual host video group GID
 ports:
 - "8096:8096"
 volumes:
 - /srv/jellyfin/config:/config
 - /srv/media:/media
 restart: unless-stopped

Grab the right group IDs from the host with getent group render and getent group video. Drop the numeric GID into group_add in place of render_gid and video_gid. If you run a beefier Arc card, the same Compose file applies and you get more headroom for parallel streams.

Sparkle Intel Arc B580 Titan The Intel Arc B580 is a transcoding powerhouse, with full hardware support for AV1, HEVC, VP9, and H.264 plus 12 GB of VRAM for smooth multi-stream 4K/8K workflows. Its 160 XMX AI engines turbocharge upscaling and media conversions, making it perfect for Plex, Jellyfin, or Docker-based media servers.

Amazon Price: Loading...

Availability: Checking...

Contains affiliate links. I may earn a commission at no cost to you.

Once the Compose file is in place and the GPU is wired through, the only thing left is troubleshooting whatever the first docker compose up -d throws at you.

Resolving Common GPU Passthrough Issues on Debian with Docker

no available runtime or could not select device driver means the NVIDIA Container Toolkit isn’t installed or the daemon hasn’t been restarted since you configured it.
no such device /dev/dri/renderD128 means the device nodes aren’t mapped, or the GPU drivers aren’t loaded on the host. Run ls -l /dev/dri/ to confirm.
Permission denied errors almost always trace back to missing group_add for render and video. Double-check the numeric GIDs match the host.
After a kernel update, device numbering can shift. Use a udev rule to pin permissions, or symlink /dev/dri/renderD128 so the path stays stable.

Verifying GPU Access Inside Your Docker Container

For NVIDIA: docker run --rm --gpus=all nvidia/cuda nvidia-smi. You want to see your card listed.
For Intel/AMD: docker run --rm --device /dev/dri:/dev/dri jrottenberg/ffmpeg ffmpeg -hwaccels. Look for vaapi or qsv in the output.

If those work from a throwaway container, your Compose file will work too.

Real-World Example: Jellyfin GPU Passthrough on Debian

NVIDIA-enabled Jellyfin:

services:
 jellyfin:
 image: jellyfin/jellyfin:latest
 container_name: jellyfin
 volumes:
 - /srv/jellyfin/config:/config
 - /srv/media:/media
 ports:
 - "8096:8096"
 restart: unless-stopped
 runtime: nvidia
 deploy:
 resources:
 reservations:
 devices:
 - driver: nvidia
 count: all
 capabilities: [gpu]

Intel iGPU Jellyfin:

services:
 jellyfin:
 image: jellyfin/jellyfin:latest
 container_name: jellyfin
 devices:
 - /dev/dri/renderD128:/dev/dri/renderD128
 user: "1000:1000"
 group_add:
 - "render_gid"
 - "video_gid"
 volumes:
 - /srv/jellyfin/config:/config
 - /srv/media:/media
 ports:
 - "8096:8096"
 restart: unless-stopped

After the container is up, head into Jellyfin’s Dashboard, open Playback, and switch hardware acceleration to VA-API (Intel/AMD) or NVENC (NVIDIA). Set the render device to /dev/dri/renderD128 for VA-API. Play a 4K file from a phone or browser and watch intel_gpu_top or nvidia-smi dmon light up on the host. If the host stays quiet and the CPU spikes, transcoding is still landing on software.

Final Tips for Installing Docker on Debian and Running GPU Passthrough on Raspberry Pi and Home Servers

Always verify GPU functionality on the host before you touch Docker.
Install Docker on Debian from the official repositories or Docker’s install script.
- My Docker install instructions
Use docker run -it with --gpus for a quick smoke test on NVIDIA before you commit to a Compose file.
A Raspberry Pi 4 or 5 has no useful video encoder for modern codecs. If you want serious Jellyfin transcoding, run it on x86 with an Intel iGPU or a discrete Arc card. The NUC below is the small-footprint version of that recommendation.

Run those steps in order and you’ll have hardware-accelerated transcoding working inside Docker on Debian.

Other Resources

Happy transcoding with Docker.

Intel NUC 12 Pro (NUC12WSHi5) Compact mini PC for lightweight servers, GPU Passthrough, Docker stacks, and VMs.

Amazon Price: Loading...

Availability: Checking...

Contains affiliate links. I may earn a commission at no cost to you.

Proxmox Intel GPU Passthrough: QuickSync & Arc Setup Guide

Fri, 15 Aug 2025 05:17:37 -0600

So, you want smooth media transcoding in your Jellyfin VM running on Proxmox, and you’ve heard Intel QuickSync is the silver bullet. Or maybe you’re chasing GPU cycles for gaming, but Proxmox’s default CPU emulation isn’t cutting it. Hardware passthrough is the promise of bare-metal performance wrapped in the warm hug of virtualization.

Here’s the kicker Reddit forgets to mention: halfway in, your server can black out. Silent, unresponsive, and only revivable through SSH. Think digital coma. Good times.

If you’ve ever wrestled with PCIe passthrough, IOMMU groups, or found yourself frantically Googling “why is my Proxmox host dead after GPU passthrough?” with the host unreachable, welcome to the club. The membership fee? A few gray hairs and an extra helping of existential dread. If not, congrats, and read on to keep it that way.

This guide walks through GPU passthrough in Proxmox, the gotchas that matter, and how to get QuickSync (or any GPU) transcoding without turning your Proxmox box into a doorstop.

💭

TL;DR: Want blazing-fast media transcodes in your Jellyfin or Plex VM? GPU passthrough lets your VM access your Intel QuickSync or discrete GPU directly, with no emulation and no lag. But if you recklessly hand over your only GPU, your Proxmox host might go dark faster than your hopes during a Blue Screen of death. This guide walks you through setup, IOMMU group hell, and how to avoid turning your homelab into a brick.

Amazon Price: Loading...

Availability: Checking...

Contains affiliate links. I may earn a commission at no cost to you.

What Is Hardware Passthrough, Really?

Think of your typical VM setup like a hotel stay. Your VM gets a comfortable room (virtualized hardware), but it shares resources with every other guest. Proxmox, our hypervisor, is the hotel manager allocating what you get and when.

Hardware passthrough is like buying out an entire floor, with an express elevator. Instead of your VM politely asking Proxmox for GPU power, you hand over the hardware directly. “This is yours, use it as you like.”

The payoff: your VM’s applications talk directly to the hardware, bypassing virtualization overhead. For transcoding, Intel QuickSync runs at full bare-metal speed.

Here’s the thing: when you do Proxmox PCIe passthrough, you’re yanking that hardware away from the host. Was Proxmox using that GPU for the console display? Say goodbye to that output.

The IOMMU Groups Reality Check

IOMMU groups are the rules that decide what hardware you can actually pass through.

IOMMU (Input-Output Memory Management Unit) groups are like apartment buildings for PCIe devices. Everything in one group shares certain pathways. You can’t evict one tenant in isolation, you have to pass the whole group to your VM.

Why does this matter? If your GPU shares an IOMMU group with, say, your network card, you can’t pass through the GPU alone. It’s all or nothing. This is where most passthrough dreams go to die.

The good news? Most modern systems have sensible group layouts, especially for integrated graphics. Intel’s QuickSync, baked into the CPU, usually plays nice.

Pre-Flight Checklist: What You Need

Before you tear apart a perfectly functional Proxmox setup, check these requirements:

Hardware Requirements:

CPU with Intel QuickSync (think almost any modern Intel CPU)
Motherboard with IOMMU/VT-d (enable in BIOS)
Enough PCIe lanes (if you’re using a discrete GPU)
Backup access to your Proxmox host (SSH, IPMI, or a secondary GPU)

❌

Danger: The Backup Access Point Crucial Detail: Don’t pass through your only graphics output to a VM without an alternative. SSH is great, until something breaks and you need console access. IPMI is king if you have it, and a basic secondary GPU for the host is even better.

Software Prerequisites:

Proxmox VE (obviously)
A guest OS that supports your hardware

Intel® Core™ i5-14500 14th Generation Desktop Processor This 14th-gen i5 packs QuickSync with UHD 770 graphics, enough to power 4K → 1080p transcodes like a champ. You’ll push 10+ simultaneous 1080p streams with near-zero CPU load. Ideal for low-power, headless Proxmox boxes that run hot and quiet. No dGPU? No problem.

Amazon Price: Loading...

Availability: Checking...

Contains affiliate links. I may earn a commission at no cost to you.

Be honest. If you’re here, your CPU is probably choking on media transcoding while you dream of QuickSync.

What Is GPU Passthrough and Why Should You Care?

GPU passthrough in proxmox means telling Proxmox to stop hogging your GPU and give it directly to your VM. This gives your VM the keys to the Ferrari while Proxmox walks home. For QuickSync, this means Jellyfin or any media workflow will fly through transcoding.

⚠️

Warning: Once you pass that GPU through, your Proxmox host loses access. If it’s your only GPU, the host display output goes dark. Remote access via SSH (or a serial console) is essential, not optional.

Prerequisites: What You’ll Need Before Diving In

Don’t skip the homework before shuffling hardware assignments:

CPU must support IOMMU:

Intel calls it VT-d
AMD calls it: AMD-Vi
And enable it in the BIOS (often OFF by default).

Motherboard must support IOMMU groups properly:

These groups decide what you can pass through
Some boards group devices nonsensically, making passthrough a pain.

You need remote access (SSH/IPMI):

Without it, losing your display means flying blind.
My SSH Guide

GPU isolation:

The PCIe slot should NOT share an IOMMU group with critical components, or passthrough may not work.

❌

Danger: This is the quickest way to break your server.

Checking IOMMU Groups: The Foundation

Check how your system organizes devices. On your Proxmox host:

find /sys/kernel/iommu_groups/ -type l | sort -V

It should look something like this:

/sys/kernel/iommu_groups/0/devices/0000:00:02.0
/sys/kernel/iommu_groups/1/devices/0000:00:00.0
/sys/kernel/iommu_groups/2/devices/0000:00:06.0
/sys/kernel/iommu_groups/3/devices/0000:00:14.0
/sys/kernel/iommu_groups/3/devices/0000:00:14.2
/sys/kernel/iommu_groups/4/devices/0000:00:15.0
/sys/kernel/iommu_groups/5/devices/0000:00:16.0
/sys/kernel/iommu_groups/6/devices/0000:00:17.0
/sys/kernel/iommu_groups/7/devices/0000:00:1c.0
/sys/kernel/iommu_groups/8/devices/0000:00:1c.2
/sys/kernel/iommu_groups/9/devices/0000:00:1f.0
/sys/kernel/iommu_groups/9/devices/0000:00:1f.3
/sys/kernel/iommu_groups/9/devices/0000:00:1f.4
/sys/kernel/iommu_groups/9/devices/0000:00:1f.5
/sys/kernel/iommu_groups/10/devices/0000:01:00.0
/sys/kernel/iommu_groups/11/devices/0000:02:00.0
/sys/kernel/iommu_groups/12/devices/0000:02:00.1
/sys/kernel/iommu_groups/13/devices/0000:03:00.0

To better ID what these components are run:

lspci -nn

Results:

00:00.0 Host bridge [0600]: Intel Corporation Device [8086:4648] (rev 02)
00:02.0 VGA compatible controller [0300]: Intel Corporation AlderLake-S GT1 [8086:4680] (rev 0c)
00:06.0 PCI bridge [0604]: Intel Corporation 12th Gen Core Processor PCI Express x4 Controller #0 [8086:464d] (rev 02)
00:14.0 USB controller [0c03]: Intel Corporation Alder Lake-S PCH USB 3.2 Gen 2x2 XHCI Controller [8086:7ae0] (rev 11)
00:14.2 RAM memory [0500]: Intel Corporation Alder Lake-S PCH Shared SRAM [8086:7aa7] (rev 11)
00:15.0 Serial bus controller [0c80]: Intel Corporation Alder Lake-S PCH Serial IO I2C Controller #0 [8086:7acc] (rev 11)
00:16.0 Communication controller [0780]: Intel Corporation Alder Lake-S PCH HECI Controller #1 [8086:7ae8] (rev 11)
00:17.0 SATA controller [0106]: Intel Corporation Alder Lake-S PCH SATA Controller [AHCI Mode] [8086:7ae2] (rev 11)
00:1c.0 PCI bridge [0604]: Intel Corporation Alder Lake-S PCH PCI Express Root Port #2 [8086:7ab9] (rev 11)
00:1c.2 PCI bridge [0604]: Intel Corporation Alder Lake-S PCH PCI Express Root Port [8086:7aba] (rev 11)
00:1f.0 ISA bridge [0601]: Intel Corporation Z690 Chipset LPC/eSPI Controller [8086:7a84] (rev 11)
00:1f.3 Audio device [0403]: Intel Corporation Alder Lake-S HD Audio Controller [8086:7ad0] (rev 11)
00:1f.4 SMBus [0c05]: Intel Corporation Alder Lake-S PCH SMBus Controller [8086:7aa3] (rev 11)
00:1f.5 Serial bus controller [0c80]: Intel Corporation Alder Lake-S PCH SPI Controller [8086:7aa4] (rev 11)
01:00.0 Non-Volatile memory controller [0108]: Sandisk Corp WD Black SN770 NVMe SSD [15b7:5017] (rev 01)
02:00.0 Ethernet controller [0200]: Intel Corporation 82576 Gigabit Network Connection [8086:10c9] (rev 01)
02:00.1 Ethernet controller [0200]: Intel Corporation 82576 Gigabit Network Connection [8086:10c9] (rev 01)
03:00.0 Ethernet controller [0200]: Realtek Semiconductor Co., Ltd. RTL8125 2.5GbE Controller [10ec:8125] (rev 05)

Find your GPU in the output. Ideally, it stands alone or with non-essential devices. If grouped with essentials (USB, network), you might need to pass more than planned or use ACS override patches (advanced territory that I will not be covering).

You can see my GPU on 00:02.0. This is my QuickSync GPU.

Configuring Proxmox for GPU Passthrough

If your hardware checks out, congrats, now on to configuration:

1. Enable IOMMU in Proxmox:

Edit /etc/default/grub and change GRUB_CMDLINE_LINUX_DEFAULT:

nano /etc/default/grub

Intel example:

GRUB_CMDLINE_LINUX_DEFAULT="quiet intel_iommu=on iommu=pt"

AMD example:

GRUB_CMDLINE_LINUX_DEFAULT="quiet amd_iommu=on iommu=pt"

Update grub with:

update-grub

2. Load VFIO modules: Add these to /etc/modules:

nano /etc/modules

Paste these in:

vfio
vfio_iommu_type1
vfio_pci
vfio_virqfd

3. Blacklist host GPU drivers:

For Intel iGPU (QuickSync):

echo "blacklist i915" >> /etc/modprobe.d/blacklist.conf

For NVIDIA:

echo "blacklist nouveau" >> /etc/modprobe.d/blacklist.conf

For AMD:

echo "blacklist amdgpu" >> /etc/modprobe.d/blacklist.conf

4. Bind GPU to VFIO: Find your GPU’s PCI ID:

lspci -nn | grep -E "VGA|3D|Display"

Then create /etc/modprobe.d/vfio.conf:

nano /etc/modprobe.d/vfio.conf

Paste this (Replace YOUR_GUP_ID with your ID example 00:02.0):

options vfio-pci ids=YOUR_GPU_ID

5. Rebuild initramfs and reboot:

update-initramfs -u

Then reboot

reboot

VM Setup: The Fun Part

In Proxmox UI:

Edit your VM → Hardware → Add PCI Device
Select your GPU (and its audio function, if present)
Check “All Functions” and “Primary GPU” if necessary
For some VMs (Windows), you may need a matching VBIOS/ROM file
Boot VM and install drivers (Linux: intel-media-driver for QuickSync, or the Windows/OS driver you need)

Passing through both graphics and audio functions mimics real hardware. The “All Functions” and “Primary GPU” options help make the transition smooth, especially for picky OSes like Windows.

Intel NUC 12 Pro (NUC12WSHi5) Compact mini PC for lightweight servers, GPU Passthrough, Docker stacks, and VMs.

Amazon Price: Loading...

Availability: Checking...

Contains affiliate links. I may earn a commission at no cost to you.

Troubleshooting: When Things Go Sideways

Proxmox PCIe passthrough feels like wizardry, until it doesn’t. If you get a black screen or your VM crashes, don’t panic:

Double-check driver blacklists. One typo can ruin your weekend.
Confirm IOMMU is active: dmesg | grep -e DMAR -e IOMMU should show enable messages.
Rely on SSH or IPMI over the local console.
Check /var/log/syslog and journalctl -b for PCI errors. VM logs live under /var/log/pve/qemu-server/{VMID}.log.
Try another PCI slot or disable peripheral devices that share the GPU’s IOMMU group.

If your system is completely unresponsive, comment out VFIO and GPU configurations, rebuild initramfs, and reboot. Most disasters are reversible if you don’t panic.

Gotchas, Caveats, and Advanced Notes

Single-GPU pass-through disables your Proxmox host’s display.
You will lose all video output on the host. Recovery requires remote access or another GPU.

NVIDIA consumer cards may throw tantrums.
Windows “Code 43” errors can appear.
Hyper-V spoofing in the VM args (hidden=1,kvm=off) often clears them.

QuickSync isn’t always present. Verify your CPU model.
Xeon CPUs may lack QuickSync even if they have integrated graphics.
Always check official Intel docs:
Intel Product Details

Or use the Quick Sync compatibility checker: pick your CPU generation and see exactly which codecs it can decode and encode in hardware.

Check your CPU

LXC vs. VM passthrough are different creatures.
LXCs share hardware via device mapping (lxc.cgroup2.devices.allow and /dev/dri bind-mounts).
VMs demand exclusive, full PCI assignment.

EULA caveats for consumer GPUs in datacenters.
NVIDIA and AMD consumer cards often restrict use in virtualized environments, especially commercial or datacenter.

Common Misconceptions

Myth: Any consumer GPU works.
- Reality: Pro cards (Quadro/Radeon Pro) are better supported.
Myth: Rebooting fixes EVERYTHING.
- Reality: Sometimes you need to completely remove and re-add the GPU or reset the PCIe slot.
Myth: Passthrough is rock-solid once it boots.
- Reality: VM restarts may need extra care (cold boots, PCIe resets).

Recovery, Best Practices, and Sanity Saving

Use multiple GPUs if possible (one for Proxmox, one for your VM).
Always set up SSH or IPMI access before tinkering.
Backup /etc/pve before major changes.
Keep copies of your IOMMU and driver blacklist configs.
If locked out: Boot live USB, chroot, and reverse your changes step-by-step.

For stability:

Match your VM’s drivers to your GPU
Set VM CPU type to host or enable passthrough
Only pass through required PCI devices

A clean GPU passthrough setup means less time in the recovery console and more time transcoding or gaming.

Wrapping Up

GPU passthrough on Proxmox is like taming a clever, unpredictable cat. When it works, your VM stops behaving like a VM and QuickSync (or your RTX card) chews through workloads the host CPU used to choke on. When it doesn’t, you’ll become very familiar with the recovery console.

Key Takeaways:

Passthrough gives your VM direct hardware access. The host loses that hardware. Plan accordingly.
Never pass through your last GPU unless you’re ready for a headless server.
IOMMU groups, BIOS settings, and Proxmox module configs must all align.
Back up /etc/pve and your /etc/modprobe.d/ files before making changes.
Keep SSH or IPMI working before you reboot. That’s your lifeline when the console goes dark.

Once you nail it, the Proxmox PCIe passthrough setup blends virtualization flexibility with raw GPU performance, and your Jellyfin or gaming VM stops fighting the hypervisor.

Need more information?

MINISFORUM MS-A2 A Ryzen-powered beast in a mini PC shell. Dual 2.5GbE, 10GbE option, triple NVMe. Small box, big Proxmox energy.

Amazon Price: Loading...

Availability: Checking...

Contains affiliate links. I may earn a commission at no cost to you.

Master the Basics - SMB Guide for Media Servers

Sat, 09 Aug 2025 05:53:49 -0600

You’ve got files. You’ve got machines. And you’re tired of playing sneakernet with USB sticks like some kind of caveman.

What you want is simple. A shared folder that every device on your network can see. Windows boxes. Macs. That crusty ThinkPad running Ubuntu in the corner. Even your “smart” TV that somehow needs to stream 4K remuxes but can’t figure out basic networking.

Enter Samba. It’s your network’s Swiss Army knife, part bouncer, part bartender, part DJ. And once you set it up right, it stays out of your way.

💭

TL;DR: Samba turns your Linux box into a file server every device on your network can use. We’ll skip the garbage defaults and build something that streams 4K without stuttering and doesn’t require a PhD to troubleshoot.

UGREEN NASync DXP4800 Plus 4-Bay Desktop NAS UGREEN NASync DXP4800 Plus, 4-Bay NAS with an Intel Pentium Gold 8505 5-core CPU, 8GB DDR5, a 128GB built-in SSD, 2x M.2 NVMe slots, and both 10GbE and 2.5GbE ports (Diskless). This is perfect if you don’t want to DIY your NAS.

Amazon Price: Loading...

Availability: Checking...

Contains affiliate links. I may earn a commission at no cost to you.

When SMB Is Your Best Friend

SMB shines in these scenarios:

Mixed OS chaos: Windows, macOS, Linux all playing nice together. No more “sorry, your OS isn’t supported.”
Apps that demand SMB: Time Machine backups. Windows Explorer mapping. Kodi libraries. Sonos music folders. They speak SMB or they speak nothing.
User-based security: You decide who gets in and what they can touch. No more “everyone has access to everything” nonsense.
Dumb devices: Your smart TV, IoT gadgets, and network printers don’t know NFS from a hole in the ground. But they know SMB.
Cross-platform development: Same project folder on Windows, Mac, and Linux. No sync conflicts, no version hell.

Skip SMB When…

Linux-only network: NFS is faster, simpler, and doesn’t carry Windows baggage.
Remote access: SSHFS or WebDAV won’t make you cry when you’re connecting over WAN.

Install Samba (Debian/Ubuntu)

Install the samba package:

sudo apt update && sudo apt install samba

That’s it. No package maze, no dependency hell.

Now set the Samba user’s password. This is not optional:

sudo smbpasswd -a yourusername

⚠️

Warning: Why this matters: Samba uses its own password database. Your Linux user exists? Great. But without smbpasswd, you’re locked out. I’ve watched too many people bang their head against “authentication failed” errors because they skipped this step.

Start the services:

sudo systemctl enable --now smbd nmbd

A Configuration File That Works

Time to ditch the ancient defaults in /etc/samba/smb.conf. Here’s what you need.

`[global]` Settings: With Large File Transfers and Security in Mind

[global]
 workgroup = WORKGROUP
 netbios name = MEDIA-SERVER
 server string = %h server (Samba %v)

 # Security that makes sense
 security = user
 map to guest = Bad User

 # Force modern protocols
 server min protocol = SMB2
 server max protocol = SMB3
 client min protocol = SMB2

 # Encrypt everything
 smb encrypt = required

 # Disable insecure features
 lanman auth = no
 ntlm auth = no

 # Kill anonymous access
 restrict anonymous = 2

 # Network optimizations
 socket options = TCP_NODELAY SO_RCVBUF=131072 SO_SNDBUF=131072

 # File transfer optimization
 use sendfile = yes

 # Async I/O for large files
 aio read size = 16384
 aio write size = 16384

 # Reduce metadata overhead
 strict allocate = yes

 # Logging that helps
 log file = /var/log/samba/log.%m
 max log size = 1000

 # Stop being a DNS server
 dns proxy = no

Why these settings work:

security = user: Per-user authentication. Not “everyone’s admin” madness.
map to guest = Bad User: Invalid usernames become guest access (if you allow it).
server min/max protocol: Forces SMB2/3, ditches the security nightmare that is SMB1.
dns proxy = no: Samba shouldn’t handle DNS. That’s your DNS server’s job.
smb encrypt = required: All traffic encrypted. No plaintext passwords floating around.
restrict anonymous = 2: Kills guest browsing and anonymous enumeration.
lanman/ntlm auth = no: Forces modern authentication methods.

`[share]` Definition: Where the Magic Happens

[media]
 path = /media/storage
 browseable = yes
 read only = no
 guest ok = no
 valid users = yourusername
 force user = yourusername
 create mask = 0660
 directory mask = 0770

Why this configuration works:

force user/group: Every file gets the same owner. No more permission spaghetti.
create/directory mask: Sane default permissions. Files get 660, directories get 770.
browseable = yes: Shows up in Windows Network Explorer without extra clicking.
guest ok = no: Authentication required. Because security matters.

A share definition like this is only as fast as the pipe it rides on. If you’re still on a single 1GbE link and pushing 4K remuxes, you’re going to feel it.

TP-Link 2.5GB PCIe Network Card (TX201) Plug-and-play 2.5GbE PCIe card that unlocks multi-gig speeds for about $30. Works out of the box with Proxmox, Linux, and Windows. No drama, no driver hunt, faster transfers.

Amazon Price: Loading...

Availability: Checking...

Contains affiliate links. I may earn a commission at no cost to you.

Troubleshooting: Fix the Usual Suspects

Check your configuration:

sudo testparm

Test shares without leaving the server:

smbclient -L localhost -U yourusername

Check Samba’s view of connected users:

sudo smbstatus

Watch logs live:

tail -f /var/log/samba/log.smbd

Flush config changes without a reboot:

sudo systemctl restart smbd nmbd

Common Problems, Fast Fixes

“Access denied” but login works:

Check Linux filesystem permissions
Verify valid users matches actual usernames

Share invisible in Windows:

Add netbios name to [global]
Restart both services: sudo systemctl restart smbd nmbd
Windows sometimes caches old network info. Reboot the client.

Slow transfers:

Enable use sendfile = yes
Check your network. Gigabit wired > WiFi > carrier pigeon
Large files? Enable async I/O settings above

“Mount error: Protocol not supported”:

Client trying to use SMB1
Fix: mount -t cifs //server/share /mnt -o vers=3.0

The Nuclear Option:

When nothing else works: Stop samba:

sudo systemctl stop smbd nmbd

Remove samba’s cache files:

sudo rm /var/cache/samba/*

Start samba

sudo systemctl start smbd nmbd

Real-World Scenarios

Media Server Hub:

Point Jellyfin, Plex, or Kodi at your SMB share. Works across containers, VMs, and bare metal. One library, every device.
Development Folder

Same codebase accessible from your Windows IDE, Mac laptop, and Linux server. No git commits to shuffle files around.
Backup Target

Time Machine over SMB. Veeam backups. Even rsync via mounted shares. Central storage that everything can hit.
Cheap NAS Alternative

Old PC + big drives + Samba = network storage that doesn’t cost $800.

SMB vs. The Alternatives

Feature	SMB	NFS	SSHFS
Windows native	✅	❌	❌
macOS native	✅	❌	❌
Performance (LAN)	Good	Excellent	Okay
Security over WAN	❌	❌	✅
Setup complexity	Medium	Low	High
Device compatibility	Excellent	Poor	Poor

The verdict:

SMB wins on compatibility.
NFS wins on pure speed.
SSHFS wins on security.

Pick your poison based on what matters most.

The macOS Update That Broke Everything

Client calls in a panic. “My media server died.” Nothing changed on his end except a macOS update.

The culprit? Apple dropped SMB1 support. His Samba config was still allowing the old protocol, and macOS decided it wasn’t secure enough anymore.

One line in /etc/samba/smb.conf:

server min protocol = SMB2

Five minutes later, his movie night was back on track.

Lesson learned: Set your protocol minimums now. Let the OS updates come. You’ll be ready.

The Bottom Line

Samba isn’t sexy. It’s not the hot new container orchestration platform. It doesn’t have a JavaScript framework named after it.

But it works. It connects everything to everything else. And once you configure it right, it fades into the background and does its job.

That’s the best kind of technology.

Your Network, Your Rules

Stop wrestling with cloud sync conflicts and USB cable hell. Set up a proper SMB share. Stream your movies without stuttering. Back up your machines to something you control.

When you run your own file server, you’re sharing files and taking back control of your data. That’s worth the thirty minutes it takes to get Samba running right.

Ready to build something that works? Start with the basic config above, test it with one device, then expand from there. Your future self will thank you when everything connects on the first try.

Seagate Barracuda 24TB Internal Hard Drive

A 3.5-inch SATA desktop-class drive that delivers huge capacity for bulk storage. Perfect for media libraries, game installs, and cold backups without paying NAS/enterprise premiums. Best for single-drive or light-duty DAS use

Amazon Price: Loading...

Availability: Checking...

Contains affiliate links. I may earn a commission at no cost to you.

Master the Basics - NFS Guide for Media Servers

Sat, 02 Aug 2025 07:46:39 -0600

You spin up an NFS share and think you’re done. Your media server is humming, files are flowing, everything looks perfect. But here’s what you probably missed: you handed every client’s root user complete administrative access to your server. That “quick setup” you found online? It passed out master keys to anyone on your network.

Don’t panic. We’ve all been there. Setting up NFS properly isn’t rocket science once you understand what’s happening under the hood. Let me walk you through an NFS setup that’s fast, secure, and won’t keep you up at night.

💭

TL;DR: Use root_squash so a remote root user can’t become your new system admin. Lock down access to specific trusted IPs, not your entire network. Always use sync, because files sitting in memory aren’t saved files, they’re hopes. Never touch no_root_squash unless you’d hand that client machine your banking passwords. Get your user IDs sorted across all systems, or use all_squash to sidestep the whole mess.

Amazon Price: Loading...

Availability: Checking...

Contains affiliate links. I may earn a commission at no cost to you.

Why NFS Matters for Your Home Lab

Network File System (NFS) is the backbone of most serious home media setups. Samba can be sluggish. FTP is a pain for media apps. NFS gives you near-native filesystem performance across your network. Your Jellyfin server, Sonarr, Radarr, and download clients can all share the same storage without fighting each other.

Here’s the catch. NFS was designed back when networks were trusted and security was someone else’s problem. It assumes every client is honest about who they are. That’s not how the real world works.

Understanding NFS Security: Why Your Setup Matters

Before we get into the technical stuff, let’s talk about why NFS security matters. When you share a folder via NFS, you’re telling the network “here’s some storage you can use.” The problem? NFS trusts whatever user ID (UID) the client claims to be.

Think about it. If your client machine says “hey, I’m root (UID 0), give me access,” NFS shrugs and says “sure thing, boss.” That client can now read, write, delete, and modify permissions on anything in your share. Not what you had in mind when you wanted to stream some movies.

This is where “squashing” comes in. Squashing is NFS’s way of saying “I don’t care who you claim to be, you’re getting mapped to this safe user instead.”

Setting Up the NFS Server

Install the NFS server package:

sudo apt update && sudo apt install nfs-kernel-server

Create your share directory. For media servers, something like /media/storage:

Create the folder:

sudo mkdir -p /media/storage

Set the ownership of the folder:

sudo chown -R nobody:nogroup /media/storage

Set the permissions on the folder:

sudo chmod 755 /media/storage

💡

Tip: Why nobody:nogroup? It’s a safe default owner that unprivileged processes can work with.

Configure Your Exports

Open /etc/exports in your favorite editor and add your share configuration:

/media/storage 192.168.1.0/24(rw,sync,no_subtree_check,root_squash)

Here’s what each piece does:

/media/storage: The directory you’re sharing
192.168.1.0/24: Your network subnet (adjust this to match your actual network)
rw: Read-write access
sync: Wait for writes to complete before responding (more on this later)
no_subtree_check: Skip path validation for better performance
root_squash: Map remote root to the nobody user

Apply the config and start NFS. Run each of these separately:

sudo exportfs -ra
sudo systemctl restart nfs-kernel-server
sudo systemctl enable nfs-kernel-server

Note: The -ra flag tells NFS to re-export all shares and pick up your new configuration.

NFS Squash Options: Your Security Toolkit

This is where most people get confused. Let’s make it crystal clear.

root_squash: The Sensible Default

/media/storage 192.168.1.100(rw,sync,root_squash)

With root_squash, any client claiming to be root (UID 0) gets mapped to the nobody user. That means:

Root can’t change file ownership
Root can’t set special permissions
Root can’t access files owned by other users
Your server stays safe from root-level shenanigans

Use this for: Pretty much everything unless you have a specific reason not to.

all_squash: Maximum Security (This is what I use)

/media/storage 192.168.1.100(rw,sync,all_squash,anonuid=1000,anongid=1000)

With all_squash, every user gets mapped to the anonymous user you specify. It’s like a shared account where nobody can tell who did what.

💡

Tip: Use this for: Public drop folders, backup destinations, or anywhere you want maximum simplicity and security.

no_root_squash: Danger Zone

/media/storage 192.168.1.100(rw,sync,no_root_squash)

This disables squashing entirely. Remote root stays root with full privileges.

❌

Danger: Use this for: Honestly? Almost never in a home setup. Maybe Proxmox backup storage, or system imaging. Only use this if you’d trust that client with SSH root access to your server.

Option	Who’s Root on Client	Permissions on Server	Best For	Danger Level
`root_squash`	Root becomes `nfsnobody`	Limited, can’t chown/setuid	Multi-user environments	🟢 Low
`all_squash`	Everyone becomes `anonuid`	Everyone writes as same safe user	Guest shares, dropzones	🟡 Medium
`no_root_squash`	Root stays root	Full control	Proxmox backups (maybe)	🔴 High

NFS Client Setup: Connecting the Pieces

Now let’s get your client machines connected.

Install Client Tools

sudo apt update && sudo apt install nfs-common

Create Mount Points

sudo mkdir -p /mnt/media

Test Your Connection

Before making anything permanent, test the mount:

sudo mount -t nfs 192.168.1.5:/media/storage /mnt/media

If this works, run ls /mnt/media and you should see your shared content.

Make It Permanent

Add this line to /etc/fstab to mount automatically on boot:

192.168.1.5:/media/storage /mnt/media nfs defaults,nfsvers=4,hard,intr 0 0

TP-Link 2.5GB PCIe Network Card (TX201) Plug-and-play 2.5GbE PCIe card that unlocks multi-gig speeds for about $30. Works out of the box with Proxmox, Linux, and Windows. No drama, faster transfers.

Amazon Price: Loading...

Availability: Checking...

Contains affiliate links. I may earn a commission at no cost to you.

Additional Details

The sync vs async Debate: Why Data Integrity Matters

Here’s a decision that affects both performance and safety.

sync: The Safe Choice

With sync, your NFS server waits for each write to actually hit the disk before telling the client “yep, that’s saved.” It’s slower, but your data is safe.

async: The Fast Option

With async, the server says “sure, I’ll save that” and returns immediately, even if the data is still sitting in memory. It’s faster. If your server crashes, you might lose recent writes.

The verdict: Use sync unless you’re running benchmarks or you enjoy living dangerously. Your media library is worth the small performance hit.

Solving the UID/GID Nightmare

This is where many NFS setups fall apart. Your Jellyfin server runs as user ID 998 on one machine. Your download client runs as user ID 1001 on another. When they try to access the same files over NFS, permissions explode.

The Manual Approach

Align user IDs across all your machines:

# On each client machine
sudo usermod -u 1000 jellyfin
sudo usermod -u 1000 sonarr
sudo groupmod -g 1000 media

The Group Approach (Recommended)

Create a shared group and add all your media services to it:

# On the NFS server
sudo groupadd -g 2000 mediausers
sudo chgrp -R mediausers /media/storage
sudo chmod -R 775 /media/storage

# On each client
sudo usermod -a -G mediausers jellyfin
sudo usermod -a -G mediausers sonarr

Everyone in the mediausers group can read and write, regardless of their individual user IDs.

NFSv3 vs NFSv4: Choosing Your Version

Understanding the differences helps you make the right call.

NFSv3: The Old Reliable

Uses multiple ports (2049 plus random high ports)
Separate daemons for locking and status
Simpler protocol, potentially faster for basic operations
Pain in the neck for firewalls

NFSv4: The Modern Choice

Single port (2049)
Built-in locking and security
Better support for ACLs and modern features
Slightly more overhead but much easier to secure

💡

Tip: Go with NFSv4 unless you have specific legacy requirements. It’s easier to firewall and generally more robust.

Mount Options That Matter

The default mount options are okay. You can do better:

192.168.1.5:/media/storage /mnt/media nfs hard,intr,nfsvers=4,rsize=1048576,wsize=1048576,noatime 0 0

Here’s what each option does:

hard: Don’t give up on network failures, keep retrying
intr: Allow interruption with Ctrl+C if things get stuck
nfsvers=4: Force NFSv4 for better security and single-port operation
rsize/wsize=1048576: Use 1MB read/write buffers for better performance
noatime: Don’t update access timestamps, reduces I/O overhead

Docker and NFS: The Right Way

Here’s a common mistake: mounting NFS shares directly inside Docker containers. Don’t do this. It’s unreliable and causes weird permission issues.

Instead, mount NFS on your Docker host and bind-mount into containers:

# Mount on the host first
sudo mount 192.168.1.5:/media/storage /mnt/media

# Then use in docker-compose.yml
 volumes:
 - /mnt/media:/data/movies
 user: "1000:1000" # Match your media user

This approach is more reliable and gives you better control over permissions.

Firewall Configuration: Locking Down Access

Out of the box, NFSv3 can open multiple ports. That’s a security nightmare. Here’s how to lock it down.

For NFSv3 (If You Must)

You’ll need to pin the additional services to specific ports. Add this to /etc/default/nfs-kernel-server:

RPCMOUNTDOPTS="--manage-gids --port 32767"
STATDOPTS="--port 32765 --outgoing-port 32766"

Then restart NFS and open the ports:

sudo systemctl restart nfs-kernel-server
sudo ufw allow from 192.168.1.0/24 to any port 2049
sudo ufw allow from 192.168.1.0/24 to any port 32765:32767

For NFSv4 (Recommended)

sudo ufw allow from 192.168.1.0/24 to any port 2049

Common NFS Problems and How to Fix Them

Stale File Handles

This happens when you move or delete files on the server while clients are accessing them. The fix is usually a remount:

sudo umount /mnt/media
sudo mount 192.168.1.5:/media/storage /mnt/media

To prevent this, avoid editing files directly on the NFS share. Work on files locally and move them into place when complete.

For example, if you’re processing a video file, edit it in /tmp/processing/movie.mkv and then mv /tmp/processing/movie.mkv /mnt/media/movies/movie.mkv when done. NFS clients either see the old file or the new file, never a half-written mess that causes stale handles.

Performance Issues

If NFS feels slow:

Check your network. Gigabit Ethernet is the minimum for media streaming.
Verify your disk I/O isn’t the bottleneck with iostat -x 1
Try increasing rsize/wsize values in your mount options
Consider NFSv4 if you’re still on v3

Permission Denied Errors

Usually a UID/GID mismatch. Check:

What user/group owns the files on the server?
What user/group is your client process running as?
Are your squash settings allowing the access you need?

Performance Tuning and Benchmarking

Don’t assume your NFS setup is fast. Measure it.

Basic Write Test

dd if=/dev/zero of=/mnt/media/testfile bs=1M count=1000

Real-World Performance Testing

Install fio for more realistic testing:

sudo apt install fio

Test random read/write (simulates media streaming):

fio --name=nfs-test --ioengine=libaio --rw=randrw --bs=64k --size=1G --numjobs=4 --runtime=60 --group_reporting --filename=/mnt/media/fiotest

Look for:

Sustained throughput above 100MB/s for 4K media streaming
Low latency (under 10ms for most operations)
No dramatic performance drops under load

Advanced Security: Beyond Basic IP Filtering

Using hosts.allow and hosts.deny

Add an extra layer of access control. Add this to /etc/hosts.allow:

rpcbind mountd nfsd statd lockd rquotad : 192.168.1.0/24

Add this to /etc/hosts.deny:

rpcbind mountd nfsd statd lockd rquotad : ALL

Network Segmentation

Consider putting your NFS traffic on a dedicated VLAN or subnet. It limits the blast radius if something goes wrong and makes monitoring easier.

Your NFS Pre-Flight Checklist

Before you call your setup “done,” verify:

Squash options are configured for your security needs
You’re using sync for data safety
no_subtree_check is enabled for performance
IP restrictions are tight and tested from allowed and denied hosts
Firewall rules only allow access from trusted networks
User IDs are aligned or properly squashed
Docker containers use host bind mounts rather than direct NFS mounts
Mount options include hard,intr,nfsvers=4
You’ve tested normal operations and permissions

Wrapping Up: NFS That Works

Anyone can copy-paste some commands and get NFS technically functioning. There’s a big difference between “technically working” and rock-solid reliable. One approach gets you streaming tonight and leaves you troubleshooting permission disasters next month. The other gets you streaming tonight and still working flawlessly two years from now.

The security stuff is insurance. Those squash settings and firewall rules seem like overkill until the day they save you from a client machine that got compromised or misconfigured. Your media server should be boring in the best possible way. It works, day after day, without drama.

When NFS is set up right, you forget it exists. Your Jellyfin scans run smoothly, your download clients move files without hiccups, and you never get woken up by permission errors. That’s not luck. That’s good engineering.

Build it once, build it right, then move on to the next project in your lab.

Seagate Barracuda 24TB Internal Hard Drive

Amazon Price: Loading...

Availability: Checking...

Contains affiliate links. I may earn a commission at no cost to you.

Jellyfin QuickSync in a Proxmox Unprivileged LXC (Working Setup)

Sat, 26 Jul 2025 07:46:41 -0600

Why Everyone Gets This Wrong

People treat unprivileged LXC like it’s cursed black magic. “You can’t do NFS!” “GPU passthrough is impossible!” “Use a VM, it’s easier!”

Complete bullshit.

You absolutely can run Jellyfin with Intel QuickSync transcoding in an unprivileged LXC container. The problem isn’t the technology, it’s that most tutorials skip the crucial details or rely on hacky workarounds that break on the first system update.

This guide walks you through the proper way to set up hardware-accelerated Jellyfin transcoding in an unprivileged LXC on Proxmox. No sketchy scripts. No Snap packages. No privileged containers. Clean, secure transcoding.

💭

TL;DR: Yes, Intel QuickSync works in unprivileged LXC. All you need is to give the container access to the GPU, map its group IDs to match the host, install Intel drivers and Jellyfin using APT (not Snap), and flip the hardware transcoding switch in Jellyfin. The result? A secure, lightweight setup that chews through simultaneous 1080p streams without breaking a sweat.

Why VMs Are Overkill for This Job

First, let’s destroy the lazy “use a VM instead” argument once and for all.

The Resource Waste is Criminal

Running Jellyfin in a VM means you’re literally wasting resources you paid for:

Memory: 512MB-1GB VM overhead vs. 10-20MB for LXC
Storage: 12-20GB VM footprint vs. 400-800MB container
Boot time: 30-60 seconds vs. 2-5 seconds
Backups: 10-20GB snapshots vs. 200-500MB

On a typical 16GB homelab box, that VM overhead costs you 2-3 additional services you could be running.

GPU Passthrough Complexity

VM route: VFIO setup, IOMMU groups, driver blacklisting, potential single-GPU nightmares.
LXC route: Map device nodes. Done.

Every disk I/O and network packet in a VM goes through unnecessary virtualization layers. LXC gives you direct host kernel access with zero translation overhead.

The “Easier” Myth

People claim VMs are “easier” because they’re familiar. That’s not easier. That’s lazy. You are wasting resources, creating a more complex GPU passthrough, larger backups, and full OS maintenance overhead for zero benefit. VMs make sense for different kernels, untrusted workloads, or legacy apps that need system control. For a media server? Not so much.

The Real Reason

Fear. Fear of learning device mapping. Fear of doing things better instead of familiar. This guide eliminates that fear. Once you understand LXC device passthrough, you’ll wonder why you ever considered wasting resources on a VM for simple application hosting.

Prerequisites: What You Need

Hardware Requirements

Intel 8th gen CPU or newer with integrated graphics (Coffee Lake+)
QuickSync support enabled in BIOS
Proxmox VE 8.0+ host

Intel® Core™ i5-14500 14th Generation Desktop Processor

Forget GPUs. This 14th-gen i5 packs QuickSync with UHD 770 graphics, enough to power 4K → 1080p transcodes like a champ. You’ll push 10+ simultaneous 1080p streams with near-zero CPU load. Ideal for low-power, headless Proxmox boxes that run hot and quiet. No dGPU? No problem.

Amazon Price: Loading...

Availability: Checking...

Contains affiliate links. I may earn a commission at no cost to you.

Supported Codecs

Intel QuickSync can hardware-accelerate:

H.264 (AVC) - encode/decode
H.265 (HEVC) - encode/decode (9th gen+)
VP9 - decode only (some newer CPUs)
AV1 - decode only (12th gen+)

Not sure what your exact generation can transcode? The Quick Sync compatibility checker lists decode and encode support per codec, including whether you get 4K HDR tone mapping.

Check your CPU

❌

Danger:

This is an in-depth topic.

Any missed or skipped details could cause QuickSync transcoding to fail.

All commands and confs have been tested and re-tested to ensure everything is accurate.

Step 1: Verify Your Hardware Setup

Before diving into container configuration, confirm your hardware is ready.

Check iGPU Detection

On your Proxmox host:

ls -la /dev/dri/

You should see something like:

crw-rw---- 1 root video 226, 0 card0
crw-rw---- 1 root render 226, 128 renderD128

card0 - Display interface (major:minor = 226:0)
renderD128 - Render interface for compute (major:minor = 226:128)

Understanding Device Major:Minor Numbers

When you see 226:0 and 226:128 in the GPU device configuration, these aren’t random numbers, they’re part of Linux’s device identification system. Understanding them is crucial for GPU passthrough because you need to grant the container permission to access these specific device numbers.

What the Hell Are Major:Minor Device Numbers?

In Linux, every hardware device is represented by a file in /dev/. But don’t get too excited, are not files you can open and modify. They are more like hotline numbers that the kernel uses to dial up the right hardware driver.

Each device file has two ID numbers:

Major Number: Identifies the device driver/subsystem
Minor Number: Identifies the specific device within that subsystem

Think of it like a phone system:

Major number = Area code (which phone company/region)
Minor number = Local number (which specific phone)

Load Intel Graphics Driver

Ensure the i915 kernel module is loaded:

lsmod | grep i915

Load if missing:

modprobe i915

Make persistent across reboots:

echo "i915" >> /etc/modules

Verify QuickSync Capability

Install tools if not present:

apt install intel-gpu-tools vainfo intel-media-va-driver-non-free

Check available encoders

vainfo | grep -i enc

Look for entries like:

 VAProfileH264Main : VAEntrypointEncSliceLP
 VAProfileH264High : VAEntrypointEncSliceLP
 VAProfileJPEGBaseline : VAEntrypointEncPicture
 VAProfileH264ConstrainedBaseline: VAEntrypointEncSliceLP
 VAProfileHEVCMain : VAEntrypointEncSliceLP
 VAProfileHEVCMain10 : VAEntrypointEncSliceLP
 VAProfileVP9Profile0 : VAEntrypointEncSliceLP
 VAProfileVP9Profile1 : VAEntrypointEncSliceLP
 VAProfileVP9Profile2 : VAEntrypointEncSliceLP
 VAProfileVP9Profile3 : VAEntrypointEncSliceLP
 VAProfileHEVCMain444 : VAEntrypointEncSliceLP
 VAProfileHEVCMain444_10 : VAEntrypointEncSliceLP
 VAProfileHEVCSccMain : VAEntrypointEncSliceLP
 VAProfileHEVCSccMain10 : VAEntrypointEncSliceLP
 VAProfileHEVCSccMain444 : VAEntrypointEncSliceLP
 VAProfileHEVCSccMain444_10 : VAEntrypointEncSliceLP

If you don’t see these, your CPU might not support QuickSync or it’s disabled in BIOS.

ASRock Intel Arc A580 Challenger 8GB OC
The Arc A580 can hold its own in games, but here it’s for obliterating video streams. With support for H.264, HEVC, and full AV1 hardware encode/decode across two media engines, it crushes 20+ 1080p streams or 6–8 HDR tone-mapped 4Ks without breaking a sweat. Drop it in your media server, give Jellyfin direct VA-API access, and watch your CPU finally cool off for a bit.

Amazon Price: Loading...

Availability: Checking...

Contains affiliate links. I may earn a commission at no cost to you.

Step 2: Create the LXC Container

In Proxmox web interface:

Create CT → Use Ubuntu 24.04 LTS template (Jellyfin prefers Ubuntu over Debian)
Keep “Unprivileged” checked (this is crucial)
Resources:
- CPU: 2-4 cores
- RAM: 2GB minimum, 4GB recommended
- Disk: 80GB+ for Jellyfin metadata and cache
Network: Bridge to your main network
Don’t start the container yet

Step 3: Configure Device Access

This is where the magic happens. Edit /etc/pve/lxc/<CTID>.conf and add:

Allow access to DRI devices:

lxc.cgroup2.devices.allow: c 226:0 rwm
lxc.cgroup2.devices.allow: c 226:128 rwm

Mount DRI devices into container:

lxc.mount.entry: /dev/dri/ dev/dri/ none bind,optional,create=dir

What These Lines Do

lxc.cgroup2.devices.allow - Grants permission to access specific device nodes
lxc.mount.entry - Bind mounts the entire /dev/dri directory into the container

Step 4: Handle Group ID Mapping (Critical!)

This step trips up 90% of people attempting GPU passthrough. Here’s why. Unprivileged LXC containers use user namespaces to isolate processes, which means group IDs inside the container don’t directly correspond to group IDs on the host. Without proper mapping, your container processes can’t access the GPU devices even if the device files are present.

Understanding User Namespaces and ID Mapping

When Proxmox creates an unprivileged container, it maps container user/group IDs to a range of IDs on the host system. By default:

Container UID/GID 0 (root) → Host UID/GID 100000
Container UID/GID 1 → Host UID/GID 100001
Container UID/GID 1000 → Host UID/GID 101000
And so on…

This means when a process inside the container tries to access /dev/dri/renderD128 (owned by group ID 104 on the host), the kernel sees it as an access attempt from group ID 100104, which doesn’t exist and has no permissions.

The ID Mapping Strategy

We need to create “holes” in the default mapping to let specific container group IDs map directly to host group IDs. Think of it like creating bridges between the container and host for specific groups while keeping everything else isolated. This is similar to how firewall rules work.

Find the Host Render Group ID

On the Proxmox host:

ls -n /dev/dri/renderD128

Output example:

crw-rw---- 1 0 104 226, 128 Nov 15 10:30 /dev/dri/renderD128

Breaking this down:

crw-rw---- = Character device with read/write for owner/group
0 = Owner UID (root)
104 = Group ID that owns the device (usually render group)
226, 128 = Major:minor device numbers

The 104 is what we need to remember. This is the host group ID we need to map later.

Standardize GPU Device Ownership

Instead of dealing with potentially different group IDs for different GPU devices, let’s ensure both GPU devices use the same group:

Change the group for card0

chgrp render /dev/dri/card0

Make it persistent:

echo 'SUBSYSTEM=="drm", KERNEL=="card0", GROUP="render", MODE="0660"' > /etc/udev/rules.d/99-render.rules
udevadm control --reload-rules && udevadm trigger

Now both card0 and renderD128 should be owned by the same group ID (usually 104 for render).

Create User in Container

Start the container and enter the console to create the Jellyfin user:

adduser jellyfin --system --group --home /var/lib/jellyfin

Create the group render

groupadd -g 993 render

Add the render group to the Jellyfin user:

usermod -aG render,media jellyfin

Why GID 993?

We’re going to map container GID 993 to host GID 104 (the render group).
The choice of 993 is arbitrary. It only needs to be:

Available in the container (not already used)
Consistent with our mapping configuration

Show the group IDs of the user jellyfin:

id jellyfin

Make sure the 993 render group is listed.

Configure ID Mapping

⚠️

Warning: This assumes you’re using the group media with an ID of 1001 to access your media.
If yours is different, replace any references to media and 1001 with your own.

Stop the container and edit /etc/pve/lxc/<CTID>.conf:
Map container UIDs/GIDs to host:

lxc.idmap: u 0 100000 65536
lxc.idmap: g 0 100000 993
lxc.idmap: g 993 104 1
lxc.idmap: g 994 100994 7
lxc.idmap: g 1001 1001 1
lxc.idmap: g 1002 101002 64534

Detailed Breaking Down Each Mapping Line:

lxc.idmap: u 0 100000 65536

Maps all container UIDs (user IDs) normally
Container UID 0 → Host UID 100000
Maps 65536 UIDs total (standard range)
This line handles all user accounts

lxc.idmap: g 0 100000 993

Maps container GIDs 0-992 to host GIDs 100000-100992
This is the “normal” mapping for system groups
Stops at 992 to leave room for our special mapping

lxc.idmap: g 993 104 1

This is the critical line.
Maps container GID 993 → host GID 104 (render group)
Only maps 1 GID (this specific group)
This creates our bridge to GPU device access

lxc.idmap: g 994 100994 7

Resumes normal mapping for GIDs 994-1000
Maps to host GIDs 100994-101000
Fills the gap between our special mapping and media group

lxc.idmap: g 1001 1001 1

Maps container GID 1001 → host GID 1001 (media group)
Assumes your media files are owned by GID 1001
Adjust this to match your actual media group ID

lxc.idmap: g 1002 101002 64534

Resumes normal mapping for all remaining GIDs
Maps container GIDs 1002-65535 → host GIDs 101002-165535
Handles any additional groups that might be created

Update Host Subordinate GIDs

On the Proxmox host add the render and media groups to the subgid file:

echo "root:104:1" >> /etc/subgid

and

echo "root:1001:1" >> /etc/subgid

This tells the system that the root user (which manages LXC containers) can map:

Host GID 104 (render group) into containers
Host GID 1001 (media group) into containers

Step 5: Install Software Stack

Start the container and install the required packages:

Update package lists:

apt update && apt upgrade -y

Install Intel GPU drivers and tools

apt install intel-gpu-tools intel-media-va-driver libdrm-intel1 vainfo curl gnupg software-properties-common -y

Add Jellyfin repository:

Pull the gpg key:

curl -fsSL https://repo.jellyfin.org/jellyfin_team.gpg.key | gpg --dearmor -o /usr/share/keyrings/jellyfin-archive-keyring.gpg

Add the Repository:

echo "deb [signed-by=/usr/share/keyrings/jellyfin-archive-keyring.gpg] https://repo.jellyfin.org/ubuntu $(lsb_release -cs) main" > /etc/apt/sources.list.d/jellyfin.list

Install Jellyfin:

apt update && apt install jellyfin -y

Why Not Snap/Flatpak/Docker?

Snap: Broken device access due to confinement
Flatpak: Similar sandboxing issues
Docker: Adds unnecessary complexity to device mapping

APT packages have proper system integration and device access.

Step 6: Verify Device Access

Check Device Permissions

Inside the container:

ls -la /dev/dri/

You should see:

crw-rw---- 1 nobody render 226, 0 card0
crw-rw---- 1 nobody render 226, 128 renderD128

If the group isn’t render, you need to check your:

lxc.mount.entry and/or lxc.idmap entries in the LXC conf file.

Test Hardware Acceleration

Read Test:

sudo -u jellyfin test -r /dev/dri/renderD128 && echo "Readable"

Write Test:

sudo -u jellyfin test -w /dev/dri/renderD128 && echo "Writable"

Step 7: Configure Jellyfin

Access Web Interface

Navigate to http://<container-ip>:8096 and complete the initial setup wizard.

Enable Hardware Acceleration

Dashboard → Playback → Transcoding
Hardware acceleration: Intel QuickSync (QSV)
Enable hardware decoding for: H264, HEVC, VP9 (as supported)
Enable hardware encoding: Yes
Enable VPP Tone mapping: Yes (for HDR content)
Save

Advanced Settings

For better performance:

Allow encoding in HEVC format: Yes (if supported)
Transcoding thread count: Auto

Need a Mini Server?

The DeskMini B760 is a compact and powerful barebone system perfect for homelab use. It supports 14th Gen Intel CPUs, dual DDR4 RAM up to 64GB, and fast storage via M.2 slots plus dual 2.5" drive bays. It’s ideal for running lightweight VMs and/or containers.

Amazon Price: Loading...

Availability: Checking...

Contains affiliate links. I may earn a commission at no cost to you.

Step 8: Test Hardware Transcoding

Force Transcoding Test

Upload a high-bitrate H.264/HEVC video to Jellyfin
Start playback and immediately change quality to force transcoding
On the Proxmox host (not in container) run:

intel_gpu_top

You should see spikes in the Video engine usage during transcoding.

Browser Verification

In Chrome/Edge:

Navigate to chrome://media-internals/
Start playing your test video
Look for:
- video_codec: h264 or hevc
- hardwareAccelerated: true

Jellyfin Dashboard

Check Dashboard → Activity for active transcodes. Hardware transcoding shows much lower CPU usage than software.

Troubleshooting Guide

Problem	Symptoms	Solution
No /dev/dri in container	Missing device files	Check `lxc.mount.entry` in config
Permission denied on GPU	“Cannot access /dev/dri/renderD128”	Fix GID mapping or group membership
vainfo fails	“libva error” or crashes	Normal in LXC - test via Jellyfin instead
CPU still transcoding	High CPU usage during playback	Enable QSV in Jellyfin playback settings
Transcoding fails entirely	Playback errors or fallback to direct play	Check Jellyfin logs for codec support issues
GPU owned by wrong group	Device shows render/video instead of jellyfin	Map to correct host group ID

Advanced Debugging

Check Jellyfin logs:

tail -f /var/log/jellyfin/jellyfin.log

Verify codec support:

ffmpeg -hide_banner -encoders | grep qsv

Performance Expectations

Transcoding Capacity

Intel QuickSync can typically handle:

8th-10th gen: 4-6 simultaneous 1080p H.264 transcodes
11th gen+: 6-8 simultaneous 1080p transcodes, 2-3 4K HEVC
12th gen+: 8-10 simultaneous 1080p, 3-4 4K transcodes

Quality Considerations

Hardware encoding produces slightly larger files than software (x264)
Quality is excellent for streaming but may not match software for archival
HEVC hardware encoding (if available) provides better efficiency than H.264

Additional Optimizations

Performance Tweaks

Memory Tuning

For 4K transcoding, increase container RAM:

memory: 4096

CPU Priority

Give transcoding higher priority:

cores: 4
cpulimit: 0
cpuunits: 1024

What About NFS?

Since we’re on the topic of “impossible” things in unprivileged LXC:

NFS works perfectly fine. Mount it on the host, then bind mount into the container:

Host:

mount -t nfs nas.local:/volume1/media /mnt/nas-media

Container config: In /etc/pve/lxc/CTID.conf add:

mp0: /mnt/nas-media,mp=/mnt/media

Security Benefits

This setup provides several security advantages over alternatives:

Process isolation: Jellyfin runs in its own namespace
Limited privilege: No root access to host system
Resource limits: CPU/memory can be strictly controlled
Network isolation: Can be restricted to specific VLANs
Minimal attack surface: Only required devices are exposed

Conclusion

Unprivileged LXC containers aren’t the limitation. Lack of understanding is. With proper device mapping and group management, you get the security benefits of containerization with near-native hardware performance.

This setup gives you:

Secure, unprivileged execution
Direct GPU access without overhead
Professional-grade media streaming
Easy maintenance and updates

Stop settling for bloated VMs or dangerous privileged containers. Master the mappings and run Jellyfin the right way.

Next Steps

Want to level up further? Consider:

Remote storage: Set up NFS/SMB mounts for media libraries
Reverse proxy: Add Nginx/Traefik for HTTPS and custom domains
Backup strategy: Implement container snapshots and config backups

MINISFORUM MS-A2
A Ryzen-powered beast in a mini PC shell. Dual 2.5 GbE, 10 GbE option, triple NVMe. Small box, big Proxmox energy.

Amazon Price: Loading...

Availability: Checking...

Contains affiliate links. I may earn a commission at no cost to you.

Why I Ditched My VM NAS and Went Bare-Metal (And You Should Too)

Thu, 24 Jul 2025 06:44:27 -0600

My Jellyfin server used to forget movies. Random ones wouldn’t show up, or new ones would vanish into the ether. Reboot Proxmox, and poof, they’re back. The culprit? A race condition nightmare from running my NAS in a Proxmox-hosted VM.

I tried everything. Automount. Systemd ordering. UID hacks. Ritual sacrifices to the filesystem gods. The best I ever got was “mostly works.” That’s not good enough when Jellyfin is your nightly unwind ritual.

So I ditched the VM, went bare-metal with XFS and MergerFS, and finally built a NAS that boots clean and mounts right. Every. Single. Time.

💭

TL;DR: Running your NAS inside a VM? Fine until you’re fighting race conditions you didn’t sign up for. Go bare-metal with XFS and MergerFS for simple, fast, rock-solid storage. You’re trading Proxmox’s creature comforts for predictable behavior that holds up.

Fractal Design Define 7 XL

The Define 7 XL can accommodate up to 18 HDDs/SSDs plus five additional SSDs in the Storage Layout, with flexible configurations using included multi-brackets and HDD/SSD trays.

Amazon Price: Loading...

Availability: Checking...

Contains affiliate links. I may earn a commission at no cost to you.

A case like the Define 7 XL is what makes a bare-metal NAS practical. You need somewhere to physically put all those drives, and a chassis with proper drive trays beats stacking SSDs on a tower mid-plate any day. Now, why the VM approach falls apart in the first place.

Why VM NAS Setups Sound Sexy (But Aren’t)

It looks efficient on paper. One box. Multiple VMs. Snapshots. Live migrations. The homelab porn writes itself. Reality hits a bit different:

Race conditions from hell: Proxmox boots, VMs start spinning up, but your containers beat NFS to the punch. Result? Jellyfin loads with a library that looks like Swiss cheese.
Mounting nightmares: Getting the Proxmox host to mount NFS shares after the NAS VM boots is like herding cats. I tried automounts and failed spectacularly. Switched to systemd mounts. Same story. Finally built UID-mapped folders to sidestep Proxmox’s 100000 offset nonsense. Worked 97% of the time. “Mostly working” storage is like being “mostly pregnant.”
Death by a thousand cuts: Every virtualization layer (Proxmox to QEMU to ext4/XFS to NFS to LXC) adds latency. You bleed throughput. You sacrifice reliability.
The debugging tax: When things break, and they will, you’re troubleshooting across multiple abstraction layers. Is it the VM? The host? The container? The mount? Good luck figuring that out Sunday afternoon when your family is rioting because they can’t watch their favorite movie or the latest episode of their current indulgence.

“There is not much difference in performance if any at all.” - Some Reddit user who clearly never spent a weekend troubleshooting missing folders.

Try saying that after your fourth reboot hoping your media will magically reappear.

Why Bare-Metal XFS + MergerFS Wins

No more race conditions: NFS shares mount early via proper systemd ordering. Containers see their media, first boot, every boot, forever.
Direct I/O that doesn’t suck: XFS is battle-tested and fast. MergerFS pools drives together without the virtualization overhead tax. Your drives work at their actual speed.
Predictable boots: No more crossing your fingers hoping your storage VM came up in time. No more UID hacks. Clean systemd dependencies that do what they say on the tin.

Bonus wins:

Full 10GbE bandwidth (not strangled by virtio drivers)
Simpler storage stack, fewer things to break
Cleaner disaster recovery: rsync, backups, and mounts you understand
Sleep peacefully knowing your storage isn’t playing startup roulette

Bare-Metal vs. VM: The Real Scorecard

Setup	Pros	Cons
VM NAS	✔️ Snapshots ✔️ Easy Proxmox backups ✔️ Service consolidation ✔️ Looks good in /r/homelab	❌ NFS race conditions ❌ I/O performance tax ❌ Complex UID/GID mapping ❌ Multi-layer debugging hell
Bare-Metal NAS	✔️ Predictable boots ✔️ Zero virtualization overhead ✔️ Simple, direct mounts ✔️ Full hardware performance	⚠️ Manual backup strategy ⚠️ Extra box to power & manage ⚠️ No VM convenience features

Power tradeoff? Absolutely. That’s why I went with a G3220. It sips power like a gentleman but handles the workload without breaking a sweat. The 10Gb NIC and HBA get to stretch their legs properly.

Build Blueprint: The Setup I Run

Hardware (Stuff I had lying around):

Intel G3220
Gigabyte GA-Z87X-D3H
16GB DDR3
LSI 9300-8i HBA in IT mode
10Gb NIC

Software Stack:

Debian Trixie
XFS on each drive
MergerFS for pooling
NFS for rock-solid container access
systemd for proper mount ordering

Why this combo works: Dead simple architecture. Nothing fancy. It boots and works, every time.

For Details on MergerFS and HBAs:

The HBA is the part most people skimp on. If you’re running more than a handful of drives, an LSI card flashed to IT mode is the right answer. Onboard SATA falls apart once you push past six drives.

LSI 9300-8i

Already Flashed to IT mode.

Amazon Price: Loading...

Availability: Checking...

Contains affiliate links. I may earn a commission at no cost to you.

The Cold, Hard Truth About My Experience

I burned two entire weekends trying to make VM-NAS race conditions disappear. They laughed at my attempts.

I deployed automounts like a hopeful fool. I crafted systemd units with the precision of a Swiss watchmaker. I even UID-hacked workarounds that would make a kernel developer weep. And still, some folders only materialized after rebooting the entire Proxmox host.

Bare-metal isn’t perfect. You lose snapshots. You lose centralized VM backups. You lose the satisfaction of running everything on one box.

You gain something precious in return: predictability. When you power on your NAS, it works. When containers start, they see their media. When users browse your library, the files are there.

One box, one job, one stack to debug. That clarity is worth the extra 20 watts, especially when your CPU barely registers on the power meter and your Jellyfin setup never misses a beat.

The Bottom Line

A VM NAS can work if you enjoy weekend troubleshooting sessions and the thrill of uncertainty. A bare-metal NAS does work, every single time, without drama or surprise downtime.

Tired of startup order roulette, phantom mount points, and explaining to family why half the movie collection disappeared again? Go physical. Go simple. Go fast.

Your sanity will thank you. Your users will thank you. Your Saturday mornings will thank you.

Ready to Build It Right?

Ditch the VM complexity. Build your NAS properly with bare-metal XFS and MergerFS. Stop trusting virtualization layers to mount your media collection in the correct order.

I’ve got fstab configs, systemd unit files, and plenty of battle scars if you need guidance.

Ask away.

Seagate Barracuda 24TB Internal Hard Drive

Amazon Price: Loading...

Availability: Checking...

Contains affiliate links. I may earn a commission at no cost to you.

Why Unprivileged LXC + NFS = Regret (Here’s How I Learned the Hard Way)

Tue, 22 Jul 2025 06:04:43 -0600

I spun up some unprivileged LXCs on Proxmox (Jellyfin, Sonarr, Radarr, and Audiobookshelf). The plan was to keep it lightweight, clean, and have them all talk to my NAS over NFS.

That plan lasted about a week.

What followed was a parade of silent failures, missing files, and permission bugs that made me question reality. Unprivileged sounded safe. Turns out LXCs are too stripped down to work reliably if you need NFS access.

Let me show you why unprivileged LXC is a trap for anything that needs NFS access, and how I crawled back to VMs running Docker. Humbled but functional.

💭

TL;DR: Unprivileged LXC + NFS seems awesome and secure until root mapping, id shifts, and bind mount hell break your stack. Use privileged LXC or, better yet for NFS, a VM. I learned this the hard way with Proxmox.

The Two Faces of LXC: Privileged vs Unprivileged

LXC containers come in two flavors: privileged and unprivileged. That one word changes everything about how your containers behave, what they can access, and how much pain you’ll experience.

Privileged Containers: Power at a Price

A privileged container runs as root on the host. Not “container root.” Actual host root.

What that means:

Container UID 0 = host UID 0
Full access to system calls
Direct read/write access to host files
Minimal UID translation (things work with NFS, USB devices, bind mounts, etc.)

Sounds scary? It should be. If a service inside that container gets compromised, the attacker now has root on your host. Full stop.

When privileged LXC makes sense:

Internal-only services you fully trust
Containers behind a firewall, with zero external exposure
Services that need real root access

Unprivileged Containers: Safe but Issues with NFS

Unprivileged containers were designed to fix that security risk by adding a layer of UID mapping.

They add 100000 to all container UIDs:

Container UID 0 → host UID 100000
Container UID 1000 → host UID 101000
And so on…

So even if something breaks inside, the container can’t mess with your host. It’s sandboxed. Safe.

But here’s the catch: that UID mapping breaks everything outside the container.

NFS doesn’t recognize 100000 as root.
File permissions stop making sense.
Accessing anything shared with the host becomes a pain.

Unprivileged containers work great when:

You don’t need to write to NFS
You don’t care about permissions on shared files
You want to sandbox a sketchy app or test environment

So Which One Should You Use?

Use Case	Best Container Type
Running Jellyfin/Arr stack with NFS	Virtual Machine or Privileged
Public-facing container	Virtual Machine or Unprivileged
Docker inside LXC	Privileged (not recommended)
Internal utility that touches host fs	Privileged
Unsafe app or 3rd-party binary	Unprivileged

Bottom line: Privileged = easier, more powerful, more dangerous Unprivileged = safer, but crippled when it comes to real-world file access

And if you’re mixing in NFS? Unprivileged goes from “safe” to “useless.”

MINISFORUM MS-A2 A Ryzen-powered beast in a mini PC shell. Dual 2.5 GbE, 10 GbE option, triple NVMe. Small box, big Proxmox energy.

Amazon Price: Loading...

Availability: Checking...

Contains affiliate links. I may earn a commission at no cost to you.

My Descent Into Troubleshooting Hell

Let me walk you through the steps I took. Each one with hope, each one crushed by reality. If this looks like your future, do yourself a favor and skip ahead to VMs now.

Attempt #1: Custom UID Mapping

I tried overriding lxc.idmap to fake container UID 0 as host UID 1000:

lxc.idmap: u 0 100000 1000
lxc.idmap: g 0 100000 1000
lxc.idmap: u 1000 101000 1
lxc.idmap: g 1000 101000 1
lxc.idmap: g 1001 101001 1
lxc.idmap: u 1001 101001 64534
lxc.idmap: g 1002 101002 64534

Result: Partially worked, but created more permission edge cases.

Attempt #2: NFS Export Tweaking

I tried various NFS settings and settled on this:

/media/Storage/ *(all_squash,anongid=1001,anonuid=1000,insecure,rw,fsid=100,subtree_check)

Result: Files appeared but the permissions were still an issue.

Attempt #3: Host Mount + Bind Mount

I mounted NFS on the host, then bind-mounted into the LXC:

mp0: /mnt/storage/Shows,mp=/media/Shows
mp1: /mnt/storage/Movies,mp=/media/Movies
mp2: /mnt/storage/Music,mp=/media/Music
mp3: /mnt/storage/eBooks,mp=/media/eBooks
mp4: /mnt/storage/AudioBooks,mp=/media/AudioBooks

Result: Files showed up but were owned by nobody:nogroup. Jellyfin couldn’t scan, play, or write. When the host mount failed during reboots, containers booted with empty folders. Silent disasters everywhere.

Attempt #4: The bindfs Hail Mary

In my final attempt, I tried bindfs to remap ownership:

[Unit]
Description=Bindfs mounts for NAS directories
Requires=mnt-nas_storage.mount

[Service]
Type=oneshot
ExecStart=/usr/bin/bindfs -u 101000 -g 101001 /mnt/nas_storage /mnt/mapped_nas_storage
RemainAfterExit=true

[Install]
WantedBy=multi-user.target

Result: This worked the best, but I’d still randomly lose files. Every workaround fixed one thing and broke three more.

I’m sure someone has forced unprivileged LXCs to work. I want to enjoy my media, not fight with permissions every weekend.

The Privileged Container Security Trap

So what’s the catch with using a privileged container to fix NFS? You’ve now handed root access from the container directly to the host.

Root inside = root outside

If someone compromises Jellyfin (or any dependency), they’re root on your Proxmox node. Game over.

Security Misconfigurations

Most people don’t harden their containers. Leave one small crack that someone could exploit, and the container can damage your host or pivot to other network devices.

Network Exposure Risks

Privileged containers can mess with host-level network settings. Bridge them carelessly, and an attacker could sniff or spoof traffic across your entire LAN.

Shared kernel = Shared fate

Containers don’t isolate the kernel. A bug in ffmpeg, libva, or any media processing library could expose your entire host system.

It’s not a sandbox. It’s a potential backdoor.

TP-Link Omada SG3210X-M2 Full-featured, compact, rack-ready. Eight multi-gig ports, dual 10 GbE uplinks, VLAN/QoS/ACL/LACP, and seamless integration with TP‑Link’s Omada controller. It locks down your Jellyfin/NAS traffic while scaling effortlessly with your homelab.

Amazon Price: Loading...

Availability: Checking...

Contains affiliate links. I may earn a commission at no cost to you.

The Solution: Embrace VMs with Docker

After weeks of fighting with LXC permissions, I gave up and moved everything to VMs running Docker. Here’s why this works:

True Isolation

VMs provide actual isolation. If Jellyfin gets compromised, the attacker is trapped in a virtual machine and not loose on your host.

Docker Handles Permissions

Docker’s built-in user mapping and volume mounts handle NFS permissions much more gracefully than LXC’s UID mapping.

Predictable Behavior

No more silent failures, missing files, or permission mysteries. Things work the way you expect them to.

Final Recommendations

For Jellyfin + NFS + Remote Access:

Use a VM with Docker (best option)
Use privileged LXC only if it’s internal-only and you understand the risks
Avoid unprivileged LXC entirely for this use case

For Other Use Cases:

Internal utilities: Privileged LXC is fine
Public-facing services: Unprivileged LXC or VM
Anything touching NFS: VM with Docker

The Bottom Line:

Unprivileged LXC sounds safe until it isn’t. Add NFS, media servers, and remote access, and you’re stacking pain on top of pain.

I’ve patched, mounted, and prayed my way through this mess. My final verdict? If you’re doing anything serious with NFS or Jellyfin, ditch the LXC complexity and use VMs with Docker.

Don’t fight your stack. If you need NFS, go VM. If you’re exposing Jellyfin publicly, go VM. Save your sanity and your weekends.

TP-Link 2.5GB PCIe Network Card (TX201) Plug-and-play 2.5 GbE PCIe card that unlocks multi-gig speeds for about $30. Works out of the box with Proxmox, Linux, and Windows. No drama, only faster transfers.

Amazon Price: Loading...

Availability: Checking...

Contains affiliate links. I may earn a commission at no cost to you.

Two Years of LXC Hell - Why I Crawled Back to Docker (And You Should Too)

Sun, 06 Jul 2025 07:29:44 -0600

So, you’re feeling clever. You’ve read the blogs, watched the YouTube tutorials, and decided that unprivileged LXC containers are the “right” way to run your Arr stack. Lightweight! Efficient! So much better than Docker!

Fast forward two years. You’re debugging NFS stale handle errors for the third night running, your downloads corrupt mid-transfer, and you’re questioning every life choice that led you to this moment.

That was me. Now I’m back on Docker, tail between my legs, with a rock-solid docker-compose.yml that works.

💭

TL;DR: Thought LXC was smarter than Docker? So did I. Until stale NFS handles, ghost downloads, and permission nightmares broke my will to live. This Docker Compose setup works. Copy, run, exhale.

Need a Mini Server?

The DeskMini B760 is a compact and powerful barebone system perfect for homelab use. It supports 14th Gen Intel CPUs, dual DDR4 RAM up to 64GB, and fast storage via M.2 slots plus dual 2.5" drive bays. It’s a solid host for VMs or containers without eating a full rack.

Amazon Price: Loading...

Availability: Checking...

Contains affiliate links. I may earn a commission at no cost to you.

The Hard Truth About LXC vs Docker Compose

Let me save you the pain I went through. LXC sounds perfect for media servers until you try to run something complex like the full Arr suite and NFS shares.

Here’s what Docker Compose gives you that LXC never could:

One File to Rule Them All

With LXC, adding a new service means spinning up another container, configuring networking, setting up mounts, and praying everything talks to each other. With Docker Compose: Edit a few lines, run docker compose up -d, and you’re done.

Want to restart everything?

docker compose restart

Want to migrate to a new server? Copy two files. Your .env and your docker-compose.yml. You’re back online in minutes.

No More Permission Purgatory

Ever watch a file download successfully but never move to your media folder? Or see Sonarr throw “access denied” errors with zero explanation? That’s LXC’s unprivileged user permissions playing games with your sanity.

This is the one I could never resolve: the file is downloaded and moved to the NFS share but the LXC host never sees it in the mount point until the system is rebooted.

This Docker setup uses PUID and PGID across every container, so they all behave like the same user on your host. No more mystery permission errors. No more chmod 777 voodoo dances.

Shared Downloads That Work

One /downloads directory for everything. SABnzbd drops files there. Sonarr, Radarr, and their friends watch that same folder and move files cleanly. No bind mount spaghetti. No symbolic link nightmares. Clean, predictable file handling.

What Finally Broke Me

After two years of LXC “optimizations,” these were the straws that broke the camel’s back:

NFS + LXC = Stale File Handle Roulette
Try debugging why your mounts randomly go read-only mid-download or why Jellyfin can’t see a file that’s clearly in the share until you restart NFS. I spent months chasing these ghosts.

Every Container Needs Its Own IP (Maybe)
Unless you NAT everything (gross), LXC means manually assigning static IPs and keeping track of them. Docker Compose skips this entirely. All your apps talk over an internal bridge network.

Updates Are a Gamble
Something breaks in LXC? Hope you documented every tweak you made over the past six months. Docker? Blow it away and recreate it in seconds. Your config survives because it’s volume-mounted.

The Stack That Finally Worked

Here’s the battle-tested docker-compose.yml that ended my suffering:

services:

 #################################
 ## PROWLARR ##
 #################################
 prowlarr:
 image: lscr.io/linuxserver/prowlarr:latest
 container_name: prowlarr
 user: "${PUID}:${PGID}"
 env_file: .env
 restart: unless-stopped
 ports:
 - ${PROWLARR_PORT}:9696
 volumes:
 - ${CONFIG_PATH}/prowlarr:/config
 environment:
 - PUID=${PUID}
 - PGID=${PGID}
 - TZ=${TZ}
 networks:
 - media_network

 #################################
 ## SONARR ##
 #################################
 sonarr:
 image: lscr.io/linuxserver/sonarr:latest
 container_name: sonarr
 user: "${PUID}:${PGID}"
 env_file: .env
 restart: unless-stopped
 ports:
 - ${SONARR_PORT}:8989
 volumes:
 - ${CONFIG_PATH}/sonarr:/config
 - ${MEDIA_PATH}/Shows:/tv
 - ${DOWNLOADS_PATH}:/downloads
 environment:
 - PUID=${PUID}
 - PGID=${PGID}
 - UMASK=0007
 - TZ=${TZ}
 networks:
 - media_network

 #################################
 ## RADARR ##
 #################################
 radarr:
 image: lscr.io/linuxserver/radarr:latest
 container_name: radarr
 user: "${PUID}:${PGID}"
 env_file: .env
 restart: unless-stopped
 ports:
 - ${RADARR_PORT}:7878
 volumes:
 - ${CONFIG_PATH}/radarr:/config
 - ${MEDIA_PATH}/Movies:/movies
 - ${DOWNLOADS_PATH}:/downloads
 environment:
 - PUID=${PUID}
 - PGID=${PGID}
 - UMASK=0007
 - TZ=${TZ}
 networks:
 - media_network

 #################################
 ## Lidarr ##
 #################################
 lidarr:
 image: lscr.io/linuxserver/lidarr:latest
 container_name: lidarr
 user: "${PUID}:${PGID}"
 env_file: .env
 restart: unless-stopped
 ports:
 - ${LIDARR_PORT}:8686
 volumes:
 - ${CONFIG_PATH}/lidarr:/config
 - ${DOWNLOADS_PATH}:/downloads
 - ${MEDIA_PATH}/Music:/music
 environment:
 - PUID=${PUID}
 - PGID=${PGID}
 - UMASK=0007
 - TZ=${TZ}
 networks:
 - media_network

 #################################
 ## Readarr1 eBooks ##
 #################################
 readarr1:
 image: lscr.io/linuxserver/readarr:develop
 container_name: readarr1
 user: "${PUID}:${PGID}"
 env_file: .env
 restart: unless-stopped
 ports:
 - ${READARR1_PORT}:8787
 volumes:
 - ${CONFIG_PATH}/readarr1:/config
 - ${DOWNLOADS_PATH}:/downloads
 - ${MEDIA_PATH}/eBooks:/books
 environment:
 - PUID=${PUID}
 - PGID=${PGID}
 - UMASK=0007
 - TZ=${TZ}
 networks:
 - media_network

 #################################
 ## Readarr2 ##
 #################################
 readarr2:
 image: lscr.io/linuxserver/readarr:develop
 container_name: readarr2
 user: "${PUID}:${PGID}"
 env_file: .env
 restart: unless-stopped
 ports:
 - ${READARR2_PORT}:8787
 volumes:
 - ${CONFIG_PATH}/readarr2:/config
 - ${DOWNLOADS_PATH}:/downloads
 - ${MEDIA_PATH}/AudioBooks:/books
 environment:
 - PUID=${PUID}
 - PGID=${PGID}
 - UMASK=0007
 - TZ=${TZ}
 networks:
 - media_network

 #################################
 ## Bazarr ##
 #################################
 bazarr:
 image: lscr.io/linuxserver/bazarr:latest
 container_name: bazarr
 user: "${PUID}:${PGID}"
 env_file: .env
 restart: unless-stopped
 ports:
 - ${BAZARR_PORT}:6767
 volumes:
 - ${CONFIG_PATH}/bazarr:/config
 - ${MEDIA_PATH}/Movies:/movies
 environment:
 - PUID=${PUID}
 - PGID=${PGID}
 - UMASK=0007
 - TZ=${TZ}
 networks:
 - media_network

 #################################
 ## SABnzbd ##
 #################################
 sabnzbd:
 image: lscr.io/linuxserver/sabnzbd:latest
 container_name: sabnzbd
 user: "${PUID}:${PGID}"
 env_file: .env
 restart: unless-stopped
 ports:
 - ${SABNZBD_PORT}:8080
 volumes:
 - ${CONFIG_PATH}/sabnzbd:/config
 - ${DOWNLOADS_PATH}:/downloads
 environment:
 - PUID=${PUID}
 - PGID=${PGID}
 - UMASK=0007
 - TZ=${TZ}
 networks:
 - media_network

#################################
## NETWORK ##
#################################
networks:
 media_network:
 name: media_network
 external: true

What Each Piece Does

services:
Each app gets its own container. Easier to debug, update, or nuke from orbit when things go sideways.

image:
I use linuxserver.io images exclusively. They’re clean, well-documented, and there are no weird surprises hiding in latest.

user: "${PUID}:${PGID}"
This is the magic that prevents permission hell. Every container runs as your host user.

env_file: .env
Keeps sensitive info and paths out of the compose file. Makes the whole thing portable between servers.

volumes:

/config: App settings and databases that persist forever
/downloads: Shared workspace for all apps and SAB
/media: Your precious media collection

networks:
Everything sits on media_network. Internal traffic stays inside Docker. No extra IPs to manage.

restart: unless-stopped
Containers come back after reboots, crashes, or when you’re mid-binge and don’t want to babysit anything.

The Essential .env File

# User and Group ID (Prevents permission issues)
# Main user ID
PUID=1000
# Main group ID:
PGID=1001

# Timezone (Ensures correct scheduling and logs)
TZ=America/Denver

# Define Ports (Ports for each container are defined here)
RADARR_PORT=7878
SONARR_PORT=8989
SABNZBD_PORT=8080
PROWLARR_PORT=9696
LIDARR_PORT=8686
READARR1_PORT=8787
READARR2_PORT=8788
BAZARR_PORT=6767

# Data Directories (Keeps storage paths centralized)
CONFIG_PATH=/docker
DOWNLOADS_PATH=/downloads
MEDIA_PATH=/media/Storage

💡

Tip:

Run id to get your PUID and PGID
Set TZ correctly or your downloads will happen at weird hours
Use absolute paths everywhere. Don’t get cute with relative paths.

Getting Started (The Easy Way)

Drop both files in the same folder: Edit the .env to match your real paths and UID/GID.
Fire it up:
```
docker compose up -d
```
Access your apps:
- Sonarr: http://your-ip:8989
- Radarr: http://your-ip:7878
- Prowlarr: http://your-ip:9696
- (and so on…)

Real-World Scenarios Where This Shines

Running Jellyfin?

This stack becomes your automated feeder system. Jellyfin handles playback, and the Arr apps handle acquisition. New episode downloads → automatically appear in Jellyfin. No more manual file moves. No more metadata headaches.

Tired of Snap’s BS on Ubuntu?

Snap has a mind of its own. Sometimes Snap won’t update, force-updates when you don’t want it to, or your Docker CLI vanishes.

This stack uses real Docker, on your terms, with predictable behavior. (Also why I moved everything back to Debian, but that’s another rant.)

Want Boring Updates? Yes please.

docker compose pull
docker compose up -d

That’s it. Your config persists, your ports don’t change, and you’re back online in seconds with fresh code.

The One Gotcha That’ll Bite You

⚠️

Warning:

Mounts matter. If your paths don’t match between host and container, nothing works.

Double-check that:

Host /downloads maps to container /downloads
Same for /media and /config
Your PUID/PGID matches your actual user

Get this wrong and you’ll be back to debugging permission errors like it’s 2019.

The Bottom Line

You now have the complete stack. One YAML file. One .env. All your media apps work together without fighting over ports, permissions, or your sanity.

I fought for two years trying to outsmart this problem with clever LXC setups. Turns out the solution was to stop being clever and let Docker do the work.

I hope my pain and suffering saves you some time and effort.

Need A NAS?

UGREEN NASync DXP4800 Plus, 4-Bay NAS with an Intel Pentium Gold 8505 5-core CPU, 8GB DDR5, a 128GB built-in SSD, 2x M.2 NVMe slots, and both 10GbE and 2.5GbE ports (Diskless). This is perfect if you don’t want to DIY your NAS.

Amazon Price: Loading...

Availability: Checking...

Contains affiliate links. I may earn a commission at no cost to you.

Docker vs Mutiple LXCs for the Arr Suite

Sun, 22 Jun 2025 07:13:47 -0600

I used to think running each Arr app in its own LXC was a smart move. Felt clean. Minimal. Efficient. But if you’ve ever tried to juggle Sonarr, Radarr, SABnzbd, and the rest across a handful of Proxmox containers, you know the cracks show up fast. Trust me. I’ve been there, and it’s not worth the pain.

If you’re serious about your media setup, move the Arr stack into a Docker environment inside a single VM. Here’s why it matters. (Want the step-by-step build rather than the argument? Follow the complete arr stack Docker Compose guide.)

Points That I’m Willing to Concede

You can run the Arr suite in its own unprivileged LXCs. I did it. It worked. I didn’t like managing it.
I know some of you run Docker inside an LXC. That’s a special kind of headache I want nothing to do with, and it isn’t officially supported by Proxmox.

What We’re Working With

Proxmox is a virtualization platform that runs multiple operating systems on a single physical box. Perfect for a homelab or media hoarders consolidating services onto one machine.

LXC containers are lightweight virtualized environments that share the host’s kernel. Think isolated spaces that use fewer resources than full virtual machines.

Virtual machines (VMs) are complete, isolated operating systems that share nothing with the host.

The Arr suite is Sonarr (TV automation), Radarr (movie automation), Lidarr (music automation), and SABnzbd (download client). They work together to find, download, and organize your media library automatically.

LXC Containers Look Great on Paper, But They Trip You Up Fast

LXCs are lightweight. They share the Proxmox host’s kernel and don’t suck up much in the way of resources. Sounds ideal, right? Until you realize how tightly integrated the Arr apps actually are.

Too Many Moving Parts: Seven LXCs means seven operating systems, seven update schedules, seven IP addresses, and seven things that can break. Docker bundles everything together. Less patching. Fewer surprises.

Networking Gets Messy: Sonarr and Radarr need to talk to Prowlarr and your downloader constantly. Getting that cross-talk working between LXCs means manually configuring IP addresses, firewall rules, and routing between containers. Here’s where Docker shines. It creates an internal network where services find each other by name automatically. Instead of remembering that Sonarr lives at 192.168.1.100:8989, you point it at sonarr:8989 and Docker handles the rest.

Storage and Permissions Are a Nightmare: When multiple LXCs try to access the same media folders, you’ll run into UID and GID issues. One container creates files another can’t read or modify. With Docker, you map your storage once to the VM, and all containers share the same user context. Permission headaches gone.

Unprivileged Containers Make Network Storage a Pain: If you’re running unprivileged LXCs (which you should, for security), accessing NFS or SMB shares becomes a special kind of hell. Unprivileged containers map user IDs differently than the host, so your media files might show up as owned by nobody or become completely inaccessible. You’ll burn hours tweaking UID maps, CIFS mount options, and NFS export settings to get basic file access working. Meanwhile, a VM with Docker mounts your network shares normally and passes them through to containers without the mapping headaches.

Config Drift Is Real: One LXC gets updated while another doesn’t. Suddenly an app fails and you’re hunting down why a version mismatch is breaking API calls between services. Docker Compose gives you a single source of truth: a YAML file that pins your entire stack to specific versions.

Docker in a VM: The Sweet Spot for Media Automation

Here’s where things get easier.

One VM to Rule Them All: Instead of babysitting a small army of containers, you manage one Debian or Ubuntu VM. Update once. Patch once. Reboot once.

Docker Compose = Sanity: Everything lives in a single docker-compose.yml file. It handles every Arr app you need (Sonarr, Radarr, Lidarr, SABnzbd, etc.), their connections, volumes, ports, environment variables, user IDs, and timezones, all centralized and clean. Spin up the stack with docker compose up -d. Shut it down with docker compose down. Pull updates with docker compose pull without touching the rest of the system.

True Isolation: VMs are fully fenced off from your Proxmox host. If something breaks, it won’t leak into your main system. Need to move the stack? Back up the VM and drop it in the new location.

Less Headache When Things Break: One place to look for problems. Run docker logs <container> and get answers fast. No jumping between LXCs hunting through logs scattered across the host.

Better Community Support: Most media server guides today assume you’re running Docker. That means more tutorials, more troubleshooting help, and fewer dead ends.

Sensible Use of Resources: A single VM with Docker uses slightly more memory than a pile of LXCs up front. Long term, it’s more stable, more predictable, and easier to maintain. The small resource overhead is worth the massive reduction in complexity.

Stop Fighting. Start Watching.

LXCs are great for simple, fire-and-forget services that don’t need to talk to each other. The Arr suite is the opposite. These apps need to work together without friction, and they need consistency across your entire stack.

Docker inside a VM gives you that consistency. You get the benefits of isolation and virtualization with the simplicity of containerized apps that find each other on a shared network without fuss.

So skip the mess. Build your media automation stack inside a VM. Use Docker Compose. Spend less time debugging networking and permissions, and more time enjoying your perfectly organized media library.

Set it up once. Watch it work. Enjoy your media.

ASRock Mini-Desktop Computer

The DeskMini B760 is a compact but capable barebone system perfect for homelab use. It supports up to 14th Gen Intel CPUs (65W), dual DDR4 RAM up to 64GB, and fast storage via both Gen5 and Gen4 M.2 slots plus dual 2.5" drive bays. Ideal for running lightweight VMs and containers in a tiny footprint.

Amazon Price: Loading...

Availability: Checking...

Contains affiliate links. I may earn a commission at no cost to you.

Choosing the Right Linux Distro Debian vs Ubuntu

Sun, 15 Jun 2025 12:47:22 -0600

So you want to build a server that stores and shares files across your home network. A digital filing cabinet that every laptop, phone, and tablet in the house can hit. That’s a NAS, Network Attached Storage.

When you go to build one, you’ll end up staring at two Linux distros: Debian or Ubuntu. There are others. For most home labs, the decision comes down to these two. Both are Linux. Both are free. They behave very differently under load, and that’s where the choice matters. Here’s why Debian is the better pick for a file server.

What Makes Debian and Ubuntu Different?

Both are Debian-based, so the tooling looks identical from the command line. The difference is how each one decides what goes into the release.

Debian is a carefully organized library. Every package is tested, then tested again, then frozen. Nothing ships until the maintainers are sure it plays nice with everything else on the shelf.

Ubuntu is a modern bookstore. New releases land on the shelves fast. Sometimes the binding holds. Sometimes a new title doesn’t get along with the others you already own.

For a file server, you want the library.

Why Debian Wins for File Servers

Rock-Solid Stability

You’re storing family photos, tax documents, and the music collection. You want a system that doesn’t surprise you on a Tuesday morning.

No surprise changes. Once Debian 13 ships, the behavior of the installed packages stays put. Same Samba config, same NFS exports, same MergerFS pool, for years.
Fewer regressions. Debian’s freeze cycle catches a lot of the upstream bugs before they hit your disk.
Predictable upgrades. You won’t wake up to find that an unattended-upgrade quietly changed how smb.conf parses a directive.

Ubuntu updates more aggressively. Sounds great until your file server reboots into a kernel that doesn’t love your HBA.

Lean by Default

Install Debian without a desktop and you get exactly what you asked for. Nothing else. Pick “SSH server” and “standard system utilities” in tasksel and you’re done.

What that gets you:

Faster boot. Fewer services means systemd-analyze blame is a short list.
Lower RAM idle. More memory left over for the ZFS ARC, the page cache, or whatever else is actually doing work.
Smaller attack surface. Every package you don’t install is one you don’t have to patch.

Ubuntu Server pulls in snapd, cloud-init, and a stack of other things you didn’t ask for. Useful in a cloud VM. Noise on a home NAS.

Software That Behaves

A file server needs three things:

Samba for Windows clients over SMB
NFS (nfs-kernel-server) for Linux and Mac clients
MergerFS for pooling drives without a hardware RAID

Debian gives you well-aged versions of all three. A five-year-old car with the recalls already done, versus a brand-new model on the first production run. When the data on the drives matters, the boring version is the right version.

Ubuntu ships newer point releases. New is not always better when “better” means “doesn’t lose your data.”

Easy Major-Version Upgrades

Every few years you’ll bump the OS. With Debian, the path is well-trodden. Edit /etc/apt/sources.list, swap bookworm for trixie, then run apt update && apt full-upgrade. Read the release notes first. They’re short and honest about the gotchas.

Ubuntu’s do-release-upgrade works most of the time. The rest of the time it picks a fight with a PPA you forgot about, or a snap that refuses to migrate, and you’re in recovery mode with no working machine. Ask me how I know.

No Canonical in the Driver’s Seat

Debian is run by volunteers who care about the project. Ubuntu is owned by Canonical, and Canonical has shareholders. That changes which decisions get made.

What you get with Debian:

No snap. Debian uses apt and standard .deb packages. No mandatory store backend.
No telemetry surprises. Decisions happen on a public mailing list.
No “Pro” upsell at the MOTD. Your terminal stays quiet.

Long-Term Support

Both projects offer multi-year support windows:

Ubuntu 24.04 LTS: 5 years of standard updates. Extended to 10 years if you sign up for Ubuntu Pro.
Debian 13: Roughly 5 years through the LTS team. Free. No account required.

If you want a decade on Ubuntu, you’re paying Canonical or registering machines against their free tier limit. On Debian, you wait for the next stable and run apt full-upgrade.

What About Debian 13’s Release Date?

Debian 13 (“Trixie”) isn’t shipped yet. The current target is mid-2025. If you’re building a NAS today, install Debian 12 (“Bookworm”) and ride the upgrade train when Trixie drops. The in-place upgrade is one of Debian’s best-tested code paths.

Debian Feels Like Home

I’ve spent the last two weeks migrating all my VMs and LXC containers back to Debian. Nothing was broken. Debian feels like home. Clean, predictable, mine. No corporate layer between me and the system. The system I want, and nothing more.

The Bottom Line

A home file server is the foundation under your family’s data. You want reliable. You want long-lasting. You want the kind of system you can ignore for three years and have it still running when you ssh back in.

Ubuntu 24.04 is fine. It comes with extra moving parts and a few Canonical decisions that get in the way of a quiet NAS. When the goal is file sharing that doesn’t fight you, Debian wins.

For a home NAS, pick Debian.

Need a new HDD to keep up with your downloads?

Seagate Barracuda 24TB Internal Hard Drive

Amazon Price: Loading...

Availability: Checking...

Contains affiliate links. I may earn a commission at no cost to you.

Prowlarr Docker Compose Setup Guide (2026)

Sun, 25 May 2025 06:24:52 -0600

💭

TL;DR: Run Prowlarr in Docker with one Compose service, point it at your existing media stack, and let it sync indexers and downloaders to Sonarr, Radarr, Lidarr, and Readarr through the API. Configure once, never again.

💡

Tip: Default port: Prowlarr runs on port 9696. Access the web UI at http://your-server-ip:9696 once the container is running.

I run this exact Compose stack on a Debian 12 box with the LinuxServer.io images, alongside Sonarr, Radarr, and SABnzbd on the same media_network bridge. The config below is running on my box right now, copied straight out of the live compose file.

What is Prowlarr?

Prowlarr is the index and download manager for your media server. It’s the glue between your torrent and Usenet sources and the Arr apps (Sonarr, Radarr, Lidarr, Readarr). Set up your indexers and downloaders once in Prowlarr, and it pushes them out to every Arr app over the API.

Here’s what it does day to day:

Connects to public and private torrent trackers, plus Usenet indexers.
Wires your local downloaders (qBittorrent, SABnzbd, NZBGet) into the Arr apps.
Centralizes every connection and monitors them for availability.
Syncs indexers to your other Arr apps automatically.
Categorizes indexers by media type (TV, movies, music) and sends them to the right app.
Gives you one dashboard for every source your automation relies on. And when an indexer dies, Prowlarr tells you before Sonarr does.

Why You Should Use Prowlarr

Running a media server without Prowlarr means logging into Sonarr, then Radarr, then Lidarr, pasting the same API key into each one, then doing it all again when an indexer changes its URL. Fine for a weekend. Painful by month three.

Here’s what you get:

Saves time. Add an indexer or downloader once. No more copy-pasting API keys and login info across three or four apps.
Reduces errors. When one app works and another doesn’t, the culprit is usually a stale or misconfigured indexer. Prowlarr keeps them aligned.
Monitors health. You find out an indexer went offline today instead of a week later, when you’re missing the new episode of your show.
Supports everything. Private trackers, paid Usenet, free public indexers. Prowlarr handles all of them.

One messy manual setup becomes one clean, scalable system.

Step 1: Install Docker

You’ll need Docker installed on your server first. Walkthrough: Master the Basics - How to Install Docker

Step 2: Create or Modify Your Docker Compose File

Define the Prowlarr container in docker-compose.yml. The file below runs Prowlarr on its own. Already running the rest of the stack (say, from my Sonarr guide)? Drop the prowlarr: service into your existing services: block and reuse the same media_network instead of pasting the whole thing.

Open the Compose File

Open your existing docker-compose.yml or create a new one:

nano /docker/docker-compose.yml

Paste this in:

services:
 #################################
 # PROWLARR
 #################################
 prowlarr:
 # Official LinuxServer.io Prowlarr image
 image: lscr.io/linuxserver/prowlarr:latest
 # Friendly name for the container
 container_name: prowlarr
 # Pulls PUID, PGID, UMASK, TZ, ports, and paths from the .env file
 env_file: .env
 ports:
 # Maps the host port to Prowlarr's web UI (9696) inside the container
 - ${PROWLARR_PORT}:9696
 volumes:
 # Prowlarr's config and database (persists across restarts)
 # Prowlarr only manages indexers, so it needs no media or downloads mounts
 - ${CONFIG_PATH}/prowlarr:/config
 healthcheck:
 # Lets `docker ps` show "healthy" once the UI starts answering
 test: wget --no-verbose --tries=1 --spider http://localhost:9696/ping || exit 1
 start_period: 30s
 timeout: 3s
 interval: 30s
 retries: 3
 networks:
 # Joins the shared media network so it can reach Sonarr/Radarr by name
 - media_network
 # Restart automatically unless you stop it yourself
 restart: unless-stopped

#################################
# NETWORK
#################################
networks:
 media_network:
 # Shared network, created once with: docker network create media_network
 name: media_network
 external: true

Tip: Spacing matters. YAML is picky. Two-space indents only. No tabs.

Step 3: Customize the .env File

Open the .env File

nano /docker/.env

The contents should look like this:

# User and Group ID (Prevents permission issues)
# Main user ID
PUID=1000
# Main group ID:
PGID=1001
# File permission mask
UMASK=0007

# Timezone (Ensures correct scheduling and logs)
TZ=America/Denver

# Define Ports (Ports for each container are defined here)
RADARR_PORT=7878
SONARR_PORT=8989
SABNZBD_PORT=8080
PROWLARR_PORT=9696
BAZARR_PORT=6767

# Data Directories (Keeps storage paths centralized)
CONFIG_PATH=/docker
DOWNLOADS_PATH=/downloads
MEDIA_PATH=/media/Storage

Step 4: Start Prowlarr

The Compose file attaches to an external network called media_network, so create it once before you bring the stack up:

docker network create media_network

Bring the stack online:

docker compose up -d

Confirm the container is running:

docker ps

You should see prowlarr in the list:

CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
604d2ed3850c lscr.io/linuxserver/prowlarr:latest "/init" 6 seconds ago Up 5 seconds (healthy) 0.0.0.0:9696->9696/tcp, [::]:9696->9696/tcp prowlarr

If the container exits a few seconds after up -d, check the logs:

docker logs prowlarr

Permission errors on /config are the usual culprit. Step 5 fixes that.

Step 5: Fix Permissions (If Needed)

Permissions are the number-one snag with media containers. Make sure your user and the media group own everything the containers touch:

sudo chown -R `yourusername`:media /docker/ && sudo chmod -R 770 /docker/
sudo chown -R `yourusername`:media /media/ && sudo chmod -R 770 /media/

Want the full background on Linux permissions and why PUID/PGID matter? Master the Basics - Linux Permissions

Step 6: Access and Set Up Prowlarr in Your Browser

Open a browser and go to:

http://your-server-ip:9696

The setup wizard walks you through:

Adding your Usenet and torrent indexers
Linking your downloader (qBittorrent, SABnzbd, or NZBget) via API
Linking Sonarr, Radarr, Lidarr via API
Setting categories (movies to Radarr, TV to Sonarr, and so on)
Turning on Sync so Prowlarr pushes indexers automatically

Once that’s wired up, Prowlarr becomes the single place to update every indexer in your stack.

Step 7: Keep Your Docker Software Updated

To update:

docker compose pull # Fetches the latest image
docker compose down # Stops and removes the running container
docker compose up -d # Starts a fresh container with the new image

Prowlarr comes back up on the latest image. No reconfig needed.

In Closing

Prowlarr plugs the biggest gap in the Arr automation chain. It keeps indexers and downloaders consistent, online, and in sync with the rest of your stack. Run it in Docker and stop touching it.

Next move: pin the LinuxServer.io image to a known-good tag (e.g. lscr.io/linuxserver/prowlarr:1.21) once you’re happy with the setup. latest is convenient until the day it isn’t.

Building the whole automation stack rather than one app at a time? The complete arr stack Docker Compose guide wires Prowlarr, Radarr, Sonarr, and Bazarr together in a single file.

Running the whole Arr suite? Stand up Prowlarr, Radarr, Sonarr, and Bazarr from one Docker Compose file, with a fast download drive and clean imports into your media pool.

Need a new HDD to keep up with your downloads?

Seagate Barracuda 24TB Internal Hard Drive

Amazon Price: Loading...

Availability: Checking...

Contains affiliate links. I may earn a commission at no cost to you.

How To Install SABnzbd in Docker

Sat, 10 May 2025 05:04:12 -0600

If you’re getting into Usenet, you’ll run into SABnzbd fast. Radarr and Sonarr decide what to download and when. SABnzbd handles the how. It grabs NZB files from your indexer, repairs and unpacks them, then drops the finished files into your media library.

And the best part? Once it’s configured, it hums quietly in the background and you stop thinking about it.

Why SABnzbd Is a Core Part of Your Media Stack

Here’s why SABnzbd still wins:

Free and open source. No premium licenses or paywalls. Fully featured out of the box.
Handles everything automatically. Repair, extract, and cleanup using built-in par2 and unrar.
Custom categories. Route TV, movies, and music into separate folders so Sonarr, Radarr, and Lidarr each get their own pile.
Web interface. Clean, responsive UI for managing and monitoring downloads from any device.
API and script support. Post-processing scripts plus first-class integration with the *arr stack.

If you’re on Usenet, this is the download client you want.

Why Run SABnzbd in Docker?

Docker keeps SABnzbd clean and portable:

Cleaner installs. No Python dependencies or package conflicts on the host.
Effortless updates. Pull the latest image and recreate the container.
Easy to move. Switching servers? Copy the config folder and the compose file. Done.
Better separation. Your download service stays sandboxed from the rest of the system.

Step 1: Install Docker

You’ll need Docker on your server. If you don’t have it yet, follow this guide: Master the Basics - How to Install Docker

Step 2: Create or Modify Your Docker Compose File

Time to add SABnzbd to your stack. The file below runs SABnzbd on its own. Already running Sonarr and Radarr in a Compose file (say, from my Sonarr guide)? Drop the sabnzbd: service into your existing services: block and reuse the same media_network instead of pasting the whole thing.

Open the Compose File

Open your existing docker-compose.yml or create a new one:

nano /docker/docker-compose.yml

Paste this in:

services:
 #################################
 # SABNZBD
 #################################
 sabnzbd:
 # Official LinuxServer.io SABnzbd image
 image: lscr.io/linuxserver/sabnzbd:latest
 # Friendly name for the container
 container_name: sabnzbd
 # Pulls PUID, PGID, UMASK, TZ, ports, and paths from the .env file
 env_file: .env
 ports:
 # Maps the host port to SABnzbd's web UI (8080) inside the container
 - ${SABNZBD_PORT}:8080
 volumes:
 # SABnzbd's config (persists across restarts)
 - ${CONFIG_PATH}/sabnzbd:/config
 # Shared download folder (must be the same path Sonarr and Radarr use)
 - ${DOWNLOADS_PATH}:/downloads
 healthcheck:
 # Lets `docker ps` show "healthy" once the UI starts answering
 test: wget --no-verbose --tries=1 --spider http://localhost:8080/ || exit 1
 start_period: 30s
 timeout: 3s
 interval: 30s
 retries: 3
 networks:
 # Joins the shared media network
 - media_network
 # Restart automatically unless you stop it yourself
 restart: unless-stopped

#################################
# NETWORK
#################################
networks:
 media_network:
 # Shared network, created once with: docker network create media_network
 name: media_network
 external: true

💡 Tip: Watch the indentation. YAML is picky. Two spaces per level, never a tab.

Step 3: Customize the .env File

Open the .env File

nano /docker/.env

The content of the .env file should look like this:

# User and Group ID (Prevents permission issues)
# Main user ID
PUID=1000
# Main group ID:
PGID=1001
# File permission mask
UMASK=0007

# Timezone (Ensures correct scheduling and logs)
TZ=America/Denver

# Define Ports (Ports for each container are defined here)
RADARR_PORT=7878
SONARR_PORT=8989
SABNZBD_PORT=8080
PROWLARR_PORT=9696
BAZARR_PORT=6767

# Data Directories (Keeps storage paths centralized)
CONFIG_PATH=/docker
DOWNLOADS_PATH=/downloads
MEDIA_PATH=/media/Storage

Update the paths to match your setup:

CONFIG_PATH=/docker is the root folder where Docker stores persistent config.
DOWNLOADS_PATH=/downloads is where your download client writes both incomplete and finished files.

Sonarr, Radarr, and SABnzbd all need to see the same /downloads path inside their containers. SABnzbd writes finished files there, and Sonarr and Radarr copy them into your library on import. As long as all three mount the download drive at the identical /downloads path, the apps find what SABnzbd finished with no remote path mapping.

Also update the timezone (TZ) to match yours. The full list lives here: valid timezones (Wikipedia).

Step 4: Start SABnzbd

The Compose file attaches to an external network called media_network, so create it once before you bring the stack up:

docker network create media_network

Bring the container online:

docker compose up -d

Check it’s running:

docker ps

You should see sabnzbd in the list:

CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
d152d14e3fe3 lscr.io/linuxserver/sabnzbd:latest "/init" 15 seconds ago Up 11 seconds (healthy) 0.0.0.0:8080->8080/tcp, [::]:8080->8080/tcp sabnzbd

If the container isn’t there, check what happened:

docker compose logs sabnzbd

Step 5: Fix Permissions (If Needed)

Permissions trip up everyone the first time. The PUID/PGID inside the container have to actually own the host directories, or SABnzbd can’t write to them. Fix it like this:

sudo chown -R `yourusername`:media /docker/ && sudo chmod -R 770 /docker/
sudo chown -R `yourusername`:media /media/ && sudo chmod -R 770 /media/

For the full breakdown of why this works, read this: Master the Basics - Linux Permissions

Step 6: Set Up SABnzbd in Your Browser

Open a web browser and visit:

http://your-server-ip:8080

Follow the setup wizard to:

Add your Usenet provider’s server info (host, port, username, password, connections)
Set up download folders
Create categories like tv and movies so Sonarr and Radarr can route downloads
Grab the API key from Config > General for Sonarr and Radarr to talk back

Once that’s done, SABnzbd is the download engine for the rest of the stack.

Step 7: Keep Your Docker Software Updated

To update:

docker compose pull # Fetches the latest image
docker compose down # Stops and removes the running container
docker compose up -d # Starts a fresh container with the new image

SABnzbd comes back up on the latest image with all your config intact.

In Closing

SABnzbd is the workhorse behind Usenet downloads. Pair it with Sonarr and Radarr and you have a media stack that runs itself. Running it in Docker keeps the install clean, makes upgrades a one-liner, and lets you move the whole thing between servers without rebuilding.

If something breaks after this, the two places to look first are container logs (docker compose logs sabnzbd) and host directory permissions on /docker and /media. Nine times out of ten, that’s where the problem is.

Running the whole Arr suite? Stand up Prowlarr, Radarr, Sonarr, and Bazarr from one Docker Compose file, with a fast download drive and clean imports into your media pool.

Master the Basics - How to Use parted to Create Partitions Format Them and Add a Mount Point

Fri, 09 May 2025 06:24:47 -0600

You bought a new multi-terabyte drive for your media server and you’re ready to slap it into service. Hold up. Before you run fdisk like it’s 1999, you should know it’s no longer the right tool for the job. If your drive is over 2TB, you need GPT instead of MBR. fdisk can’t create GPT partitions. So parted is the way to go.

I’ll walk you through how to use parted to create partitions, format them, and set up automatic mounting with fstab. I’ve run this exact sequence on every new drive I’ve added to my mergerFS pool.

Why Parted Over Fdisk?

fdisk only works with MBR partition tables, which caps your partition sizes at 2TB. That’s a deal-breaker for modern drives. parted works with both MBR and GPT, and it doesn’t care how big the drive is.

It also has better support for scripting, alignment, and resizing. If you’re working with advanced setups or want to future-proof your system, parted is the tool to learn.

fdisk vs parted: Feature Comparison

Feature	`fdisk`	`parted`
Partition Table Support	MBR (Master Boot Record) only	MBR and GPT (GUID Partition Table)
Maximum Disk Size	Up to 2TB	Supports disks larger than 2TB
Partition Resizing	Not supported	Supports resizing and moving partitions
Filesystem Creation	No (requires separate tools like `mkfs`)	Yes (can create filesystems during partitioning)
User Interface	Text-based, menu-driven	Command-line and scriptable interface
Advanced Features	Basic partitioning tasks	Advanced features like alignment and scripting
Best Use Case	Simple setups with MBR partitioning	Complex setups, large disks, GPT partitioning

When to Use Each Tool

Use fdisk for straightforward partitioning on disks smaller than 2TB using the MBR scheme. Fine for legacy systems and simple setups.
Use parted for disks larger than 2TB, anything that needs GPT, or anything that needs resizing and scripting. This is the modern default.

Setting Up Your New Drive with Parted

Here’s how to prep that new drive with parted.

Step 1: Identify the Target Disk

Run:

lsblk

Look for the disk you installed. If it’s /dev/sdb and shows no partitions, that’s the one.

⚠️ Triple-check you’ve got the right disk before you do anything else. Wipe the wrong one and you’ll cry.

Step 2: Install and Launch Parted, Then Create a GPT Partition Table

Install parted and xfsprogs:

sudo apt install parted xfsprogs

Start parted:

sudo parted /dev/sdb

Set the disk label to GPT. This is what you want for drives over 2TB or UEFI systems:

mklabel gpt

Step 3: Create a New Partition

Still inside parted:

mkpart primary xfs 0% 100%

Swap out xfs for another filesystem label if you plan to use ext4 or btrfs later. This step doesn’t actually format the drive. It defines what it’s for.

Now type:

quit

Then:

sudo partprobe /dev/sdb

Step 4: Format the New Partition

Run:

sudo mkfs.xfs /dev/sdb1

You can use ext4 if you prefer. For media servers handling big files, XFS is fast and reliable.

Step 5: Create a Mount Point

Say you’re adding a 5th disk to a mergerFS pool:

sudo mkdir -p /mnt/pool0/disk5

Step 6: Mount It for Testing

Test it before you make anything permanent:

sudo mount /dev/sdb1 /mnt/pool0/disk5

Check that it worked:

df -h

You should see /dev/sdb1 mounted at /mnt/pool0/disk5.

Step 7: Add It to fstab

First, grab the UUID:

sudo blkid /dev/sdb1

You’ll get something like:

UUID="abc123-xyz789" TYPE="xfs"

Copy the UUID.

Edit your fstab:

sudo nano /etc/fstab

Add this line:

UUID=abc123-xyz789 /mnt/pool0/disk5 xfs defaults 0 0

Save and exit.

Step 8: Test Your fstab Config

Unmount the drive:

sudo umount /mnt/pool0/disk5

Now reload fstab:

sudo mount -a

No errors? You’re good.

Wrapping Up

parted is the right tool when you’re working with modern storage. You’ve now set up your drive with a GPT table, created a partition, formatted it, and wired it into fstab. All without hitting the 2TB wall that haunts fdisk.

Next time you drop a new drive into your rig, reach for parted first.

Don’t have a new drive yet? Pick one up here:

Seagate Barracuda 24TB Internal Hard Drive

Amazon Price: Loading...

Availability: Checking...

Contains affiliate links. I may earn a commission at no cost to you.

The Best and Worst PC Cases for Media Servers – Ranked and Reviewed

Sat, 03 May 2025 07:39:35 -0600

You don’t need RGB LEDs and tempered glass side panels to build a good home server. You need airflow. You need drive bays. And most of all, you need peace of mind. Most PC cases aren’t built for this. They’re built for looks, not longevity. If you’re stacking hard drives and chasing silence, the case matters more than you think.

I’ve built more home servers than I can count. Friends, clients, online strangers, all run into the same wall: case selection. They assume any big or “premium” tower will do. Then they try to cram 12 spinning drives into a gaming case and realize there’s no airflow, no cable space, and no way to keep it quiet. The whole thing sounds like an F/A-18 Super Hornet and cooks the hard drives like an air fryer.

This is not the way.

Home media servers aren’t about flexing GPU specs or running rainbow light shows. They’re about stacking storage, managing heat, and keeping your build dead silent. Whether you’re building a 100TB media monster or a modest 24TB file server, the case is the make-or-break stat.

So here’s the shortlist. I’ve ranked the cases I’ve actually built in, based on hands-on time, airflow, cable management sanity, and raw drive capacity. Every pick includes specs and an honest verdict. No sponsorships. No hype. Only what works when you’re building for the long haul.

🟩 S-Tier – Best of the Best

Fractal Design Define 7 XL

Manufacturer’s Link: Factal Design
Price: 💰💰💰💰

The Define 7 XL is the endgame for serious NAS and media server builders. It’s big, heavy, and not cheap, but it earns every inch and dollar. With room for up to 18 drives, whisper-quiet acoustics, and a modular layout that adapts to your needs, it’s the only consumer case that handles a 100TB+ array without hacks or headaches.

This is the gold standard. Built like a tank, cooled like a server, and quiet enough to live next to your desk. The Define 7 XL dominates long-term, high-capacity builds.

Want to build it once and use it forever? This is the case you buy.

Form Factor: Full Tower
Dimensions: 23.8" × 9.4" × 22.3"
Motherboard Support: E-ATX / ATX / mATX / mITX / EE-ATX / SSI-CEB / SSI-EEB
Storage: You can get up to 18 3.5”/2.5” drives inside with optional trays.
Cooling: Three 140mm fans out of the box. You can fit a 480/420mm rad in the top, another 480/420mm rad in the front, and still have room to breathe. Up to 11 120mm fans or 9 140mm fans can be used in this case. Airflow is good, even fully loaded.
Cable Management: You’ve got space behind the motherboard tray for thick SATA and power cables, even with 10+ drives. Velcro straps and deep channels make routing easy.
Noise: Sound-dampening panels on all major surfaces. It’s incredibly quiet, even with a full drive load.
Build Quality: Thick steel, zero flex, excellent panel fitment. You can tell Fractal didn’t cheap out here.
Build Material: Steel, plastic, sound-dampened panels
Pain Points: It’s big. You need room on or under your desk. And it’s not cheap. Worth every penny.

Verdict: If you’re serious about building a media server you can set and forget, the Define 7 XL is the one to beat. Yes, it’s expensive, but you’ll never outgrow it.

Fractal Design Define 7 XL

Amazon Price: Loading...

Availability: Checking...

Contains affiliate links. I may earn a commission at no cost to you.

SilverStone CS380B

Manufacturer’s Link: SilverStone
Price: 💰💰💰💰

Built for one job, and built well. The SilverStone CS380B is a no-nonsense NAS case with real hot-swap support at a price that won’t gut your budget. You get 8 hot-swap bays with proper backplanes, solid cooling, and a compact footprint perfect for closet installs or headless setups.

Yeah, the internal layout is cramped. Cable routing is a pain. And no, it won’t win any beauty contests. But if you care more about function than flash, this case delivers what matters: easy drive access, reliable airflow, and a build that’s purpose-built for storage.

If hot-swapping is a must, this is the case to get.

Form Factor: Mid Tower
Dimensions: 16.8" × 8.5" × 19.2"
Motherboard Support: ATX / mATX / Mini-ITX
Storage: 8 hot-swap bays in the front, each with a metal tray and built-in backplane. Add two 5.25" bays above for accessories or more drives with adapters.
Cooling: Two 120mm side fans and a 120mm rear fan keep drives reasonably cool. Load all 8 bays and you’ll want better fans.
Cable Management: This is where it hurts. It’s tight, especially around the drive bay area. You’ll fight with SATA power cables. Modular PSUs help.
Noise: Not dampened. The stock fans are loud. You’ll hear the drives spinning. Not ideal for a living room.
Build Quality: The frame is solid, but the plastic front door feels cheap and wobbly. Hinges are known to pop loose over time.
Build Material: SECC steel, plastic
Pain Points: Limited GPU space (9.5”) and low CPU cooler clearance (5.7”) restrict future upgrades.

Verdict: It’s a bit awkward to build in, but for a dedicated NAS tucked in a closet or rack, this case nails the essentials: hot-swap support at a fair price.

Update: SilverStone has discontinued the CS380B, and it no longer shows stock on Amazon. The current equivalent is the CS382, which keeps the eight hot-swap bays, moves them to SAS-12G/SATA-6G trays with a status LED per drive, adds USB-C to the front panel, and fits a 240 or 280mm radiator. One change matters before you swap one for the other: the CS382 tops out at Micro-ATX, so a full-size ATX board that fit the older case won’t fit this one. Everything above describes the CS380B.

SilverStone CS382

The successor to the CS380B reviewed above. Same eight hot-swap bays, now Micro-ATX only.

Amazon Price: Loading...

Availability: Checking...

Contains affiliate links. I may earn a commission at no cost to you.

🟨 A-Tier – Strong Performers with Minor Quirks

Fractal Design Define R5

Manufacturer’s Link: Fractal Design
Price: 💰💰💰

The Define R5 is the quiet, compact workhorse of the Fractal lineup. Think of it as the little brother to the Define 7 XL. Smaller, easier to fit into media centers or home offices, and still packed with premium features. You lose some drive slots but gain acoustic dampening, modular cages, and a build that feels perfect.

It’s not built for massive arrays or hot-swapping. But for up to 10 drives in a whisper-quiet setup, the R5 hits a sweet spot. Perfect for bedroom or office servers where silence matters more than scale.

Form Factor: Mid Tower
Dimensions: 20.5" × 9.1" × 17.8"
Motherboard Support: ATX / mATX / Mini-ITX
Storage: Comes with 8 combo 3.5"/2.5" bays plus 2 SSD mounts. Enough for a modest media or backup server.
Cooling: Two quiet 140mm fans included. Add more if needed. This case supports up to 9 fans total or a 420mm rad.
Cable Management: Generous space behind the board. It’s easy to keep things clean, even with a bunch of SATA runs.
Noise: It’s quiet. One of the quietest mid-towers you can buy.
Build Quality: Excellent. Panels are thick, the door is sturdy, and everything lines up perfectly.
Build Material: Steel, plastic, sound-dampened panels
Pain Points: You’re capped at 10 total drives, and no hot-swap. Front I/O is aging. No USB-C.

Verdict: If you want a whisper-quiet server in the same room you work or sleep in, the R5 is a top choice. Keep in mind the front I/O is a little dated.

Update: Fractal has discontinued the Define R5, and Amazon now lists it as unavailable rather than out of stock. If you want the same sound-dampened build quality from a case you can still buy, the Define 7 XL reviewed at the top of this post is the current option. It’s a full tower rather than a mid tower, so it’s bigger and pricier than the R5 was, but it carries the acoustic panels and modular cages forward. Everything above describes the R5.

Fractal Design Define 7 XL

The current Fractal option now that the R5 is discontinued. Reviewed in full at the top of this post.

Amazon Price: Loading...

Availability: Checking...

Contains affiliate links. I may earn a commission at no cost to you.

Montech KING 95 PRO

Manufacturer’s Link: Montech
Price: 💰💰💰

Want a media server that performs well and looks good doing it? The KING 95 PRO delivers. With space for up to 13 drives, strong airflow, and a dual-chamber layout, it has real substance behind the looks. The tempered glass and ARGB fans add flair without getting in the way.

It’s not a perfect case, but for the price, it’s surprisingly capable. The budget-friendly case that proves your server doesn’t have to look like a file cabinet to get the job done.

Form Factor: Mid Tower
Dimensions: 18.7" × 11.8" × 17.4"
Motherboard Support: ATX / mATX / Mini-ITX
Storage: 8 x 3.5" HDDs and 5 x 2.5" SSDs. Enough for most users unless you’re running a full-blown archive.
Cooling: Comes with six PWM ARGB fans and a 10-port hub. Excellent airflow. Great out of the box.
Cable Management: Dual-chamber layout makes routing easy. You’ll have plenty of room to hide cables.
Noise: Not bad, but no insulation. Fan curve tuning will matter here.
Build Quality: Surprisingly solid. Panels fit well. The curved tempered glass is sturdy, but it’s a fingerprint magnet.
Build Material: 0.8mm SPCC steel, tempered glass
Pain Points: No hot-swap. Bottom filter is a pain to clean. Riser cable for vertical GPU not included.

Verdict: Slick, spacious, and stylish. This case looks great in an office or home theater setup. It’s not for massive arrays or hot-swapping, and build quality isn’t perfect, but for the price, it punches way above its weight.

Update: The KING 95 PRO is no longer available on Amazon, so I’ve pulled the buy link. The review stays up because the case still turns up secondhand, and it’s worth knowing what you’re getting if one comes your way. For a new build at this capacity, the S-tier picks at the top of this post are where I’d look now. Everything above describes the KING 95 PRO.

Rosewill Helium NAS

Manufacturer’s Link: Rosewill
Price: 💰

The Helium NAS is all about stuffing in drives without draining your wallet. It’s not polished. The case suffers from thin panels, sharp edges, and noisy stock fans. But for under $100, it gets the job done. You get high drive capacity, reasonable airflow, and enough room to build something serious on a tight budget.

It’s rough around the edges. If you care more about storage than style, the Helium NAS delivers real value where it counts.

Form Factor: Mid Tower
Dimensions: 19.2" × 8.5" × 19.2"
Motherboard Support: ATX / mATX / Mini-ITX
Storage: 10 x 3.5" + 3 x 2.5". Huge capacity for the price.
Cooling: Four 140mm fans stock. All intake by default and needs reconfiguration for proper airflow.
Cable Management: Tight. Especially with full SATA and Molex bundles. Plan your routing before plugging anything in.
Noise: Mesh front and aggressive airflow = louder than you’d expect. But temps stay good.
Build Quality: It’s budget steel. Side panels flex. Drive cage fitment isn’t always great. Expect quirks.
Build Material: SECC steel, plastic
Pain Points: No hot-swap. Some drives may block airflow. Front I/O is decent though, with USB-C included.

Verdict: You’ll fight some build quirks, but for under $100, it’s a solid budget case for stuffing full of drives. 13 bays and mesh airflow seal the deal.

Rosewill Helium NAS

Amazon Price: Loading...

Availability: Checking...

Contains affiliate links. I may earn a commission at no cost to you.

🟧 B-Tier – Usable if You’re Handy

DARKROCK Classico Max

Manufacturer’s Link: DARKROCK
Price: 💰💰

This case aims for maximum drive count on a budget and mostly nails it. It has space for 13 drives, four pre-installed fans, and a clean exterior, all for around $90. It’s a solid foundation for a media server, especially if you’re trying to stretch every dollar.

The build quality won’t blow you away. Thin panels, tight cable routing, and sharp edges make the build process a hassle. But if you have patience and a first aid kit (you will cut your hands), it’s hard to beat the value for the drive count.

Form Factor: Mid Tower
Dimensions: 18.9" × 8.3" × 18.5"
Motherboard Support: E-ATX (with drive cage removed) / ATX / mATX / Mini-ITX
Storage: 10 x 3.5", 3 x 2.5". Impressive at this price.
Cooling: Four fans included, and it fits a 360mm rad on top. Drive area airflow could be better.
Cable Management: Weak spot. Rear cable space is limited. SATA and Molex cables bulge the panel.
Noise: No dampening. Expect noticeable fan and drive noise.
Build Quality: Metal panels are thin. Side panel fitment is hit-or-miss.
Build Material: Steel, plastic
Pain Points: USB-C missing. One USB 3.0 port only. Watch out for cable bulk behind the tray.

Verdict: Need maximum drive count at a low cost? This case has you covered (in your own blood). Expect thin panels and a serious fight for cable space.

DARKROCK Classico Max

Amazon Price: Loading...

Availability: Checking...

Contains affiliate links. I may earn a commission at no cost to you.

Thermaltake CTE C700 TG

Manufacturer’s Link: Thermaltake
Price: 💰💰💰

The C700 TG isn’t really built for storage, but it brings some serious firepower if you’re building a hybrid rig. With a rotated motherboard layout for direct airflow, triple ARGB fans, and room for custom loops, it’s clearly aimed at high-performance builds. Think media storage, gaming, and VMs all in one box.

It’s massive, flashy, and absolute overkill for a pure NAS. If you need a case that can handle mixed workloads and look good doing it, the C700 TG pulls it off with style. Don’t expect drive-focused design. It’s all about airflow and flexibility.

Form Factor: Mid Tower
Dimensions: 22.3" × 12.9" × 19.8"
Motherboard Support: E-ATX / ATX / mATX / Mini-ITX
Storage: 7 x 3.5" + 6 x 2.5". Okay, but not great for dedicated NAS use.
Cooling: Includes 3 140mm fans. This case can support up to 11 fans. One of the best for airflow. It can also support up to 3 rads.
Cable Management: Excellent, thanks to the dual chamber. Cables route cleanly, even with multiple drives and fans.
Noise: With high-RPM fans, it gets loud. Replace them for silence.
Build Quality: Very solid. Premium glass and thick panels.
Build Material: Steel, tempered glass, plastic
Pain Points: Heavy. Top I/O not ideal for under-desk setups.

Verdict: This case is suited for high-performance setups like gaming, media playback, VMs, or creative workstations. It’s overkill for pure storage but works if you want fancy cooling and extra headroom.

Update: The C700 TG is no longer available on Amazon, so the buy link is gone. I’ve kept the review because the rotated-motherboard layout is worth understanding before you buy any case built around one. It moves air beautifully and it still won’t hold many drives. Everything above describes the C700 TG.

Phanteks Enthoo Pro TG

Manufacturer’s Link: Phanteks
Price: 💰💰💰

This case is starting to show its age, but it still holds up if you manage your expectations. You get decent drive support, solid build quality, and enough room for fans. Airflow and cable management don’t match what newer cases offer.

It was top-tier back in 2016. Today? It’s functional, not exceptional. If you already own it, it’s worth using. If you’re shopping for something new, there are better options on the market.

Form Factor: Full Tower
Dimensions: 21.1" × 9.3" × 21.7"
Motherboard Support: SSI-EEB / E-ATX / ATX / mATX / Mini-ITX
Storage: 6 x 3.5", 4 x 2.5". Good for mid-size builds.
Cooling: One front fan and one rear fan are included. Airflow is okay, but you’ll want more fans.
Cable Management: Lots of tie points and channels. Easy to keep tidy.
Noise: No insulation. Average sound profile.
Build Quality: Decent. Nothing to write home about.
Build Material: Steel, tempered glass, plastic
Pain Points: Vertical GPU mount needs a riser. Build layout is less optimized by today’s standards.

Verdict: This case is dated but dependable. Still usable if you already have it. If you’re buying new, there are better options for the price.

Update: The Enthoo Pro TG is no longer available on Amazon, which is no great loss given where the review landed. It was a 2016 design being judged by today’s standards, and it didn’t have far to fall. The section stays as a reference for anyone who already owns one. Everything above describes the Enthoo Pro TG.

🟥 C-Tier – Functional with Major Tradeoffs

Corsair 7000D AIRFLOW

Manufacturer’s Link: Corsair
Price: 💰💰💰💰

This case is an absolute monster. Built for custom loops, high-end hardware, and airflow that won’t quit. It’s big, bold, and stunning to look at. When it comes to media server duty, it misses the mark.

Drive support is the weak link. You’ll be improvising mounts by the time you hit six drives, and it’s clearly not designed with storage in mind. Unless you’re building a dual-purpose gaming and media rig, this is the wrong tool for the job. Beautiful, but not practical for a server.

Form Factor: Full Tower
Dimensions: 21.6" × 9.8" × 23.6"
Motherboard Support: E-ATX / ATX / mATX / Mini-ITX
Storage: 6 x 3.5" and 4 x 2.5" out of the box. You’ll need adapters or mods to expand.
Cooling: 3 140mm fans are included. Supports up to 12 120mm or 7 140mm fans. Top-tier airflow. Fits every radiator and fan combo.
Cable Management: Corsair’s RapidRoute system is excellent. 36mm of routing space.
Noise: Loud with stock fans. Quiet down with Noctua or Be Quiet swaps.
Build Quality: Premium all the way. Heavy, rigid, and beautifully finished.
Build Material: Steel, tempered glass, plastic
Pain Points: Expensive, overkill for NAS use, lacking drive expansion out of the box.

Verdict: This case looks amazing and works great for gaming or workstations. For a media server, the size and cost aren’t worth it. There are better picks for storage and cooling.

Update: The 7000D AIRFLOW is no longer available on Amazon, and I’ve removed the buy link. That changes very little here, since the verdict was already to skip it for server duty. If you want a case this size, the Define 7 XL at the top of this post does the job with far better drive support. Everything above describes the 7000D AIRFLOW.

Cooler Master MasterBox NR400

Manufacturer’s Link: Cooler Master
Price: 💰💰💰

The NR400 is compact, clean, and easy to work with. It has great ventilation, a solid layout, and is a breeze to build in. With support for only 4 drives, it’s not built for serious media server applications.

It’s a good fit for HTPCs, small servers, or setups where storage is handled elsewhere. Planning to scale your media library? You’ll outgrow it quickly.

Form Factor: Mini Tower
Dimensions: 16.2" × 8.3" × 16.2"
Motherboard Support: mATX / Mini-ITX
Storage: 4 x 3.5"/2.5" bays. That’s it.
Cooling: Two 120mm fans included. Good airflow, but not enough for dense builds.
Cable Management: Space is tight. Modular PSU strongly recommended.
Noise: No insulation. Expect fan and drive noise.
Build Quality: Not bad for a mini-tower. Side panel is a bit wobbly.
Build Material: Steel, plastic, tempered glass
Pain Points: Drive cage blocks PSU airflow. Limited upgrade path.

Verdict: Good airflow and a simple layout make it beginner-friendly, but it’s more HTPC than a server case. Best for a tiny, low-power build with storage handled elsewhere.

Cooler Master MasterBox NR400

Amazon Price: Loading...

Availability: Checking...

Contains affiliate links. I may earn a commission at no cost to you.

Final Words

Building a home media server? Prioritize function over flashy aesthetics. That means thinking about storage, airflow, cable space, and noise before aesthetics or gaming extras. The Fractal Define 7 XL is my top recommendation for anyone serious about capacity and silence. The SilverStone CS382 is the best plug-and-play option if you need hot-swap capabilities, now that its predecessor the CS380B is discontinued. Building on a budget? The Rosewill Helium or DARKROCK Classico will get you there with a little extra effort.

Pick based on your storage needs, noise tolerance, and build experience. Pick right, and you only have to buy a case once.

Radarr Docker Compose Setup Guide (2026)

Sun, 20 Apr 2025 05:50:50 -0600

💡

Tip: Default port: Radarr runs on port 7878. Access the web UI at http://your-server-ip:7878 once the container is running.

If you love watching movies, you know the drill. Keeping a library organized and current feels like a second job. Release dates slip, quality options multiply, and sources scatter across the internet. Pretty soon your “movie collection” is a folder full of mystery files.

That’s where Radarr comes in. Instead of rummaging through torrent or Usenet sites for a new release, or trying to remember when something drops digitally, Radarr handles it. It watches your wanted list, grabs releases through your torrent or Usenet client, then renames, organizes, and files the result into your media library. Ready to watch on Jellyfin, Plex, or Kodi.

Set it and forget it. That’s the whole pitch.

Why Radarr Is a Must-Have

Here’s why Radarr is my go-to for movie automation:

Automated downloads. Add a movie. Radarr searches for it, grabs it, and upgrades to a better release when one shows up.
Missing movie search. Radarr keeps scanning for anything missing or unavailable when you first added it.
Download client integration. Works with qBittorrent, Deluge, SABnzbd, and NZBGet.
Library management. Clean folder structures, proper naming, full metadata.

Radarr turns your movie library into a system that runs itself.

Why Run Radarr in Docker?

Docker is one of the best ways to run it. Here’s why:

Clean isolation. Radarr and its dependencies stay separate from your host system.
Effortless updates. Pull the latest image. Done.
Portability. Move your setup to another machine without rebuilding from scratch.
No dependency hell. No conflicting libraries fighting with your other software.

Running Radarr in Docker keeps things tidy, predictable, and easy to troubleshoot when something breaks. And something always breaks eventually.

If you’re ready to take control of your movie collection, this is the way.

Step 1: Install Docker

You’ll need Docker installed on your server first. Walk through this guide if you haven’t already: Master the Basics - How to Install Docker

Step 2: Create or Modify Your Docker Compose File

Let’s define your Radarr container in docker-compose.yml. The file below runs Radarr on its own. Already have other Arr apps in a Compose file (say, from my Sonarr guide)? Drop the radarr: service into your existing services: block and reuse the same media_network instead of pasting the whole thing.

Open the Compose File

Open your existing docker-compose.yml or create a new one:

nano /docker/docker-compose.yml

Paste this in:

services:
 #################################
 # RADARR
 #################################
 radarr:
 # Official LinuxServer.io Radarr image
 image: lscr.io/linuxserver/radarr:latest
 # Friendly name for the container
 container_name: radarr
 # Pulls PUID, PGID, UMASK, TZ, ports, and paths from the .env file
 env_file: .env
 ports:
 # Maps the host port to Radarr's web UI (7878) inside the container
 - ${RADARR_PORT}:7878
 volumes:
 # Radarr's config and database (persists across restarts)
 - ${CONFIG_PATH}/radarr:/config
 # Your movie library
 - ${MEDIA_PATH}/Movies:/movies
 # Shared download folder (must be the same path in every Arr container)
 - ${DOWNLOADS_PATH}:/downloads
 healthcheck:
 # Lets `docker ps` show "healthy" once the UI starts answering
 test: wget --no-verbose --tries=1 --spider http://localhost:7878/ping || exit 1
 start_period: 30s
 timeout: 3s
 interval: 30s
 retries: 3
 networks:
 # Joins the shared media network
 - media_network
 # Restart automatically unless you stop it yourself
 restart: unless-stopped

#################################
# NETWORK
#################################
networks:
 media_network:
 # Shared network, created once with: docker network create media_network
 name: media_network
 external: true

💡 Tip: Watch your spacing. YAML is picky. Two spaces per indent, no tabs. Mix them and the container won’t start.

Step 3: Customize the .env File

Open the .env File

nano /docker/.env

The contents should look like this:

# User and Group ID (Prevents permission issues)
# Main user ID
PUID=1000
# Main group ID:
PGID=1001
# File permission mask
UMASK=0007

# Timezone (Ensures correct scheduling and logs)
TZ=America/Denver

# Define Ports (Ports for each container are defined here)
RADARR_PORT=7878
SONARR_PORT=8989
SABNZBD_PORT=8080
PROWLARR_PORT=9696
BAZARR_PORT=6767

# Data Directories (Keeps storage paths centralized)
CONFIG_PATH=/docker
DOWNLOADS_PATH=/downloads
MEDIA_PATH=/media/Storage

Update the Radarr paths to match your setup. Here’s what each one does:

CONFIG_PATH=/docker is the root folder where Docker stores persistent container files.
MEDIA_PATH=/media/Storage is the root folder for your media files.
DOWNLOADS_PATH=/downloads is where your download client drops temp and incomplete files.

Make sure your download client container shares access to the /downloads path. If it doesn’t, Radarr can’t move finished downloads into your library and you’ll spend an afternoon wondering why.

Also update TZ to your timezone. Reference: this list of valid timezones.

Step 4: Start Radarr

The Compose file attaches to an external network called media_network, so create it once before you bring the stack up:

docker network create media_network

Bring your new Radarr container online:

docker compose up -d

Check that it’s running:

docker ps

You should see radarr in the list of containers:

CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
ff12a474a4fe lscr.io/linuxserver/radarr:latest "/init" 54 seconds ago Up 53 seconds (healthy) 0.0.0.0:7878->7878/tcp, [::]:7878->7878/tcp radarr

Step 5: Fix Permissions (If Needed)

Permission problems are the classic gotcha with media containers. Here’s how to make everything play nice:

sudo chown -R `yourusername`:media /docker/ && sudo chmod -R 770 /docker/
sudo chown -R `yourusername`:media /media/ && sudo chmod -R 770 /media/

Want the longer explanation of what’s going on here? Read this: Master the Basics - Linux Permissions

Step 6: Access Radarr

Open your browser and hit:

http://your-server-ip:7878

From there you can add movies, set quality profiles, and connect your download clients.

For deeper configuration, the official Radarr Wiki is the definitive source.

Step 7: Keep Your Docker Software Updated

To update:

docker compose pull # Fetches the latest image
docker compose down # Stops and removes the running container
docker compose up -d # Starts a fresh container with the new image

Radarr comes back up on the latest version. No reconfig needed.

Conclusion

Radarr does the boring work. It tracks, downloads, upgrades, and organizes your movies without you babysitting it. No more hunting for files, renaming releases, or shuffling folders around by hand.

Running it in Docker keeps your host system clean and your container easy to manage. Pair Radarr with Sonarr for TV shows and Lidarr for music, and you’re running a self-updating media library that mostly takes care of itself.

Want to run the whole suite from a single Compose file instead of one app at a time? See the complete arr stack Docker Compose guide.

Running the whole Arr suite? Stand up Prowlarr, Radarr, Sonarr, and Bazarr from one Docker Compose file, with a fast download drive and clean imports into your media pool.

How I Fixed My 24 Hour NFS Crash Loop With MergerFS LXC and Proxmox

Fri, 11 Apr 2025 06:52:23 -0600

Every sysadmin, professional or weekend warrior, has that one issue that haunts them. For me, this week, it was a weird NFS crash loop on Proxmox that kicked in like clockwork. Every 24 hours, like it was on a timer. (It was. My backups were running.) The server booted, NFS shares mounted fine, media apps ran smoothly. Looked solid. Then boom. NFS would stop responding. Containers started throwing stale file handle errors and memory usage shot through the roof.

I spent days chasing ghosts. If you’re running NFS exports from a MergerFS-backed VM in Proxmox, especially with LXC clients, here’s what fixed it for me and why you should check your own setup.

Stack Snapshot

Before we dig into the fix, here’s what my setup looked like:

Proxmox host with a ZFS RAIDZ1 pool
NAS VM with an HBA passing through XFS drives, combined using MergerFS
MergerFS presenting /media/Storage
NFS server inside the NAS VM, exporting that MergerFS mount
LXC containers (Sonarr, Jellyfin, etc.) mounting those exports as clients

On paper, this setup checks out. Under the hood, it was primed for failure thanks to one small flag: noforget.

Where Things Went Sideways

It wasn’t obvious at first. But the symptoms started stacking:

VM would freeze after ~24 hours
LXC clients hit “stale file handle” errors
Slab memory ballooned, especially fuse_inode (over 110,000 inodes)

That last one was the smoking gun. Hundreds of thousands of inodes hanging around with no cleanup.

Wait, What’s an Inode?

Think of an inode as the metadata brain behind every file in a Linux filesystem. It stores everything about the file except its name and contents. That means stuff like:

File size
Permissions
Owner and group
Timestamps
Pointers to where the actual data lives on the disk

Every time you create, read, or move a file, the system checks the inode to figure out what it’s dealing with. The inode number is what NFS uses to track files across the network. If those numbers change or pile up, things get ugly fast. Especially with MergerFS and NFS in the mix.

Smoking Gun: `noforget` in MergerFS

Here’s what I originally had for my MergerFS entry in /etc/fstab:

/mnt/Pool0/Disk* /media/Storage fuse.mergerfs direct_io,defaults,allow_other,noforget,dropcacheonclose=true,category.create=mfs,minfreespace=50G,fsname=storage 0 0

The noforget flag was the root of my problems.

What it does: prevents the kernel from purging unused FUSE inodes. Great for certain workloads. Awful for MergerFS over NFS.

What happened: every NFS client interaction added more FUSE inodes. The kernel kept them all. Memory usage exploded. Stability collapsed.

Check Your `fuse_inode` Count

Run this:

cat /proc/slabinfo | grep fuse_inode

Before the fix, mine hit 100,000+ entries. After? Around 200. Immediate memory relief.

The Fixes That Saved My Sanity and Marriage

1. Replace `noforget` with `inodecalc=path-hash`

I pulled noforget out of my MergerFS options and put inodecalc=path-hash in its place. This is the key change for NFS stability. Without it, inode numbers jump around and NFS freaks out. New MergerFS line in /etc/fstab:

/mnt/Pool0/Disk* /media/Storage fuse.mergerfs direct_io,defaults,allow_other,dropcacheonclose=true,category.create=mfs,minfreespace=50G,inodecalc=path-hash,fsname=storage 0 0

Now FUSE inodes are purged normally, and NFS clients get consistent inode numbers.

2. Boost `vfs_cache_pressure`

Force the kernel to clean inodes and dentries more aggressively. Add it to /etc/sysctl.conf:

echo vm.vfs_cache_pressure=200 | sudo tee -a /etc/sysctl.conf

Then reboot or run:

sudo sysctl -p

3. Change Proxmox Disk Cache to `writethrough`

In the Proxmox VM Hardware settings, switch the disk cache mode to:

cache=writethrough

This forces better consistency between Proxmox, ZFS, and your VM’s disk I/O.

What Stability Looks Like Now

After these changes:

No more stale handles or NFS hangs
fuse_inode count is flat, around 8,000 after days of uptime
Memory usage is predictable
LXC clients mount and run cleanly, even under load

Quick Fix Table

Tweak	Why It Matters
Remove `noforget`	Stops memory leaks via inode bloat
Add `inodecalc=path-hash`	Prevents NFS from freaking out
Set `vfs_cache_pressure=200`	Cleans up unused inode/dentry entries
Use `writethrough` in Proxmox	Improves disk I/O behavior with ZFS
Monitor `/proc/slabinfo`	Catch inode bloat before it breaks stuff

TL;DR

NFS + MergerFS + Proxmox VM + LXC? Check your MergerFS flags.

Specifically:

Ditch noforget. Add inodecalc=path-hash. Crank vfs_cache_pressure. Set Proxmox disk cache to writethrough.

These four config changes saved my server from daily crashes. If your NFS setup feels haunted, start here.

Try it. Get your sanity back and sleep again.

Hardware - Why You Need an HBA

Sun, 06 Apr 2025 08:14:46 -0600

Ever hit a wall with your media server setup? Maybe you maxed out your motherboard’s SATA ports. Or you want to hand control of your drives to a VM in Proxmox without the host getting in the way. That’s where a Host Bus Adapter (HBA) earns its keep. It gives you smoother storage configuration, more drives, and better performance, especially if you’re running a virtualized environment.

Here’s what you need to know. When to use an HBA, why it works so well in virtual storage VMs, what cables you’ll need, and how to buy one that works out of the box.

What’s an HBA and When Should You Use It?

A Host Bus Adapter (HBA) is a PCIe card that gives your server more drive connectivity than your motherboard can. Think of it as a high-performance SATA or SAS controller, way more capable than those cheap expansion cards that drop drives under load.

You’ll want one if:

You’re out of SATA ports. Most motherboards give you six. Run a Plex or Jellyfin server and you’ll blow through those fast.
You’re using Proxmox or any hypervisor. Want to pass your drives directly to a VM? You need an HBA flashed to IT mode.
You care about reliability. HBAs are built to handle a pile of drives without dropping them randomly like bargain-bin SATA controllers do.

When to Use an HBA

Problem	HBA Fixes It By…
Not enough SATA ports	Expands drive capacity (8+ drives)
Running Proxmox VMs	Allows direct passthrough to VM
Cheap SATA cards unreliable	Provides stable, enterprise-grade control
Want future expansion	Supports SAS expanders (24+ drives)

HBAs in Virtual Storage VMs (This Is Where They Shine)

Running a NAS in a VM? Stop fighting your hypervisor. Pass the HBA straight to the storage VM and let it take over.

1. Direct Passthrough = Better Performance

Instead of juggling drive access through the host, pass the HBA to your VM. That VM gets direct, raw control over the drives. Perfect for ZFS, MergerFS, or SnapRAID.

2. IT Mode: No RAID, No Nonsense

Flashing the HBA to IT mode strips out the RAID firmware. The VM sees each drive on its own, the way it should. No weird RAID layer getting in the way of SMART tools or parity calculations.

3. Fewer Headaches, More Stability

Onboard SATA gets weird in VMs. Unreliable, slow, or flat-out flaky. An HBA gives you dedicated hardware built for this job.

4. Room to Grow

Planning for expansion? A single HBA can talk to a SAS expander and let you run 24 or more drives through one PCIe slot.

How to Buy an HBA That Works Out of the Box

Get One Already Flashed to IT Mode

Most used enterprise HBAs ship with RAID firmware (IR mode). You want IT mode. That’s what makes each drive show up independently.

Popular models:

LSI 9211-8iB

Already Flashed to IT mode.

Amazon Price: Loading...

Availability: Checking...

Contains affiliate links. I may earn a commission at no cost to you.

LSI 9300-8i

Already Flashed to IT mode.

Amazon Price: Loading...

Availability: Checking...

Contains affiliate links. I may earn a commission at no cost to you.

Dell H310

Already Flashed to IT mode.

Amazon Price: Loading...

Availability: Checking...

Contains affiliate links. I may earn a commission at no cost to you.

Also look for pre-flashed cards on:

eBay (search for “IT mode HBA”)
Server resellers with refurb listings

They usually run $50 to $100. Cheap, considering the performance and stability boost.

Need More Drives? Get a SAS Expander

If 8 ports aren’t enough, plug a SAS expander into your HBA.

What It Does

Think of it like a network switch for hard drives. You plug the HBA into the expander, and the expander gives you dozens of ports.

Why It’s Useful

More drives per HBA - Some expanders support 24 or more drives.
Fewer PCIe slots used - Leave room for GPUs, NICs, or other gear.
Lower cost - Expanders cost less than more HBAs.

Popular SAS Expander

Intel RES2SV240

Compact and solid for home labs.

Ebay

Contains affiliate links. I may earn a commission at no cost to you.

Cables: Here’s What You Need

HBAs don’t use regular SATA ports. They use SFF connectors.

SFF-8087 to 4x SATA

Used for older HBAs like the LSI 9211-8i.

Amazon Price: Loading...

Availability: Checking...

Contains affiliate links. I may earn a commission at no cost to you.

SFF-8643 to 4x SATA

Used for newer HBAs like the LSI 9300-8i.

Amazon Price: Loading...

Availability: Checking...

Contains affiliate links. I may earn a commission at no cost to you.

If you’re using an expander, you’ll also need:

SFF-8087 to SFF-8087

Used for older HBAs like the LSI 9211-8i.

Amazon Price: Loading...

Availability: Checking...

Contains affiliate links. I may earn a commission at no cost to you.

SFF-8643 to SFF-8087

Used for newer HBAs like the LSI 9300-8i.

Amazon Price: Loading...

Availability: Checking...

Contains affiliate links. I may earn a commission at no cost to you.

HBA Port Type	Use This Cable
SFF-8087	SFF-8087 to 4x SATA
SFF-8643	SFF-8643 to 4x SATA
Expander Link	SFF-8087 to SFF-8087

Wrap-Up: Yes, You Should Use an HBA

Want to scale up? Want your VM to manage your drives directly? Tired of janky SATA cards dropping disks under load? Then an HBA flashed to IT mode is a must. Pair it with an expander if you’re going big. Use the right cables. And your home media server actually scales.

Before you buy, check the seller’s listing for the exact firmware revision. P20 is the standard for the LSI 9211-8i in IT mode. If the listing won’t say, assume it’s IR and budget time to reflash. And run the card in a real PCIe x8 slot, not an x1 riser, or you’ll bottleneck every drive on it.

Skip the guesswork. Get an HBA controller flashed to IT mode.

SABnzbd vs NZBGet: Which NZB Downloader Should You Choose in 2026?

Sat, 29 Mar 2025 06:26:41 -0600

Choosing between SABnzbd vs NZBGet matters more than most folks realize. Back in the day, Usenet meant hours of manual unpacking, repairing, and sorting. Now SABnzbd and NZBGet do all of that for you. The hard part? Picking which one to run.

If you’re brand new to Usenet or building your first DIY media server, this decision matters more than it looks. Pick the wrong downloader and you’ll spend nights fighting settings, broken automation, or a pegged CPU. Pick the right one and Usenet becomes the set-it-and-forget-it experience it was supposed to be.

This guide breaks down the sabnzbd vs nzbget debate from a beginner’s point of view. I’ll cover setup, day-to-day performance, automation with the Arr stack, and long-term support, so you can confidently pick the right NZB downloader for your setup in 2026.

💭

TL;DR: If you’re new to Usenet and want the least painful setup, SABnzbd is the winner. NZBGet is faster and lighter, but SABnzbd’s guided setup, polished interface, and straightforward automation make it the better choice for most beginners.

What Are SABnzbd and NZBGet?

Before comparing them, let’s define what they are.

Both SABnzbd and NZBGet are NZB download managers, software that automates Usenet downloads.

They:

Download files from Usenet using NZB files
Repair missing parts with PAR files
Unpack archives
Rename and sort files
Hand everything off to apps like Sonarr or Radarr

In short, they’re the backbone of any Usenet-based media server.

The difference is how they do it and how much effort they ask from you. And that effort adds up fast when you’re trying to get a fresh server online.

SABnzbd vs NZBGet: Performance and System Requirements

Raw Speed and Resource Usage

Alright, this is the one area where NZBGet clearly wins.

NZBGet is written in C++, which makes it extremely efficient. It uses less CPU, less RAM, and generally downloads faster on the same hardware. Reports from the community show noticeable speed differences, especially during heavy post-processing like repairing and unpacking large files.

SABnzbd is written in Python. Python is easier to maintain and extend, but it costs more CPU cycles. During unpacking and repair, SABnzbd can spike CPU usage, which matters on weaker systems.

📝

Note: On a Raspberry Pi 4 downloading a 50GB file, NZBGet typically uses 15-20% less CPU during unpacking and finishes the job 10-15% faster.

Here’s the thing though. For most people, this doesn’t matter as much as you’d think.

Decisions:

If you’re running on a Raspberry Pi, older Intel CPU, or NAS hardware, choose NZBGet
If you have a modern mini PC, desktop CPU, or home server, either works fine

Even low-end Intel N100 and Ryzen mini PCs handle SABnzbd without breaking a sweat. Hardware is no longer the bottleneck for most beginners.

Setup and Installation: NZBGet vs SABnzbd

SABnzbd: Built for Beginners

This is where SABnzbd earns its reputation.

On first launch, SABnzbd walks you through a clean setup wizard:

Enter your Usenet provider
Test the connection
Pick download and completed folders
Enable basic security options

You can be downloading within minutes, even if you’ve never touched Usenet before. The defaults are sensible, and most users never need to touch advanced settings.

NZBGet: More Control, More Work

NZBGet installs easily, especially via Docker or NAS app stores. The challenge comes after installation.

A lot of important behavior needs manual configuration:

Paths
Post-processing options
Security settings
Script behavior

None of this is impossible, but it assumes you know what you’re configuring and why. And honestly? When you’re starting out, you usually don’t.

Example setup flow:

SABnzbd: Install, run wizard, start downloading
NZBGet: Install, configure paths, set up categories, configure post-processing, start downloading

See the difference? SABnzbd gets you downloading in three steps. NZBGet needs five, and every one assumes you know what you’re doing.

RaspberryPi 4GB A low-cost, beginner-friendly platform for running SABnzbd or NZBGet, making it ideal for novices following this guide.

Amazon Price: Loading...

Availability: Checking...

Contains affiliate links. I may earn a commission at no cost to you.

A Pi 4 is the kind of hardware where NZBGet’s efficiency actually shows up in your download times. SABnzbd still runs fine on one, but you’ll feel the CPU pressure during big unpacks.

Web Interface and Day-to-Day Usability

SABnzbd Interface

SABnzbd has one of the cleanest web interfaces in the Usenet world.

Modern layout
Clear queue view
Multiple themes
Easy access to logs and warnings

You always know what’s downloading, what failed, and why. For novices, that matters more than raw speed. Visibility prevents frustration.

I can’t tell you how many times I’ve avoided a headache because SABnzbd showed me exactly what went wrong instead of making me dig through logs.

NZBGet Interface

NZBGet’s interface is fast and minimal. It works well, but it assumes you already know your way around Usenet terminology.

It shines when you customize it with widgets and scripts, but out of the box it feels utilitarian rather than welcoming. NZBGet will get the job done. You won’t enjoy looking at it.

Automation and Arr App Integration

SABnzbd: Plug and Play Automation

SABnzbd plays nicely with:

Sonarr
Radarr
Lidarr

No scripts required. Point the Arr apps at SABnzbd, map your folders, and you’re done.

Basic Sonarr integration:

Sonarr Settings → Download Clients → Add SABnzbd
Host: localhost
Port: 8080
Category: tv
Completed Download Handling: Enabled

SABnzbd also handles:

Obfuscated NZBs (those weirdly-named files that trip up other downloaders)
Renaming files reliably
Sorting downloads without manual rules

What success looks like: After adding SABnzbd to Sonarr, you’ll see a green checkmark in the download client settings. Your first episode will download, unpack, and appear in your media library without you touching anything.

NZBGet: Powerful but Script-Driven

NZBGet supports everything SABnzbd does, and often more, but frequently through scripts or extra configuration:

Custom post-processing
Advanced RSS filters
RPC API access

Both tools plug into the Arr apps fine. SABnzbd tends to work out of the box. NZBGet may need category mapping or post-processing scripts for complex workflows.

📝

Note: If you love tinkering, NZBGet gives you more knobs to turn. But if you want your shows to download while you sleep? SABnzbd gets you there faster.

Power Efficiency and Background Behavior

This is a subtle but potentially important difference for 24/7 systems.

SABnzbd uses iNotify on Linux, which lets it detect new files instantly without constantly scanning folders. That can cut background CPU usage and lets systems sleep when idle.

NZBGet periodically rescans folders, which may:

Prevent sleep modes
Use more background CPU
Increase power consumption on always-on systems

The actual impact varies by system and configuration. On modern hardware the difference is small, but it adds up over time on power-conscious setups.

If you’re running a home server 24/7 and care about your power bill, this is worth a thought. Five watts here, ten watts there. It piles up over a year.

Seagate Barracuda 24TB Internal Hard Drive Large storage is essential for media server users downloading content with SABnzbd or NZBGet, but this drive is best for single-drive/light-duty setups, not advanced NAS.

Amazon Price: Loading...

Availability: Checking...

Contains affiliate links. I may earn a commission at no cost to you.

Whichever downloader you pick, you’ll fill a drive faster than you expect. Plan storage like you mean it.

Long-Term Support and Updates

SABnzbd

Frequent updates
Active development
Large user community
Excellent documentation

From a stability and security perspective, SABnzbd is the safer long-term choice. When something breaks, a fix usually lands within days.

NZBGet

NZBGet development slowed significantly after 2019, which spooked the community. Development has picked back up under new maintainers, but the update cadence is still less predictable.

It remains stable and functional, but beginners benefit from active ecosystems. You want a tool that’s being actively maintained when you run into issues.

SABnzbd vs NZBGet Comparison Table

Feature	SABnzbd	NZBGet
Performance	Higher resource usage	Extremely lightweight
Setup	Wizard-driven, beginner-friendly	Manual configuration
Interface	Polished and modern	Minimal and utilitarian
Automation	Plug and play	Script-based options
Power Efficiency	iNotify-based monitoring	Folder rescans
Updates	Frequent and consistent	Less predictable
Best For	New users, automation	Low-power hardware

Troubleshooting Common Beginner Issues

Downloads Are Slow

Check your Usenet provider’s connection limits (most cap you at 20-30 connections)
Verify SSL is on (it should be, but double-check)
NZBGet may outperform SABnzbd on weak CPUs

Files Fail to Unpack

Turn on automatic repair and unpack (should be on by default in SABnzbd)
Confirm enough free disk space (you need at least 2x the download size)
Don’t move files before post-processing finishes. Let the downloader finish its job first.

Sonarr or Radarr Cannot See Downloads

Double-check folder mappings, especially in Docker (this trips up everyone at least once)
Confirm completed download paths match Arr app settings exactly

High CPU Usage During Downloads

Normal during unpacking. That’s how PAR repair works.
Consider NZBGet if you’re running on older hardware
Schedule downloads for off-hours if it’s bothering you

Fractal Design Define 7 XL A quiet full-tower with room for a stack of drives, so a SABnzbd or NZBGet box stays tidy and has somewhere to grow. It isn’t required if you’re reusing hardware you already own.

Amazon Price: Loading...

Availability: Checking...

Contains affiliate links. I may earn a commission at no cost to you.

A good case won’t make either downloader faster, but it will keep the box quiet enough that you forget it’s running. That matters when SABnzbd or NZBGet are pulling files while you’re asleep.

FAQs: NZBGet vs SABnzbd 2026

➤ Which is faster, NZBGet or SABnzbd?

NZBGet is typically faster and more efficient due to its C++ architecture. The difference is most noticeable on low-powered hardware.

➤ I have a Raspberry Pi or NAS. What should I use?

NZBGet. It was built for low-resource systems, and you’ll notice the performance difference.

➤ Which is easier for beginners?

SABnzbd. The setup wizard, interface, and defaults are designed for novices. You’ll be downloading in minutes instead of hours.

➤ Can both integrate with Sonarr and Radarr?

Yes. SABnzbd tends to work out of the box, while NZBGet offers deeper customization options if you need them.

➤ Which one uses less power?

SABnzbd typically uses less background power thanks to iNotify-based file monitoring, though the difference varies by setup.

➤ Which one should I pick if I'm unsure?

Start with SABnzbd. You can always switch later if you outgrow it, but honestly? Most people never do.

Conclusion: SABnzbd vs NZBGet Winner

After going back and forth between these two for years, I always end up back on SABnzbd.

Yes, NZBGet is faster and lighter. But SABnzbd wins the sabnzbd vs nzbget debate where it matters most for beginners:

Easier setup
Better interface
Cleaner automation
More predictable updates

If you want something that works without babysitting, SABnzbd is the best choice for 2026.

If you’re running very limited hardware or love tweaking every detail, NZBGet still has a place. For everyone else? Start with SABnzbd and enjoy Usenet the way it was meant to work. Automatic, reliable, and quiet.

Resources

SABnzbd Official Documentation

NZBGet Official Documentation

Sonarr Integration Guide

Radarr Integration Guide

Amazon Fire TV Stick 4K Max Useful for streaming downloaded media to a TV, but not necessary for running SABnzbd/NZBGet or building the server itself.

Amazon Price: Loading...

Availability: Checking...

Contains affiliate links. I may earn a commission at no cost to you.

Usenet vs Torrenting (2026): Speed, Privacy & Cost Compared

Fri, 21 Mar 2025 06:52:48 -0600

If you’re building a home media server with Jellyfin, Kodi, Plex, Emby, or whatever your flavor, you quickly run into the same question everyone does:

How do I get the media?

For most people, the choice comes down to Usenet or torrenting. They both work, are popular and they both can be automated. But they feel very different once you live with them day to day.

I ran torrents for years. They worked, but between sketchy files, malware scares, dead downloads, and always needing a VPN, I eventually hit a point where I wanted something easier, even if it cost a few extra dollars a month.

This post breaks down the Usenet vs torrent comparison so you can pick the right system for your media server, without hype or gatekeeping. You’ll learn which system fits your priorities (speed, cost, privacy, or automation) and what trade-offs each one brings.

💭

TL;DR: If you want free and familiar, torrents still work. If you want speed, privacy, automation, and fewer headaches, Usenet usually wins for home media servers, even if it costs a bit each month.

Quick Comparison: Usenet vs Torrent

Factor	Torrents	Usenet
Cost	Free (VPN ~$5/mo)	~$10-15/mo total
Speed	Depends on seeders	Maxes your connection
Privacy	VPN required	SSL encrypted (No VPN needed)
Automation	Good with setup	Excellent
Old content	Depends on seeders	Up to 18 years or more retention
Setup complexity	Simple	Moderate

Usenet vs Torrenting: What Are You Really Choosing?

Before we compare pros and cons, let’s talk about what problem each system solves.

Torrents (P2P downloading)

Torrents use peer-to-peer sharing. When you download a file, you’re pulling pieces from other users (seeders) who already have it, while also uploading pieces you have to others. It’s a community effort, which sounds great until you realize that means you’re dependent on that community to share the content you want.

You usually need:

A torrent client like qBittorrent
A tracker (public or private)
A VPN if you care about privacy (unless you like getting nasty letters in the mail from your ISP)

Usenet (NZB-based downloading)

Usenet uses centralized servers run by providers. Files get uploaded once, then sit on those servers for years. When you download, you pull directly from the provider using an NZB file as a map. No peers. No sharing. A direct line to the content.

You usually need:

A Usenet provider (paid)
An indexer (to find content, usually paid)
A downloader like SABnzbd or NZBGet

Look, if this sounds more complex, it can be at first. But it also unlocks a lot of automation that makes your life way easier down the road.

If you want the deeper history? Check out these other posts:

History of Torrents
How P2P Changed the Way We Share Files

History of Usenet
And How It Powers NZB Media Downloads Today

Torrents: Pros, Cons, and Reality in 2026

Pros of Torrents

Free to use - No subscriptions needed (though you’ll want a VPN)
Huge content library - Almost anything popular has been torrented
Resumable downloads - Pick up where you left off, even days later
Simple starting point - Install client, click magnet link, done

Cons of Torrents

Here’s where it gets real.

Speed depends on seeders - Few seeders means slow or dead downloads. You’ll sit there watching a 4K movie crawl at 200KB/s because three people are seeding and two of them are on dial-up. Okay, maybe not dial-up, but it feels like it.
Privacy exposure - Your IP is visible to peers and trackers. Everyone can see you.
Higher legal risk - Copyright monitoring is easier with P2P. Those cease-and-desist letters? They come from torrent activity.
Dead torrents happen - If nobody seeds, the file is gone. I’ve spent hours hunting for a specific release only to find every torrent has zero seeders.
Sketchy files exist - Public torrents can include malware or junk. You wanted a movie, you got a .exe file. Do not run any executable files found in torrents.

NVIDIA SHIELD Pro
Acts as a robust Jellyfin/Plex client and server, making it easy to stream downloaded content to your TV.

Amazon Price: Loading...

Availability: Checking...

Contains affiliate links. I may earn a commission at no cost to you.

Usenet (NZB): Pros, Cons, and Why It Feels Different

Pros of Usenet

Very fast downloads - Direct from high-bandwidth servers. You can max out your gigabit connection, every single time. No waiting, no hoping someone seeds.
Better privacy by default - SSL encryption, no peer exposure. You’re not broadcasting to strangers.
Long retention - Top providers offer 18+ years of file storage. That obscure show from 2008? Still there.
Excellent automation - Pairs seamlessly with Sonarr, Radarr, and the rest of the *arr stack. Set it and forget it.
Consistency - If the NZB exists and your provider has it, it downloads. No “check back later, maybe someone will seed.”

Cons of Usenet

Nothing’s perfect.

It costs money - $7.50-20/month for unlimited plans. For some people, that’s a dealbreaker. I get it.
More pieces to set up - Provider + indexer + downloader. It’s not complicated, but it’s more than “install qBittorrent.”
DMCA takedowns happen - Content can be removed faster than torrents. Popular stuff gets hit within hours sometimes.
Retention is not infinite - Files age out after many years.
Sketchy files still exist - Although I have encountered less on Usenet, they do still exist. Do not run any executable files found in NZBs.

Privacy and Safety

Let’s talk about what actually protects you, because there’s a lot of misinformation out there.

Torrents and VPNs

If you torrent, a VPN is mandatory. But here’s what most guides skip: bind your torrent client to the VPN interface. This kills downloads the moment the VPN drops (a kill switch).

Without this, your real IP can leak during connection drops. And it will drop. VPNs aren’t perfect. I learned this the hard way when my ISP sent me a friendly letter about a download that happened during a very short VPN hiccup.

Five minutes setting up interface binding saves you from that.

Usenet Privacy Limits

Usenet feels more private because you’re not sharing with peers, and SSL encrypts the connection. But let’s be clear: providers still log your activity, and your payment method links to your identity.

SSL only protects data in transit, not metadata about what you downloaded. If someone really wants to know what you’re doing, they can find out. It’s way harder than with torrents, where your IP gets broadcast to every peer in the swarm.

NZB vs Torrent: Indexers and Trackers Explained

This is where many beginners get confused, so let me break it down.

Torrent Trackers

Trackers coordinate who has which pieces of a file. They’re like a phonebook for the swarm.

Public trackers are easy but unreliable. Anyone can use them, which means quality varies wildly.
Private trackers are reliable but invite-only. You’ll need to maintain a ratio (upload as much as you download) or get kicked.

Trackers don’t host files. They only help peers find each other. When a tracker goes down, your torrents stop working until it comes back.

Usenet Indexers

Indexers catalog Usenet posts and generate NZB files. Think of them as search engines for Usenet.

Good indexers show completion rates, file health, and categories
Some are free, some require invites, some cost money
You’ll want at least two indexers for coverage

Indexers make Usenet automation work, especially with Prowlarr (which manages all your indexers in one place). Without a good indexer, Usenet is useless.

LSI 9211-8iB IT MODE Useful for expanding storage with multiple drives in a DIY NAS or media server, but only needed if you plan to scale beyond a few disks.

Amazon Price: Loading...

Availability: Checking...

Contains affiliate links. I may earn a commission at no cost to you.

Decision Guide: Usenet vs Torrenting for Your Setup

Alright, so which one’s right for you?

Choose Torrents if:

You want zero monthly cost and don’t mind the VPN subscription
You’re comfortable using a VPN at all times (and binding it properly)
You mainly download popular, well-seeded content
You don’t mind occasional dead or slow downloads

Choose Usenet if:

You want fast, consistent downloads without the seeder lottery
You value privacy without mandatory VPN usage
You want full automation with media management tools
You’re okay paying a small monthly fee for the convenience

Budget reality check

If your budget is under $10 per month, here’s what I’d do:

Try Usenet free trials first. Most providers offer them. See if it works for you. If it feels too complex or limited, fall back to torrents + VPN. There’s no shame in that. Torrents still work. They’re more hands-on, that’s all.

Basic Setup Overview (High Level)

Let’s walk through what you’re signing up for with each system.

Torrent setup in practice

Install qBittorrent
Subscribe to a VPN and bind the client to VPN interface (seriously, do this)
Add trackers (public or private)
Optional: connect Sonarr (TV shows) and Radarr (movies) via Prowlarr

What success looks like: You click a magnet link, the download starts immediately, and your VPN shows as connected. If you disconnect the VPN, downloads pause automatically.

If downloads are slow, check seeders. If there are fewer than 10, expect problems. That’s how P2P works.

Usenet setup in practice

Choose a provider (trial first, don’t commit until you’ve tested)
Join one or two indexers
Install SABnzbd or NZBGet
Add provider details, enable SSL
Connect Sonarr and Radarr via Prowlarr

What success looks like: You add a show to Sonarr, and within minutes it’s downloading at full speed. No waiting. No checking seeders. Done.

If speeds are slow, check that you’re on an unlimited plan and using enough connections (20-60 depending on provider). Some providers throttle if you’re not using their recommended settings.

Hybrid Approach: Best of Both Worlds

Here’s what many experienced homelab users do:

Usenet as primary for new and popular media
Torrents as backup for rare or niche content

This gives you speed and automation without losing coverage. Sonarr and Radarr can search both simultaneously, grabbing from whichever source has the best release.

I’ve been running this setup for 10 years. Usenet handles 95% of my downloads, torrents catch the rest. It’s the best of both worlds, and honestly, once you’ve got it configured, you forget it’s even there.

Seagate Barracuda 24TB Internal Hard Drive Must have for this build. Why it fits this post: Large, reliable storage is essential for both torrent and Usenet media libraries, and this drive offers high capacity for bulk downloads and archiving.

Amazon Price: Loading...

Availability: Checking...

Contains affiliate links. I may earn a commission at no cost to you.

Troubleshooting Common Problems

You’re going to hit issues. Everyone does. Here’s how to fix the most common ones.

Problem	System	Solution
Downloads are slow	Torrents	Check seeders (need 5+), try different tracker, verify VPN isn’t throttling
Downloads never finish	Torrents	Dead torrent. Look for different release with active seeders
Downloads are slow	Usenet	Confirm unlimited plan, increase connections (20-60)
NZBs fail or missing blocks	Usenet	DMCA takedown. Try different indexer or provider
No results in Sonarr/Radarr	Both	Sync Prowlarr, check indexer categories, verify retention settings

FAQs: Usenet vs Torrent Questions

➤ What is the difference between NZB vs torrent files?

A torrent file points to peers sharing pieces of a file. An NZB file points to Usenet servers storing those pieces. Same end result, completely different infrastructure.

➤ Do I need a VPN with Usenet?

Usually no. SSL encryption is standard, and you’re not exposing your IP to a swarm. Some users still use a VPN for extra privacy, but it’s not required like torrenting.

➤ Are there free Usenet providers?

There are free tiers and trials, but they’re limited by speed, data, or retention. You’ll hit those limits fast if you’re using it. Think of free tiers as test drives, not long-term solutions.

➤ Why do torrents die, but Usenet files last years?

Torrents need active seeders. If everyone stops seeding, the file’s gone. Usenet’s files are stored on servers for a defined retention period, usually years. The file exists whether anyone’s downloading it or not.

➤ Which is better for old or rare content?

It depends. Usenet has long retention (18+ years on some providers), but private torrent trackers can sometimes win for ultra-niche content. If you’re looking for a specific fansub from 2005, you might need both.

Final Verdict: Usenet vs Torrenting

The Usenet vs torrenting debate really comes down to what you value.

Torrents are free, familiar, and still useful. But they come with trade-offs: slower speeds, privacy risks, dead files, and the constant need for a VPN.

Usenet costs money, but in return you get speed, privacy, automation, and reliability. For me, that trade was worth it. I stopped worrying about sketchy downloads and let my media server do its thing.

If you’re brand new, try both. Use trials. Break things. Learn what annoys you. Then make your decision.

That’s how you end up with a setup you enjoy using.

MINISFORUM MS-A2 Must have for this build. Why it fits this post: A powerful, flexible mini-server that can handle torrent/Usenet clients, indexers, and media server duties with ample I/O for future growth.

Amazon Price: Loading...

Availability: Checking...

Contains affiliate links. I may earn a commission at no cost to you.

The History and Usage of Torrents

Sat, 15 Mar 2025 07:29:33 -0600

Back in the early 2000s, the internet was changing fast, and new ways to share files were popping up everywhere. Traditional downloads had a real problem. Servers got hammered when too many people piled onto the same file at once. That’s where torrents came in. Instead of pulling a file from one source, torrents let users share pieces of a file with each other. The technology itself is 100% legal. People use it every day to distribute Linux ISOs, share public domain media, and move large files without melting a server.

If you’ve ever wondered how torrents actually work, how they’re used for media, and why everyone keeps telling you to run a VPN while downloading them, this post breaks it down.

What Are Torrents, and How Do They Work?

A torrent is a peer-to-peer (P2P) file-sharing method built on a decentralized network. Instead of downloading from a single server, you pull bits and pieces from other users who already have the file. A BitTorrent client coordinates the whole thing and makes sure everyone is sending and receiving pieces efficiently.

Here’s how the process works:

You grab a torrent file or magnet link. This contains the metadata about the content you want.
Your BitTorrent client connects to a tracker. The tracker is a server that helps coordinate connections between users.
You download file fragments from multiple sources. Instead of one server, your client pulls bits from users all over the world.
You upload pieces while you download. As you receive parts of the file, your client shares them back out. That’s what keeps the swarm fast.
The file is reassembled on your device. Once all pieces are in, your client stitches them together into the final file.

This is why torrenting is so fast for large files. Every downloader is also an uploader.

Before torrents took over, earlier P2P networks laid the groundwork for how digital media moves online. They were rough, but they shaped everything that came next.

1. Napster (1999 - 2001): The Beginning of P2P

Napster was the first major P2P file-sharing service to hit the mainstream. It let users share MP3 files directly with each other, and it kicked off the first large-scale digital music piracy fight. Napster’s centralized design made it easy to use. It also made it easy to shut down. In 2001, after a brutal legal battle with the Recording Industry Association of America (RIAA), Napster was forced offline. The idea of P2P file sharing, though, was already loose in the world.

2. Limewire & Kazaa (2001 - 2010): Decentralization and the Golden Age of P2P

After Napster fell, the next wave of P2P networks went decentralized, which made them harder to take down. Limewire and Kazaa stepped up and used the Gnutella and FastTrack networks to share files without a central server.

These programs let users share music, movies, software, and pretty much anything else. They also had real problems:

Malware & Viruses: Plenty of downloads came stuffed with spyware, adware, or outright malicious payloads.
Fake Files & Corrupt Downloads: No verification system meant a lot of files were mislabeled, broken, or both.
Legal Battles: Like Napster, Limewire and Kazaa eventually got sued into the ground.

Flaws and all, these services proved one thing. Decentralized file-sharing networks were the future.

3. How These P2P Networks Shaped Modern Torrents

The downfall of Napster, Limewire, and Kazaa made it obvious that centralized P2P was too easy to kill. That paved the way for BitTorrent, which fixed the old models by:

Using swarming. Instead of pulling from one source, BitTorrent splits files into small pieces and pulls them from many users at once. That speeds transfers up.
Killing the single-server dependency. Unlike Napster or Kazaa, torrents don’t lean on a central authority. That makes them much harder to take down.
Verifying file integrity. Torrents use hash checks on each piece, so corrupt or tampered chunks get caught instead of ending up in your final file.

Torrents are the evolution of early P2P. They fixed most of the old problems while keeping the core idea: distributed sharing.

How Are Torrents Used for Media?

Torrents have played a huge role in how media gets distributed online. Here are some of the most common legal and practical uses:

1. Distributing Open-Source Software

Plenty of open-source projects use torrents to ship their software. Linux distributions like Ubuntu and Debian offer torrents for their ISO files, which keeps the official mirrors from getting flattened on release day.

2. Archiving Public Domain Media

Groups like The Internet Archive use torrents to distribute huge libraries of public domain books, movies, and music. Torrents cut their bandwidth costs, which makes them a great fit for freely available media.

3. Gaming and Large File Transfers

Some game developers, especially in the early days of digital distribution, used torrents to push patches or entire game files. That kept central servers alive when thousands of players hammered them for updates at the same time.

4. Peer-to-Peer Streaming

A few platforms have experimented with torrent-based streaming, where users share video files as they watch. It reduces the load on a single hosting provider and spreads the cost across the swarm.

The Dark Side of Torrents: Piracy and Legal Issues

Torrents have plenty of legal uses. They’ve also been a piracy workhorse for two decades. Some of the most common illegal uses include:

Downloading pirated movies, TV shows, and music from sites like The Pirate Bay.
Sharing cracked software and video games that bypass DRM protections.
Distributing leaked content and pre-release media without authorization.
Spreading malware and scams by disguising harmful files as legitimate downloads.

Legal Consequences of Illegal Torrenting

Many countries have strict anti-piracy laws, and ISPs do monitor torrent traffic. If you get caught downloading copyrighted material, you could face:

Fines.
ISP warnings and throttling.
Lawsuits from copyright holders.

The best way to stay out of trouble is to use torrents for legal purposes and pull from trusted sources.

Why You Might Need a VPN When Downloading Torrents

Even if you’re only grabbing legal stuff, your ISP probably isn’t thrilled to see torrent traffic on their network. Here’s why a VPN is worth the few bucks a month:

Privacy. A VPN hides your IP address from other users in the swarm.
No ISP throttling. Some ISPs slow torrent traffic to a crawl. A VPN gets you around that.
Bypass geo-restrictions. Some countries block torrent sites outright. A VPN lets you reach them.
Anonymity on public trackers. Public torrents expose your IP to thousands of strangers. A VPN cuts that risk way down.

Final Thoughts

Torrents changed how big files move around the internet. They’re fast, efficient, and don’t fall over when one server goes down. Early P2P networks like Napster and Limewire introduced the world to decentralized sharing. Torrents took the idea and made it faster, safer, and tougher to kill.

The technology is legal. What you download is the part that matters. Stick to legal uses, and run a VPN to keep your traffic and IP private.

The Rise, Fall, and Rebirth of Usenet

Tue, 11 Mar 2025 07:57:16 -0600

Before Google, social media, or even the World Wide Web, Usenet was the backbone of online communication. It started as a way for researchers and tech enthusiasts to swap information, then grew into a sprawling, decentralized network for discussions, debates, and file sharing. It’s not the household name it used to be. But it’s still alive, and it’s still one of the best ways to pull down media using NZB files.

What Is Usenet?

Usenet was built in 1979 as a decentralized system for passing messages between a network of servers. It wasn’t a web forum and it wasn’t email. Articles got copied across multiple servers so anyone could read them, and no single server owned the conversation.

In the early days it was all discussions. Think of it as Reddit before Reddit existed. Topics were organized into “newsgroups” covering everything from kernel debates to music and movies. You’d post a message, the servers would fan it out, and other users would reply.

The Evolution of Usenet: From Text to Binaries

By the 1990s, people figured out Usenet could do more than host conversations. It could move files too. That kicked off the “binary newsgroups,” where users started sharing images, software, and eventually full movies and TV shows.

Here’s the catch. Usenet wasn’t designed for file transfers. Files had to be chopped into small fragments and posted as separate articles. Miss one piece and the whole download was useless. The community came up with the NZB file format to fix that, and it’s what made Usenet downloads fast and reliable.

NZB Files: The Modern Usenet Experience

An NZB file works like a torrent file, but for Usenet. Instead of hunting down hundreds of file fragments by hand, the NZB points your Usenet client at every piece and tells it to grab them all and reassemble the file.

Here’s the flow:

Grab an NZB file from an indexer, a site that catalogs Usenet content.
Open the NZB in a Usenet client like SABnzbd, NZBGet, or Newsbin.
The client logs into your Usenet provider, pulls every part, and stitches the file back together.

This is fast. Often faster than torrents, because Usenet providers serve you directly at high speed. No seeding, no peers, no waiting for the swarm to wake up.

Do You Need a VPN for Usenet?

This is the question every new Usenet user asks. Short answer: it depends on what you care about and what your ISP is up to.

Torrents expose your IP to every other peer in the swarm. Usenet doesn’t. You connect straight to your provider’s servers, which means your activity isn’t visible to other users. Most providers also support SSL encryption, so your ISP can see you’re talking to a Usenet server but can’t see what you’re pulling down.

So why would you still bother with a VPN?

ISP Throttling - Some ISPs slow down sustained large downloads. A VPN hides what kind of traffic you’re moving and can keep your speeds intact.
Additional Privacy - SSL hides the contents of the connection, not the fact that you’re using Usenet. A VPN hides both.
Access to Restricted Content - Some countries block Usenet providers or indexers outright. A VPN lets you connect from somewhere they aren’t blocked.

For most people, an SSL-encrypted connection to a reputable provider is enough. If you want belt-and-suspenders privacy, layer a VPN on top.

Why Choose Usenet Over Torrents?

Usenet has a few real advantages over torrents:

Speed: Downloads come straight from high-speed servers, so you can saturate your connection.
Privacy: No peer-to-peer swarm, no IP address handed out to strangers.
Retention: Providers typically hold files for years, sometimes more than a decade. Old releases that died on torrents are often still sitting on Usenet.

Getting Started with Usenet

Here’s what you need to get going:

A Usenet Provider - Newshosting, Eweka, and UsenetServer all give you access to the newsgroups.
An NZB Indexer - NZBGeek, DrunkenSlug, and NZBPlanet are the usual suspects for finding NZBs.
A Usenet Client - SABnzbd, NZBGet, or Newsbin will download and manage the files.

Pair the client with Sonarr, Radarr, or Lidarr and the whole pipeline runs itself. The *arr app queries your indexers, hands the NZB to SABnzbd or NZBGet, and the file lands in your media library without you touching it.

Final Thoughts

Usenet doesn’t get the attention torrents or streaming services do. That’s fine. If you care about speed, retention, and not broadcasting your IP to strangers, it’s still the most efficient way to feed a media server. NZB files made the workflow approachable, and the *arr stack makes it automatic.

If you’ve never tried it, set up a provider, an indexer, and a client, and run one download end to end. You’ll see why people who use Usenet rarely go back.

Master the Basics Dockers Compose

Sat, 08 Mar 2025 05:34:38 -0800

So you’ve heard about Docker and the magic of containers, but the words “YAML” and “Compose file” sound like something out of a sci-fi movie? Don’t worry. You’re in the right place. If you’re new to Docker and wondering how to use a docker-compose.yml file to manage your containers, I’ve got you covered.

By the end of this guide, you’ll know what a Docker Compose file is, how to use it, and why it makes running multiple Docker containers easier.

What Is a Docker Compose File?

A Docker Compose file is a YAML file (usually named docker-compose.yml) that tells Docker how to run multiple containers together.

Think of it like a recipe. Instead of manually starting each container, setting its configurations, and linking them together one by one, you write it all down in this file. Docker does the rest.

Why Use Docker Compose?

Docker Compose makes container management sane. Here’s why you want it:

Easy multi-container setup – Instead of running a wall of docker run commands, you define everything in one file.
Portability – Share your docker-compose.yml and anyone can replicate your setup.
Easier management – Start, stop, or restart all your containers with a single command.
Environment variables – Configure your setup using a .env file.

I’ll break down my own docker-compose.yml down. First, a quick word on what’s actually happening under the hood.

What Is Orchestration?

Orchestration is a fancy word for automating how different parts of your system work together.

Think of it like a movie production. You’ve got a pile of moving parts that all have to land at the same time:

The director keeps everything on schedule.
The actors perform their roles based on the script.
The camera crew captures the right angles.
The editors put it all together in post-production.

If each person had to be hand-walked through every cue, it would be chaos. Instead, they follow a plan, and the whole thing runs without constant micromanagement.

Docker Compose works the same way. You define the services once, and Docker handles the rest.

YAML Formatting Rules (Read This or Nothing Will Work)

Before you crack open a docker-compose.yml, you need to understand YAML formatting. One stray space or tab will break the whole file. Unlike JSON or XML, YAML lives and dies on indentation.

YAML Rules You Must Follow

Use spaces, not tabs. Indentation must be done using spaces. Tabs are not allowed.
Consistent indentation. Use the same number of spaces per level (2 or 4 is standard).
Key-value pairs are separated by colons. Example: container_name: radarr.
Lists use dashes. Each item in a list starts with -.
Strings don’t need quotes (but sometimes they do). Strings are usually fine bare, but wrap them in double quotes "" if they contain special characters.
Boolean values (true, false) and numbers don’t need quotes. Write them as-is.

Example of Correct vs. Incorrect YAML Formatting

✅ Correct YAML

services:
 radarr:
 container_name: radarr
 restart: unless-stopped

❌ Incorrect YAML (Tabs used instead of spaces)

services:
 radarr: # ❌ Tabs used (invalid)
 container_name: radarr
 restart: unless-stopped

❌ Incorrect YAML (Inconsistent indentation)

services:
 radarr:
 container_name: radarr
 restart: unless-stopped  # ❌ Indentation is off (invalid)

Breaking Down a Docker Compose File

Here’s a real-world docker-compose.yml that runs Radarr, Sonarr, Prowlarr, and SABnzbd, the core tools for an automated media server. Follow this pattern and you can drop in other services without much fuss.

services:
 radarr:
 image: lscr.io/linuxserver/radarr:latest
 container_name: radarr
 env_file: .env
 ports:
 - "${RADARR_PORT}:7878"
 volumes:
 - ${CONFIG_PATH}/radarr:/config
 - ${DOWNLOADS_PATH}:/downloads
 - ${MEDIA_PATH}/Movies:/movies
 environment:
 - PUID=${PUID}
 - PGID=${PGID}
 - TZ=${TZ}
 restart: unless-stopped
 depends_on:
 - sabnzbd
 - prowlarr

 sonarr:
 image: lscr.io/linuxserver/sonarr:latest
 container_name: sonarr
 env_file: .env
 ports:
 - "${SONARR_PORT}:8989"
 volumes:
 - ${CONFIG_PATH}/sonarr:/config
 - ${DOWNLOADS_PATH}:/downloads
 - ${MEDIA_PATH}/TV:/tv
 environment:
 - PUID=${PUID}
 - PGID=${PGID}
 - TZ=${TZ}
 restart: unless-stopped
 depends_on:
 - sabnzbd
 - prowlarr

 prowlarr:
 image: lscr.io/linuxserver/prowlarr:latest
 container_name: prowlarr
 env_file: .env
 ports:
 - "${PROWLARR_PORT}:9696"
 volumes:
 - ${CONFIG_PATH}/prowlarr:/config
 environment:
 - PUID=${PUID}
 - PGID=${PGID}
 - TZ=${TZ}
 restart: unless-stopped

 sabnzbd:
 image: lscr.io/linuxserver/sabnzbd:latest
 container_name: sabnzbd
 env_file: .env
 ports:
 - "${SABNZBD_PORT}:8080"
 volumes:
 - ${CONFIG_PATH}/sabnzbd:/config
 - ${DOWNLOADS_PATH}:/downloads
 environment:
 - PUID=${PUID}
 - PGID=${PGID}
 - TZ=${TZ}
 restart: unless-stopped

Alright, let’s pick this apart.

1. Defining Services

The services: block lists every container you want to run. Each service is a separate Docker container.

radarr and sonarr are the service names.
Each service runs a specific Docker image (lscr.io/linuxserver/radarr, etc.).
container_name sets a custom name for the running container.

2. Environment Variables

Instead of hardcoding values, the Compose file pulls from an .env file. That means you can change a port or a path without touching the Compose file at all.

Example .env file:

RADARR_PORT=7878
SONARR_PORT=8989
PROWLARR_PORT=9696
SABNZBD_PORT=8080
CONFIG_PATH=/path/to/config
DOWNLOADS_PATH=/path/to/downloads
MEDIA_PATH=/path/to/media
PUID=1000
PGID=1001
TZ=America/Denver

Tweak the .env file and your whole stack picks up the change on the next docker compose up.

3. Port Mapping

Each container has ports mapped like this:

ports:
 - "${RADARR_PORT}:7878"

Port 7878 inside the container (where Radarr listens) is exposed on your host at ${RADARR_PORT} (set in the .env file).

4. Volume Mounts

Volumes persist data between container restarts. Skip them and you lose your settings every time the container cycles.

volumes:
 - ${CONFIG_PATH}/radarr:/config
 - ${DOWNLOADS_PATH}:/downloads
 - ${MEDIA_PATH}/Movies:/movies

5. Restart Policy

The restart: unless-stopped line tells Docker to restart the container automatically unless you manually stop it. Reboot the host, the stack comes back on its own.

6. Depends On

The depends_on keyword sets the startup order between containers. It guarantees one container starts before another, but it does NOT wait for the dependency to be fully ready. Only that the process has launched.

Confused about .env files? See my Master the Basics - Docker’s .env Files post for the full breakdown.

Running the Docker Compose File

Once your docker-compose.yml and .env files are ready, here’s the workflow:

1. Navigate to the folder containing your Compose file

cd /docker

2. Start your containers in the background

docker compose up -d

-d runs the containers in detached mode, so they keep humming along in the background instead of holding your terminal hostage.

3. Check running containers

docker ps

4. Stop the containers

docker compose down

This stops and removes the containers but keeps your data intact, because your volumes live on the host filesystem.

Wrapping It Up

You can now spin up a full multi-container stack with one command. That’s the whole point of Compose.

From here, dig into Docker networks, named volumes, and healthcheck: blocks. Those are the next layers worth learning. But the file you’ve got is enough to run a real media server today.

Drop the file in /docker, run docker compose up -d, and you’re off.

Master the Basics - Docker Env Files

Fri, 28 Feb 2025 07:00:25 -0700

💭

TL;DR: A .env file pulls every shared variable (PUID, PGID, TZ, ports, paths) out of your docker-compose.yml into one editable file. Change one value, restart the stack, and every Arr container picks it up.

Why You Need a `.env` File

Setting up a media server with Radarr, Sonarr, Prowlarr, and SABnzbd gets messy fast. If you’ve ever dug through your docker-compose.yml to change one setting across four services, you know the pain.

Hardcoding paths, user IDs, and timezone values across multiple containers makes updates a nightmare. Want to change your downloads directory? That’s at least four places you’ll need to edit. Move your media to a new drive? Worse.

That’s where the .env file comes in.

A .env file centralizes every shared variable into a single file. Update one value, restart the stack, and every container follows. Clean, modular, portable. I run this exact setup on my own Proxmox host with the LinuxServer.io Radarr, Sonarr, Prowlarr, and SABnzbd images, and the day I moved my media drive I edited two lines and was done.

Here’s how to create, wire up, and lock down a .env file for your Arr stack.

Step 1: Creating the `.env` File

Drop the .env file in the same directory as your docker-compose.yml. In previous posts the compose file lives in /docker, so that’s where this one goes too.

cd /docker
nano .env

The .env file is hidden. Any file starting with . won’t show up in a normal ls (use ls -a to see it).

Paste this in:

# User and Group ID (Prevents permission issues)
# Main user ID
PUID=1000
# Our media group:
PGID=1001

# Timezone (Ensures correct scheduling and logs)
TZ=America/Denver

# Define Ports (Ports for each container are defined here)
RADARR_PORT=7878
SONARR_PORT=8989
PROWLARR_PORT=9696
SABNZBD_PORT=8080

# Data Directories (Keeps storage paths centralized)
CONFIG_PATH=/docker
DOWNLOADS_PATH=/media/Downloads
MEDIA_PATH=/media

Breaking Down the Variables

PUID & PGID - Which user the container runs as. If you’ve ever had files created with the wrong ownership, this fixes it.
TZ - Time zone for logs and scheduled tasks (downloads, library scans).
*_PORT - The host port each container binds to. Change one number here instead of hunting through compose.
CONFIG_PATH - Where each app stores its settings. Keeping all configs in one parent folder makes backups and migrations trivial.
DOWNLOADS_PATH - Shared download directory for SABnzbd (and any other download client).
MEDIA_PATH - Where finished movies and TV shows live. Jellyfin, Plex, and Emby read from here.

One file, one place to edit. That’s the whole point.

Important Note

Make sure CONFIG_PATH exists and has the right permissions before you bring the stack up:

sudo mkdir /docker
sudo chown -R $USER:media /docker
sudo chmod -R 770 /docker

Step 2: Securing the `.env` File

This file holds configuration values and, if you extend it, API keys. Lock it down:

chmod 600 /docker/.env

Why This Is Important

chmod 600 means only the owner can read or write the file.
Stops accidental edits and blocks anyone else on the box from reading it. Important the day you add a real API key.

Step 3: Using the `.env` File in `docker-compose.yml`

Now wire docker-compose.yml to pull values from .env.

services:
 radarr:
 image: lscr.io/linuxserver/radarr
 container_name: radarr
 env_file: .env
 ports:
 - ${RADARR_PORT}:7878
 environment:
 - PUID=${PUID}
 - PGID=${PGID}
 - TZ=${TZ}
 volumes:
 - ${CONFIG_PATH}/radarr:/config
 - ${DOWNLOADS_PATH}:/downloads
 - ${MEDIA_PATH}/Movies:/movies
 restart: unless-stopped

 sonarr:
 image: lscr.io/linuxserver/sonarr
 container_name: sonarr
 env_file: .env
 ports:
 - ${SONARR_PORT}:8989
 environment:
 - PUID=${PUID}
 - PGID=${PGID}
 - TZ=${TZ}
 volumes:
 - ${CONFIG_PATH}/sonarr:/config
 - ${DOWNLOADS_PATH}:/downloads
 - ${MEDIA_PATH}/Shows:/tv
 restart: unless-stopped

 prowlarr:
 image: lscr.io/linuxserver/prowlarr
 container_name: prowlarr
 env_file: .env
 ports:
 - ${PROWLARR_PORT}:9696
 environment:
 - PUID=${PUID}
 - PGID=${PGID}
 - TZ=${TZ}
 volumes:
 - ${CONFIG_PATH}/prowlarr:/config
 restart: unless-stopped

 sabnzbd:
 image: lscr.io/linuxserver/sabnzbd
 container_name: sabnzbd
 env_file: .env
 ports:
 - ${SABNZBD_PORT}:8080
 environment:
 - PUID=${PUID}
 - PGID=${PGID}
 - TZ=${TZ}
 volumes:
 - ${CONFIG_PATH}/sabnzbd:/config
 - ${DOWNLOADS_PATH}:/downloads
 restart: unless-stopped

How This Works

env_file: .env loads every variable from .env into the container’s environment.
${CONFIG_PATH}, ${DOWNLOADS_PATH}, and ${MEDIA_PATH} replace the hardcoded paths at compose time.
Moving your media to a new drive? Update .env and docker compose up -d. Done.
${PUID} and ${PGID} swap the user and group the containers run as.
${TZ} changes the time zone everywhere at once.

Step 4: Testing and Validating Your Setup

Bring the stack up:

docker compose up -d

Check the logs to confirm the variables landed:

docker logs radarr

You should see the right paths and time zone in the startup output.

You can also exec into the container and read the env directly:

docker exec -it radarr env | grep CONFIG_PATH

You should see:

CONFIG_PATH=/docker

If that matches what’s in your .env, you’re good.

Step 5: Why This Matters in the Long Run

1. Easy Updates

Moving media to a new drive? Edit .env, restart the stack, every container follows.
Changing the time zone? One edit, not five.

2. Portability

New server? Copy docker-compose.yml and .env over and the stack is wired up.

3. Clean and Readable Configs

No more massive docker-compose.yml files stuffed with hardcoded paths.

4. Security and Best Practices

API keys and passwords stay out of docker-compose.yml, where they’re more likely to end up in a git push you regret.

Taking It Further: Advanced `.env` Use Cases

Want more out of .env? A couple of patterns worth knowing.

Use `.env` for API Keys (Carefully)

For services like NZBHydra or a third-party indexer, drop the API key into .env:

NZBHYDRA_API_KEY=yourapikeyhere

Then reference it in docker-compose.yml:

environment:
 - API_KEY=${NZBHYDRA_API_KEY}

Caution: never commit .env to GitHub or any public repo. Add it to .gitignore the moment you create it. While you’re there, add .env.* too so backup copies like .env.bak don’t sneak in.

One file. Easy updates. No headaches.

Wrapping Up

Once the stack is up, you can hit each container from your browser:

Sonarr: http://your-server-ip:8989
Radarr: http://your-server-ip:7878
Prowlarr: http://your-server-ip:9696
SABnzbd: http://your-server-ip:8080

Need your server’s IP? Run:

ip a | grep inet

A .env file is one of the highest-leverage habits in your Docker toolbox. It keeps your Arr stack modular, easy to manage, and portable.

Set it up now and stop hardcoding settings.

Frequently Asked Questions

➤ Where does Docker Compose look for the `.env` file?

Docker Compose loads .env from the same directory as the docker-compose.yml file you’re running. Run docker compose from /docker and it picks up /docker/.env automatically. If you keep your compose file elsewhere, pass --env-file /path/to/.env on the command line.

➤ Does `env_file: .env` do the same thing as variable substitution?

No. env_file: injects variables into the container’s runtime environment so the app inside sees them. ${VAR} substitution happens at compose parse time and rewrites the YAML before the container starts. Use substitution for ports and volume paths, and env_file for variables your app reads at runtime.

➤ How do I check which variables a running container actually received?

Run docker exec -it <container> env to dump every variable inside the container. Pipe it through grep to find a specific one, for example docker exec -it radarr env | grep TZ. If a variable is missing, the .env file wasn’t found or the key was misspelled in compose.

➤ Is it safe to put API keys in a `.env` file?

Safer than putting them in docker-compose.yml, but .env is still plain text on disk. Lock the file with chmod 600, add .env and .env.* to .gitignore, and never paste it into a screenshot or pastebin. For higher-stakes secrets, look at Docker secrets or a dedicated secrets manager.

Master the Basics - Understanding Linux Permissions

Fri, 28 Feb 2025 05:52:14 -0700

Ever tried to open a file on Linux and gotten hit with a “Permission Denied” error? It’s one of those moments that makes you feel like your computer is laughing at you. You’re not alone, and it’s not as bad as it looks. Linux permissions seem cryptic at first. Once you understand the basics, you’ll be using them like a pro.

Here’s how Linux permissions work, and how you fix who can read, write, or execute files on your system. By the end, you’ll know what “Permission Denied” actually means and how to make it go away.

What Are Linux Permissions?

Every file and directory on Linux carries a set of permissions that decide who can read, write, or execute it. That’s how the system keeps users out of each other’s stuff and out of yours. Permissions break into three categories:

Owner – The person who created the file.
Group – A set of users who share permissions for the file.
Others – Anyone else who has access to the system.

Run ls -l on a file and you’ll see something like this:

-rwxr-xr--

Looks like gibberish. It isn’t. Here’s the breakdown:

The first character (-) shows the file type (- for a regular file, d for a directory).
The next three characters (rwx) are the Owner’s permissions.
The next three (r-x) are for the Group.
The final three (r--) are for Others.

And here’s what those letters mean:

r – Read permission (view the file’s contents)
w – Write permission (modify the file)
x – Execute permission (run the file as a program)

How to Read Linux Permissions

Take this example:

-rwxr-xr--

Read it like this:

Owner has rwx, so they can read, write, and execute the file.
Group has r-x, so they can read and execute, but not modify it.
Others have r--, so they can only read the file.

Want to see this in action? Run this in your terminal:

ls -l /

You’ll see permissions, owner, group, and other file details for everything in the root directory. It’s a quick way to check who can do what.

Changing Permissions with `chmod`

To change permissions, use the chmod (change mode) command. Two ways to do it: Symbolic and Numeric.

Symbolic Method

The symbolic method uses letters. Syntax:

chmod [who][operation][permissions] filename

who: u (user/owner), g (group), o (others), a (all)
operation: + (add), - (remove), = (set exactly)
permissions: r, w, x

Example:

chmod u+x filename

That gives the owner execute permission.

You can stack changes:

chmod u+x,g-w filename

This lets the owner execute the file while stripping write from the group.

Numeric Method

The numeric method uses three digits, one each for Owner, Group, and Others. Each permission has a value:

r = 4
w = 2
x = 1

Add them up to get the digit you want:

7 (4+2+1) = Read, Write, Execute
6 (4+2) = Read, Write
5 (4+1) = Read, Execute
4 = Read only

Example:

chmod 755 filename

Breaks down as:

7 (Owner: rwx)
5 (Group: r-x)
5 (Others: r-x)

Owner reads, writes, and executes. Group and others can read and execute. That’s it.

Changing File Ownership with `chown`

You can also change who owns a file using the chown command:

chown newowner filename

Or change both owner and group at once:

chown newowner:newgroup filename

Need to apply it to a whole directory tree? Use the -R option:

chown -R newowner:newgroup directoryname

Practical Examples

Let’s put this into practice. Say you have a script called backup.sh, and you want to:

Make it executable for yourself,
Allow your group to read it but not modify or run it,
Keep everyone else out entirely.

Here’s how:

chmod u+x,g=r,o= backup.sh

Or with the numeric method:

chmod 750 backup.sh

Check the result:

ls -l backup.sh

You should see:

-rwxr-x---

That confirms:

Owner can read, write, and execute.
Group can read, but not write or execute.
Others have no access.

Why Understanding Permissions Matters

Learning Linux permissions isn’t about avoiding “Permission Denied” errors. It’s about controlling who can touch sensitive files, keeping the system from getting wrecked by accident, and holding the line on security.

Linux puts you in control. That comes with a cost. Misconfigured permissions lead to security holes or system failures, so it’s worth the time to learn how they work.

Why Using 777 Permissions is a Bad Idea

If you’ve spent any time searching for fixes to permission errors, you’ve probably seen the advice to “use 777.” On the surface, it sounds like a magic bullet. After all, it gives everyone full access to read, write, and execute. Problem solved, right? Not quite.

Setting permissions to 777 is the equivalent of leaving your front door wide open with a neon sign that says, “Come on in, take whatever you want.” It grants read, write, and execute to everyone. Owner, Group, Others, all of them. Any user on the system can do anything they want with that file or directory. Modify it. Delete it. Run a malicious script from it. That’s a security nightmare waiting to happen.

Picture this. You have a web server running a site, and you set one of the directories to 777 because it “fixes” a permission error. Congratulations. You’ve handed every user, including anonymous visitors, permission to upload and execute any file they want. Hackers love that, because it makes compromising your system trivial.

It’s also risky from a stability angle. If anyone, even by accident, modifies or deletes a critical file, applications crash or the whole system falls over. You’ll be left scratching your head, wondering what went wrong.

So what should you do instead? Follow the principle of least privilege. Grant only the permissions a file or directory needs. Unsure? Stop and think about who needs access and what they need to do. Web server reading files but not modifying them? Use 755. Directory where a specific group writes files? Try 775.

The bottom line: avoid 777 unless you’re in a throwaway test environment and understand the risks. In production, it’s an invitation for trouble. Set permissions properly, and you’ll save yourself a lot of headaches and maybe a few sleepless nights.

Final Thoughts

Mastering Linux permissions is one of the first real steps toward being comfortable on the command line. It feels overwhelming at first. Stick with it, and it clicks fast.

Next time you see -rw-r--r--, you’ll know what it means and how to change it.

Ready to try it? Open your terminal and take control of your files.

Linux Basics for Hackers, 2nd Edition: Getting Started with Networking, Scripting, and Security in Kali

This is the book I used to learn Linux basics. I read the first edition, and this is the 2025 revision

Amazon Price: Loading...

Availability: Checking...

Contains affiliate links. I may earn a commission at no cost to you.

Sonarr Docker Compose Setup Guide (2026)

Tue, 18 Feb 2025 06:24:50 -0700

💡

Tip: Default port: Sonarr runs on port 8989. Access the web UI at http://your-server-ip:8989 once the container is running.

If you’re anything like me and love watching a few good TV shows, keeping up with new episodes is a headache. The streaming landscape is chaotic. One week your favorite show is on Netflix, the next it’s pulled for an exclusive run on yet another platform. Tracking what’s available where, remembering release dates, and manually grabbing episodes turns into more work than the shows are worth.

That’s where Sonarr comes in. Instead of hopping between streaming platforms or hunting for downloads, Sonarr automates the whole pipeline. It watches your shows, spots new episodes the moment they’re available, and pulls them via your preferred method (torrent or Usenet). Once a file lands, Sonarr renames it, files it into your library, and makes it ready to watch on Jellyfin, Plex, or Kodi. Your shows come to you.

Why Sonarr Earns Its Spot in the Stack

Here’s what Sonarr actually does for you:

Automation. No more manually searching for torrents or NZB files. Sonarr does it for you.
Download client integration. Works with qBittorrent, Deluge, SABnzbd, and NZBGet out of the box.
Library organization. Renames and sorts downloaded episodes into clean folder structures your media server can read.
Quality control. Want 4K for some shows and 1080p for others? Set the rules per show. Sonarr will even upgrade a file later if a better version shows up.
Missing episode search. If an episode isn’t out yet, Sonarr keeps looking until it finds a valid source.

You stop juggling websites and tools. Sonarr turns your TV collection into a hands-off pipeline.

Why Run Sonarr in Docker?

You could install Sonarr directly on the host. But running it in Docker pays off:

Isolation. Sonarr and its dependencies live in their own container, separate from the host OS.
Easy updates. docker compose pull and you’re on the latest build.
Portability. Move the whole setup to a new machine by copying the compose file and the config volume.
No dependency hell. No conflicting mono versions or library mismatches to chase.

If you want to take control of your TV library, Sonarr in Docker is the way to go.

Step 1: Install Docker

You need Docker first. If you don’t already have it, follow this guide: Master the Basics - How to Install Docker

Step 2: Create the Sonarr Docker Compose File

Now set up a docker-compose.yml file to define the Sonarr container.

Pick a Folder

Decide where you want to keep Sonarr’s compose file. I use a root folder named docker:

sudo mkdir -p /docker && cd /docker

Create the `docker-compose.yml` File

Open it in your favorite editor:

nano /docker/docker-compose.yml

Paste this in:

services:
 #################################
 # SONARR
 #################################
 sonarr:
 # Official LinuxServer.io Sonarr image
 image: lscr.io/linuxserver/sonarr:latest
 # Friendly name for the container
 container_name: sonarr
 # Pulls PUID, PGID, UMASK, TZ, ports, and paths from the .env file
 env_file: .env
 ports:
 # Maps the host port to Sonarr's web UI (8989) inside the container
 - ${SONARR_PORT}:8989
 volumes:
 # Sonarr's config and database (persists across restarts)
 - ${CONFIG_PATH}/sonarr:/config
 # Your TV library
 - ${MEDIA_PATH}/Shows:/tv
 # Shared download folder (must be the same path in every Arr container)
 - ${DOWNLOADS_PATH}:/downloads
 healthcheck:
 # Lets `docker ps` show "healthy" once the UI starts answering
 test: wget --no-verbose --tries=1 --spider http://localhost:8989/ping || exit 1
 start_period: 30s
 timeout: 3s
 interval: 30s
 retries: 3
 networks:
 # Joins the shared media network
 - media_network
 # Restart automatically unless you stop it yourself
 restart: unless-stopped

#################################
# NETWORK
#################################
networks:
 media_network:
 # Shared network, created once with: docker network create media_network
 name: media_network
 external: true

Step 3: Customize the .env File

Open the .env File

nano /docker/.env

The content should look like this:

# User and Group ID (Prevents permission issues)
# Main user ID
PUID=1000
# Main group ID:
PGID=1001
# File permission mask
UMASK=0007

# Timezone (Ensures correct scheduling and logs)
TZ=America/Denver

# Define Ports (Ports for each container are defined here)
RADARR_PORT=7878
SONARR_PORT=8989
SABNZBD_PORT=8080
PROWLARR_PORT=9696
BAZARR_PORT=6767

# Data Directories (Keeps storage paths centralized)
CONFIG_PATH=/docker
DOWNLOADS_PATH=/downloads
MEDIA_PATH=/media/Storage

Update the paths to match your setup. Here’s what each one does:

CONFIG_PATH=/docker is the root folder where Docker stores persistent files.
MEDIA_PATH=/media/Storage is the root folder for your media files.
DOWNLOADS_PATH=/downloads is the root folder where your download client drops temp and incomplete files.

Make sure the download client container shares access to the /downloads path. If it doesn’t, Sonarr can’t see the finished files and the whole pipeline breaks at the import step.

Also set the timezone (TZ) to match yours. Pull the right string from this list of valid timezones.

💡 Pro Tip: Your download client (qBittorrent, SABnzbd, whatever) needs the same /downloads mount Sonarr uses. Same path, same UID/GID. Skip this and Sonarr will see a “download not found” error every time.

Step 4: Start Sonarr

The Compose file attaches to an external network called media_network, so create it once before you bring the stack up:

docker network create media_network

With everything in place, fire up the container:

docker compose up -d

The -d flag runs the container in the background (detached mode).
Sonarr should now be running.

Verify it:

docker ps

You should see sonarr in the list of running containers:

CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
e49175ef37c5 lscr.io/linuxserver/sonarr:latest "/init" 23 seconds ago Up 22 seconds (healthy) 0.0.0.0:8989->8989/tcp, :::8989->8989/tcp sonarr

Step 5: Ensure Permissions Are Set Correctly

Folder permissions are the single most common reason the Arr suite blows up inside Docker. Save yourself the pain. Fix the permissions on your docker and media folders before you touch the UI:

sudo chown -R `yourusername`:media /docker/ && sudo chmod -R 770 /docker/
sudo chown -R `yourusername`:media /media/ && sudo chmod -R 770 /media/

For more on Linux permissions, read this: Master the Basics - Linux Permissions

Step 6: Access and Configure Sonarr

Open a browser and go to:

http://your-server-ip:8989

From here you’ll wire Sonarr up to your download client and your indexers, and point it at your TV library folder. For the full configuration walkthrough, the official Sonarr Wiki is the source of truth.

Step 7: Keeping Sonarr Updated

One of Docker’s biggest wins is painless updates:

docker compose pull # Fetches the latest image
docker compose down # Stops and removes the running container
docker compose up -d # Starts a fresh container with the new image

Run that every month or so. You’ll stay on top of features and security patches without ever opening Sonarr’s UI.

Conclusion

Sonarr handles the boring parts of running a TV library. It watches, downloads, renames, and files episodes so you don’t have to. In Docker, you get all that without polluting the host OS, and updating it is three commands.

Next, point Sonarr at an indexer (NZBGeek, Drunkenslug, or your tracker of choice) and a download client. Once shows start flowing in, add Radarr for movies and Lidarr for music. Same compose file, same .env, same network. That’s how the Arr stack snowballs into a full media automation rig. If you’d rather build the whole thing at once, follow the complete arr stack Docker Compose guide.

Running the whole Arr suite? Stand up Prowlarr, Radarr, Sonarr, and Bazarr from one Docker Compose file, with a fast download drive and clean imports into your media pool.

Master The Basics - Linux File Folders - What They Do and Why They Matter

Sun, 16 Feb 2025 07:15:05 -0700

💭

TL;DR: Linux puts everything under a single root (/) tree, and each top-level folder has a job. Learn the ten that matter and you can troubleshoot, manage, and break things on purpose with a lot more confidence.

New to Linux? The file system can look like a wall of cryptic two-letter folders the first time you ls /. Windows hands you drive letters (C:, D:, E:). Linux hands you one tree. Everything, and I mean everything, lives somewhere under the root (/) directory, including your USB stick, your CPU info, and the password file.

Every folder under / has a job. Once you know what each one is for, troubleshooting stops feeling like guesswork. I’ve poked through these directories on Debian 12 and Ubuntu 22.04 servers for years, so here’s the tour I wish someone had given me on day one. Ten directories. What they do, what’s inside, and why you should care.

1. `/` - The Root Directory

What it does:

The root directory (/) is the top of the Linux file tree. Every file, folder, and mounted device hangs off of it somewhere.
It’s the base that holds every other directory.

Why it matters:

Windows scatters programs and data across drives. Linux puts the whole system under /.
The installer builds this layout for you. You don’t create it by hand.
Delete or corrupt the wrong thing inside / and your system stops booting. Be careful up here.

2. `/home` - User Home Directories

What it does:

/home holds a personal directory for every user account on the system.
If your username is john, your stuff lives in /home/john/.

What’s inside:

Personal files: Documents, downloads, pictures, music, videos.
Configuration files: Hidden “dotfiles” like .bashrc or .profile that hold per-user settings.
User-specific app data: Folders like ~/.config/ and ~/.local/share/.

Why it matters:

Windows hides user data in C:\Users\. Linux keeps it clean inside /home.
Put /home on its own partition and you can wipe and reinstall the OS without losing your files. Worth doing on any serious build.

3. `/root` - The Root User’s Home Directory

What it does:

/root is the home directory for the root user, the superuser who can do anything.
It sits separate from regular accounts (/home/username/).

What’s inside:

Root’s personal config files and dotfiles.
Admin scripts and commands that only root should run.

Why it matters:

Regular users can’t read or write /root. That’s the point. It keeps daily-driver accounts away from things that can hose the system.
If you ever log in as root (don’t, use sudo), this is your home.

4. `/etc` - System Configuration Files

What it does:

/etc holds the system-wide configuration files that tell Linux and its services how to behave.
Almost every service you install drops a config here.

What’s inside:

Network settings: /etc/network/interfaces or /etc/netplan/ for network config, /etc/hosts for local hostnames.
User accounts: /etc/passwd for accounts, /etc/shadow for password hashes.
Service configs: /etc/ssh/sshd_config, /etc/fstab for mounts, firewall rules, web server configs, the lot.

Why it matters:

If a service is misbehaving, the answer is almost always in /etc.
Edit the wrong line in the wrong file and you can lock yourself out or refuse to boot. Back up the file before you touch it: sudo cp /etc/ssh/sshd_config /etc/ssh/sshd_config.bak.

5. `/bin` and `/sbin` - Essential System Programs

What they do:

/bin (binaries) and /sbin (system binaries) hold the core programs that make Linux usable.
Heads up: on modern Debian, Ubuntu, and most distros, /bin and /sbin are symlinks to /usr/bin and /usr/sbin. Same files, different paths. Run ls -l /bin and you’ll see the link.

What’s inside /bin:

Basic commands every user needs:
- ls (list files)
- cp (copy files)
- rm (remove files)
- cat (view file contents)

What’s inside /sbin:

Admin commands, usually root-only:
- shutdown (turn off the system)
- fdisk (partition disks)
- iptables / nft (firewall rules)

Why they matter:

These are the tools the system itself needs to boot and recover.
Lose /bin and you can’t run ls. You’re in single-user-mode-with-a-rescue-USB territory.

6. `/var` - Variable Data (Logs, Caches, Databases)

What it does:

/var holds files that change all the time: logs, caches, mail queues, package data, database files.

What’s inside:

Logs: /var/log/ holds syslog, auth.log, journal/, service-specific logs.
Web roots: /var/www/ is the default home for Nginx and Apache sites.
Spools: /var/spool/ holds print queues and mail.
Package data: /var/lib/ and /var/cache/apt/ hold dpkg and apt state.

Why it matters:

Server acting weird? Start in /var/log/. The answer is almost always in there. Run sudo journalctl -xe or sudo tail -f /var/log/syslog and read.
Fill /var and things break in ugly ways. Runaway logs can crash databases, web servers, and mail. Watch df -h /var on any box that’s been up a while.

7. `/usr` - User-installed Programs and Libraries

What it does:

/usr holds the bulk of installed software, the libraries those programs need, and shared system data.

What’s inside:

/usr/bin/: Most of the commands you actually use day-to-day (nano, git, vim).
/usr/sbin/: Non-essential admin tools.
/usr/lib/: Shared libraries the binaries depend on.
/usr/local/: Software you install by hand outside the package manager. Anything you compile from source usually lands in /usr/local/bin/.

Why it matters:

Installed a tool from source and can’t find it? Try /usr/local/bin/.
The split between /bin and /usr/bin was historical. With usrmerge, the distinction is mostly cosmetic on modern systems.

8. `/tmp` - Temporary Files

What it does:

/tmp holds scratch files that the system wipes on reboot. Some distros also wipe files older than 10 days via systemd-tmpfiles.

What’s inside:

Whatever apps and users decide to drop there: download fragments, session data, sockets, scratch files.

Why it matters:

Great for one-off testing, scratch tarballs, anything you don’t care about.
Don’t put real files here. They will disappear. I have watched more than one person lose a script they “saved real quick” to /tmp.

9. `/mnt` and `/media` - Mount Points for External Drives

What they do:

Both directories are mount points for drives that aren’t part of the root filesystem: USB sticks, extra hard drives, NFS shares, ISOs.

What’s inside:

/mnt/: Generic spot for manual mounts. Make a subfolder and mount whatever you want there.
/media/: Where desktop environments auto-mount removable drives (e.g., /media/yourusername/USB_NAME).

Why they matter:

On a server with no desktop, almost everything you mount lands in /mnt/ because you put it there.
Plug in a USB drive and nothing shows up in /media/? You’re on a headless box. Mount it by hand.

Example:

sudo mkdir -p /mnt/usb
sudo mount /dev/sdc1 /mnt/usb

Use lsblk first to find the right device name. Don’t guess.

10. `/dev`, `/proc`, and `/sys` - System and Hardware Information

These three are virtual filesystems. Nothing in them lives on disk. The kernel builds them on the fly.

`/dev/` - Device Files

Files that represent hardware:
- /dev/sda, /dev/sdb, etc. for SATA and USB disks
- /dev/nvme0n1 for NVMe drives
- /dev/tty* for terminals
- /dev/null and /dev/zero for the classic Unix tricks

`/proc/` - Process and Kernel Information

Live system info, regenerated by the kernel:
- /proc/cpuinfo for CPU details
- /proc/meminfo for RAM usage
- /proc/<pid>/ for everything about a running process

`/sys/` - Kernel and Hardware Settings

A structured view of devices, drivers, and kernel knobs you can read and sometimes write to.

Why they matter:

Need CPU info without installing anything? cat /proc/cpuinfo.
Looking for the right disk to format? lsblk reads from /sys and tells you exactly what’s there.
/dev/ is how you talk to hardware. Mount commands, dd, fdisk, every one of them points at /dev/ paths.

Wrapping Up

The Linux file system looks like alphabet soup until you understand what each folder is for. Then it stops being scary. You’ll know that logs live in /var/log, configs live in /etc, your stuff lives in /home, and the kernel exposes hardware through /dev, /proc, and /sys.

Best way to lock it in? Go look. Open a terminal and poke around:

ls /
ls /etc
ls /usr/bin
ls -l /bin
cat /proc/cpuinfo | head -20

Read what’s there. The Linux file hierarchy isn’t a mystery once you’ve seen it. It’s a map, and now you’ve got the legend.

Master the Basics - How to Install Docker in Linux

Thu, 13 Feb 2025 07:02:47 -0700

What Is Docker and Why Should You Use It?

Docker is a containerization platform that lets you run applications inside isolated environments called containers. Each container packages an app with all its dependencies, so it stays lightweight, portable, and easy to manage.

Why Use Docker?

Simpler deployments. Instead of installing software directly on your server and fighting dependency conflicts, Docker bundles everything into a self-contained unit. It runs the same way on every system.

Lighter on resources. Docker containers share the host OS kernel, so they’re far cheaper on memory and CPU than a stack of full virtual machines. You can comfortably run dozens of containers on a single box.

Easier software management. Want Jellyfin, Sonarr, Radarr, or Home Assistant? You pull an image, run a container, and you’re done. No hand-compiling, no dependency hell.

Isolation by default. Containers don’t see each other. If one crashes or gets compromised, the rest of the system keeps running.

Updates and rollbacks are cheap. Pulling a newer image is one command. Rolling back to a known-good tag is one more.

Now that you know why Docker is worth running on your home server, let’s install it correctly with security in mind.

Intel NUC 12 Pro (NUC12WSHi5) Compact mini PC for lightweight servers, GPU Passthrough, Docker stacks, and VMs.

Amazon Price: Loading...

Availability: Checking...

Contains affiliate links. I may earn a commission at no cost to you.

1. Update Your System and Install Dependencies

Before installing Docker, update your system and pull in the prerequisites. This gives you a clean, stable base.

Run the following:

sudo apt update && sudo apt upgrade -y
sudo apt install -y ca-certificates curl gnupg

These commands:

Refresh the package list (apt update)
Upgrade installed packages (apt upgrade -y)
Install the dependencies you’ll need (if curl and gnupg aren’t already on the box)

2. Add Docker’s Official GPG Key and Repository

Ubuntu ships a Docker package in its default repositories, but you shouldn’t use it. Here’s why:

Outdated versions. Ubuntu’s repo lags behind Docker’s latest stable releases, so you miss features and security fixes.
Slower updates. Critical bug fixes and security patches land in Docker’s official repo first. Ubuntu’s version gets them later, if at all.
Missing features. The Ubuntu package can lack support for newer Docker functionality.

So, install from Docker’s official repository. Run the following commands.

Cheat Sheet - Cut & Paste Commands:

sudo install -m 0755 -d /etc/apt/keyrings

curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo tee /etc/apt/keyrings/docker.asc > /dev/null

sudo chmod a+r /etc/apt/keyrings/docker.asc

echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

sudo apt update

The Long and Detailed Explanation of the Commands:

sudo install -m 0755 -d /etc/apt/keyrings

Breaking It Down:

sudo runs the command with superuser (root) privileges.
install is a command that can copy files, set permissions, and create directories.
-m 0755 sets the directory permissions to 0755 (read and execute for everyone, write for the owner).
-d tells install to create a directory if it doesn’t already exist.
/etc/apt/keyrings is where the directory is created. This is where trusted GPG keys for package signing live.

Security Purpose:

Ensures only the owner (root) can modify the keyring directory.
Prevents unauthorized users from tampering with the trusted GPG keys used to verify software packages.
Ubuntu 24.04 and later recommend storing GPG keys in /etc/apt/keyrings/ instead of the older /etc/apt/trusted.gpg. It’s better security hygiene.

curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo tee /etc/apt/keyrings/docker.asc > /dev/null

Breaking The Three Parts of This Command Down:

1. `curl -fsSL https://download.docker.com/linux/ubuntu/gpg`

curl is a tool for downloading files from the internet.
-f fails silently if the URL is wrong, so you don’t end up saving an error page.
-s runs in silent mode (hides progress output).
-S shows errors when they occur, which makes troubleshooting easier.
-L follows redirects in case the URL points somewhere else.
https://download.docker.com/linux/ubuntu/gpg is the URL of Docker’s official GPG key.

What this does: downloads Docker’s GPG key, which is used to verify the authenticity of Docker packages.

2. `| sudo tee /etc/apt/keyrings/docker.asc`

| pipes the output of curl into the tee command.
sudo runs the command as root (needed to write to system directories).
tee /etc/apt/keyrings/docker.asc:
- tee writes the Docker GPG key into /etc/apt/keyrings/docker.asc.
- That file is later used to verify Docker packages are signed and authentic before installing.

3. `> /dev/null`

> redirects output somewhere else.
/dev/null is the Linux “trash” file that throws away anything written to it.

sudo chmod a+r /etc/apt/keyrings/docker.asc

Breaking It Down:

sudo runs the command with superuser (root) privileges.
chmod changes file permissions.
a stands for “all users” (owner, group, and others).
+r adds read permission so the file can be read by everyone.
/etc/apt/keyrings/docker.asc is the GPG key file used to verify Docker packages when installing or updating via apt.

What this does:

Lets the system use the key. When apt installs or updates Docker, it checks package signatures against this GPG key. Without read access, apt will fail to verify Docker’s authenticity and throw errors at you.

Prevents unauthorized modifications. The file is still protected (only root can modify it), but every user can now read it. System processes and normal users can verify packages, but they can’t tamper with the key.

Follows Ubuntu’s newer security guidelines. Older versions stored GPG keys in /etc/apt/trusted.gpg, which gave every key full system-wide trust. That’s loose. Newer Ubuntu releases put each key under /etc/apt/keyrings/, where it’s isolated and trusted only for its own repository.

echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

Breaking The Three Parts of This Command Down:

1. `echo "deb [...] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable"`

echo prints the text inside the quotes.
"deb [...] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" is a software repository entry in Debian/Ubuntu format.

What’s inside the `deb [...]` line?

deb tells apt this is a binary package repository, not source code.
[arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc]
- arch=$(dpkg --print-architecture) detects your system architecture (amd64, arm64, etc.) so you install the right build.
- signed-by=/etc/apt/keyrings/docker.asc uses Docker’s GPG key (the one you downloaded a minute ago) to verify package authenticity.
https://download.docker.com/linux/ubuntu is the URL of Docker’s official repository.
$(lsb_release -cs) inserts your Ubuntu codename (e.g., noble for 24.04) so you get the right release.
stable pulls the stable Docker channel instead of edge or testing builds.

2. `| sudo tee /etc/apt/sources.list.d/docker.list`

| pipes the echo output into tee, which writes it to a file.
sudo runs the command with root privileges, since /etc/apt/sources.list.d/ requires admin access.
tee /etc/apt/sources.list.d/docker.list saves the repository entry into /etc/apt/sources.list.d/docker.list.

3. `> /dev/null`

Throws away the output from tee so your terminal stays clean.

Update your apt repositories:

sudo apt update

3. Install Docker

Now install Docker. The following command also pulls in the dependencies:

sudo apt install -y docker-ce

Make sure Docker starts at boot:

sudo systemctl enable --now docker

Once installed and enabled, verify Docker is running:

sudo docker ps

If Docker is running, you should see this after running docker ps:

CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES

With nothing showing under those headers.

Security Step: Prevent Unauthorized Docker Access

By default, Docker runs as root. That’s a problem. Anyone in the docker group gets effective root on the host, so add a dedicated group and put your user in it deliberately:

sudo groupadd docker
sudo usermod -aG docker $USER
newgrp docker

After running these commands, you can run Docker without sudo:

docker run hello-world

4. Configure Docker for Better Security

A stock Docker install carries real risk. Let’s harden it.

Enable AppArmor

Ubuntu ships with AppArmor, a security module that restricts what Docker containers can do on the host.

Check whether it’s enabled:

sudo aa-status

If it isn’t, turn it on:

sudo systemctl enable --now apparmor

Stop Containers from Getting Root Privileges

By default, containers can run with elevated privileges. Restrict that with user namespaces.

Cheat Sheet - Cut & Paste These Commands:

sudo mkdir -p /etc/systemd/system/docker.service.d

echo -e "[Service]\nExecStart=\nExecStart=/usr/bin/dockerd --userns-remap=default" | sudo tee /etc/systemd/system/docker.service.d/override.conf

sudo systemctl daemon-reload

sudo systemctl restart docker

Breakdown of These Commands:

Create a configuration directory for Docker:

sudo mkdir -p /etc/systemd/system/docker.service.d

sudo runs the command as root (required for modifying system settings).
mkdir -p creates a directory if it doesn’t already exist (-p keeps it from erroring out if the directory’s already there).
/etc/systemd/system/docker.service.d is where custom systemd overrides for Docker live.

Why? This gives you a place to drop a custom configuration for the Docker service without editing the main service file.

Create an override file to enable user namespace remapping:

echo -e "[Service]\nExecStart=\nExecStart=/usr/bin/dockerd --userns-remap=default" | sudo tee /etc/systemd/system/docker.service.d/override.conf

echo -e "[Service]\nExecStart=\nExecStart=/usr/bin/dockerd --userns-remap=default":
- Builds a custom systemd service override for Docker.
- ExecStart= (empty) clears the previous ExecStart from the default Docker service.
- ExecStart=/usr/bin/dockerd --userns-remap=default replaces it with one that enables user namespace remapping.
| sudo tee /etc/systemd/system/docker.service.d/override.conf:
- Pipes the output (|) into tee, which writes it into the override file at /etc/systemd/system/docker.service.d/override.conf.
- sudo gives tee the root access it needs.

Why?

User namespace remapping (--userns-remap=default) makes Docker containers run as an unprivileged user on the host instead of root.
If a container is compromised, it doesn’t get full root on the host.

Reload systemd to apply the changes:

sudo systemctl daemon-reload

sudo runs as root.
systemctl daemon-reload reloads systemd so it picks up the new Docker service override.

Why? Without it, systemd never notices the new override.conf file.

Restart Docker to apply the new configuration:

sudo systemctl restart docker

sudo runs as root.
systemctl restart docker restarts Docker so it runs with the new --userns-remap=default setting.

Why?

Applies the security change without rebooting.
From now on, Docker containers run as an unprivileged user instead of root.

Wrapping Up

Docker is a powerful tool for running apps on your Ubuntu 24.04 server. An insecure setup will bite you. Follow this guide and you’ve got Docker installed correctly, with sensible security mitigations in place.

Want to push security further? Look at ufw for the firewall layer and fail2ban for blocking brute-force attempts on exposed services.

Next up: deploying Sonarr and Radarr on top of this Docker install.

Amazon Price: Loading...

Availability: Checking...

Contains affiliate links. I may earn a commission at no cost to you.

Master the Basics - How to Install and Use SnapRAID for a Resilient Home Media Server

Sat, 08 Feb 2025 07:26:32 -0700

Why You Need SnapRAID with MergerFS

You’ve spent years building the perfect media collection. Movies, TV shows, music, personal backups, all neatly spread across a stack of hard drives. Then one day you hear that clicking sound coming out of the server. Panic. Did you lose everything on that drive? Not if you planned ahead.

That’s where MergerFS and SnapRAID come in. MergerFS pools multiple drives into one logical storage location, and SnapRAID adds parity so you can recover from a drive failure. If you haven’t set up MergerFS yet, start with my Master the Basics - MergerFS post. Together they give you a cheap, flexible way to protect your data without the headaches of traditional RAID.

SnapRAID is a parity-based protection system. Unlike traditional RAID, it doesn’t constantly write to every disk. That makes it a good fit for media servers, where most of your data sits unchanged for months at a time.

I’ve been running this setup on my own Debian-based media server with a mix of mismatched drives, and it’s saved me from at least one dying disk. Here’s how to install and configure it.

What is SnapRAID Parity?

SnapRAID parity is the backbone of the whole thing. It works by creating a file containing mathematical parity data about the files on your data disks. If a drive dies, SnapRAID uses that parity file to reconstruct what was on it.

Think of parity as an insurance policy for your media collection. If one of your drives crashes, the parity file is the blueprint that lets SnapRAID rebuild the missing data using the remaining disks.

How SnapRAID Parity Works

Parity calculation: SnapRAID scans your data disks and calculates parity based on their contents. The result lives on a dedicated parity disk, separate from the data drives.
Parity updates: Parity does not refresh on its own. You run snapraid sync when you want it updated. I’ll cover automating that with cron later.
Drive recovery: When a data disk fails, SnapRAID uses the surviving data drives plus the parity disk to rebuild the lost files. More parity disks means more simultaneous failures you can survive.

Why SnapRAID Parity Matters

It protects against drive failures

Without parity, a dead drive means everything on that disk is gone. With parity, you can recover it.

It saves space compared to full backups

Parity stores difference-based data, not a full copy of every drive. One parity drive can protect several data drives. That’s a lot cheaper than mirroring everything.

It scales with your storage

You can mix and match different-sized disks. No need for identical drives like traditional RAID. Start with one parity drive and add more as your array grows.

You can run multiple parity drives

One parity drive recovers from one failed disk. Add more if you want more cushion:

1 parity drive → recovers from 1 failed disk
2 parity drives → recovers from 2 failed disks
3 parity drives → recovers from 3 failed disks

To add more parity drives, update /etc/snapraid.conf:

parity /mnt/disk4/snapraid.parity
parity /mnt/disk5/snapraid.parity2

Parity is the difference between losing a movie collection and shrugging off a dead drive. Set up at least one parity disk before you trust the array with anything you care about.

Not sure how many parity drives your array needs? Enter your drive sizes into the SnapRAID calculator and it generates the parity recommendation, the full snapraid.conf, and the matching MergerFS fstab line.

Open the calculator

What Is SnapRAID Content?

The SnapRAID content file (snapraid.content) stores metadata about your files: checksums, timestamps, and the layout information needed for recovery. The parity file rebuilds the actual data. The content file tells SnapRAID what your data looked like at the last sync.

Every snapraid sync updates the content file with new metadata. That’s how SnapRAID detects changes, catches corruption, and rebuilds lost files when you need it to.

Why Keep `snapraid.content` on Multiple Drives?

One copy is a single point of failure

If your only copy of snapraid.content lives on disk1 and disk1 dies, recovery fails. SnapRAID no longer has a record of your data layout, so it can’t rebuild anything. Put a copy on disk2 and disk3 and SnapRAID still has what it needs.

A single copy of the content file undercuts the resilience you installed SnapRAID for. Multiple copies are cheap insurance.

How to Store `snapraid.content` on Multiple Drives

In /etc/snapraid.conf, define multiple content locations:

content /mnt/disk1/snapraid.content
content /mnt/disk2/snapraid.content
content /mnt/disk3/snapraid.content

Each entry creates a duplicate of the content file on a different disk. SnapRAID updates all of them on every sync, so they stay identical.

Spread the content file across two or more drives and you’ve removed a real failure mode. If disaster hits, you still have a path back.

NOTE: You can use the same drives for both content and data.

What Is SnapRAID Data?

In SnapRAID, “data” means the actual files on your media server: movies, TV shows, music, backups. Those files live on data drives, which are the physical disks SnapRAID protects with parity.

Unlike traditional RAID, SnapRAID does not mirror or stripe data across disks. Each file exists in one location, and SnapRAID tracks which files live on which drive.

Why Data Drives Have to Be Defined in `snapraid.conf`

SnapRAID Needs to Know Where Your Files Live

SnapRAID uses parity calculations to recover lost files. If you don’t tell it which drives hold data, it can’t protect them and can’t restore anything.

In /etc/snapraid.conf, you define each data drive explicitly:

data d1 /mnt/disk1
data d2 /mnt/disk2
data d3 /mnt/disk3

Each data entry tells SnapRAID:

Which disks hold your files
Which disks need to be included in parity calculations
Where to look when checking for data integrity

It Lets SnapRAID Detect Changes and Fight Corruption

SnapRAID doesn’t track file changes on its own. You run snapraid sync to update parity.

With your data drives listed in snapraid.conf, SnapRAID knows:

Which files were added, modified, or deleted
When to update parity data
How to detect bit rot (silent file corruption)

Skip these entries and SnapRAID has no idea what files exist. It can’t protect what it doesn’t know about.

It Makes Recovery Possible

If a drive dies, SnapRAID uses parity to reconstruct the lost files. That only works when:

The missing drive was listed in snapraid.conf
A valid parity file exists
The remaining data disks are intact

Forget to list a drive in snapraid.conf and SnapRAID won’t protect it. If the drive fails, those files are gone for good because they were never included in parity calculations.

It Keeps Storage Expansion Painless

One of SnapRAID’s strengths is drive flexibility. Add a new data disk of any size at any time. Mount the new drive and add it to snapraid.conf:

data d4 /mnt/disk4

Run snapraid sync and the new disk is now under parity protection. No rebuild. No reformat. Add the drive.

Defining data drives in snapraid.conf is non-negotiable. Without these entries, SnapRAID doesn’t know what to protect, can’t detect changes, and can’t restore lost files.

If you care about keeping your media safe, list every data drive in snapraid.conf and run snapraid sync on a schedule.

Installing SnapRAID

On Debian or Ubuntu, installation is one command. SnapRAID lives in the official package repository:

sudo apt update && sudo apt install snapraid -y

To verify SnapRAID is installed, run:

snapraid status

You’ll see:

Self test...
No configuration file found at '/etc/snapraid.conf'

That’s expected. You haven’t written the config yet.

Configuring SnapRAID

Planning Your SnapRAID Setup

Before you touch the config, plan it out:

How many data disks? SnapRAID stores parity on a separate drive, so you need at least one data disk and one parity disk.
How much parity? One parity disk protects against one drive failure. Two parity disks protect against two. Pick based on how much pain a multi-drive failure would cause you.
Which drives hold parity and content? The parity disk needs to be at least as big as your largest data drive. Spread content files across several data drives so you don’t lose the recovery layout if one disk dies.

Creating the SnapRAID Configuration File

The main configuration file for SnapRAID is /etc/snapraid.conf. Open it in a text editor:

sudo nano /etc/snapraid.conf

A basic configuration for three data disks and one parity disk looks like this:

# Parity file - stored on the largest disk or a dedicated parity drive
parity /mnt/disk3/snapraid.parity

# Content files - store metadata; should be on multiple drives for redundancy
content /mnt/disk1/snapraid.content
content /mnt/disk2/snapraid.content

# Data drives - these contain actual files
data d1 /mnt/disk1
data d2 /mnt/disk2
data d3 /mnt/disk3

NOTE: Disk 1 and disk 2 are used for both content and data. That’s fine.

Key Points to Consider

Parity drive: Has to be as large as your biggest data drive, or larger.
Content files: Belong on multiple drives for redundancy.
Data drives: List every drive that holds files you want protected.

Additional SnapRAID Options

For better protection and logging, add:

# Define the block size used for parity calculations (default is 256K)
block_size 256

# Auto-save changes to the content file before syncing
autosave 300

# Enable scrub (data integrity check) with a limit on recovered errors
scrub_percent 10
scrub_recover 5

Save and exit the file (CTRL + X, then Y, then Enter).

Running SnapRAID for the First Time

Step 1: Perform an Initial Sync

The first time you run SnapRAID, it has to build the initial parity. Run:

sudo snapraid sync

This takes a long time. Hours on a small array, days on a big one. When it finishes, SnapRAID has recorded parity and you can actually recover from a failure.

Step 2: Verify Data Integrity

SnapRAID doesn’t detect changes on its own, so check it periodically:

sudo snapraid check

This compares stored parity against the actual files to catch corruption.

Step 3: Scrubbing for Bit Rot

Files can rot quietly over time. SnapRAID can scrub a slice of your data to catch and fix errors before they spread:

sudo snapraid scrub -p 10

-p 10 limits scrubbing to 10% of files, which keeps disk wear reasonable.
Run scrubs on a schedule so issues get caught early.

Step 4: Recovering a Lost Drive

If a drive fails, don’t panic. SnapRAID can rebuild it. Replace the dead drive with a new one and mount it in the same location. Then run:

sudo snapraid fix

SnapRAID reconstructs the missing data using the parity drive.

Automating SnapRAID Maintenance

Schedule syncs and scrubs so you don’t have to remember. Open the crontab:

crontab -e

Add:

0 3 * * * /usr/bin/snapraid sync
0 4 * * * /usr/bin/snapraid scrub -p 10

Sync runs daily at 3 AM to update parity.
Scrub runs at 4 AM to look for silent corruption.

Save and exit (CTRL + X, then Y, then Enter).

Why MergerFS and SnapRAID Make the Perfect Combo

Run MergerFS and SnapRAID together and you get:

Simple storage management. All your drives show up as one mount point.
Flexible disk usage. Mix and match drives of different sizes without rebuilding anything.
Data redundancy. SnapRAID protects against disk failures.
Low resource usage. No constant mirroring like traditional RAID.

This setup is built for media servers, where most data is read-heavy and rarely changes. When a drive fails, you replace it and run snapraid fix instead of restoring from a full backup.

Final Thoughts

Set up SnapRAID with MergerFS once and the next dead drive becomes a chore instead of a crisis. Your files stay organized, accessible, and protected, and you don’t have to buy matching drives to keep the array honest.

Now build the config, run that first sync, and stop relying on luck.

Master the Basics - MergerFS the Best Way to Combine Drives for Your Home Media Server

Sun, 02 Feb 2025 07:23:12 -0700

What if you could combine every mismatched drive in your server into one pool? If you’re like me, you buy hard drives whenever you find the best price per terabyte. Over time, that leaves you with a pile of different-sized disks and a storage layout that’s a mess. Media files end up scattered across drives, and tracking down where anything lives turns into a chore. That’s what MergerFS fixes.

MergerFS combines drives into a single mount point without RAID and without the risk of losing everything if one disk dies. It plays nicely with Sonarr, Radarr, and Jellyfin out of the box.

In this guide I’ll explain how MergerFS works, walk through the configuration I run, and show you how to install it on a Linux media server. By the end you’ll have one tidy storage pool that uses every gigabyte you bought.

Here’s the kind of mismatched mess MergerFS handles without complaint:

Seagate BarraCuda 8TB Internal Hard Drive
Western Digital 14TB Internal Hard Drive
Toshiba N300 12TB Internal Hard Drive

Any combination of capacities works. MergerFS doesn’t care if the sizes match. That’s the whole point.

Seagate Barracuda 24TB Internal Hard Drive

Amazon Price: Loading...

Availability: Checking...

Contains affiliate links. I may earn a commission at no cost to you.

When you’re ready to add a fresh disk to the pile, something like the 24TB Barracuda above slots in next to your existing mismatched drives. No reformatting, no array rebuild, no drama. Mount it, add it to the pool, done.

What is MergerFS and Why Do You Need It?

MergerFS is a union filesystem for Linux that combines multiple storage devices into a single mount point. Instead of juggling separate drives, you access everything from one unified path. Compared to RAID, MergerFS is:

Flexible - Add or remove drives anytime. No array rebuild.
Safe - If a drive dies, you only lose what was on that drive. The rest of the pool keeps working.
Simple - Works with standard filesystems like ext4, XFS, and Btrfs.
Transparent - Pull a drive out, plug it into any Linux box, and the files are still there as plain files on a regular filesystem.

How It Works

Think of MergerFS as a smart directory overlay. It doesn’t move files or create duplicates. It shows you a virtual filesystem where every drive looks like one.

For example, if you have:

/mnt/disk1/Movies/
/mnt/disk2/Movies/
/mnt/disk3/Movies/

MergerFS lets you access everything under:
/mnt/storage/Movies/

Apps like Jellyfin and Sonarr only need to look in one place. They don’t care which physical disk a file lives on.

How to Install MergerFS on Your Linux Server

MergerFS is in the package repos for most Linux distributions. Here’s how to install it on Debian-based systems (Ubuntu, Proxmox, etc.) and Arch Linux.

Install on Ubuntu/Debian

First, update your package list and install MergerFS:

sudo apt update && sudo apt install mergerfs -y

The version in your distro’s repo is sometimes a release or two behind. For most home media setups that’s fine. If you want the latest features, grab the .deb from the official MergerFS releases page.

Verify Installation

Once installed, check the version to confirm it’s working:

mergerfs -V

If you get a version string back, you’re good. If you get “command not found”, the package didn’t install. Check your repo configuration and try again.

Best MergerFS Configuration for a Home Media Server

Setting it up correctly is what makes the difference between a pool that quietly works and one that fights your media apps. Here’s the setup I run.

Step 1: Mount Your Drives

Before configuring MergerFS, your drives need to be mounted. List what’s connected with:

lsblk -o NAME,FSTYPE,MOUNTPOINT,SIZE

If your drives are /dev/sdb1 and /dev/sdc1, create mount points:

sudo mkdir -p /mnt/disk1 /mnt/disk2

Then mount them manually (replace ext4 with your actual filesystem type):

sudo mount -t ext4 /dev/sdb1 /mnt/disk1
sudo mount -t ext4 /dev/sdc1 /mnt/disk2

While you’re here, grab the UUIDs with sudo blkid and use those in /etc/fstab instead of /dev/sdX paths. Drive letters can shuffle around between reboots. UUIDs don’t.

Step 2: Create a MergerFS Pool

Make a directory for the pooled mount:

sudo mkdir -p /mnt/storage

Then mount the drives through MergerFS:

sudo mergerfs -o defaults,allow_other,use_ino,cache.files=off,dropcacheonclose=true,minfreespace=50G,category.create=mfs /mnt/disk* /mnt/storage

Understanding the Options

Here’s what each option does:

allow_other - Lets other users (Jellyfin, Sonarr, your Docker containers) access the files.
use_ino - Makes MergerFS report consistent inode numbers across the pool, which keeps hardlinks and rsync happy.
cache.files=off - Disables FUSE page caching. Better for large media files and avoids stale-cache surprises.
dropcacheonclose=true - Drops cached pages when a file handle closes. Pair this with cache.files=off.
category.create=mfs - New files land on the drive with the most free space.
minfreespace=50G - Stops writing to a disk once it has less than 50GB free. Leaves headroom for the filesystem.

Step 3: Make the MergerFS Mount Permanent

Edit /etc/fstab so the pool comes back on every boot:

sudo nano /etc/fstab

Add this line at the bottom (adjust paths as needed):

/mnt/disk* /media/Storage fuse.mergerfs direct_io,defaults,allow_other,noforget,dropcacheonclose=true,category.create=mfs,minfreespace=50G,fsname=storage 0 0

Save and exit (CTRL+X, then Y and ENTER).

Reload the fstab so the new entry takes effect:

sudo mount -a

Confirm it mounted with mount | grep mergerfs or df -h /media/Storage. If you see the pool listed and the size adds up to your combined drives, you’re done.

Optimizing MergerFS for Media Servers

Now that the pool is running, here’s how to tune it for media work.

Best `category.create` Policy

The category.create option controls where new files land.

mfs (Most Free Space) - Best for spreading files across drives evenly.
epmfs (Existing Path, Most Free Space) - Keeps related files together. Good if you want a whole TV show season on the same disk.
lus (Least Used Space) - Fills one drive before moving to the next. Useful if you want to spin down idle disks.

For most media servers, mfs is the right call. It balances usage and keeps any single drive from filling up first.

Handling Deleted Files

When you delete a file from the pool, MergerFS removes it from the drive that held it. If a deleted file looks like it’s still hanging around, drop the filesystem cache:

sync && echo 3 | sudo tee /proc/sys/vm/drop_caches

That clears the kernel’s page cache and forces the next directory listing to read fresh from disk.

Why MergerFS is Perfect for Home Media Servers

MergerFS is the right call for combining mismatched drives into one storage pool. It’s flexible, quick to set up, and plays nicely with Jellyfin, Sonarr, and Radarr.

Key Benefits:

Easy Setup - No RAID configuration. No array rebuild.
No Total Data Loss - Each drive is a regular filesystem. Lose one and you only lose what was on it.
Flexible Expansion - Add or pull drives whenever you need.
Built for Media Servers - Works with Jellyfin, Proxmox, and Docker without fighting them.

Tired of juggling individual disks? Install MergerFS, set it up the way I showed above, and get on with watching your media.

OpenMediaVault vs TrueNAS vs Unraid: Best NAS OS for Homelabs

Fri, 31 Jan 2025 07:24:52 -0700

Picking a NAS OS sounds easy until you actually try. Each one swears it’s the right call. Each one breaks differently when you push it. So before you commit a stack of drives and a weekend to the wrong platform, here’s what each option costs you, what it handles well, and where it falls apart.

This post compares the five NAS options I’ve run or seriously evaluated: OpenMediaVault, Unraid, TrueNAS Core, TrueNAS Scale, and rolling your own. I’ll lay out the honest pros and cons of each so you can make the call without sitting through marketing pages.

1. OpenMediaVault (OMV)

OpenMediaVault (OMV) is a Debian-based NAS OS that turns standard hardware into a web-managed server. The GUI handles storage, users, and shares without dropping you straight into the terminal, which makes the on-ramp easier for folks who don’t live in a shell. It speaks SMB, NFS, and FTP out of the box, so anything on your network can mount it. RAID management, scheduled backups, and basic monitoring are all wired into the same interface.

The real strength is the plugin system. Docker, rsync, and a stack of community plugins extend OMV well past the default feature set. The catch: OMV is happiest when you stay close to the official release path. Heavy customization tends to bite you on the next update.

Pros

Free and open source. No licensing fees.
Debian-based, so any Debian package is fair game.
Web GUI for setup and day-to-day management.
Plugin system for Docker, rsync, and more.
Supports EXT4, XFS, and Btrfs.
Docker and virtualization support for extra services.

Cons

Light on enterprise features.
Heavy customization causes stability issues. Plugins also fight each other.
Support is community forums only.
Interface and updates are rougher than the polished competition.

Notes

I ran OMV for several years on my own gear. It handles the default workload fine. The moment you start stacking custom plugins, third-party repos, or anything outside the official update path, stability gets shaky. If you want something to install once and leave alone, it works. If you want to tinker, you’ll be fighting it.

2. Unraid

Unraid bundles NAS, container hosting, and virtualization into one OS. It boots off a USB stick and runs in RAM, so the system disk isn’t part of your storage pool. A modern Linux kernel underneath means it’ll run on pretty much any 64-bit x86 box, from a recycled office tower to a proper homelab build.

The web UI is the part most people fall in love with. Sensible defaults out of the box, with knobs to turn when you want them. The three jobs Unraid does. Network storage, Docker, and VMs. They all live behind the same interface, so you’re not bouncing between five tools to spin up a media server or a personal cloud.

Pros

Flexible storage pooling. Mix and match drives of different sizes.
Parity-based protection instead of traditional RAID. Drive replacement and expansion are painless.
Strong Docker and VM support. Jellyfin, Sonarr, Radarr, full Linux VMs.
Web interface is genuinely friendly.
Efficient storage usage with one or two parity disks.

Cons

Paid license. $49 to $109 depending on drive count.
Subscription model now, or pony up $249 for the Lifetime License.
Light on enterprise features.
Single-disk-at-a-time writes are slower than RAID. A cache disk fixes most of this.

Notes

The price has always kept me off Unraid. When they moved to a subscription model, that closed the door for me entirely. Plenty of people swear by it, and I get why. The Docker and VM experience is hard to beat. If the licensing doesn’t bother you, grab the 30-day free trial and see how it feels on your hardware before you commit.

3. TrueNAS Core

TrueNAS Core is the FreeBSD-based, ZFS-backed NAS OS formerly known as FreeNAS. ZFS is the headline feature. Snapshots, checksums, self-healing, the works. If data integrity is the top priority, this is the platform built around it. SMB, NFS, iSCSI, and AFP cover almost any client you’ll throw at it.

The web UI is dense but powerful. Plugins and jails let you run Jellyfin, Sonarr, Radarr, or backup tooling on the NAS itself instead of standing up another machine. The trade-off is hardware. ZFS wants ECC RAM and plenty of memory. Skimp on either and you give up some of the data integrity story you came here for.

Pros

ZFS. Data integrity, snapshots, compression.
Enterprise protocols. iSCSI, SMB, NFS.
Web-based management with deep configuration options.
Free and open source.
VMs and jails for running services on the NAS.

Cons

Hardware hungry. ECC RAM and serious memory are expected.
Adding drives to a ZFS pool one at a time is inefficient.
FreeBSD is less familiar than Linux for most homelab users.
ZFS and FreeBSD both have a learning curve.
Storage expansion needs planning up front.

Notes

If I could buy all my storage up front and had a board with ECC support, TrueNAS Core or Scale would be the easy call. Buying six to eight large drives at once isn’t realistic for me. Even with the budget, I’d pick Scale over Core. The Linux base, container support, and broader hardware compatibility make Scale a better fit for the way I use a NAS.

4. TrueNAS Scale

TrueNAS Scale is the Debian Linux sibling to TrueNAS Core. Same ZFS underneath. Same data protection story. The difference is what’s bolted on top. Native Kubernetes, Docker, and KVM support, plus the broader Linux hardware compatibility you’d expect. If you want a NAS that doubles as an app server or a lightweight hypervisor, Scale is built for that.

The web UI is similar to Core but designed around the Linux stack. Storage, networking, and apps all live in the same interface. Scale is also built to grow, with clustering and high-availability options available if you ever need them.

Pros

Linux-based. Better hardware and software compatibility.
ZFS for data protection and redundancy.
Native Kubernetes and Docker support.
Designed to scale from one box to a cluster.
Strong fit for homelab and small-business use.

Cons

Newer than Core. Some features still maturing.
Same hardware demands as Core. ECC RAM, strong CPU and memory.
ZFS pool expansion still painful.
Steeper learning curve than OMV or Unraid.
ZFS limits on adding drives to existing pools remain.

Notes

Same story as Core. If buying the full storage stack up front were on the table and I had ECC-capable hardware, I’d run Scale today. The Linux base and container story make it the better pick over Core for the way I work. The upfront cost is what keeps me on a DIY setup instead.

5. Build Your Own NAS (DIY)

A DIY NAS is the option for folks who want full control. Pick the OS. Pick the storage stack. Pick the filesystem. Ubuntu Server, Debian, Arch, even a custom FreeBSD install. Nothing is off the table. That freedom means you can tune the box for whatever you care about. Power draw, transcoding, snapshots, raw capacity. Roll your own MergerFS pool. Roll a ZFS array. Run Btrfs if you like living dangerously. The result is a NAS shaped exactly to your workload instead of someone else’s idea of what a NAS should be.

The cost is complexity. There’s no friendly web UI by default. You’ll be in a terminal for most setup and maintenance. You’re the support team. You’re the upgrade path. If you’re comfortable with Linux, networking, and storage, that’s a fair trade for the flexibility and the lack of licensing fees. If you’re not, one of the turnkey options above will save you a lot of weekends.

Pros

Fully customizable. Any OS, any hardware, any stack.
No licensing fees with open-source tooling.
Total control over RAID, MergerFS, ZFS, or Btrfs.
Best fit for users comfortable with Linux and storage.

Cons

Steep learning curve. Real technical depth required.
No web UI unless you bolt one on. Webmin, OMV, or Cockpit are the usual options.
More maintenance. Manual updates, patches, troubleshooting.
No official support. Community forums and your own notes.

Notes

This is the option I chose for my media server NAS. Redundancy wasn’t my priority. Capacity was. So I watch SMART data closely and pull disks at the first sign of bad blocks. A catastrophic drive failure means re-ripping a chunk of my movie collection, which is annoying but survivable.

Critical data is a different story. Family photos and important documents are backed up locally and to the cloud. Redundancy where it matters, raw capacity everywhere else. That’s the balance that works for my workload.

Conclusion: Which NAS Solution Wins?

Beginners and home users: OpenMediaVault or Unraid. Easy setup, sane defaults.
Media enthusiasts and virtualization: Unraid. Docker and VM support are the strongest of the bunch.
Enterprise and data integrity: TrueNAS Core. ZFS, redundancy, and serious uptime.
Advanced users and tinkerers: DIY. Maximum control if you’re willing to do the work.
Best balance of features and flexibility: TrueNAS Scale. ZFS plus Linux plus containers.

Pick the one that matches the gear you have and the time you’re willing to spend. If you’ve got ECC RAM and a full drive set ready to go, run Scale. If you want Docker and VMs and don’t mind the license, run Unraid. If you want free and easy, run OMV. If you want to build the thing yourself, build it. There’s no single right answer. Only the one that fits your stack.

Master the Basics - The 10 Most Important Linux Commands and How to Use Them

Sun, 26 Jan 2025 07:34:05 -0700

You’ve installed Linux on your new media server and you’re staring at a prompt like this:

john@mediaserver:~$

A blinking cursor and no idea what to type. If you’re new to the terminal, that little prompt feels like a black box. Cryptic commands, weird symbols, infinite options. It’s intimidating.

Here’s the good news. You don’t need to know hundreds of commands. You need ten. The ten in this post are the ones I use every single day on Debian and Ubuntu boxes to keep media servers running. Learn these and you’ll have the confidence to navigate, manage, and unscrew almost any Linux system you touch.

Think of it like learning a new language. You don’t need the whole dictionary to order a beer. A handful of solid verbs gets you a long way. Same idea here.

I run these commands daily on Debian 12 and Ubuntu 24.04 servers hosting Plex, Jellyfin, and the *arr stack. Everything below works the same on both.

1. `ls` - List Directory Contents

ls is the first command anyone should learn. It shows you what’s in a directory. That’s it. The Linux equivalent of opening a folder in a file manager, except faster.

Basic Usage

Type ls and it prints the files and folders in your current working directory.

Useful Options

ls -l: Detailed view. Permissions, owner, group, size, last modified date.
ls -a: Shows hidden files and directories (the ones starting with a dot, like .config).
ls -h: Human-readable file sizes (KB, MB, GB) when paired with -l.

Practical Examples

See what’s in a directory: Running ls /media/Movies shows every file in that folder. Useful when you can’t remember if you already imported that movie.

Spot hidden config files: Most app config lives in dotfiles. Use ls -a when you’re troubleshooting or trying to find where some daemon hid its settings.

Check file details: When permissions or size matter (is this script executable? Did this download finish?), ls -lh gives you everything in one shot.

Why It Matters

You can’t manage what you can’t see. ls is how you see. Get comfortable with it first, because every other command in this list assumes you know what’s on disk.

2. `cd` - Change Directory

cd is how you move around. It stands for “change directory,” which is exactly what it does. Think of it as double-clicking a folder, except your hands never leave the keyboard.

Basic Usage

cd <directory>: Move into that directory.

Want to jump to your Movies folder?

cd /media/Movies

Useful Shortcuts

Home directory: cd on its own takes you back home, no matter where you are.

Parent directory: cd .. moves you one level up.

Root directory: cd / drops you at the top of the file system.

Previous directory: cd - jumps back to wherever you were before the last cd. This one’s a lifesaver when you’re bouncing between two folders.

Practical Examples

Jump to an absolute path:

cd /media

Jump straight to a nested folder, no need to walk down step by step:

cd /media/Shows

Back up one level:

cd ..

Why It Matters

You’ll run cd more than any other command. Efficient navigation is the difference between feeling lost and feeling in control. Learn it cold.

Troubleshooting

If cd errors out, check the directory name. Linux file systems are case-sensitive. media and Media are two different folders. Run ls first to confirm what’s there.

3. `pwd` - Print Working Directory

pwd stands for “print working directory.” It tells you exactly where you are in the file system. Think of it as the “you are here” arrow on a mall map.

Basic Usage

Type pwd and you get the full absolute path of your current directory.

If you’re in your Movies folder, pwd returns:

/media/Movies

Practical Use Cases

Know where you are: After three SSH sessions and ten cd commands, it’s easy to lose track. pwd ends the guessing.

Script writing: When you write a shell script that builds relative paths, pwd confirms you’re starting from the right place.

Debugging: A command not working? Half the time you’re in the wrong directory. pwd tells you in one second.

Why It Matters

It’s a small command, but it’s the one you reach for when you’re confused. Pair it with ls and cd and you can always orient yourself.

Example Workflow

You SSH into a remote server and don’t know where you landed. Run pwd.
You’ve changed directories five times. Run pwd again before you copy or delete anything.

Tips

You can drop it into scripts to log the current directory:

echo "You are currently in $(pwd)"

Useful when creating symbolic links or setting environment variables. If you’re not sure where you are, you can’t be sure where the link will point.

4. `mkdir` - Make Directory

mkdir creates new directories. Whether you’re laying out your media library or staging a backup folder, this is your tool.

Basic Usage

mkdir <directory-name>

This creates a directory in your current location.

mkdir media

That creates a folder called media right where you are.

Practical Use Cases

Build a media library structure in one command:

mkdir -p /media/{Movies,Shows,Music}

That builds the media folder (if it doesn’t already exist) and creates Movies, Shows, and Music inside it. One line, three folders, no clicking.

Spin up a temp folder for scratch work:

mkdir temp_files

Useful Options

-p (Parent): Creates parent directories as needed. Saves you from “no such file or directory” errors when the path doesn’t exist yet.

-v (Verbose): Confirms each directory as it’s created. Handy when you’re building deep trees.

mkdir -pv /media/{Movies,Shows,Music}

Output:

mkdir: created directory 'media'
mkdir: created directory 'media/Movies'
mkdir: created directory 'media/Shows'
mkdir: created directory 'media/Music'

Troubleshooting

“Permission denied”? You don’t have write access where you’re trying to create the folder. Use sudo mkdir for system locations like /etc or /var. But think before you sudo.
Typos. Linux is case-sensitive, so media and Media are not the same folder.

Why It Matters

You’ll create directories constantly. Setting up a Plex library, staging downloads, organizing backups. mkdir -p is one of those small tools you’ll use hundreds of times and never think about. Until you forget the -p flag and curse at “No such file or directory” for the tenth time.

5. `rm` - Remove Files or Directories

rm deletes files and directories. It stands for “remove.” It does not move things to a trash can. It does not ask “are you sure?” by default. Files go away. Forever.

Read that paragraph twice before you run rm on anything you care about.

Basic Usage

To remove a file:

rm <file-name>

For example:

rm old_document.txt

Gone.

Deleting Multiple Files

You can list several files in one command:

rm file1.txt file2.txt file3.txt

Removing Directories

By default, rm won’t touch directories. You need flags.

rm -r (Recursive): Removes a directory and everything in it.

rm -r folder_name

rm -rf (Recursive + Force): Deletes everything, no prompts, no warnings.

rm -rf /path/to/directory

This one earned the nickname “the nuclear option” for a reason. I’ve watched people run rm -rf on / because of a stray space. Once it’s running, you can’t get it back. Be deliberate.

Practical Use Cases

Clean up after testing:

rm -r /tmp/my_temp_files

Drop a movie you’ll never watch again:

rm -r /media/Movie/Movie_I_No_Longer_Need

Useful Options

-i (Interactive): Asks before deleting each file. Slow, but it’ll save you the day you mistype a path.

rm -i important_file.txt

-v (Verbose): Prints what it’s deleting.

rm -rv /path/to/directory

-f (Force): Ignores warnings and deletes without asking. Combine with -r only when you’re certain.

Safety Tips

Double-check the path. Always. If you can’t read the path out loud and feel confident, don’t run the command.
Avoid sudo unless you need it. Running rm as root can wipe system files. Use it sparingly.
Preview with ls first. Run ls /path/to/directory before rm -r /path/to/directory. Confirm you’re looking at the right files.

Why It Matters

Cleanup is part of running a server. Logs grow, downloads pile up, old configs linger. rm keeps the system tidy. But every Linux user has an rm -rf horror story. Don’t earn yours.

Example Workflow

Delete a single file:

rm Movie_I_Hate.mkv

Remove a directory and its contents:

rm -r ~/Downloads/temp_folder

Clean all .tmp files in a directory:

rm *.tmp

6. `cp` - Copy Files and Directories

cp copies files and directories. Backups, duplicates, config snapshots before you mess with something. You’ll reach for this one constantly.

Basic Usage

Copy a file:

cp <source-file> <destination>

cp config.conf backup_config.conf

This copies config.conf to backup_config.conf in your current directory. Cheap insurance before editing.

Copying Multiple Files

cp file1.txt file2.txt /path/to/destination/

Copying Directories

cp won’t copy directories without the recursive -r flag:

cp -r /source/directory /destination/directory

That duplicates the whole tree, subdirectories and all.

Practical Use Cases

Snapshot a config before editing:

cp config.yaml config_backup.yaml

If you break the edit, you have a known-good copy to restore.

Copy media between folders or drives:

cp /home/user/downloads/movie.mkv /media/Movies/Movie_Name/

Useful Options

-i (Interactive): Asks before overwriting existing files.

cp -i file1.txt /destination/

-v (Verbose): Shows each file as it copies. Helpful on large operations.

cp -v file1.txt file2.txt /destination/

-u (Update): Only copies if the source is newer or the destination file doesn’t exist. Great for syncing.

cp -u file1.txt /destination/

-p (Preserve): Keeps timestamps, permissions, and ownership.

cp -p file1.txt /destination/

Tips

Preview first: Use ls to confirm both source and destination paths before running cp.

Avoid overwrites: Use -i to prompt before clobbering, or -n (no-clobber) to skip overwrites entirely.

Why It Matters

Anytime you’re about to edit something important, copy it first. cp config.yaml config.yaml.bak takes one second and has saved me more times than I can count. Cheap insurance.

7. `mv` - Move or Rename Files and Directories

mv does two jobs. It moves files and directories, and it renames them. Same command, depending on where the destination points.

Basic Usage

Move a file:

mv <source-file> <destination>

mv movie.mkv /media/Movies/Movie_Name/

This moves movie.mkv into the Movie_Name directory.

Rename a file:

mv <old-name> <new-name>

mv Movie_Name.mkv Movie_Name_2022.mkv

Same command, different destination. Linux treats a rename as a move within the same directory.

Moving Multiple Files

mv file1.txt file2.txt file3.txt /destination/directory/

Moving Directories

Move an entire directory:

mv /source/directory /destination/

Whole tree, one command.

Useful Options

-i (Interactive): Prompts before overwriting.

mv -i file.txt /destination/

-v (Verbose): Shows each move or rename.

mv -v file.txt /destination/

-n (No-Clobber): Won’t overwrite existing files at the destination.

mv -n file.txt /destination/

Tips

Preview first: Use ls or find to check what you’re about to move. A bad mv on a system file can break things in unexpected ways.

Avoid overwrites: -i or -n will save you when the destination has a file you forgot about.

Be careful with sudo: Moving system files as root can break boot. Read your command twice before you hit Enter.

Why It Matters

mv is fast and irreversible. Move a config to the wrong place and your daemon won’t start. But used carefully, it’s how you keep a server organized. Rename a misnamed download, shuffle a folder to a new drive, restructure a media library. All mv.

8. `chmod` - Change File Permissions

chmod controls who can read, write, and execute a file. It’s how Linux keeps users out of each other’s stuff and stops accidental damage to system files. If you’ve ever copied a script and gotten “Permission denied,” chmod is the fix.

Understanding File Permissions

Before touching chmod, look at what permissions look like. Run ls -l on a file:

-rwxr-xr-- 1 user group 4096 Jan 23 10:00 script.sh

Three letters, three categories:

r (read): View the file’s contents.
w (write): Modify the file.
x (execute): Run the file as a program or script.

Three categories of users:

Owner (rwx) - Full access.
Group (r-x) - Read and execute for group members.
Others (r--) - Everyone else can only read.

Basic Usage

Symbolic notation:

chmod <permissions> <file>

Give the owner execute permission:

chmod u+x script.sh

Symbolic targets:

u (user): The file’s owner.
g (group): Users in the file’s group.
o (others): Everyone else.
a (all): Applies to u, g, and o.

Modifiers:

+ (add): Adds a permission.
- (remove): Removes a permission.
= (set): Sets a permission exactly.

Add read and write for the group:

chmod g+rw file.txt

Remove execute for others:

chmod o-x script.sh

Octal notation:

Faster once you know it. Numbers map to permission bits:

4 (read): r--
2 (write): -w-
1 (execute): --x

Add them up. 7 = rwx, 6 = rw-, 5 = r-x.

chmod 755 script.sh

That sets:

Owner: Read, write, execute (7 = rwx).
Group: Read, execute (5 = r-x).
Others: Read, execute (5 = r-x).

Practical Use Cases

Make a script executable:

chmod +x my_script.sh

Lock down a sensitive file:

chmod 600 private_file.txt

Only the owner can read or write. Everyone else is shut out.

Open a file for group collaboration:

chmod g+rw shared_file.txt

Useful Options

-R (Recursive): Applies permissions to a directory and everything inside.

chmod -R 755 /path/to/directory

--reference: Copies permissions from one file to another.

chmod --reference=source_file target_file

Example Workflow

Check current permissions:

ls -l file.txt

Modify permissions. Grant read and write to the owner and group, deny everything to others:

chmod 660 file.txt

Open a directory and everything inside:

chmod -R 755 /media/Movies

Tips

Test on one file first. Don’t run chmod -R on a directory tree until you’ve confirmed the result on a single file. Recursive permission changes are hard to unwind.

Don’t use 777. It opens the file to every user on the system. I know it makes the “Permission denied” error go away. It also makes every security audit cry. For shared media folders I use 770. Owner and group get full access, everyone else gets nothing. Files stay protected and invisible to outsiders.

Check regularly: Use ls -l to confirm permissions are what you expect, especially after big copies or moves.

Why It Matters

Permissions are where Linux security starts. chmod is how you control it. Get this one wrong on a media server and either nothing works or the world can read your config files. Take the time to understand it.

9. `chown` - Change File Ownership

chown changes who owns a file or directory. Every file in Linux has two ownership attributes: a user and a group. chown lets you reassign both. Critical for multi-user systems and for fixing the “why can’t Plex read this folder” problem after a copy from somewhere else.

Basic Usage

Change the owner of a file:

chown <new-owner> <file>

chown kryptikwurm movie.mkv

That sets the owner of movie.mkv to kryptikwurm.

Change both owner and group:

chown <new-owner>:<new-group> <file>

chown kryptikwurm:media movie.mkv

Owner becomes kryptikwurm, group becomes media.

Changing Ownership of Directories

Use -R (recursive) to apply ownership to a directory and everything inside:

chown -R kryptikwurm:media /media

That changes ownership on /media and every file and subfolder inside it.

Useful Options

-R (Recursive): Applies changes to a directory tree.

chown -R kryptikwurm:media /media

-v (Verbose): Prints each change as it happens.

chown -v kryptikwurm:media movie.mkv

Checking File Ownership

Use ls -l before and after:

ls -l file.txt

Output:

-rw-r--r-- 1 user group 4096 Jan 23 12:00 file.txt

The first name is the owner, the second is the group.

Safety Tips

Be careful with sudo: Double-check the path. A chown on the wrong directory can lock you out of system files until you fix it.

No wildcards on root paths: chown -R user:group /* will trash your system. Don’t.

Preview first: Use ls -l to inspect ownership before changing it.

Why It Matters

Proper ownership is how Linux decides what a service can read and write. Use chown to:

Let the right user account access your media folders.
Hand a shared folder to a group so multiple users can collaborate.
Fix permission errors after migrating data between machines.

Get ownership right and most of your “Plex can’t see this folder” or “Sonarr can’t write to this directory” headaches disappear.

10. `df` - Display Disk Space Usage

df shows how much disk space you have. Short for “disk free.” Run it before you launch a big download. Run it when a service mysteriously stops writing. Run it when the server feels slow. It’s a thirty-character command that catches a lot of problems early.

Basic Usage

df

Example output:

Filesystem 1K-blocks Used Available Use% Mounted on
/dev/sda1 500000000 250000000 250000000 50% /
tmpfs 4000000 0 4000000 0% /dev/shm

Key Fields

Filesystem: The disk or storage device (/dev/sda1).

1K-blocks: Total space in 1KB blocks. Ugly. Use -h.

Used: Space currently in use.

Available: Space free.

Use%: Percentage in use. The number that matters.

Mounted on: Where the filesystem is mounted in the directory tree.

Useful Options

-h (Human-Readable): Show sizes in MB, GB, TB.

df -h

Output:

Filesystem Size Used Avail Use% Mounted on
/dev/sda1 500G 250G 250G 50% /

-T (Show Filesystem Type): Include the filesystem type (ext4, xfs, btrfs).

df -T

Filesystem Type 1K-blocks Used Available Use% Mounted on
/dev/sda1 ext4 500000000 250000000 250000000 50% /

Practical Use Cases

Check storage on a media server:

df -h

Spot filesystems nearing capacity. A 98% full disk will silently break Plex transcoding and Sonarr imports:

Filesystem Size Used Avail Use% Mounted on
/dev/sda1 500G 490G 10G 98% /

Verify external drives or network shares are mounted:

df -h /media/usb

If the line doesn’t appear, the mount failed.

Tips

Always use -h. The default output is unreadable.

Check before big writes. Before you rip a Blu-ray to disk or pull down a 50GB Linux ISO, run df -h and confirm you have room.

Confirm mounts after reboot. Use df to verify external drives and NFS shares came back up correctly. Half the time a “missing files” panic is actually a dropped mount.

Why It Matters

A full disk is one of the most common reasons services break on a media server. Plex can’t write metadata. Sonarr can’t import. Backups silently fail. df is a five-second check that saves hours of debugging.

In Conclusion

That’s the toolkit. Ten commands. Learn these and you can navigate a Linux box, manage files, set permissions, control ownership, and keep an eye on disk space. Which covers most of what running a media server requires.

You’re not going to memorize the flags from a blog post. Open a terminal. Make some folders. Move them. Delete the wrong one. Recover. That’s how this sticks. The best way to learn Linux is to break a test box and fix it.

When you’re ready for the next step, start chaining these commands together with pipes and writing small shell scripts. That’s where Linux stops being a list of commands and starts feeling like a tool you actually own.

Don’t stop at ten. But start here.

Turn an Old Computer Into a Media Server Part 4 How to Configure Jellyfin

Mon, 20 Jan 2025 08:05:12 -0700

Introduction

You’ve done the heavy lifting. Ubuntu Server 24.04 LTS is installed, your storage is partitioned and mounted, SMB shares are working, and Jellyfin is sitting there waiting. Now it’s time to point it at your media and finish the wizard so you can watch something.

This post walks the rest of the way. You’ll complete the setup wizard, add your libraries, set a few sane defaults, and confirm playback works. By the end, your old PC will be a working media server that streams to anything on your LAN.

Accessing the Jellyfin Web Interface

Step 1: Connect to Jellyfin

Open a web browser on a device connected to your network.

Enter the server’s IP address followed by the port number :8096.

Example: http://192.168.1.100:8096

This loads the Jellyfin setup wizard. It should look like this:

If the page doesn’t load, check this post: Troubleshooting - Jellyfin Server Access Issues

Running the Jellyfin Setup Wizard

Step 1: Choose Your Language and Region

Pick your preferred language.

Step 2: Create an Admin Account

Pick a strong admin username and password. This is the account that controls everything on the server, so don’t reuse a password you’ve used anywhere else.

Tips for Creating a Strong Username and Password

Use Unique Credentials: Skip common usernames like “jellyfin” and passwords like “123456.” Pick a unique username, and for the password use a mix of letters, numbers, and special characters.
Make It Long: Passwords should be at least 12 characters.
Avoid Predictable Words: Don’t use easily guessed information like your name, birthday, or server name.
Use a Password Manager: If remembering complex passwords is a pain, a password manager can generate and store them securely for you.

Step 3: Add Media Libraries

Click “Add Media Library.”

Pick the content type (Movies, TV Shows, Music, etc.).

Click the + next to “Folders” and browse to the folder where the media is stored (e.g., /mnt/media/Movies).

The defaults are fine for an initial setup. Leave them alone.

Repeat for /mnt/media/Shows and /mnt/media/Music.

Step 4: Configure Metadata Options

Metadata pulls in the cover art, plot summaries, cast lists, and ratings for your movies, shows, and music. It’s what turns a folder of filenames into something that looks like a streaming service.

For now, accept the defaults. You can fine-tune later.

Step 5: Remote Access (Optional)

Not recommended. If you want remote access, you’ll need to forward Jellyfin’s port (default 8096) on your router to the server’s internal IP. That exposes the server to the public internet. If you do this, use a VPN or put it behind a reverse proxy with HTTPS and a real certificate. Don’t open port 8096 to the world and hope for the best.

Step 6: Finish the Wizard

Click “Finish.” The server will start scanning your media folders and populating the libraries.

If everything went well, you should see the web interface with your media listed.

Testing Your Jellyfin Setup

Step 1: Open the Jellyfin Client

You can use the web browser, or install the Jellyfin app on the device you want to watch on (phone, tablet, TV, streaming stick).
Note: Right now this is only accessible while you’re connected to your local network.
Jellyfin apps: download from your platform’s app store, or grab them from the official site.

Step 2: Test Playback

Play a sample movie or TV show to confirm the server is working. You can do it straight from the web browser, but some browsers choke on certain codecs. For a cleaner test, use the official Jellyfin client app. It handles more formats natively and doesn’t lean on the browser for decoding.
Client apps: Jellyfin Client Downloads

Conclusion

That’s Jellyfin up and running with user accounts, metadata, and media libraries. Your server is now streaming to anything on your network.

There’s plenty more to dig into when you’re ready. Themes, plugins, hardware transcoding, user permissions, and remote access are all next steps worth exploring. Get comfortable with what you’ve built first, then pick one thing at a time.

Time to grab some popcorn and watch something on the server you built.

Troubleshooting - Jellyfin Server Access Issues

Mon, 20 Jan 2025 07:44:15 -0700

You set up Jellyfin, you’re ready to watch something, and the browser hangs on http://your-server-ip:8096. Frustrating, but fixable. Most of the time it’s one of a handful of dumb things, and you can work through them in a few minutes. Here’s the order I check them in.

1. Double-Check the IP Address

First, make sure you’re hitting the right address. Typos here waste more time than anything else.

On the server, open a terminal and run:

ip a

Find the inet line under your active interface (like eth0 or wlan0). It’ll look like 192.168.1.100.

That’s the address you should be typing into the browser, followed by :8096. If your server has more than one interface, make sure you’re using the one that’s on the same network as your client.

2. Make Sure Jellyfin Is Running

If the service is dead, the browser has nothing to talk to. Check it:

sudo systemctl status jellyfin

Look for Active: active (running). If it isn’t, start it:

sudo systemctl start jellyfin

And while you’re there, make sure it’ll come back up after a reboot:

sudo systemctl enable jellyfin

I’ve lost more time than I want to admit to a Jellyfin install that wasn’t enabled, then quietly stayed dead after a power blip.

3. Test Connectivity

Now check that the client can actually reach the server. From the client device:

ping <server-ip>

Swap <server-ip> for the address from step 1 (e.g. 192.168.1.100). Replies coming back? Good, the network path is fine. No replies? You’ve got a firewall, VLAN, or wifi-isolation problem between the two machines, and that’s where to focus next.

4. Reboot the Server

Yes, it’s a cliche. Yes, it works. A reboot clears stuck network state and restarts every service cleanly:

sudo reboot

Wait for the box to come back, then try the browser again.

5. Check Browser Compatibility

The Jellyfin web UI expects a modern browser. Chrome, Firefox, and Edge all work fine. If you’re on something old or weird, update it or try a different one before you go any deeper into the logs.

When All Else Fails: Check the Logs

If you’ve worked through the list and you’re still locked out, the logs will usually tell you why. Pull them with:

sudo journalctl -u jellyfin

Scroll through the recent output and look for errors or warnings. Port conflicts, permission problems, and missing config files all show up here. That’s normally where the real answer is hiding.

Work the list top to bottom and you’ll catch the problem somewhere along the way. Most Jellyfin access issues are network, service, or browser, not Jellyfin itself.

Turn an Old Computer Into a Media Server Part 3 Installing Jellyfin and Its Dependencies

Sat, 18 Jan 2025 07:00:43 -0700

Recap: Your Journey So Far

In the previous posts, we turned an old PC into a server running Ubuntu Server 24.04 LTS. Along the way, we:

Covered why an old PC is a smart starting point. It’s cheap, eco-friendly, and forgiving for beginners.
Walked through the minimum hardware Jellyfin needs. You don’t need a new rig to run a media server.
Installed Ubuntu Server step by step, from flashing a USB drive to finishing the installer.
Added storage and got the drives partitioned, formatted, and mounted.
Set up a Samba share so you can drop files onto the server from any machine on your network.

The server is ready. Time to put Jellyfin on it. I ran every step in this post on a fresh Ubuntu Server 24.04 LTS install, and the same commands work on 22.04 and 23.10 with no changes.

What Is Jellyfin?

Jellyfin is a free, open-source media server that organizes, manages, and streams your collection to any device. Think of it as your own Netflix, but you own the data and the server. Movies, TV, music, photos, all of it lives in one place you can hit from your phone, smart TV, computer, or a web browser.

Here’s what we’ll cover:

Preparing Ubuntu Server. Patch the system and install curl.
Adding the Jellyfin repository. Pull the official GPG key and source list so apt knows where to look.
Installing Jellyfin. Run apt install, then enable, start, and verify the service.
Accessing Jellyfin for the first time. Find the server IP, hit port 8096, and load the setup wizard.

Section 1: Preparing Your Server for Jellyfin

SSH Into Your New Server

Not sure how to use SSH? Read this first: Master the Basics - How to SSH Into a Linux Server.

Steps to Connect Using SSH

Open PowerShell on Windows and run:

ssh <username>@<server-ip>

Example from Part 1:

ssh kryptikwurm@192.168.1.200

Authenticate. Type the server password when prompted. You won’t see any characters as you type. That’s normal. SSH hides the input on purpose.

Once you’re in, you’ve got a full remote shell. Time to install Jellyfin.

Install System Updates and Curl

Update the system first.

Patches close security holes and pull in the bug fixes that keep new software from breaking on day one. Run this before anything else:

sudo apt update && sudo apt upgrade -y

Install curl.

curl is a command-line tool for moving data between your machine and a remote server. It speaks HTTP, HTTPS, FTP, and a pile of other protocols, and you’ll use it to grab the Jellyfin GPG key in the next step. It might already be on your system. Install it anyway. It’s harmless if it’s already there:

sudo apt install curl -y

Section 2: Adding the Jellyfin Repository

Adding the Jellyfin repository pulls Jellyfin straight from its official source. You get the latest stable release, security fixes show up through normal apt upgrade runs, and you never have to chase a .deb file off a forum post.

Run these one at a time.

First, fetch and store the GPG key. apt uses it to verify Jellyfin packages haven’t been tampered with:

curl -fsSL https://repo.jellyfin.org/ubuntu/jellyfin_team.gpg.key | sudo gpg --dearmor -o /usr/share/keyrings/jellyfin.gpg

Next, register the repository. This drops a file into /etc/apt/sources.list.d/ so Ubuntu knows where to look for Jellyfin and its updates:

echo "deb [signed-by=/usr/share/keyrings/jellyfin.gpg] https://repo.jellyfin.org/ubuntu noble main" | sudo tee /etc/apt/sources.list.d/jellyfin.list

Now refresh the package index. sudo apt update doesn’t install or upgrade anything. It tells your system what’s available so the install step finds Jellyfin:

sudo apt update

If it worked, you’ll see a line like this in the output:

https://repo.jellyfin.org/ubuntu noble InRelease

Section 3: Installing Jellyfin

Use apt to install Jellyfin:

sudo apt install jellyfin -y

Enable the service so it starts at boot:

sudo systemctl enable jellyfin

Start it now, without rebooting:

sudo systemctl start jellyfin

Verify it’s running:

sudo systemctl status jellyfin

You’re looking for a line like this:

Active: active (running) since <date and time>

If you see failed or inactive (dead) instead, check journalctl -u jellyfin -n 50 for the error before moving on.

Section 4: Creating Groups and Permissions

Jellyfin runs as its own jellyfin user, and that user needs read access to your media folder. The cleanest way to handle this is a shared group both jellyfin and your login user belong to.

Create the group:

sudo groupadd media

Add the jellyfin user and your own user to it:

sudo usermod -aG media jellyfin
sudo usermod -aG media $(whoami)

Change the group owner on the media tree so anything in /mnt/media is readable by the group:

sudo chown -R :media /mnt/media

You may also need sudo chmod -R g+rX /mnt/media if existing files don’t have group-read set. And you’ll need to log out and back in (or run newgrp media) before your shell sees the new group membership.

Section 5: Accessing Jellyfin for the First Time

The server’s up. You’ve got the IP. Open a browser and hit it:

Open a web browser. Use any modern browser. Chrome, Firefox, Edge, Safari. It doesn’t matter. Use a device on the same network as the server.
Enter the address. In the address bar, type the following, swapping in your server’s IP:

http://<server-ip>:8096

Example:

http://192.168.1.200:8096

Verify the Jellyfin interface loads. You should land on the Jellyfin setup wizard. That confirms the service is running and your network can reach it on port 8096.

If the page doesn’t load, double-check the IP with ip a on the server, and confirm Jellyfin is listening with sudo ss -tlnp | grep 8096. Most first-time failures are a typo’d IP or a firewall blocking the port.

What’s Next?

Jellyfin is installed, running, and reachable. The next post walks through the setup wizard, points Jellyfin at your media folders, and gets the libraries scanning.

Ready to configure Jellyfin and start streaming? Head to Part 4 of this series to finish the build.

Turn an Old Computer Into a Media Server Part 2 Adding a Storage Drive and Setting Up SMB Shares

Fri, 17 Jan 2025 07:41:16 -0700

Recap: Your Journey So Far

In Part 1, we took your old, dusty computer and gave it a new purpose by turning it into a server running Ubuntu Server 24.04 LTS. We covered:

Why starting with an old PC is a smart move. It’s cost-effective, beginner-friendly, and environmentally conscious.
The minimum hardware specs needed to run a Jellyfin server. You don’t need the latest and greatest hardware to get started.
Step-by-step instructions for installing Ubuntu Server. From creating a bootable USB drive to finishing the install.

Ubuntu Server is installed and ready to go. Your old PC is now a dedicated server, ready to host your Jellyfin media library. But before we touch Jellyfin, you need storage and a way to push files onto it. That means adding drives and setting up an SMB share. Once that’s done, you can drop media onto the server straight from a Windows or Linux box, which is the whole point when you’re ripping Blu-rays and DVDs on a separate machine.

Section 1: Adding Storage to Your Server

Power Off the Server and Add Drives

Step 1: Physically Connect the Storage Drive(s) to Your Server

Power off command:

sudo shutdown -h now

For internal drives, install the drive into a free slot and connect it using SATA power and data cables.
For external drives, plug it into a USB port. No need to power down for this one.
Power on the server and confirm the drive is recognized.

SSH Into Your New Server

Not sure how to use SSH? Read this post: Master the Basics - How to SSH Into a Linux Server

Steps to Connect Using SSH

Open PowerShell on Windows:

The command for SSH:

ssh <username>@<server-ip>

Example From Part 1:

ssh kryptikwurm@192.168.1.200

Authenticate:

Enter your server password when prompted. (Don’t worry if you don’t see any characters while typing. That’s normal for security reasons.)

Partition and Format the New Drive

Step 2: Check if the Drive is Detected

Use the lsblk command to list all block (storage) devices:

lsblk

Identify the new drive (e.g., /dev/sdb or /dev/sdc) based on its size.

Note the name of the device (e.g., /dev/sdb). You’ll use it in the next steps.

Details on how to partition and format a hard drive in Linux are here: Master the Basics - How to Use parted to Create Partitions

Step 3: Creating the Basic Folder Structure of Your Media Library

As explained in this post your folder structure for Jellyfin should look like this:

 mnt/media/
├── Movies/
├── Shows/
└── Music/

To create these folders in /mnt/media use this command:

sudo mkdir -p /mnt/media/Movies /mnt/media/Shows /mnt/media/Music

To verify this worked:

ls -l /mnt/media

It should look something like this:

drwxr-xr-x 2 root root 4096 Jan 17 13:47 Movies
drwxr-xr-x 2 root root 4096 Jan 17 13:47 Music
drwxr-xr-x 2 root root 4096 Jan 17 13:47 Shows

The root:root ownership won’t work for your normal user. Let’s fix that.

Change ownership of the folders:

sudo chown -R <username>:<username> /mnt/media

Example:

sudo chown -R kryptikwurm:kryptikwurm /mnt/media

To verify the ownership change worked:

ls -l /mnt/media

It should now look like this:

drwxr-xr-x 2 kryptikwurm kryptikwurm 4096 Jan 17 13:47 Movies
drwxr-xr-x 2 kryptikwurm kryptikwurm 4096 Jan 17 13:47 Music
drwxr-xr-x 2 kryptikwurm kryptikwurm 4096 Jan 17 13:47 Shows

Now grant Read, Write, and Execute to this user:

sudo chmod -R 770 /mnt/media/

To verify the permission change worked:

ls -l /mnt/media

It should now look like this:

drwxrwx--- 2 kryptikwurm kryptikwurm 4096 Jan 17 13:47 Movies
drwxrwx--- 2 kryptikwurm kryptikwurm 4096 Jan 17 13:47 Music
drwxrwx--- 2 kryptikwurm kryptikwurm 4096 Jan 17 13:47 Shows

Section 2: Setting Up SMB (Samba) Shares

Step 1: Install Samba and Nano

To share folders and files between your Linux server and other devices (including Windows boxes), you need Samba. Think of Samba as the bridge that connects different operating systems so they can swap files without drama.

You’ll also want Nano, a beginner-friendly text editor for Linux. It’s perfect for quickly editing config files without fuss.

To install both Samba and Nano in one step, run:

sudo apt install samba nano -y

This tells your server to download and install the required packages automatically. The -y flag confirms the installation for you.

Open the Samba configuration file for editing:

sudo nano /etc/samba/smb.conf

Add the following section at the end of the file to define the media share:

 [Media]
 path = /mnt/media
 browseable = yes
 read only = no
 guest ok = no
 valid users = your-username

Save and exit Nano:

Press Ctrl+O to save changes.
Press Enter to confirm.
Press Ctrl+X to exit.

So what does all of this actually do? Let’s break it down:

`[Media]`

This is the name of the share. When you connect from a client device, this is what shows up in the network. Change it to something meaningful for your setup, like [Movies] or [Files].

`path = /mnt/media`

This points to the directory on your server that gets shared. In this example, the folder /mnt/media is being shared. Replace /mnt/media with the actual path of the directory you want to share.

`browseable = yes`

Setting this to yes makes the share visible when users browse the network. Set it to no and users have to know the share’s name to connect manually.

`read only = no`

This lets users add, modify, or delete files in the share. Set it to yes and the share becomes read-only.

`guest ok = no`

This blocks unauthenticated users (guests) from touching the share. Only users with valid credentials get in.

`valid users = your-username`

This restricts access to the share to the specified username. Replace your-username with the actual username you set up on the Ubuntu server. Only that account can connect.

Step 3: Create a Samba User

Add your server user as a Samba user:

sudo smbpasswd -a your-username

Follow the prompts to create a password for the Samba user.

Step 4: Restart Samba Service

Restart the Samba service to apply the changes:

sudo systemctl restart smbd

On Windows

Open File Explorer and type the server’s IP address in the address bar, prefixed with \\:

\\<server-ip>\<share-name>

Example: \\192.168.1.100\media

Enter your Samba username and password when prompted.

The shared folder should now be accessible, and you can drag and drop files into it.

On macOS or Linux

Open your file manager and choose “Connect to Server” (or a similar option).
Enter the SMB address:

smb://<server-ip>/Media

Example: smb://192.168.1.100/Media.

Conclusion

Adding storage and setting up SMB shares looks intimidating until you’ve done it once. By the end of this guide you added a new drive, built a clean media library structure, and shared it across your network with Samba. Your server can now accept files from any machine on your LAN.

Next, test the share by copying a movie file from your desktop to \\<server-ip>\media\Movies. If it lands and you can read it back, your storage layer is done. If Windows throws a permission error, recheck the chmod -R 770 and the valid users line in smb.conf first. Those are the two settings that bite most people.

Storage is ready. Head to Part 3 of this series to install Jellyfin and start serving your collection.

Jellyfin Folder Structure & File Naming: Auto-Fetch Metadata

Sun, 12 Jan 2025 09:47:56 -0700

What Is Jellyfin Folder Structure and Why Does It Matter?

Jellyfin folder structure is the specific way you organize media files so Jellyfin can automatically fetch metadata, display posters, and group content correctly. Getting this wrong can cause blank posters, duplicate movies, and scattered TV episodes. Using the proper folder structure makes everything work automatically, no manual intervention needed.

Remember: it’s almost never Jellyfin’s fault. It’s your folder structure and file naming.

I know what you’re thinking, “But it worked fine in Kodi!” or “My folders make perfect sense to me!” I’ve been there too. When I migrated from Kodi to Jellyfin, I thought my organization was solid. It mostly was. But “mostly” meant duplicate movies, missing shows, and entire seasons that refused to group correctly. Once I fixed the structure and naming, everything fell into place.

Jellyfin is good at fetching posters, descriptions, cast info, and episode data from TMDB and TheTVDB. But it needs your help. It can’t read your mind. It reads your folder names and filenames, then matches them against online databases.

This guide will show you exactly how to organize your media so Jellyfin’s metadata matching works without manual cleanup.

The Three Rules That Break Everything

Before we dig in, three mistakes cause about 90% of metadata problems:

1. Missing release years on movies

Without the year, Jellyfin’s playing a guessing game. “The Thing” could be the 1982 classic or the 2011 prequel. Guess which one it picks? Usually the wrong one.

2. Wrong season/episode format

Use S01E01, not 1x1 or Season 1 Episode 1 or whatever creative variation you’ve got going on. Jellyfin expects a specific format, and anything else confuses it.

3. Mixed content types in one library

Movies and TV shows need separate libraries. Mix them, and you’ll get generic metadata, broken browsing, and a headache.

Get these three right and most of your problems disappear.

Why Folder Organization Matters for Jellyfin

You probably have thousands of files that work fine in your file browser. Why does Jellyfin care how they’re named?

Because Jellyfin doesn’t know what your files are. It looks at folder names and filenames, then tries to match them against online metadata providers. When your media organization is correct, Jellyfin can automatically:

Download posters and background art
Group TV episodes into seasons
Sort movies correctly
Display accurate titles, summaries, and cast info

When it’s wrong? You get blank posters, duplicate movies, TV episodes listed as individual videos, and missing or mismatched metadata.

That flat folder with 500 randomly-named movie files might work for you, but it’s a nightmare for automated metadata. And honestly, it’ll become a nightmare for you too once your library hits a few hundred items.

Seagate Barracuda 24TB Internal Hard Drive Large, reliable storage is essential for organizing and storing a well-structured media library that Jellyfin can index and fetch metadata from accurately; however, this drive is best for single-drive or light-duty setups rather than high-availability NAS arrays.

Amazon Price: Loading...

Availability: Checking...

Contains affiliate links. I may earn a commission at no cost to you.

Start With the Right Top-Level Folder Structure

Before you worry about individual filenames, get your top-level structure right. Jellyfin works best when each media type lives in its own library.

Here’s what I recommend:

/media
├── movies
├── shows
└── music

Each of these folders should be added to Jellyfin as a separate library, with the correct library type selected. Don’t mix movies and TV shows in the same library. I know it seems convenient, but it breaks everything. Mixed content gets generic metadata and kills browsing features.

How to Organize Jellyfin Library: Movies

Movies need one movie per folder, with the movie name and release year clearly visible. That’s it. That’s the secret.

The Correct Movie Folder Structure

/movies
└── Inception (2010)
 ├── Inception (2010).mkv
 ├── Inception (2010).srt
 └── poster.jpg

Critical rules:

One folder per movie
Include the release year in parentheses
Movie file name should match the folder name

Why the Year Matters

Remember “The Thing” example? Without the year, Jellyfin picks one version, often the wrong one. “The Thing (1982)” eliminates the guesswork entirely. Same goes for “True Grit” (1969 vs 2010), “Halloween” (1978 vs 2018), and dozens of other remakes.

Five seconds adding a year saves you ten minutes of manual metadata fixing later.

Extras and Bonus Content

If you’ve got deleted scenes or behind-the-scenes content, Jellyfin supports that:

Inception (2010)
├── Inception (2010).mkv
└── Extras
 └── Behind the Scenes.mkv

When you open the movie in Jellyfin, you’ll see an Extras section populated automatically.

What About Deep Folder Structures?

Some people organize like /movies/Christopher Nolan/Inception/. It can work if everything’s named perfectly, but honestly? It adds complexity without much benefit. The official Jellyfin documentation recommends keeping movies directly under the movies root for reliability.

Fractal Design Define 7 XL A quiet full-tower keeps a homelab or media server tidy, with enough drive room that the library can grow into the folder structure this guide recommends. It’s overkill for a small or prebuilt system.

Amazon Price: Loading...

Availability: Checking...

Contains affiliate links. I may earn a commission at no cost to you.

TV Show Folder Structure for Jellyfin

TV shows are where things get finicky. You need season folders and strict episode naming.

The Correct TV Show Structure

/shows
└── Breaking Bad
 ├── Season 01
 │ ├── Breaking Bad - S01E01.mkv
 │ └── Breaking Bad - S01E02.mkv
 └── Season 02
 └── Breaking Bad - S02E01.mkv

Episode Naming Rules

Use SXXEYY format for episodes
Always use leading zeros: S01, not S1
Episode numbers matter more than episode titles

You can include episode titles if you want (Breaking Bad - S01E01 - Pilot.mkv), but the S01E01 part is what Jellyfin parses for matching.

Multi-Episode Files

Got one file that contains multiple episodes? No problem:

Breaking Bad - S01E01-E02.mkv

Jellyfin understands this and will split the metadata correctly. You’ll see two episodes in the interface, both pointing to the same file.

Music Folder Organization

Music works differently. Embedded metadata matters more than filenames.

Recommended Music Structure

/music
└── Daft Punk
 └── Random Access Memories
 ├── 01 - Give Life Back to Music.flac
 ├── 02 - The Game of Love.flac
 └── 03 - Giorgio by Moroder.flac

Important: Artist and album folders help with browsing, but embedded tags (artist, album, track number) drive the metadata. If your music metadata is messy, use a tag editor like MusicBrainz Picard before importing. Jellyfin can’t fix bad tags. It only displays what’s already in the file.

Adding Your Media to Jellyfin Libraries

Your folders are organized. Now add them to Jellyfin:

Open the Jellyfin dashboard
Go to Libraries
Click Add Media Library
Select the correct type: Movies, TV Shows, or Music
Add the matching folder path
Enable metadata providers (TMDB for movies, TheTVDB for TV)
Save and scan

⚠️

Warning: Double-check that the library type matches the content. A movie library pointed at TV folders will never behave correctly. I’ve done this. It’s confusing as hell.

When the scan finishes, you should see posters appearing, episode counts looking right, and metadata filling in. If you see that, you’re golden.

Scan, Verify, and Fix Early

After the first scan, don’t assume everything worked. Spot-check a few movies and shows:

Confirm posters and summaries appear
Look for duplicates or missing items
Check that TV seasons are grouping correctly

When I first migrated from Kodi, I assumed my structure was fine. The missing years and inconsistent episode naming caused duplicates and ignored seasons. Fixing filenames solved it way faster than any manual metadata edit would have.

Catch problems early when you’ve got 50 items, not after you’ve imported 5,000.

Advanced Tools and Automation

For large libraries, manual renaming is painful. Tools like Filebot or Sonarr can automate proper naming using the same patterns I’ve shown here.

But here’s the thing: automation is powerful, but mistakes scale quickly. Always test changes on a small batch first. I once accidentally renamed 200 movies incorrectly because I didn’t check the pattern. Don’t be like me.

NVIDIA SHIELD Pro Nice to have but not required. A premium streaming client like the SHIELD Pro displays an organized Jellyfin library cleanly and handles advanced playback features, but any capable client will do once your folders are right.

Amazon Price: Loading...

Availability: Checking...

Contains affiliate links. I may earn a commission at no cost to you.

Troubleshooting Common Jellyfin Organization Issues

Jellyfin Shows Blank Posters

Check the folder and filename format
Add the release year for movies
Refresh metadata after fixing names (right-click the item, Refresh Metadata)

Movies Appear Twice

Same movie exists in multiple folders
Different naming variations creating duplicate matches (like “Inception (2010)” and “Inception”)

TV Episodes Not Grouped Into Seasons

Episode names missing SXXEYY format
Season folders incorrectly named or missing
Episodes placed at the show root instead of season folders

This one drove me nuts for a week before I realized I had episodes sitting directly in the show folder instead of in Season folders.

Music Albums Mixed or Incorrect

Embedded tags are wrong or missing
Fix tags with a music tagger before rescanning
Jellyfin can’t guess music metadata from filenames alone

Library Scans but Nothing Appears

Wrong library type selected (movies scanning TV content)
Pointing to the wrong folder path
File permissions preventing Jellyfin from accessing the files (the Jellyfin process needs read access; on Linux check ownership with ls -ln /media and confirm the jellyfin user or your Docker PUID/PGID can read the tree)

Check the Jellyfin logs if you’re stuck. They’ll usually tell you exactly what’s wrong. The dashboard exposes them at Dashboard > Logs, and on a typical Linux install they also live in /var/log/jellyfin/ (Docker users: /config/log/ inside the container).

Get Your Jellyfin Folder Structure Right Once

Proper Jellyfin folder structure is the foundation of a working library. When your folders and filenames follow these patterns, metadata fills in on its own. Posters appear, seasons group correctly, and you stop fighting your server.

Take the time to organize your Jellyfin library correctly once. It saves countless hours of manual fixes later.

If you’re starting fresh, organize first, then scan. Your future self will thank you. And if you’ve already got a messy library, it’s painful to fix, but it’s worth doing before it grows another thousand files.

Master the Basics - How to Use Fdisk to Create Partitions Format Them and Add a Mount Point

Sun, 12 Jan 2025 08:34:30 -0700

So you bought that multi-terabyte hard drive and want to bolt it onto your server. You’re staring at a fresh disk and you’re not sure where to start. I’ve got you covered.

Setting up storage on Linux looks intimidating the first time, especially when fdisk and fstab enter the picture. It’s not as bad as it looks. By the end of this guide you’ll know how to carve up a disk with fdisk, slap a filesystem on it, and wire it into fstab so it mounts automatically at boot.

The Power of Partitions (and Why They Matter)

Think of your hard drive as a giant empty filing cabinet. Without partitions, your system has no idea how to organize or access any of that space. Partitions break the drive into smaller sections, each with a specific purpose. Data here, programs there, backups over in the corner. That separation is what keeps things sane when something goes sideways.

fdisk is the tool that creates and manages those partitions. It ships with almost every Linux distribution, so you don’t have to install anything. I’ll walk you through every step, whether you’re setting up a brand-new drive or reorganizing an existing one.

Step-by-Step Guide to Using `fdisk`, Formatting Partitions, and Configuring `fstab`

Step 1: Identify the Target Disk

Before you touch anything, figure out which drive you’re working with. Use lsblk to list every disk and partition the kernel can see:

lsblk

You’ll get something like this:

NAME MAJ:MIN RM SIZE RO TYPE MOUNTPOINT
sda 8:0 0 500G 0 disk
├─sda1 8:1 0 1M 0 part
├─sda2 8:2 0 2G 0 part /boot
└─sda3 8:3 0 498G 0 part /
sdb 8:16 0 12.7T 0 disk

Here sda is your main disk and sdb is the empty drive. We’ll work with sdb for the rest of this tutorial.

⚠️ Caution: Double-check the disk name before you do anything destructive. Pick the wrong one and you wipe a drive full of data you wanted to keep.

Step 2: Launch `fdisk`

Open fdisk against the target disk:

sudo fdisk /dev/sdb

You’ll see a prompt like this:

Command (m for help):

Type m to see the available commands.

Step 3: Create a New Partition

1. Delete Old Partitions (Optional)

If the disk already has partitions you want gone, type d and follow the prompts to delete them.

2. Create a New Partition

To create a new partition, type n and press Enter. fdisk will ask:

Partition type: Choose p for primary or e for extended. Pick p for most use cases.
Partition number: Press Enter to accept the default (usually 1).
First sector: Press Enter to accept the default (start of the disk).
Last sector: Press Enter to use the entire disk, or specify a size like +100G for a 100GB partition.

When you’re done you’ll see the new partition listed.

3. Write Changes to Disk

Type w to save the changes and exit fdisk. This writes the partition table to the disk. Nothing you’ve done so far touches the disk until you hit w, so if you panicked halfway through you can always quit with q and walk away.

Step 4: Format the Partition

You’ve got a partition, but it has no filesystem on it yet. A common choice is ext4. For a media server hosting big files, I reach for XFS instead.

sudo mkfs.xfs /dev/sdb1

That formats the first partition on sdb with XFS. Swap xfs for ext4 or btrfs if you’d rather use those.

Run lsblk again and the output should look similar to this:

NAME MAJ:MIN RM SIZE RO TYPE MOUNTPOINT
sda 8:0 0 500G 0 disk
├─sda1 8:1 0 1M 0 part
├─sda2 8:2 0 2G 0 part /boot
└─sda3 8:3 0 498G 0 part /
sdb 8:16 0 12.7T 0 disk
└─sdb1 8:17 0 12.7T 0 part

Step 5: Create a Mount Point

A mount point is where the system will hang the partition in the filesystem tree. For a media drive, something like this works:

sudo mkdir -p /mnt/media

The -p flag tells mkdir to create any parent directories that don’t exist yet.

Step 6: Mount the Partition (Temporary Test)

Before you commit anything to fstab, test the mount by hand:

sudo mount /dev/sdb1 /mnt/media

Verify it’s mounted:

df -h

You should see /dev/sdb1 listed with /mnt/media as its mount point. If you don’t, stop here and figure out why before you touch fstab.

Step 7: Add the Partition to `fstab`

Now you want this thing to come back automatically after a reboot. That’s what /etc/fstab is for. Start by grabbing the partition’s UUID:

sudo blkid /dev/sdb1

You’ll see output like this:

/dev/sdb1: UUID="1234-5678-90AB-CDEF" TYPE="xfs"

Copy that UUID and open fstab:

sudo nano /etc/fstab

Add this line at the end of the file:

UUID=1234-5678-90AB-CDEF /mnt/media xfs defaults 0 2

Here’s what each field does:

UUID=1234-5678-90AB-CDEF: Unique identifier for the partition. Survives drive reordering, unlike /dev/sdb1.
/mnt/media: Mount point.
xfs: Filesystem type.
defaults: Standard mount options.
0 2: Dump and fsck options. Safe to leave as-is for a data drive.

Save the file and exit.

Step 8: Test the `fstab` Configuration

Now verify your changes work without rebooting. Unmount the partition, then remount everything in fstab:

sudo umount /mnt/media
sudo mount -a

If mount -a returns clean with no errors, your configuration is good. If it throws an error, fix the fstab line before you reboot. A broken fstab can drop the system into emergency mode on the next boot, and digging your way out of that is no fun.

Wrapping It All Up

You’ve carved up a disk, formatted it, and wired it into fstab so it mounts on every boot. That same pattern works for media storage, backup targets, Docker volume directories, or anywhere else you need a dedicated chunk of disk.

One last warning. Always double-check the disk name in lsblk before you run fdisk or mkfs, and back up anything important before you reorganize a drive that already has data on it. The commands here don’t ask for confirmation, and there’s no undo.

Master the Basics - How to SSH Into a Linux Server

Sun, 12 Jan 2025 07:33:02 -0700

💭

TL;DR: SSH lets you control your Linux server from any computer on your local network. Install an SSH client, run ssh user@server-ip, and you’re in. Keep it off the public internet.

Do you need to keep a monitor and keyboard hooked up to your server? Nope. SSH lets you reach your server’s command prompt from your Windows, Mac, or Linux box. You’ve probably seen SSH thrown around in forums and tutorials. It’s the tool that lets you run your Linux server from anywhere on your local network.

One rule first. Do not expose your SSH port to the internet unless you know exactly what you’re doing and have a good reason. Bots scan for open port 22 every minute of the day. Keep it inside your LAN.

I’ve been running SSH on my own home media server for years. Here’s how to set it up without shooting yourself in the foot.

What Is SSH, and Why Should You Care?

SSH stands for Secure Shell. It’s an encrypted protocol that lets you log into a remote machine over the network and run commands as if you were sitting at the keyboard. Want to manage your server from the couch with a laptop on your lap? That’s SSH.

With an SSH session you can run commands, edit configs, copy files with scp or rsync, and troubleshoot the box without ever plugging in a monitor. For a home media server, it’s the difference between a project and a chore.

Why You Shouldn’t Expose SSH to the Internet

Quick security detour before the how-to. Putting your SSH server on the public internet is asking for trouble. Bots and opportunistic attackers scan the entire IPv4 space for open port 22 around the clock. Find your host, and they’ll start brute-forcing usernames and passwords until something gives.

Three reasons to keep SSH on your LAN only:

Reduced Attack Surface: Only devices already on your home network can even attempt a connection.
Less Config Pain: No firewall holes, no fail2ban rules, no key-only enforcement to maintain.
No Port Forwarding or VPN: You don’t need to stand up WireGuard or punch holes in your router for a single shell session.

If you genuinely need remote access from outside your house, put SSH behind a VPN like WireGuard or Tailscale. Don’t forward port 22 and hope for the best.

Step-by-Step Guide to SSH into Your Linux Server

1. Check Your Server’s IP Address

You need the server’s local IP before you can connect. Log in at the console and run:

ip addr

Look for the inet line under your active network interface (usually eth0, ens18, or similar). The address will look like 192.168.x.x or 10.0.x.x. That’s the one you want.

Example:

2. Install an SSH Client on Your Computer

Windows: Use the built-in OpenSSH client in PowerShell, or grab PuTTY if you prefer a GUI.
Mac/Linux: Your terminal already has ssh installed. Open it and skip ahead.

3. Connect to the Server via PowerShell

On Windows, hit the Start key, type PowerShell, and click Windows PowerShell.

ssh username@192.168.x.x

Swap username for your Linux account and 192.168.x.x for your server’s IP.

For example:

ssh john@192.168.1.100

First connection? You’ll see a prompt asking you to verify the server’s fingerprint. Type yes and hit enter.

4. Enter Your Password

The server prompts for your password next. Type it in carefully. The terminal won’t echo characters as you type, which is normal and intentional. Hit enter.

If the connection works, you’ll land at a shell prompt like this:

KryptikWurm@mediaserver:~$

You’re in. Run whoami or hostname to confirm.

5. Troubleshooting Common Issues

“Connection Refused”: The SSH service isn’t running on the server. On the server’s console run:

sudo systemctl start ssh

On some distros the unit is named sshd instead, so try sudo systemctl start sshd if the first one fails. To make it survive reboots: sudo systemctl enable ssh.

“Permission Denied”: Wrong username or wrong password. Double-check both. Linux usernames are case-sensitive.
“No Route to Host” or hangs forever: Server and client aren’t on the same subnet, or a host firewall is blocking port 22. Check sudo ufw status on Ubuntu or sudo firewall-cmd --list-all on Fedora/Rocky.
Can’t find the IP at all: Confirm the server is on your LAN and not isolated on a guest VLAN.

Frequently Asked Questions

➤ What port does SSH use by default?

SSH listens on TCP port 22 by default. You can change it in /etc/ssh/sshd_config by editing the Port line and restarting the service with sudo systemctl restart ssh. Changing the port doesn’t make SSH meaningfully more secure, it only cuts down on log noise from drive-by bots.

➤ Should I use SSH keys instead of a password?

Yes, especially if SSH will ever leave your LAN. Generate a key on the client with ssh-keygen -t ed25519, copy it to the server with ssh-copy-id user@server-ip, and then disable password login in /etc/ssh/sshd_config by setting PasswordAuthentication no. Restart sshd and you’re key-only.

➤ How do I copy files over SSH?

Use scp for one-off file transfers: scp localfile user@server-ip:/remote/path/. For directory sync, rsync -avz localdir/ user@server-ip:/remote/path/ is faster and handles interruptions. Both run over the same SSH connection, so no extra setup is needed.

➤ Why does the terminal not show my password as I type it?

That’s deliberate. SSH suppresses the echo so someone glancing over your shoulder can’t count characters or guess the length. Type the password as normal and hit enter. It’s still being entered, you can’t see it.

Keep It Local, Keep It Safe

SSH is a power tool. Keep it on your LAN and you get every benefit of remote management with almost none of the risk. Open it up to the internet without a VPN and you’re putting your server on a list of free targets.

Open a terminal, run ssh user@your-server-ip, and start working your media server from wherever you sit in the house. If you ever do need outside access, put it behind WireGuard or Tailscale first. Safety third.

Turn an Old Computer Into a Media Server Part 1 Hardware and Installing Linux

Fri, 10 Jan 2025 09:07:02 -0700

Got an old computer collecting dust in the closet? The one you swore you’d find a use for someday? Today’s the day. Instead of dropping hundreds (or thousands) on shiny new hardware, you can turn that machine into a working media server. It’s a cheap way to learn the ropes of home media servers before you commit real money.

And the best part? You don’t need much to get going. A little time and some free software, and you’ll be streaming your movies, shows, and music from that old box. Here’s what you need and how to wire it up.

Why Start With an Old Computer?

There’s one rule when you’re new to home media servers: start small, upgrade later. The common mistake is jumping straight into an expensive custom build, then realizing the hobby isn’t what you thought it would be. An old computer is a low-risk way to learn the basics and find out if this is your thing.

Think of it as training wheels. You learn how to install software, organize your media, and troubleshoot the inevitable weirdness, all without burning cash on high-end hardware. And it’s eco-friendly. That old PC gets a second life instead of a trip to the e-waste pile.

Minimum Specifications: What Does Your Old Computer Need?

You don’t need a gaming rig to run a basic Ubuntu-based Jellyfin server. Ubuntu Server and Jellyfin are both lightweight, so your old machine can probably handle it. Here’s the bare minimum to get started.

Bare Minimum Hardware Requirements

Processor (CPU): Intel Core i3 2nd Gen or AMD equivalent
RAM: 4 GB
Storage: At least 100 GB of free space (more if you plan to store lots of media locally).
Operating System: Ubuntu Server 24.04 LTS
USB Stick: 32 GB for the OS installation
Network: An Ethernet connection (wired or Wi-Fi)

That’s enough to get a Jellyfin server on its feet. As your library grows or you want extra features, you can upgrade later.

Best Experience Recommended Hardware

Processor: No change
RAM: 8 GB
OS Storage: 200 GB of SSD storage

Kingston 240GB SSD

A cheap, dependable SATA SSD for a boot drive. 240GB is plenty for a Linux install plus Docker images and leaves the spinning disks free to do nothing but hold media. Not fast by NVMe standards and not what you want for a cache tier, but it is the standard answer for getting an old desktop booting off flash instead of a tired hard drive.

Amazon Price: Loading...

Availability: Checking...

Amazon

Contains affiliate links. I may earn a commission at no cost to you.
Media Storage: 8 TB or more depending on the size of your media collection

Seagate Barracuda 24TB Internal Hard Drive

A 3.5-inch SATA desktop-class drive that delivers huge capacity for bulk storage. Perfect for media libraries, game installs, and cold backups without paying NAS/enterprise premiums. Best for single-drive or light-duty DAS use

Amazon Price: Loading...

Availability: Checking...

Amazon

Contains affiliate links. I may earn a commission at no cost to you.
Network: A wired ethernet connection is best

If your computer meets these specs, you’re ready. If not, you can probably still make it work with a few tweaks, especially if you’re not asking it to transcode video on the fly. Transcoding gets its own post later in the series.

Proof Old Computers Will Work

To show you this works on real, old hardware, I’m building a media server with these parts:

Processor: i5-2500k. This CPU shipped in 2011.
RAM: 16 GB
OS Storage: 500 GB SSD
Media Storage: Two 2 TB Hard Drives
Video Card: NVIDIA 750ti (only needed for the install)

So you’ve found a candidate machine. Now it’s time to turn it into a media server by installing Ubuntu Server 24.04 LTS. This release is built for secure, efficient server work, and it runs fine on older hardware. Here’s how to get it installed and out of your way.

And yes, Debian or any other mainstream Linux distro will work. I picked Ubuntu because it’s popular, well-documented, and you’ll find an answer to almost any question with one search.

Installing Ubuntu Server 24.04 LTS

Time for the fun part. Follow these steps to get Ubuntu 24.04 installed and running.

1. Prepare Your Old Computer and Thumb Drive

Hook up a monitor, keyboard, and mouse for setup.
Download the Ubuntu Server 24.04 LTS ISO from Ubuntu.com.
Use Rufus (on Windows) or Etcher (on macOS/Linux) to write a bootable USB drive with the ISO.

2. Use Rufus to Create a Bootable Thumb Drive

Download the portable version of Rufus
Open Rufus
Press SELECT to pick the Ubuntu Server ISO you downloaded, then press START
When prompted, write in DD Image mode
Press OK to format the USB stick
- This wipes everything on the drive.

You now have a bootable USB stick with Ubuntu Server on it.

3. Boot from USB

Insert the bootable USB into the computer you’re installing Ubuntu on.
Power on and enter the BIOS/UEFI settings. The hotkey is usually F2, F12, Del, or Esc during the splash screen.
Set the boot order so USB comes before the hard drive. That way, if a USB is present, the system boots from it first.
Save and exit. The system reboots into the Ubuntu Server installer.

4. Begin the Installation

GNU Grub Menu. When prompted, press enter.
Select your default language
Select your keyboard layout
Pick the install type. Select Ubuntu Server (minimized) and “Search for third-party drivers”.
Network Config. This is a server, so it needs a static IP (one that doesn’t change). Tab up to the network device name (yours will be different) and press enter.
You’ll see this menu. Select Edit IPv4 and press enter.
Select Manual from the menu and press enter
My network config will be different from yours. Chances are your network is on the 192.168.0.0/24 or 192.168.1.0/24 subnet. If you don’t know what your network is, open PowerShell on Windows and run:

ipconfig -all

The ipconfig output gives you everything you need for the IPv4 config page.
One thing changes between Windows and Linux: the subnet format. Windows shows 255.255.255.0. Linux wants CIDR. Take your IP, change the last octet to 0, and tack on /24, like this:

192.168.0.0/24
or
192.168.1.0/24

Proxy Config. Leave this blank unless you know you’re behind a proxy.
Guided Storage Configuration. For this first setup, leave everything default. I’ll cover a more advanced storage layout in another post.
Storage Config Summary
Confirm Destructive Action. This wipes everything from the selected drive.
Profile Configuration
- Your name. Not the username. I make my username and name match.
- Your server name. What do you want to call your server?
- Pick a username. I use what I put in the Your name block.
- Password. Make this a strong one.
Upgrade to Ubuntu Pro. Skip for now.
SSH Config. Select Install OpenSSH server.
Third-party drivers. If you have any, install them here.
Featured Server Snaps. Leave all of these blank.
The install takes a few minutes. When it’s done, remove the USB stick and reboot.
Login. Confirm you can log in with the username and password you set during the install.
Update the server. Run this to pull any updates. I run it about once a week so the box stays current on security patches.

sudo apt update && sudo apt upgrade -y

Reboot from the command line.

sudo reboot

Sharp-eyed readers will notice I’m installing this on a VM, not the i5-2500k. That’s how I captured the screenshots. I’ll install Ubuntu on the physical box and use it going forward.

Congratulations. You’ve set up an Ubuntu server.

Ready to bring your media server to life? Head to Part 2 to install Jellyfin and get one step closer to streaming your library.

Stop Winging It - Use Obsidian to Master Your Server and Network Notes

Sat, 04 Jan 2025 07:22:27 -0700

Ever feel like the deeper you go into self-hosting, the more it slips out of your head? Proxmox, Docker, Jellyfin, the ARR suite. It piles up fast, and the little details disappear first. That’s where Obsidian comes in. Think of it as your personal command center for every note, command, and half-finished guide you’ve collected while building your homelab.

Honestly, I wish I’d started using it sooner. For years I worked on my home server without writing down a thing. Now I’m stuck retracing my steps, trying to remember how I configured something or what fixed that one weird issue six months ago. It’s frustrating. And it taught me the hard way how valuable a well-organized set of notes really is.

So here’s how Obsidian can save you from that same pain and give your homelab documentation a real home.

Why Documenting Your Journey Matters

A home server isn’t a one-time project. It’s an ongoing adventure. From standing up your first Proxmox node to fine-tuning backups and notification automation, there’s a lot to learn and even more to forget. Writing it down helps you:

Remember what you did: That one-off command that fixed Docker or your NFS share? It’s gone the moment you close the terminal unless you write it down.
Save time later: When it’s time to upgrade hardware or chase a bug six months from now, your own notes will save you hours of Googling.
Learn from your mistakes: Tracking what worked and what blew up helps you refine your setup and stop repeating the same dumb errors.

I wish I’d started documenting on day one. It would’ve saved me weeks of guessing now that I’m trying to reconstruct commands, configs, and fixes I figured out years ago. It feels pointless to write things down while you’re in the flow. Trust me, your future self will thank you.

Why I Like Obsidian

Here’s why Obsidian is my go-to for documenting my home server setup:

Everything in One Place: All my notes, commands, and guides live in one spot. No more scattered text files, sticky notes, or screenshots buried in Downloads.
Linked Notes: I love how Obsidian lets me link notes together. My “Docker Setup” note connects straight to my “Sonarr Configuration” note. It makes it easy to see how the pieces fit.
Markdown: Obsidian uses plain Markdown. It’s lightweight, easy to write, and exports anywhere without extra tools.
Personal Knowledge Base: Over time, my Vault has grown into a custom knowledge base tailored to my home server. Every fix, every config, every hard-won lesson.
Offline Access: If I knock my internet offline while poking at the firewall (it happens), no problem. Obsidian works entirely offline. Sync the Vault to OneDrive or Google Drive and you can pull it up on any other computer too.
Visual Representation of Notes: Obsidian’s graph view maps how all my notes connect. It’s oddly satisfying, and it shows you the shape of your own documentation.

These features have been a big deal for me. If I’d started using Obsidian sooner, I’d have saved myself a lot of frustration and made the whole homelab journey smoother.

Here’s what my graph view looks like after about 2 months:

Getting Started with Obsidian

Obsidian Download Link

Here’s how I use Obsidian to document my home server setup:

Create a Vault: In Obsidian, a Vault is where all your notes live. I made one specifically for my home server and called it “Home Data Center.” Pick whatever name makes you smile.
Organize with Categories: Set up folders or tags for the things you run. Mine has “Proxmox,” “Docker,” “Jellyfin,” and “Usenet.” It keeps the mess sorted from day one.
Document as You Go: When you fix a problem, install a new tool, or try something weird, write it down right then. Drop in screenshots and links to whatever guides got you there.
Link Related Notes: My “Radarr Setup” note links to my “Docker Compose” note. Now I can see at a glance how the two depend on each other.
Add a Daily Log: Obsidian’s Daily Notes feature gives me a running journal. What I worked on, what I learned, what broke and how I fixed it.

The best part about Obsidian is how flexible it is. Whether you write detailed guides or quick bullet points, it bends around how you think.

Practical Examples of Using Obsidian

Here’s how I use Obsidian to keep my home server sane:

Proxmox Setup Notes: A step-by-step guide for setting up VMs, with the exact commands, screenshots of the web UI, and links to the official Proxmox docs.
Troubleshooting Logs: When something breaks, like Sonarr losing its connection to SABnzbd, I document the error and the fix. So I never have to solve the same problem twice.
Wish Lists: A running list of things I want to add, like a VPN or a reverse proxy, with links to the guides that look promising. (Bonus points if they link back to diymediaserver.com.)
Personal Wiki: Over time, the Vault has turned into a custom knowledge base for my entire home server setup. As I add services or tweak configs, the notes grow with me.

These examples have saved me hours of repeated frustration. If you’re building or running a home server, Obsidian belongs in your stack.

Stick With It

If there’s one lesson I’ve learned the hard way, it’s that good documentation is priceless. Trying to rebuild a home server setup from memory is miserable and slow. You don’t have to do that.

Start documenting now with Obsidian. A few minutes of typing today can save you hours, or whole evenings, six months from now. And you’ll end up with a record of your progress that’s genuinely satisfying to look back on.

Don’t put off documentation. Your future self will thank you. Download Obsidian today and start building your second brain for your media server adventure.

Kodi vs Plex vs Jellyfin vs Emby: Which Is Best in 2026?

Fri, 03 Jan 2025 06:21:40 -0700

You’ve spent hours setting up a home media server. Movies, TV shows, and music are organized and ready to go. Now you have to pick the playback software. Kodi, Plex, Jellyfin, and Emby are the four serious options. Each one solves the same problem in a different way.

I’ve run all four on my own gear, and I landed on a hybrid: Kodi as the front-end player, Jellyfin as the backend server, with the Jellyfin for Kodi add-on bridging the two. Kodi handles the interface and local playback. Jellyfin handles watched-status sync, remote streaming, and transcoding. That combo is what this comparison keeps coming back to, but the right answer for you depends on which trade-offs you care about.

The Basics: What Do These Programs Do?

All four programs organize, play, and stream a media library. The differences are in philosophy and architecture.

Kodi is a standalone media player. It runs on the device you watch on and reads files from local disk or a network share (SMB, NFS, or a mounted drive).

Plex, Jellyfin, and Emby are server-client systems. One machine runs the server and manages the library, metadata, transcoding, and user accounts. Every TV, phone, and tablet runs a client app that talks to that server.

Plex and Emby are closed-source and gate their best features behind a paid subscription (Plex Pass and Emby Premiere). Jellyfin is fully open-source and free, forked from Emby in 2018 when Emby went closed. Kodi is open-source under the GPL.

Feature Comparison: At a Glance

Here’s how Kodi, Plex, Jellyfin, and Emby stack up:

Feature	Kodi	Plex	Jellyfin	Emby
Cost	Free	Free (Premium for advanced features)	Free	Free (Premium for advanced features)
Open Source	Yes	No	Yes	No
Offline Playback	Yes	Yes (with premium)	Yes	Yes (with premium)
Live TV/DVR Support	Yes (via add-ons)	Yes (with premium)	Yes	Yes (with premium)
Streaming Outside Home	Limited	Yes (with premium)	Yes	Yes (with premium)
Customization	Very High	Limited	Moderate	Moderate
Ease of Setup	Moderate (more technical)	Easy	Moderate	Moderate
Client Support	Wide range of devices supported	Wide range of devices supported	Growing list of supported devices	Wide range of devices supported

My Setup: A Customizable Front-End on a Server Backend

I picked Kodi as my front-end media player because of how much of the interface it lets you change. No recommended shows I didn’t ask for, no ads, no upsells. Skins, menu layouts, and add-ons are all editable. If you want full control over what you see when you turn on the TV, Kodi is hard to beat.

Kodi has limits though. It does not sync watched status across devices, stream to other rooms over the network, or transcode files for clients that can’t play them natively. Jellyfin fills those gaps as the backend: run it as a server, install the Jellyfin for Kodi add-on, and you get watched-status sync, one library shared across every device, remote streaming, and on-the-fly hardware transcoding. You keep Kodi’s customization and add Jellyfin’s server features.

That pairing is its own decision, though. For most households a plain Jellyfin client is simpler than running Kodi on every TV. If you’re deciding between these two, our Kodi vs Jellyfin comparison breaks down the trade-off: server vs. client, transcoding, remote access, and when each one wins:

Kodi vs Jellyfin: Which Should You Pick? A head-to-head on server vs. client, transcoding, remote access, and which one fits your household.

Read the Comparison

The Pros and Cons of Each Platform

Kodi: The Customizer’s Dream

Pros:

Deep customization. Hundreds of skins, custom menus, and add-ons. The whole UI is yours to rebuild.
Wide device support. Windows, macOS, Linux, Android, Raspberry Pi, Fire TV, Apple TV (via sideload). A Raspberry Pi 4 is plenty for 1080p and most 4K.
Offline playback. Designed for local files. Point it at a folder or a network share and it plays.
Free and open-source. GPL licensed. Active community.

Cons:

Steep learning curve. Add-on management, skin editing, and library sources take time to learn.
No native remote streaming. Plugins and workarounds exist, but nothing matches Plex or Jellyfin out of the box.
No backend features. No native watched-status sync or cross-device library management. Pair it with Jellyfin, Emby, or Trakt to fill the gap.

Best for: Tinkerers who want a fully personalized interface for local playback.

Kodi Download Link

Plex: The Streaming Superstar

Pros:

Easy setup. The most beginner-friendly of the four. It scans your library, pulls metadata, posters, descriptions, and trailers automatically.
Remote access. Plex.tv brokers connections to your server, so streaming from outside the LAN works without a reverse proxy or VPN on your end.
Friend sharing. Share specific libraries with named users and control what they see.
Wide device support. Smart TVs, Roku, Apple TV, Fire TV, gaming consoles, iOS, Android.
Premium features. Plex Pass adds offline downloads, hardware transcoding, live TV, and DVR.

Cons:

Paywall. Hardware transcoding, offline downloads, and DVR all require Plex Pass.
Limited customization. The UI is polished but rigid compared to Kodi.
Closed source. Updates, features, and policy changes are on Plex’s schedule. Recent direction (more ad-supported streaming, account changes) has pushed some users to Jellyfin.

Best for: People who want zero-config remote streaming and don’t mind paying for the premium tier.

Plex Download Link

Jellyfin: The Open-Source Hero

Pros:

Completely free. Remote streaming, live TV, DVR, hardware transcoding, and watched-status sync are all in the base product. No paywall.
Privacy-focused. No external account, no telemetry by default. Your library and viewing data stay on your server.
Server-client architecture. Central server, plus official apps for Android, iOS, Android TV, Fire TV, Roku, web, and third-party clients including Kodi (via the Jellyfin for Kodi add-on).
Transcoding. On-the-fly transcoding with VAAPI, QSV, NVENC, and software fallback. Configure in Dashboard > Playback > Transcoding.
Active community. GitHub-driven development, frequent releases, large Matrix/Discord community.

Cons:

Setup work. Running a server, opening ports or setting up a reverse proxy, and configuring transcoding takes more effort than Plex.
Client polish varies. Roku and tvOS apps have lagged the Android/Fire TV apps in the past. Check current state for your target device before committing.
No managed remote access. You handle external access yourself (reverse proxy with Caddy or Nginx, Tailscale, or a VPN). Plex hides this with their relay.

Best for: Open-source-first homelabbers who want the premium feature set without a subscription and don’t mind a little networking work.

Jellyfin Download Link

Emby: The Middle Ground

Pros:

Balanced feature set. More configurable than Plex, more polished than Jellyfin in places.
Remote streaming. Available via Emby Connect with an Emby Premiere subscription.
Live TV and DVR. Strong recording, scheduling, and channel management tools.
Wide device support. Smart TVs, Roku, Fire TV, Apple TV, mobile.
Premium features. Emby Premiere covers hardware transcoding, offline downloads, and DVR. Pricing is comparable to Plex Pass.

Cons:

Subscription gates. Hardware transcoding, offline sync, and Cloud Sync need Premiere.
Closed source since 2018. Emby started open, then closed the core. Jellyfin is the fork of the last open version.
Smaller community. Less third-party add-on development than Kodi or Jellyfin.

Best for: Users who want Plex-style polish with a bit more configurability and are willing to pay for premium features.

Emby Download Link

Which One Should You Choose?

The right pick depends on what you care about:

Pick Kodi for the most customizable interface and local playback on a wide range of devices.
Pick Plex for zero-config remote streaming, friend sharing, and a polished UI, if Plex Pass is in budget.
Pick Jellyfin for the full feature set with no paywall and no external account.
Pick Emby for a middle ground between Plex’s polish and Jellyfin’s openness, if you’ll pay for Premiere.

My pick stays Kodi plus Jellyfin. Jellyfin runs the backend (library, sync, transcoding, remote access). Kodi is the front-end on every TV in the house, fully skinned and laid out the way I want.

Final Thoughts

There is no single winner here. Plex wins on ease. Jellyfin wins on price and openness. Emby splits the difference. Kodi wins on interface control. The fastest way to find your answer is to install two of them on a test machine, point them at the same library folder, and watch a few things. Migration between the three server apps is straightforward because they all read the same file structures and use similar metadata (NFO and image sidecar files).

Once you’ve picked, the next steps are getting the library structure right (separate folders for Movies and TV, year in folder and filename) and enabling hardware transcoding if you plan to stream to phones or off-LAN.

The Best Devices to Play Your Locally Stored Media with Kodi Plex Jellyfin or Emby

Wed, 01 Jan 2025 06:36:03 -0700

So you’ve ripped your Blu-rays, downloaded a few movies, and pointed Jellyfin or Kodi at the folder. Now what? You need a playback device on the TV side that won’t choke on a 4K HDR remux or fight you over codecs.

The good news: there’s a device for every budget and every level of patience. Here’s how the main options actually stack up for a local media library, not for Netflix subscribers.

1. Android TV Devices: Easy and Capable

If you want something that boots up and works, Android TV boxes like the NVIDIA Shield TV or Google TV Streamer are the obvious picks.

Why they work: They run Android, so the official Kodi and Jellyfin apps install straight from the Play Store. No sideloading, no ADB hoops.
Performance: The Shield handles 4K HDR, lossless audio passthrough, and AI upscaling. The Google TV Streamer is solid for 1080p and most 4K, at a fraction of the price.
Bonus: Both cover Netflix, YouTube, and the rest of the streaming pile, and both support casting from a phone or laptop.

NVIDIA SHIELD Pro

The NVIDIA SHIELD is my go-to device. I’ve run Kodi and Jellyfin on it for years and it keeps working.

Amazon Price: Loading...

Availability: Checking...

Contains affiliate links. I may earn a commission at no cost to you.

Google TV Streamer 4K

A solid runner-up if you can’t find a Shield at a sane price. The built-in Ethernet port earns its keep here, because Wi-Fi is where high-bitrate remuxes fall apart.

Amazon Price: Loading...

Availability: Checking...

Contains affiliate links. I may earn a commission at no cost to you.

2. Raspberry Pi: For People Who Like to Tinker

If you enjoy flashing SD cards and editing config files, the Raspberry Pi is a cheap and capable Kodi box.

Why it’s cool: It’s small, cheap, and fully customizable. Flash LibreELEC for a Kodi-only appliance, or run Raspberry Pi OS and put Jellyfin in Docker.
Performance: A Pi 4 handles 1080p comfortably and most 4K H.265 content. Use wired Ethernet if you can. Wi-Fi on the Pi struggles with high-bitrate remuxes.
Who it’s for: DIY folks who want a project rather than a plug-and-play box. You’ll pick up real Linux skills on the way.

RaspberryPi 4GB

A palm-sized single-board computer with a quad-core ARM CPU and 4GB RAM that runs full Linux, with Gigabit Ethernet, dual-band Wi-Fi, USB 3.0, and dual micro-HDMI. Ideal for lightweight homelab duties like Pi-hole, Home Assistant, and small Docker stacks, or for learning GPIO-based hardware projects while sipping only a few watts.

Amazon Price: Loading...

Availability: Checking...

Contains affiliate links. I may earn a commission at no cost to you.

3. Amazon Fire TV: Cheap and Everywhere

Amazon’s Fire TV Stick 4K Max and Fire TV Cube show up in every “what should I buy” thread for a reason. They’re cheap and they’re stocked.

Why they work: Both support Kodi and Jellyfin. Jellyfin is in the Amazon Appstore in most regions. Kodi needs sideloading via the Downloader app or ADB.
Performance: The Stick 4K Max handles 4K HEVC and HDR fine. The Cube is faster and adds Ethernet.
Limitations: Fire OS is Amazon’s fork of Android, so the UI is plastered with ads and the remote is built around Alexa. If that bothers you, get a Shield instead.

Amazon Fire TV Stick 4K Max

The cheapest way to put Jellyfin on a spare TV. Wi-Fi 6E is the reason to take the Max over the plain 4K stick if you’re streaming remuxes over wireless.

Amazon Price: Loading...

Availability: Checking...

Contains affiliate links. I may earn a commission at no cost to you.

Amazon Fire TV Cube

The most powerful Fire TV, with hands-free Alexa and an IR blaster so it can control your TV, receiver, and other gear by voice. It streams 4K HDR (Dolby Vision/Atmos), adds HDMI-in for set-top boxes, and includes built-in Ethernet plus Wi-Fi 6E for rock-steady playback.

Amazon Price: Loading...

Availability: Checking...

Contains affiliate links. I may earn a commission at no cost to you.

4. Dedicated HTPCs: The No-Compromise Option

If you want the best playback you can build, nothing beats a dedicated Home Theater PC (HTPC). Prebuilt mini PC, repurposed old desktop, or a full custom build. Take your pick.

Why they win: A real x86 PC running Windows or Linux can chew through anything. Blu-ray remuxes, lossless TrueHD passthrough, madVR, you name it. Pair it with an Intel iGPU or a discrete GPU and hardware decoding handles the rest.
Customizable: Run Windows, a Linux distro, or a Kodi appliance like LibreELEC. It’s your box.
Drawbacks: It costs the most, takes up the most space, and needs occasional maintenance. Worth it if quality matters more than convenience.

5. Game Consoles: Already in the Cabinet

Own an Xbox or PlayStation? You might already have a Jellyfin client.

Xbox: Both Xbox One and Series consoles have a native Jellyfin app in the Microsoft Store. Kodi runs on Xbox through the UWP build, with some quirks.
PlayStation: No native Jellyfin app. Use the web client at https://yourserver:8096 in the PS browser, or transcode and stream via Plex if you have a subscription.
Why it works: The console is already wired to the TV and configured for HDR. Free secondary client.

6. Smartphones and Tablets: Portable Players

Don’t sleep on the device in your pocket. Jellyfin, Kodi, Plex, and Emby all ship Android and iOS apps.

Why they work: Stream over Wi-Fi at home, or use the Jellyfin app’s offline downloads for flights and trains.
Features: Direct play when codecs match, transcoded streams when they don’t. Cast to a Chromecast or AirPlay receiver to throw it on the TV.
Best use case: Secondary screen in the kitchen, on the couch, or away from home.

7. Smart TVs: One Less Box

If your TV is recent, check the app store. Both Samsung Tizen and LG webOS have native Jellyfin clients, and most Android TV sets handle Kodi too.

Why it’s convenient: No extra box. No extra remote. One HDMI input free.
Limitations: Older smart TVs are slow, lack codec support for AV1 or HEVC Main 10, and their app stores get abandoned. If your TV is more than five years old, an external box is almost always faster.

Final Thoughts: Pick the One That Fits

There’s no single right answer. Match the device to the room, the budget, and how much fiddling you’re willing to do.

Living room with a 4K HDR projector? Shield or HTPC.
Bedroom with a basic 1080p TV? Fire Stick or whatever’s already plugged in.
Tinkering project? Raspberry Pi with LibreELEC.
Already own a console? Start there before buying anything.

I run a Shield in the main living room and a Pi 4 with LibreELEC in the bedroom. Same Jellyfin server behind both. Two different boxes, same library. That’s the whole point.

How to Rip DVDs and Blu Rays for Your Home Media Server

Sat, 28 Dec 2024 07:11:39 -0700

Rip your DVDs and Blu-Rays and you’ve got every movie and show in one place. No more digging through stacks of discs to find a favorite. You browse the whole collection from any device on your media server. That means you can:

Search Quickly: Use metadata like titles, genres, and cast to find movies in seconds.
Organize Effectively: Group content by genre, director, year, or any custom structure that suits your style.
Stream to Multiple Devices: With media server tools like Jellyfin or Plex, you can access your library on smart TVs, laptops, tablets, and smartphones anywhere in your home, or even remotely.

Physical DVDs and Blu-Rays wear out. Discs get scratched, warped, or lost, and your collection goes with them. Ripping your discs gives you digital backups so you can enjoy the library for years without worrying about:

Scratched Discs: No more frustration when a favorite movie freezes or skips.
Storage Challenges: Free up space and ditch the bulky disc cases and shelves.
Discontinued Titles: Preserve rare or out-of-print movies that might be impossible to replace.

The Process is Simpler Than You Think

If ripping DVDs and Blu-Rays sounds intimidating, you’re not alone. A lot of people assume it’s overly technical or needs advanced computer skills. With the right tools, it’s surprisingly straightforward.

Today’s software is built to be approachable, often only a few clicks to get going. Tools like MakeMKV and HandBrake have intuitive interfaces that walk you through it. You don’t need to be a tech expert. If you can install software and follow basic instructions, you’re good to go.

I’ll walk you through what you need, from picking the right hardware and software to organizing and storing your ripped files. And if you hit a snag, I’ve got tips and troubleshooting to help. This is a learning process. With a bit of patience and practice, you’ll feel confident in no time.

By the end of this guide, you’ll see that ripping your DVDs and Blu-Rays is doable and genuinely rewarding. You’ll have a digital library you can enjoy whenever and wherever you want. No more wrestling with physical discs. Take it one step at a time and let’s get started.

What You’ll Need

Hardware Requirements
- A DVD/Blu-Ray drive (internal or external).
  - OWC Mercury Pro 16X Blu-ray
- A computer with sufficient storage space for the ripped files.
  - DVDs about 10GB of free space
  - Blu-Ray 1080p about 40GB of free space
  - Blu-Ray 4k UHD about 100GB of free space
- Optional: Large external / internal hard drives, or NAS for additional storage.

Seagate Barracuda 24TB Internal Hard Drive

Amazon Price: Loading...

Availability: Checking...