Skip to content
ProHomeLab
RU

Traefik

Middlewares in Traefik - What They Are, Why You Need Them, and the Full List for a Homelab

Stilicho2011Updated 10 min read43 views

Also available in: RU

Middlewares in Traefik - What They Are, Why You Need Them, and the Full List for a Homelab
Part 3 of 6 in the series Traefik
  1. Traefik in Docker - Setting Up a Reverse Proxy from Scratch
  2. Installing Traefik in a Proxmox LXC Container as a Systemd Service - Part 1
  3. Middlewares in Traefik - What They Are, Why You Need Them, and the Full List for a Homelab
  4. Installing Traefik in an LXC Container on Proxmox as a Systemd Service - Part 2
  5. Installing Traefik in an LXC Container on Proxmox as a Systemd Service - Part 3 - CrowdSec
  6. Traefik on Its Own VLAN - Configuring the Firewall in OPNsense
Contents

What middleware in Traefik is

When a request reaches the Traefik reverse proxy, it passes through a processing chain before reaching the actual service (your application behind the proxy) - or instead gets a response directly from Traefik itself, without ever reaching the backend. Middleware is exactly the mechanism that lets you intervene in the request or response along this path: modify headers, reject the request, throttle the rate of requests, require authentication, rewrite the path, and so on.

Essentially, middleware in Traefik is a direct analogue of middleware in any web framework (Express, Django, ASP.NET) - just at the reverse-proxy level rather than the application level. The difference matters: Traefik's middleware runs before the request ever reaches your service, which means it can protect an application that has no protection of its own (no authentication, no rate limiting, no header validation).

Why bother, if you can configure all of this in the application itself

Formally, a lot of what middleware does can also be implemented on the application side. But there are reasons why doing it at the proxy level is more convenient and more correct from a management and security standpoint:

  • Centralization. Rate limiting, basic authentication, security headers - if all of this is configured once in Traefik, you don't need to repeat the logic in every individual application, some of which don't even offer that capability.
  • Consistency. The same policy (for example, security headers) is applied to all services at once, without the risk of forgetting it somewhere.
  • Protecting what can't protect itself. Many self-hosted applications (dashboards, simple utilities) have no built-in authentication at all - a middleware like forwardAuth or basicAuth in front of such a service closes that gap without touching the application's own code.
  • Separation of concerns. The application handles its own direct task, while questions like "who is allowed in here" and "how often can they knock" are resolved at the infrastructure level.

How middleware is applied to a request

Middleware doesn't work on its own - it's declared in the dynamic config, and then attached to a specific router by name:

yaml
http:
routers:
my-service:
rule: "Host(`app.example.com`)"
middlewares:
- default-headers
- rate-limit
service: my-service
middlewares:
default-headers:
headers:
frameDeny: true
rate-limit:
rateLimit:
average: 100

Order in the list matters. Middlewares are applied sequentially, top to bottom - the request passes through default-headers, then through rate-limit, and only after that (if none of the middlewares rejected it) reaches the service. The response goes in the reverse order. This matters, for example, for authentication - a middleware that checks access should generally come before ones that simply modify headers, otherwise an unauthorized request might manage to touch something before it's rejected.

The same middleware can be reused across any number of routers - you declare it once and attach it anywhere by name. When using multiple providers (file provider, Docker provider), the provider suffix is appended to the name: authentik@file, redirect@docker - this is how Traefik distinguishes between identically named middlewares declared in different backends.

Defining and applying are not the same thing

Middleware is always defined in the dynamic config - its type and parameters (headers, rateLimit, forwardAuth, etc.) can't be described directly in the static config (traefik.yaml); that option simply doesn't exist there. But an already-defined middleware can be applied in two different ways.

Selectively, to a specific router - as in the example above:

yaml
# dynamic config
http:
routers:
my-service:
middlewares:
- default-headers
- authentik

In this example we first apply the standard request headers, and then redirect the request to Authentik

Globally, via the entryPoint in the static config. In traefik.yaml you can reference a middleware by name (with the provider suffix), and it will then be applied to all requests passing through that entrypoint, before Traefik even figures out which router the request belongs to:

yaml
# traefik.yaml (static config)
entryPoints:
websecure:
address: ":443"
http:
middlewares:
- rate-limit@file

The middleware is still defined in the dynamic config - the static config only holds a reference to its name. This approach is convenient for things that should apply uniformly to all traffic (rate limit, the CrowdSec bouncer) - you don't need to list them in the middlewares: section of every individual service router, since they're already applied globally through the entrypoint binding.

What a Chain is

A Chain is a middleware that itself consists of other middlewares:

yaml
http:
middlewares:
secured:
chain:
middlewares:
- default-whitelist
- default-headers

You attach the secured chain to a router - and get both (default-whitelist, then default-headers) applied in the given order, in one line. Convenient when the same combination of several middlewares repeats across many routers - instead of listing the whole set every time, you reference a single chain.

Open-source version vs Traefik Hub

Some of the middlewares in the Traefik documentation are marked as available only in Traefik Hub (the paid add-on/Enterprise) - for example, JWT, OIDC, OAuth2, OPA, WAF, LDAP, HMAC, APIKey, Distributed RateLimit. Below are only the middlewares available in the open-source version that most homelab setups (including mine) actually use.


Full list of middlewares

AddPrefix

Adds a prefix to the request path before it goes to the backend. Useful when the backend expects a path like /api/..., but you want to expose it without the prefix externally.

yaml
http:
middlewares:
add-prefix-example:
addPrefix:
prefix: "/api"

BasicAuth

Classic HTTP Basic Authentication - a login/password dialog in the browser. The password hash is generated via htpasswd (from the apache2-utils package):

Terminal window
htpasswd -nB username
yaml
http:
middlewares:
basic-auth-example:
basicAuth:
users:
- "username:$2y$05$..."
realm: "Restricted"

I use this to protect the Traefik dashboard itself - a simple and reliable fallback that doesn't depend on an external identity provider being available.

Buffering

Reads the entire request body (and optionally the response) before passing it on, and rejects anything over a set size with a 413. It's handy in two cases: capping request size for a service that has no business accepting big files in the first place (an API, a login form), and letting Traefik retry a request on a network error - a retry is only possible if the whole body was kept around.

yaml
http:
middlewares:
middlewares-buffering:
buffering:
maxRequestBodyBytes: 10485760
memRequestBodyBytes: 2097152
maxResponseBodyBytes: 10485760
memResponseBodyBytes: 2097152
retryExpression: "IsNetworkError() && Attempts() <= 2"

For services that deal in big uploads (Nextcloud, Immich, OnlyOffice), though, this middleware does more harm than good. With a maxRequestBodyBytes like the one above, anything over 10 MB bounces with a 413 - and with no limit at all, Traefik first stashes every multi-gigabyte upload in memory and on disk before handing it to the service. Traefik doesn't cap request body size by default anyway, so what large uploads actually need isn't buffering but a longer readTimeout on the entrypoint: with the default 60 seconds, a long video upload simply gets cut off (mine is set to 600 seconds - more on that in part two of the Traefik in LXC series). So buffering sits in my config as a template and isn't attached to anything.

Chain

We already covered this above - it combines several middlewares under one name.

yaml
http:
middlewares:
secured:
chain:
middlewares:
- default-whitelist
- default-headers

CircuitBreaker

Automatically cuts off traffic to a service if it starts returning mass errors or slowing down - protects the rest of the system from a cascading effect caused by one failing backend.

yaml
http:
middlewares:
circuit-breaker-example:
circuitBreaker:
expression: "NetworkErrorRatio() > 0.30 || ResponseCodeRatio(500, 600, 0, 600) > 0.25"
checkPeriod: "10s"
fallbackDuration: "30s"
recoveryDuration: "30s"

Compress

Compresses the response body (gzip) before sending it to the client - saves bandwidth. It's worth excluding already-compressed formats (images, video) - compressing them again is pointless, they're already compressed, and it just wastes CPU cycles.

yaml
http:
middlewares:
compress:
compress:
excludedContentTypes:
- "image/png"
- "image/jpeg"
- "image/webp"
- "video/mp4"

ContentType

In Traefik v3, Content-Type auto-detection is enabled by default - this middleware is only needed if you want to explicitly disable auto-detection for a specific service.

yaml
http:
middlewares:
content-type-example:
contentType: {}

DigestAuth

Similar to BasicAuth, but the password is never transmitted in plain form, even within the HTTP scheme (a hash-based challenge-response is used).

yaml
http:
middlewares:
digest-auth-example:
digestAuth:
users:
- "username:Restricted:ha1_hash"
realm: "Restricted"

Errors (Custom Error Pages)

Replaces the default Traefik/backend error page with your own - serving it from a separate service (for example, a static page).

yaml
http:
middlewares:
error-pages-example:
errors:
status:
- "500-599"
service: error-pages-service
query: "/{status}.html"

ForwardAuth

One of the most useful middlewares for a homelab with SSO. Redirects each incoming request to an external authentication service (in my case, Authentik) before letting it through. If the external service responds with success - the request goes to the real backend, with headers added from the response (username, groups, etc.); if not - Traefik itself returns the authentication response (redirect to login), without touching the backend at all.

yaml
http:
middlewares:
authentik:
forwardAuth:
address: "http://10.10.10.10:9000/outpost.goauthentik.io/auth/traefik"
trustForwardHeader: true
maxResponseBodySize: 1048576
authResponseHeaders:
- X-authentik-username
- X-authentik-groups
- X-authentik-email
- X-authentik-name
- X-authentik-uid

An important nuance: this is only needed for applications that don't know how to talk to an identity provider directly (via OIDC). If an application supports an OIDC client itself (as many modern self-hosted services do) - forwardAuth isn't needed; the application is configured directly against Authentik as an Identity Provider, without Traefik being involved in the authentication chain.

It should also be noted that not every authentication service can work with forwardAuth directly. Authentik and Authelia can; Keycloak, as of the time of writing, doesn't have this built in out of the box.

GrpcWeb

Relevant only if you're proxying a grpc-web client to a regular gRPC backend - converts the protocol on the fly.

yaml
http:
middlewares:
grpc-web-example:
grpcWeb:
allowOrigins:
- "*"

Headers

One of the most commonly used middlewares - manages HTTP headers on the request and response: security headers (HSTS, X-Frame-Options, CSP), custom headers, CORS.

yaml
http:
middlewares:
default-headers:
headers:
frameDeny: true
browserXssFilter: true
contentTypeNosniff: true
forceSTSHeader: true
stsIncludeSubdomains: true
stsPreload: true
stsSeconds: 15552000
customFrameOptionsValue: SAMEORIGIN
customRequestHeaders:
X-Forwarded-Proto: https

I keep two baseline variants - a lighter one for most services and a hardened one (hiding the server version, longer HSTS for the preload list) for more sensitive cases - plus separate variants for specific applications that need a non-standard CSP (for example, to embed a document editor in an iframe from a different domain).

InFlightReq

Limits the number of concurrent in-flight requests (as opposed to rate limit, which caps requests per second). Once the limit is hit, new requests get a 429. One detail worth knowing: if you don't set a sourceCriterion, the limit is counted per request host - meaning it's one shared pool for every client of that service, not a per-client limit.

It's useful for heavy synchronous endpoints where every single request makes the server sweat - report generation or exports, say. For background processing, though, it's pointless. Immich, for example, transcodes video and runs face recognition as background jobs after the upload, not during the request, and the load from those is controlled by the job concurrency settings in Immich itself. Limiting connections at the proxy would just make the mobile app throw 429s during a big photo upload. And for media servers like Plex and Jellyfin, which do transcode on the fly, concurrent streams are better capped in the server's own settings than by counting HTTP requests at the proxy.

yaml
http:
middlewares:
in-flight-req-example:
inFlightReq:
amount: 20

IPAllowList

Restricts access by a list of allowed IPs/subnets.

yaml
http:
middlewares:
default-whitelist:
IPAllowList:
sourceRange:
- "10.0.0.0/8"
- "192.168.0.0/16"
- "172.16.0.0/12"

All of my services are locked behind authentication, so this middleware isn't currently attached anywhere - I keep it as a ready-to-use tool just in case.

PassTLSClientCert

Relevant for mTLS scenarios, where the backend itself wants to see the client certificate in a header.

yaml
http:
middlewares:
pass-tls-client-cert-example:
passTLSClientCert:
pem: true

RateLimit

Limits the request rate from a single client (by default, by source IP) - protection against flooding/DDoS.

yaml
http:
middlewares:
rate-limit:
rateLimit:
average: 100
burst: 50

I have this attached globally on both entrypoints (web/websecure), rather than selectively per service - a general line of defense for all traffic.

RedirectScheme

Redirects a request from one scheme to another - most often HTTP → HTTPS.

yaml
http:
middlewares:
https-redirect:
redirectScheme:
scheme: https
permanent: true

RedirectRegex

The same thing, but with an arbitrary regex pattern for more complex redirects, not just scheme changes.

yaml
http:
middlewares:
redirect-regex-example:
redirectRegex:
regex: "^https://(.*)/old-path"
replacement: "https://${1}/new-path"
permanent: true

ReplacePath

Completely replaces the request path before passing it to the backend.

yaml
http:
middlewares:
replace-path-example:
replacePath:
path: "/new/path"

ReplacePathRegex

The same thing via regex, with the ability to capture and reuse parts of the original path.

yaml
http:
middlewares:
replace-path-regex-example:
replacePathRegex:
regex: "^/old/(.*)"
replacement: "/new/$${1}"

Retry

Retries the request on a network error up to a set number of attempts - unlike retryExpression inside buffering, this is a separate, more general mechanism.

yaml
http:
middlewares:
retry-example:
retry:
attempts: 3
initialInterval: "100ms"

StripPrefix

Removes a given prefix from the path before passing it to the backend - the reverse of AddPrefix.

yaml
http:
middlewares:
strip-prefix-example:
stripPrefix:
prefixes:
- "/api"

StripPrefixRegex

The same thing, but using a regex pattern.

yaml
http:
middlewares:
strip-prefix-regex-example:
stripPrefixRegex:
regex:
- "^/api/v[0-9]+"

How I organized middleware in my own setup

This setup applies across the whole Traefik-in-LXC series, not just the part about the final proxy configuration - from the base install in part one, through CrowdSec in part three, to the network isolation covered in the firewall-rules part.

Each middleware is a separate .yaml file at /etc/traefik/dynamic/middlewares/, with the filename matching its purpose. Some middlewares are actually attached to services (default-headers, rate-limit, https-redirect, the authentik forwardAuth), while some I keep as a ready-made library on standby - for whenever a specific scenario comes up (a whitelist for admin panels, buffering to cap request size, an in-flight limit for heavy endpoints), without having to invent the config from scratch on the spot.

The key benefit of this approach is that when adding a new service, I don't need to think "how does this middleware even get written" - I just grab the ready-made file, copy the relevant lines into services/<new-service>.yaml, and attach it by name.