Skip to content

A modern, self-hosted backup solution for secure, encrypted backups across local and cloud storage.

fix: resolves ERR_ERL_UNEXPECTED_X_FORWARDED_FOR error when running behind reverse-proxy

towfiqi938b5bab3e1a
diff --git a/.env.template b/.env.template
index f4fbf11..baeb0f5 100644
--- a/.env.template
+++ b/.env.template
@@ -3,4 +3,7 @@ USER_NAME=admin
USER_PASSWORD=your-secure-password
# Optional - override defaults
-SERVER_PORT=5173
\ No newline at end of file
+SERVER_PORT=5173
+
+# Reverse proxy (Caddy, Nginx, Traefik, ...) Support
+#TRUST_PROXY=1
\ No newline at end of file
diff --git a/backend/src/createApp.ts b/backend/src/createApp.ts
index 8cb05ad..9804e30 100644
--- a/backend/src/createApp.ts
+++ b/backend/src/createApp.ts
@@ -55,6 +55,7 @@ import { SelfBackupTask } from './jobs/tasks/SelfBackupTask';
import { initializeLogger } from './utils/logger';
import { configService } from './services/ConfigService';
import { BaseRestoreManager } from './managers/BaseRestoreManager';
+import { parseTrustProxy } from './utils/helpers';
const MemoryStore = createMemoryStore(session);
@@ -130,6 +131,13 @@ export async function createApp(): Promise<{ app: Express }> {
// Express App
const app = express();
+
+ // Reverse proxy support
+ const trustProxy = configService.config.TRUST_PROXY;
+ if (trustProxy !== undefined && trustProxy !== '') {
+ app.set('trust proxy', parseTrustProxy(trustProxy));
+ }
+
app.use(
cors({
origin: [
diff --git a/backend/src/services/ConfigService.ts b/backend/src/services/ConfigService.ts
index fc3b125..5de0112 100644
--- a/backend/src/services/ConfigService.ts
+++ b/backend/src/services/ConfigService.ts
@@ -22,6 +22,9 @@ const baseConfigSchema = z.object({
ALLOW_FILE_BROWSER: z.coerce.boolean().default(true).optional(),
FILE_BROWSER_ROOT: z.string().optional(),
+ // Reverse proxy: value passed to Express's `trust proxy` setting.
+ TRUST_PROXY: z.string().optional(),
+
// Security (optional in setup mode)
ENCRYPTION_KEY: z
.string()
@@ -61,6 +64,7 @@ const userConfigSchema = baseConfigSchema
ALLOW_FILE_BROWSER: true,
FILE_BROWSER_ROOT: true,
DISABLE_EVENT_SCRIPTS: true,
+ TRUST_PROXY: true,
})
.partial();
diff --git a/backend/src/utils/helpers.ts b/backend/src/utils/helpers.ts
index ecaa22e..03302f9 100644
--- a/backend/src/utils/helpers.ts
+++ b/backend/src/utils/helpers.ts
@@ -62,3 +62,34 @@ export const safeCompare = (a: string, b: string): boolean => {
if (a.length !== b.length) return false;
return timingSafeEqual(Buffer.from(a), Buffer.from(b));
};
+
+/**
+ * Translate the TRUST_PROXY config value into what Express's `trust proxy`
+ * setting expects. Without this, running Pluton behind a reverse proxy
+ * (Caddy, Nginx, Traefik, ...) makes express-rate-limit throw
+ * ERR_ERL_UNEXPECTED_X_FORWARDED_FOR, because the proxy sends X-Forwarded-For
+ * while Express trusts no proxy by default.
+ *
+ * Accepted values:
+ * - "true"/"false" -> boolean
+ * - a number (e.g. "1") -> trust that many hops (recommended: the count
+ * of proxies in front of Pluton)
+ * - IP / subnet list -> passed through as a comma-separated string
+ *
+ * Prefer a hop count over "true": trusting all proxies lets a client spoof
+ * X-Forwarded-For and defeat the auth/setup rate limiters.
+ */
+export function parseTrustProxy(value: string): boolean | number | string[] {
+ const trimmed = value.trim();
+ if (trimmed.toLowerCase() === 'true') return true;
+ if (trimmed.toLowerCase() === 'false') return false;
+
+ const asNumber = Number(trimmed);
+ if (Number.isInteger(asNumber) && asNumber >= 0) return asNumber;
+
+ // Otherwise treat it as a comma-separated list of trusted IPs/subnets.
+ return trimmed
+ .split(',')
+ .map(entry => entry.trim())
+ .filter(Boolean);
+}
diff --git a/docker-compose.yml b/docker-compose.yml
index 4279ce6..163d962 100644
--- a/docker-compose.yml
+++ b/docker-compose.yml
@@ -45,6 +45,8 @@ services:
MAX_CONCURRENT_BACKUPS: ${MAX_CONCURRENT_BACKUPS:-2}
SESSION_DURATION: ${SESSION_DURATION:-7} # How long frontend login Session lasts in Days
+ # TRUST_PROXY: ${TRUST_PROXY:-1} #Uncomment when running Pluton behind a reverse proxy (Caddy, Nginx, Traefik, ...).
+
# ===== User Interface Security Settings =====
ALLOW_CUSTOM_RESTORE_PATH: ${ALLOW_CUSTOM_RESTORE_PATH:-true}
ALLOW_FILE_BROWSER: ${ALLOW_FILE_BROWSER:-true}
diff --git a/installers/linux-server/pluton.env.template b/installers/linux-server/pluton.env.template
index 1f80414..99a4502 100644
--- a/installers/linux-server/pluton.env.template
+++ b/installers/linux-server/pluton.env.template
@@ -23,3 +23,6 @@ PLUTON_USER_PASSWORD=your-secure-password-here
# Maximum concurrent backup jobs (default: 2)
#MAX_CONCURRENT_BACKUPS=2
+
+# Reverse proxy (Caddy, Nginx, Traefik, ...) Support
+#TRUST_PROXY=1