Skip to main content

Agent as a Reverse Proxy

The orchestration agent can be configured to reverse-proxy traffic, simply by enabling this mode and completing a few configuration options, you'll be on your way to controlling HTTPs or TCP attack surface, without an additional firewall or other layer beyond what Knocknoc can provide.

The agent reverse proxy mode is currently supported on the following platforms:

  • Debian 11+
  • Ubuntu 20+
  • Debian ARM64 (e.g. Raspberry Pi)

Follow the guide below to create an Agent within the platform (as an Admin) and then run the installer on the chosen/orchestrating machine.


Base Agent installation 

If you have an existing Agent already deployed, follow the below 'enable reverseproxy' commands and skip this section.

  1. Browse to https://your-knocknoc-server/admin and login with the knocknoc-admin user.
  2. Click on Agents then Create Agent.
  3. Enter a sensible name e.g. [AgentServerHostname].
  4. Copy the token that is produced.
  5. Login to the server hosting the agent via the command line and become the root user.
  6. Run this command it will configure apt, setup secure repository access, and install knocknoc agent.
    curl -sSL https://packages.knocknoc.io/setup/setup_knocknoc_agent.sh | bash
  7. Accept the License Agreement.
  8. Enter the URL and Port of your Knocknoc server (eg: your-knocknoc-server:443).
  9. Paste the agent token from the Admin portal created earlier.
  10. Confirm if you have a valid SSL certificate on your Knocknoc server. If you are using 127.0.0.1:8756, select No.
  11. The installer will check what backends are enabled using the /opt/knocknoc-agent/knocker/knocker utility. 
  12. You can now start adding and configuring Knocs in the admin panel!

If you made a mistake, you can edit the config file (/opt/knocknoc-agent/etc/knocknoc-agent.conf) or by running configure-knocknoc-agent.

Enabling Agent reverse-proxy mode

Ensure your Agent is updated, use your operating system package manager to update/upgrade.

If you want to use the Lets Encrypt functionality you will need a domain name/FQDN mapped to the IP address of the Agent, along with inbound port 80 access.

  1. Log in to the server running the Agent
  2. Run '/opt/knocknoc-agent/knocker/knocker enable reverseproxy'
  3. Follow the steps below!
  4. Log in to your Knocknoc Server and configure the Knoc, using 101 as the ACL ID
  5. Tweak your /etc/haproxy/haproxy.cfg to suit your needs

The below example uses the IP address, which can be internal or external, and generates a self-signed certificate.

# /opt/knocknoc-agent/knocker/knocker enable reverseproxy
Enabling backend reverseproxy on this machine.
Note: Some operations may require sudo rights.
Knocker: reverseproxy enable (HAProxy v3; Debian/Ubuntu only)
Checking prerequisites (curl, dnsutils)…


This configures the Knocknoc Agent to operate as a reverse-proxy, it allows secure
authenticated control of HTTP/S or TCP port forwarding, linked to your Knocknoc server.

To configure the reverse proxy for HTTPS, assume the below diagram

+-----------+         +----------------+          +-----------+
|   CLIENT  |-------->|   This Agent   |--------->|  SERVER   |
|  10.0.1.5 |         |  ReverseProxy  |          | 10.0.2.10 |
+-----------+         +----------------+          +-----------+
      |                       |		       		|
      |------ DOMAIN:443----->|-- INT_SERVER:INT_PORT ->|

We need to collect:
1. DOMAIN       - hostname/IP/FQDN mapped to the external address of this Agent, eg: www-protected.example.com
2. INT_SERVER   - internal server hostname/IP to send authorized traffic to, eg: 10.0.2.10 or www.example.com
3. INT_PORT     - internal port on the internal server to proxy authorized traffic to, eg: 443

This turns the Agent in to a reverse proxy, complete with Knocknoc authentication control protecting the internal server.


What is the DOMAIN (FQDN or IP address): www-protected.example.com
What is the INT_SERVER (hostname or IP address) [www-test.internal]: 192.168.100.67
What is the INT_PORT [443]:
Connect to INT_SERVER:INT_PORT using https? (y/N): y
Which TLS mode would you like to use?
  1) Self signed certificate
  2) Lets Encrypt
 (default: 1): 1
Also configure a raw TCP port forward? (y/N): n

HAProxy has been enabled for knocknoc-agent. Please restart HAProxy for changes to take effect.

... install happens

✅ Reverse proxy deployed
   - Domain:   www-protected.example.com
   - Server:   192.168.100.67:443 (upstream TLS: yes)
   - Config:   /etc/haproxy/haproxy.cfg
   - Cert PEM: /etc/haproxy/certs/www-protected.example.com.pem

Next steps:
  • Log into your Knocknoc server to configure/create your Knoc
  • Select "Identity aware proxy"
  • Enter ACL ID "101" in the Knoc configuration
  • Visit https://www-protected.example.com before and after logging in to Knocknoc as an end-user to enjoy the security.

The below example shows the Lets Encrypt option utilized, whereby a domain name mapped to the Agents IP address is required, along with inbound port 80 to the Agent server to obtain the SSL certificate.

# /opt/knocknoc-agent/knocker/knocker enable reverseproxy
Enabling backend reverseproxy on this machine.
Note: Some operations may require sudo rights.
Knocker: reverseproxy enable (HAProxy v3; Debian/Ubuntu only)
Checking prerequisites (curl, dnsutils)…


This configures the Knocknoc Agent to operate as a reverse-proxy, it allows secure
authenticated control of HTTP/S or TCP port forwarding, linked to your Knocknoc server.

To configure the reverse proxy for HTTPS, assume the below diagram

+-----------+         +----------------+          +-----------+
|   CLIENT  |-------->|   This Agent   |--------->|  SERVER   |
|  10.0.1.5 |         |  ReverseProxy  |          | 10.0.2.10 |
+-----------+         +----------------+          +-----------+
      |                       |		       		|
      |------ DOMAIN:443----->|-- INT_SERVER:INT_PORT ->|

We need to collect:
1. DOMAIN       - hostname/IP/FQDN mapped to the external address of this Agent, eg: www-protected.example.com
2. INT_SERVER   - internal server hostname/IP to send authorized traffic to, eg: 10.0.2.10 or www.example.com
3. INT_PORT     - internal port on the internal server to proxy authorized traffic to, eg: 443

This turns the Agent in to a reverse proxy, complete with Knocknoc authentication control protecting the internal server.


What is the DOMAIN (FQDN or IP address): www-protected.knoc.io
What is the INT_SERVER (hostname or IP address) [www-test.internal]: www.knocknoc.io
What is the INT_PORT [443]:
Connect to INT_SERVER:INT_PORT using https? (y/N): y
Which TLS mode would you like to use?
  1) Self signed certificate
  2) Lets Encrypt
 (default: 1): 2
Email for Let's Encrypt (expiry notices): ssl-renewals@your-domain.example.com
[knocker] LE preflight: determining public IPv4…
[knocker] LE preflight: resolving A records for www-protected.knoc.io…
[knocker] LE preflight: domain A records = [170.64.158.239], host public IPv4 = 170.64.158.239
[knocker] LE preflight OK: www-protected.knoc.io -> 170.64.158.239

Also configure a raw TCP port forward? (y/N): n

... installation occurs ...

Saving debug log to /var/log/letsencrypt/letsencrypt.log
Account registered.
Requesting a certificate for www-protected.knoc.io

Successfully received certificate.
Certificate is saved at: /etc/letsencrypt/live/www-protected.knoc.io/fullchain.pem
Key is saved at:         /etc/letsencrypt/live/www-protected.knoc.io/privkey.pem
This certificate expires on 2026-01-05.
These files will be updated when the certificate renews.
Certbot has set up a scheduled task to automatically renew this certificate in the background.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
If you like Certbot, please consider supporting our work by:
 * Donating to ISRG / Let's Encrypt:   https://letsencrypt.org/donate
 * Donating to EFF:                    https://eff.org/donate-le
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Synchronizing state of haproxy.service with SysV service script with /usr/lib/systemd/systemd-sysv-install.
Executing: /usr/lib/systemd/systemd-sysv-install enable haproxy
Enabling HAProxy for knocknoc-agent...

HAProxy has been enabled for knocknoc-agent. Please restart HAProxy for changes to take effect.

✅ Reverse proxy deployed
   - Domain:   www-protected.knoc.io
   - Server:   www.knocknoc.io:443 (upstream TLS: yes)
   - Config:   /etc/haproxy/haproxy.cfg
   - Cert PEM: /etc/haproxy/certs/www-protected.knoc.io.pem

Next steps:
  • Log into your Knocknoc server to configure/create your Knoc
  • Select "Identity aware proxy"
  • Enter ACL ID "101" in the Knoc configuration
  • Visit https://www-protected.knoc.io before and after logging in to Knocknoc as an end-user to enjoy the security.

Back to top