IPWhiteList

Limiting Clients to Specific IPs

IpWhiteList

IPWhitelist accepts / refuses requests based on the client IP.

Configuration Examples

  1. # Accepts request from defined IP
  2. labels:
  3. - "traefik.http.middlewares.test-ipwhitelist.ipwhitelist.sourcerange=127.0.0.1/32, 192.168.1.7"

  1. apiVersion: traefik.containo.us/v1alpha1
  2. kind: Middleware
  3. metadata:
  4. name: test-ipwhitelist
  5. spec:
  6. ipWhiteList:
  7. sourceRange:
  8. - 127.0.0.1/32
  9. - 192.168.1.7

  1. # Accepts request from defined IP
  2. - "traefik.http.middlewares.test-ipwhitelist.ipwhitelist.sourcerange=127.0.0.1/32, 192.168.1.7"

  1. "labels": {
  2. "traefik.http.middlewares.test-ipwhitelist.ipwhitelist.sourcerange": "127.0.0.1/32,192.168.1.7"
  3. }

  1. # Accepts request from defined IP
  2. labels:
  3. - "traefik.http.middlewares.test-ipwhitelist.ipwhitelist.sourcerange=127.0.0.1/32, 192.168.1.7"

  1. # Accepts request from defined IP
  2. [http.middlewares]
  3. [http.middlewares.test-ipwhitelist.ipWhiteList]
  4. sourceRange = ["127.0.0.1/32", "192.168.1.7"]

  1. # Accepts request from defined IP
  2. http:
  3. middlewares:
  4. test-ipwhitelist:
  5. ipWhiteList:
  6. sourceRange:
  7. - "127.0.0.1/32"
  8. - "192.168.1.7"

Configuration Options

sourceRange

The sourceRange option sets the allowed IPs (or ranges of allowed IPs by using CIDR notation).

ipStrategy

The ipStrategy option defines two parameters that sets how Traefik will determine the client IP: depth, and excludedIPs.

ipStrategy.depth

The depth option tells Traefik to use the X-Forwarded-For header and take the IP located at the depth position (starting from the right).

Examples of Depth & X-Forwarded-For

  1. # Whitelisting Based on `X-Forwarded-For` with `depth=2`
  2. labels:
  3. - "traefik.http.middlewares.testIPwhitelist.ipwhitelist.sourcerange=127.0.0.1/32, 192.168.1.7"
  4. - "traefik.http.middlewares.testIPwhitelist.ipwhitelist.ipstrategy.depth=2"

  1. # Whitelisting Based on `X-Forwarded-For` with `depth=2`
  2. apiVersion: traefik.containo.us/v1alpha1
  3. kind: Middleware
  4. metadata:
  5. name: testIPwhitelist
  6. spec:
  7. ipWhiteList:
  8. sourceRange:
  9. - 127.0.0.1/32
  10. - 192.168.1.7
  11. ipStrategy:
  12. depth: 2

  1. # Whitelisting Based on `X-Forwarded-For` with `depth=2`
  2. - "traefik.http.middlewares.testIPwhitelist.ipwhitelist.sourcerange=127.0.0.1/32, 192.168.1.7"
  3. - "traefik.http.middlewares.testIPwhitelist.ipwhitelist.ipstrategy.depth=2"

  1. "labels": {
  2. "traefik.http.middlewares.testIPwhitelist.ipwhitelist.sourcerange": "127.0.0.1/32, 192.168.1.7",
  3. "traefik.http.middlewares.testIPwhitelist.ipwhitelist.ipstrategy.depth": "2"
  4. }

  1. # Whitelisting Based on `X-Forwarded-For` with `depth=2`
  2. labels:
  3. - "traefik.http.middlewares.testIPwhitelist.ipwhitelist.sourcerange=127.0.0.1/32, 192.168.1.7"
  4. - "traefik.http.middlewares.testIPwhitelist.ipwhitelist.ipstrategy.depth=2"

  1. # Whitelisting Based on `X-Forwarded-For` with `depth=2`
  2. [http.middlewares]
  3. [http.middlewares.test-ipwhitelist.ipWhiteList]
  4. sourceRange = ["127.0.0.1/32", "192.168.1.7"]
  5. [http.middlewares.test-ipwhitelist.ipWhiteList.ipStrategy]
  6. depth = 2

  1. # Whitelisting Based on `X-Forwarded-For` with `depth=2`
  2. http:
  3. middlewares:
  4. test-ipwhitelist:
  5. ipWhiteList:
  6. sourceRange:
  7. - "127.0.0.1/32"
  8. - "192.168.1.7"
  9. ipStrategy:
  10. depth: 2

If depth was equal to 2, and the request X-Forwarded-For header was "10.0.0.1,11.0.0.1,12.0.0.1,13.0.0.1" then the "real" client IP would be "10.0.0.1" (at depth 4) but the IP used for the whitelisting would be "12.0.0.1" (depth=2).

More examples

X-Forwarded-FordepthclientIP
"10.0.0.1,11.0.0.1,12.0.0.1,13.0.0.1"1"13.0.0.1"
"10.0.0.1,11.0.0.1,12.0.0.1,13.0.0.1"3"11.0.0.1"
"10.0.0.1,11.0.0.1,12.0.0.1,13.0.0.1"5""

Info

  • If depth is greater than the total number of IPs in X-Forwarded-For, then the client IP will be empty.
  • depth is ignored if its value is lesser than or equal to 0.

ipStrategy.excludedIPs

  1. # Exclude from `X-Forwarded-For`
  2. labels:
  3. - "traefik.http.middlewares.test-ipwhitelist.ipwhitelist.ipstrategy.excludedips=127.0.0.1/32, 192.168.1.7"

  1. # Exclude from `X-Forwarded-For`
  2. apiVersion: traefik.containo.us/v1alpha1
  3. kind: Middleware
  4. metadata:
  5. name: test-ipwhitelist
  6. spec:
  7. ipWhiteList:
  8. ipStrategy:
  9. excludedIPs:
  10. - 127.0.0.1/32
  11. - 192.168.1.7

  1. # Exclude from `X-Forwarded-For`
  2. - "traefik.http.middlewares.test-ipwhitelist.ipwhitelist.ipstrategy.excludedips=127.0.0.1/32, 192.168.1.7"

  1. "labels": {
  2. "traefik.http.middlewares.test-ipwhitelist.ipwhitelist.ipstrategy.excludedips": "127.0.0.1/32, 192.168.1.7"
  3. }

  1. # Exclude from `X-Forwarded-For`
  2. labels:
  3. - "traefik.http.middlewares.test-ipwhitelist.ipwhitelist.ipstrategy.excludedips=127.0.0.1/32, 192.168.1.7"

  1. # Exclude from `X-Forwarded-For`
  2. [http.middlewares]
  3. [http.middlewares.test-ipwhitelist.ipWhiteList]
  4. [http.middlewares.test-ipwhitelist.ipWhiteList.ipStrategy]
  5. excludedIPs = ["127.0.0.1/32", "192.168.1.7"]

  1. # Exclude from `X-Forwarded-For`
  2. http:
  3. middlewares:
  4. test-ipwhitelist:
  5. ipWhiteList:
  6. ipStrategy:
  7. excludedIPs:
  8. - "127.0.0.1/32"
  9. - "192.168.1.7"

excludedIPs tells Traefik to scan the X-Forwarded-For header and pick the first IP not in the list.

If depth is specified, excludedIPs is ignored.

Examples of ExcludedIPs & X-Forwarded-For

X-Forwarded-ForexcludedIPsclientIP
"10.0.0.1,11.0.0.1,12.0.0.1,13.0.0.1""12.0.0.1,13.0.0.1""11.0.0.1"
"10.0.0.1,11.0.0.1,12.0.0.1,13.0.0.1""15.0.0.1,13.0.0.1""12.0.0.1"
"10.0.0.1,11.0.0.1,12.0.0.1,13.0.0.1""10.0.0.1,13.0.0.1""12.0.0.1"
"10.0.0.1,11.0.0.1,12.0.0.1,13.0.0.1""15.0.0.1,16.0.0.1""13.0.0.1"
"10.0.0.1,11.0.0.1""10.0.0.1,11.0.0.1"""