Published: May 22, 2026
Last updated: August 5, 2026
Suggest an edit

Configure how FileBrowser listens for HTTP traffic, how URLs are built for shares and integrations, and how the server behaves behind a reverse proxy.

YAML 
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

http:
  port: 80
  listen: ""                    # default: 0.0.0.0
  baseURL: "/"
  externalUrl: ""
  internalUrl: ""
  socket: ""
  tlsCert: ""
  tlsKey: ""
  disableWebDAV: false
  trustProxyHeaders: false
  disableRateLimit: false

Configuration Options

port

TCP port FileBrowser listens on (default: 80).

YAML 
1
2

http:
  port: 80

Ignored when http.socket is set (Unix socket mode).

listen

Address FileBrowser binds to (default: 0.0.0.0 — all interfaces).

YAML 
1
2

http:
  listen: "127.0.0.1"   # localhost only

Use 127.0.0.1 when a reverse proxy on the same host forwards traffic to FileBrowser.

baseURL

Subpath FileBrowser is served under (default: /). Required when running behind a reverse proxy on a path prefix.

YAML 
1
2

http:
  baseURL: "/files"

FileBrowser normalizes this to leading and trailing slashes (e.g. /files/). Routes, static assets, and API paths are all prefixed with this value.

socket

Unix domain socket to listen on instead of TCP port (default: empty — use TCP).

YAML 
1
2

http:
  socket: "/var/run/filebrowser.sock"

When set, http.port is not used. Cannot be combined with tlsCert / tlsKey — the server exits at startup if both are configured.

tlsCert and tlsKey

Paths to TLS certificate and private key for HTTPS. Both must be set to enable TLS.

YAML 
1
2
3
4

http:
  tlsCert: "/path/to/cert.pem"
  tlsKey: "/path/to/key.pem"
  port: 443

When TLS is enabled, the server logs an https:// URL. Cannot be combined with http.socket.

externalUrl

Public base URL used when generating links. Include scheme and host only — baseURL is appended automatically when needed.

YAML 
1
2
3

http:
  externalUrl: "https://files.example.com" # will automatically apply /files if missing
  baseURL: "/files"
Used forNot used for
Share links and Open Graph metadataOIDC redirect_uri (always derived from the incoming request)
OnlyOffice download/callback URLs when internalUrl is unsetWebAuthn RP ID (uses externalUrl when set, else request host)
Session cookies or login redirects

If unset, share links and OnlyOffice public-path URLs fall back to the incoming request (Host header and scheme). Behind a reverse proxy, enable header trust so request-derived URLs use the client-facing scheme and host — http.trustProxyHeaders: true on v2.0.0+, or list forwarding headers under http.trustedHeaders on v1.4.x–v1.5.x.

internalUrl

Base URL integration services use to reach FileBrowser on the private network (optional). HTTP is allowed. This path does not use trustProxyHeaders or trustedHeaders — it is a fixed configured origin, not derived from proxied client requests.

YAML 
1
2
3

http:
  internalUrl: "http://filebrowser:80"
  baseURL: "/files"
Used forNot used for
OnlyOffice download/callback URLs (highest priority)Share links shown in the browser
OIDC redirects

URL priority for OnlyOffice → FileBrowser: internalUrl → externalUrl → incoming request (with header trust enabled when behind a proxy: trustProxyHeaders on v2.0.0+, trustedHeaders on v1.4.x–v1.5.x).

Typically a Docker service name, internal DNS name, or LAN IP. See OnlyOffice configuration.

disableWebDAV

Disable WebDAV support (default: false). When true, the /dav route is not registered.

YAML 
1
2

http:
  disableWebDAV: true

trustProxyHeaders (v2.0.0+) / trustedHeaders (v1.4.x–v1.5.x)

How FileBrowser honors reverse-proxy forwarding headers depends on your version:

VersionConfig keyBehavior
v2.0.0+http.trustProxyHeadersSingle boolean (default: false). When true, honors all standard forwarding headers.
v1.4.x–v1.5.xhttp.trustedHeadersList of header names to trust individually.

v2.0.0+:

YAML 
1
2
3

http:
  trustProxyHeaders: true
  listen: "127.0.0.1"   # recommended when proxy is on the same host

When true, FileBrowser honors X-Forwarded-Host, X-Forwarded-Proto, X-Forwarded-For, and X-Real-IP.

v1.4.x–v1.5.x:

YAML 
1
2
3
4
5
6
7

http:
  trustedHeaders:
    - X-Forwarded-Proto
    - X-Forwarded-Host
    - X-Forwarded-For
    - X-Real-IP
  listen: "127.0.0.1"   # recommended when proxy is on the same host

List only the headers your proxy sets. For OIDC or HTTPS behind a proxy, include at least X-Forwarded-Proto and X-Forwarded-Host.

Enable header trust only when a reverse proxy you control is the sole entry point to FileBrowser. Direct deployments (no proxy) should leave trustProxyHeaders false (v2.0.0+) or omit trustedHeaders (v1.4.x–v1.5.x).

When enabled, FileBrowser uses forwarded headers for:

AreaHeaders used
Client IPX-Forwarded-For (first IP), then X-Real-IP
Request hostX-Forwarded-Host
Request schemeX-Forwarded-Proto (defaults to https for public URLs when host is forwarded but proto is absent)

This affects session cookie domain, OIDC redirect_uri, WebAuthn RP ID/origin, share and page URLs, auth rate limiting, failed-login lockout, and activity audit IP.

See Reverse proxy: proxy headers for nginx, Traefik, and Caddy examples.

disableRateLimit

Turns off built-in auth route rate limiting and failed-login lockout (default: false).

YAML 
1
2

http:
  disableRateLimit: false

Leave this false in production. Setting it to true removes HTTP 429 throttling and account lockout on authentication endpoints.

Built-in authentication rate limiting

When disableRateLimit is false and password (or other credential) auth is enabled, FileBrowser applies per-process, in-memory limits on /api/auth/* routes. Limits are not configurable via YAML; they are built into the server.

Credential tier (login, OTP verify)

Used by POST /api/auth/login and POST /api/auth/otp/verify.

ControlLimit
Per-IP token bucket10 requests/minute, burst 8
Per-username token bucket10 requests/minute, burst 8
Failed-login lockout8 consecutive 401 responses for the same IP and username → 15-minute lockout

Behavior:

  • Rapid automated attempts exhaust the token bucket and receive HTTP 429 with a short Retry-After (seconds).
  • Slower guessing that stays under the per-minute rate is blocked by failed-login lockout, which returns HTTP 429 with Retry-After=900 (15 minutes).
  • A successful login clears the lockout counter for that IP and username.

Passkey login endpoints use the credential token buckets without failed-login lockout.

Other auth tiers

TierRoutes (examples)Per-key limit
Moderatelogout, signup, OTP generate30/min, burst 10 (per IP)
OIDCOIDC login and callback60/min, burst 20 (per IP)
Authenticatedtoken management, session renew, passkey register180/min, burst 60 (per logged-in username)

Limitations

  • Limits apply per FileBrowser process. Restarting the server clears counters. Multiple replicas do not share state.
  • Failed-login lockout is keyed by IP + username, not username alone. Per-username token buckets still apply when an attacker rotates IPs against one account.
  • Rate limiting is disabled when http.disableRateLimit is true or when auth.methods.noAuth is enabled.

Example: reverse proxy deployment

YAML 
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

# v2.0.0+
http:
  port: 8080
  baseURL: "/files"
  externalUrl: "https://files.example.com/files"
  trustProxyHeaders: true
  disableRateLimit: false

server:
  cacheDir: "tmp"
  sources:
    - path: "/srv"
YAML 
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

# v1.4.x–v1.5.x
http:
  port: 8080
  baseURL: "/files"
  externalUrl: "https://files.example.com/files"
  trustedHeaders:
    - X-Forwarded-Proto
    - X-Forwarded-Host
    - X-Forwarded-For
    - X-Real-IP
  disableRateLimit: false

server:
  cacheDir: "tmp"
  sources:
    - path: "/srv"