Skip to main content

Traefik

Knocknoc protects services behind Traefik with the Knocknoc Traefik plugin. The plugin is a middleware that reads and enforces a Knocknoc Allowlist (EDL).

No Knocknoc Agent is strictly needed. Traefik can poll the EDL from the Knocknoc server itself, or from a Knocknoc Agent near Traefik that caches the EDL, saving a round trip to the server on every poll. The plugin is configured the same way for either approach.

How it works

  • Traefik polls the EDL. The middleware fetches the EDL every second or two, so a user who logs in gets through almost straight away.
  • Everyone else is refused. A request from an address that isn't on the EDL gets a 403 by default.
  • Access ends within one poll. A user whose access has ended can still get through until the next poll, which by default is two seconds away.

Requirements

  • Traefik with plugin support enabled.
  • Outbound HTTPS from Traefik to your Knocknoc server, or http/https from your Knocknoc Agent.

Create the Knoc

  1. In the admin portal, create a Knoc and choose EDL (Passive) under Inline. The Allowlist (EDLs) page walks through the settings.
  2. Choose a sufficient security method. If the EDL is exclusively for your Traefik gateway, consider an allow list for its IP address.
  3. Copy the EDL URL and secret once you save the Knoc.

Configure Traefik

Add the plugin to Traefik's static configuration:

experimental:
  plugins:
    knocknoc:
      moduleName: github.com/knocknoc-io/traefik-plugin-knocknoc
      version: v0.2.0

Then declare the middleware in your dynamic configuration, pointing it at the EDL URL. The username is always apiuser and the secret is the EDL secret from the Knoc:

http:
  middlewares:
    knocknoc:
      plugin:
        knocknoc:
          sourceURL: https://knocknoc.example.com/edl/<edl-uuid>
          username: apiuser
          secret: "{{ env `KNOCKNOC_SECRET` }}"

Attach the knocknoc middleware to each router you want to protect, then restart Traefik so it loads the plugin.

The plugin page covers Docker labels, Kubernetes CRDs and the full list of options, including the poll interval and the response sent to refused requests.

Behind a load balancer or CDN

By default the plugin checks the address of whatever connected to Traefik. If Traefik sits behind a load balancer or CDN, that address belongs to the load balancer, and every user is refused. Set the plugin's ipStrategy options so it reads the user's address from X-Forwarded-For instead. The plugin page explains how to pick the right value.

Back to top