Knocker is a secure, configurable, and self-hosted service that provides a "knock-knock" single-packet authorization (SPA) gateway for your Homelab, it can be used as authentication for your reverse proxy like Caddy, or even on the firewall level using the FirewallD integration. It allows you to keep your services completely private, opening them up on-demand only for authorized IP addresses.
This is ideal for homelab environments where you want to expose services to the internet without a persistent VPN connection, while minimizing your public-facing attack surface.
- API Key Authentication: Secure your knock endpoint with multiple, configurable API keys.
- Configurable TTL: Each API key can have its own Time-To-Live (TTL), defining how long a whitelisted IP remains active.
- Remote Whitelisting: Grant specific admin keys permission to whitelist any IP or CIDR range, not just their own.
- Static IP/CIDR Whitelisting: Always allow certain IP addresses or ranges to bypass the dynamic whitelist.
- Host-Scoped Exclusion: Keep intentionally public paths scoped to the correct virtual host.
- IPv6 First-Class Citizen: Full support for IPv6 and IPv4 in whitelisting, trusted proxies, and Docker networking.
- Secure by Default: Built-in protection against IP spoofing via a trusted proxy mechanism.
- Optional Interactive API Docs: Generate Swagger UI, ReDoc, and OpenAPI JSON on demand when documentation is explicitly enabled.
- Firewalld Integration: Advanced firewall control with timed rules that automatically expire based on TTL. Creates dynamic firewall rules using firewalld rich rules for enhanced security. (Optional, requires root container access)
This project uses GitHub Actions for continuous integration and deployment.
- CI (
tests.yml): Every pull request runs Python checks and two independent Docker Compose integration jobs: Caddy authentication and real FirewallD packet filtering over IPv4/IPv6 and TCP/UDP. See TESTING.md. - Docker Publish (
docker-publish.yml): Validates pull requests with read-only permissions and publishes signed multi-arch Docker images only from non-PR events. The Dockerfile copiesuvfrom an official digest-pinned image.- On push to
main→ghcr.io/fariszr/knocker:main(rolling development) - On stable version tags (
v2.0.0) →:latest,:v2.0.0,:2.0.0,:2.0,:2,:v2
- On push to
- Release Workflow (
release.yml): Pushing a version tag creates a GitHub release. A matching file indocs/releases/supplies the release notes (for example, v2.0.0). For other versions, the workflow uses GitHub-generated notes with installation instructions.
This project is designed to be deployed as a set of Docker containers using the provided docker-compose.yml file. It uses the pre-built docker images with support for AMD64, Arm64 and risc-v.
* Docker and Docker Compose installed.
* A public-facing server to run the containers.
* (Optional) Firewalld installed and running on the host for advanced firewall integration.
-
Configuration:
- Rename
knocker.example.yamltoknocker.yaml. - Add at least one secure, random API key to
knocker.yaml; the example intentionally contains no usable defaults. - Review the
trusted_proxieslist inknocker.yaml: it must contain only the reverse proxy's own address(es) (/32//128), never its subnet. Trusting a subnet would let any container on that network claim any client identity viaX-Forwarded-For. Pin the proxy withipv4_address/ipv6_address(see the commented-outcaddyservice indocker-compose.yml) and mirror those exact addresses here. - (Optional) Enable interactive documentation by setting
documentation.enabled: true(it is disabled by default). - (Optional) Configure firewalld integration by setting
firewalld.enabled: trueand adjusting the related settings. Note: This requires the container to run as root. - Create a
Caddyfilein theknockerdirectory. See the "Caddy Integration" section below for examples.
- Rename
-
Run the Service:
docker compose up -d
This will pull the pre-built
knockerimage and start both theknockerandcaddyservices.
The service is configured entirely through the knocker.yaml file, an example config with all the option is in knocker.example.yaml
To protect your services, you will use Caddy's forward_auth directive.
-
Define a Reusable Snippet: It's best practice to define a snippet in your
Caddyfilefor the auth check. -
Protect Your Services: Import the snippet for any service you want to protect.
Example Caddyfile:
# Caddyfile
# Define a reusable snippet for the knock-knock check.
# It points to the knocker service using Docker's internal DNS.
(knocker_auth) {
forward_auth knocker:8000 {
uri /verify
}
}
# The public endpoint for performing the knock.
# Make sure this domain points to your Caddy server's IP.
knock.your-domain.com {
reverse_proxy knocker:8000
}
# An example protected service.
jellyfin.your-domain.com {
import knocker_auth # Apply the forward_auth check
reverse_proxy jellyfin_service_name:8096
}If you are enabling knocking for IPs behind tailscale or other IPs, you may face issues due to how userland-proxy works, you may get different request IP from the actual ip address.
Disabling Userland-proxy should fix it, but make sure to test your setup. You may also use host networking.
When a user is not whitelisted, Caddy's forward_auth directive will return a 401 Unauthorized response with an empty body.
Important Note: Caddy's handle_errors directive does not work with forward_auth responses. The error response comes directly from the authentication service (knocker), not from Caddy itself, so handle_errors cannot intercept or modify these responses.
If you need custom error pages for unauthorized access, you have a few alternatives:
- Modify the knocker service: Update the
/verifyendpoint to return custom HTML content in 401 responses (requires code changes). - Use a different approach: Instead of
forward_auth, you could implement authorization at the application level. - Accept the default: Use the standard 401 response for unauthorized access.
Example of the standard behavior:
jellyfin.your-domain.com {
import knocker_auth # This will return empty 401 responses for unauthorized users
reverse_proxy jellyfin_service_name:8096
}Knocker provides advanced firewall integration through firewalld, creating dynamic, time-based firewall rules that automatically expire based on the TTL specified in knock requests. This feature operates at the network level, allowing you to use knocker for non-http services like ssh or game servers.
FirewallD was chosen for the ability to separates the cli interface from the daemon. This allows Knocker to control firewalld from within a Docker container by mounting the system's D-Bus socket, and also FirewallD is the only firewall that integrates correctly with docker, meaning docker doesn't just ignore it's rules like UFW. https://docs.docker.com/engine/network/packet-filtering-firewalls/#integration-with-firewalld
- Creates a dedicated firewalld zone with high priority
- Adds DROP/REJECT rules for monitored ports to block unauthorized access
- Dynamically adds ALLOW rules for whitelisted IPs that override the blocking rules
- Automatically expires rules based on TTL using firewalld's timeout mechanism
- Recovers rules on startup by comparing whitelist.json with active firewalld rules
-
Prerequisites:
- FirewallD installed and running on the host system
- Docker container must run as root for D-Bus access
-
Configuration in
knocker.yaml:firewalld: enabled: true zone_name: "knocker" zone_priority: -100 # Higher priority (negative = higher) monitored_ports: - port: 80 protocol: tcp - port: 443 protocol: tcp - port: 22 protocol: tcp monitored_ips: - "0.0.0.0/0" # All IPv4 (requires /0 suffix) - "::/0" # All IPv6 (requires /0 suffix)
-
Docker Configuration:
services: knocker: user: "0:0" # Run as root cap_add: - NET_ADMIN volumes: - /var/run/dbus/system_bus_socket:/var/run/dbus/system_bus_socket:ro
Monitor active rules:
# Check knocker zone
firewall-cmd --zone=knocker --list-all
# View rich rules
firewall-cmd --zone=knocker --list-rich-rules
# Monitor rule changes
journalctl -u firewalld -fFor detailed configuration, architecture, and troubleshooting information, see the complete FirewallD Integration Guide.
This endpoint validates an API key and whitelists an IP.
-
Headers:
X-Api-Key: Your secret API key.
-
Body (Optional):
- To whitelist a remote IP/CIDR (requires
allow_remote_whitelist: true):{"ip_address": "YOUR_TARGET_IP_OR_CIDR"}
- To whitelist a remote IP/CIDR (requires
-
Example (Whitelisting your own IP):
curl -i -H "X-Api-Key: YOUR_SECRET_KEY" https://knock.your-domain.com/knock -
Success Response (
200 OK):{ "whitelisted_entry": "1.2.3.4", "expires_at": 1672534800, "expires_in_seconds": 3600 }
This endpoint is used by Caddy's forward_auth to check if the client's IP is whitelisted. It returns 200 OK on success and 401 Unauthorized on failure.
Caddy already forwards the relevant X-Forwarded-* request headers to Knocker so /verify can make the auth decision.
The project includes a full test suite
To run the tests locally:
-
Install Dependencies:
uv sync --all-groups
-
Run Pytest:
uv run pytest
Run bash dev/test.sh linux for the complete suite matching GitHub Actions, or
bash dev/test.sh for Python checks and both isolated integration suites only.
dev/docker-compose.firewalld-ci.yml runs container-local FirewallD and D-Bus;
dev/docker-compose.ci.yml runs Caddy authentication tests. Both run on every PR
without host ports or host D-Bus. The original host FirewallD Bash suite under
dev/docker-compose.yml and dev/firewalld_integration_test.sh also runs on every
PR, on its own disposable Linux runner. The required gate needs every suite to pass.
See TESTING.md for individual commands and requirements.
Interactive documentation endpoints (/docs, /redoc, /openapi.json) are disabled by default. To expose them, set the following in knocker.yaml:
documentation:
enabled: true
openapi_output_path: "openapi.json"The production container starts src.main:create_app as a Uvicorn factory, so these routes are selected declaratively for each app instance before requests are served. When documentation is disabled (default), the routes are not registered and any previously generated schema file is deleted during the explicit startup export step to prevent stale artifacts.
For a formal API specification and a summary of the architectural choices, please see the documentation.