Skip to main content

Nginx

Knocknoc can drive an nginx server's allow/deny list directly from the agent, without a wrapper script. Users authenticated by Knocknoc are added to a per-Knoc include file (for example /etc/nginx/acl/librenms.acl) that the agent rewrites atomically, then reloads nginx via sudo nginx -s reload.

This is the recommended approach as of v26.05.

How it works

Each gated site includes one ACL file from /etc/nginx/acl/. The agent owns that file. When you create the Knoc, the agent writes the file with a single deny all; so nginx can load it straight away. On each grant it rewrites the file with an allow line per authenticated IP followed by deny all;, then reloads nginx. On revoke or expiry the IP is removed again.

Setup on the nginx server

  1. Install knocknoc-agent (v26.05 or later) on the nginx host and register it to your Knocknoc server.

  2. Enable the nginx integration. knocker ships with the agent and is not on your PATH, so call it by its full path:

    /opt/knocknoc-agent/knocker/knocker enable nginx

This does not create the ACL file itself, the agent does that when you create the Knoc.

  1. Create the Knoc in Knocknoc (next section) before editing your nginx config. The agent only writes the ACL file once the Knoc exists, and nginx -t will fail if it includes a file that isn't there yet.

  2. Reference the ACL file from each server block you want to gate. The filename must match the path you set on the Knoc (alphanumerics, _, ., -, ending in .acl):

    server {
    listen 443 ssl;
    server_name librenms.example.com;

    # Knocknoc manages this file
    include /etc/nginx/acl/librenms.acl;

    # ...rest of your config...
}

  3. Validate and reload:

    sudo nginx -t && sudo systemctl reload nginx

Create the Knoc in Knocknoc

In the admin portal:

  1. Create a new Knoc and select Nginx.
  2. Set the ACL file to the absolute path under /etc/nginx/acl/ that you referenced in your nginx config (for example /etc/nginx/acl/librenms.acl).
  3. Select the agent running on the nginx host.
  4. Assign the Knoc to the user or group that should get access.

As soon as the Knoc is saved, the agent creates the ACL file with a default deny all;. On grant it adds the user's IP and reloads nginx. On revoke or expiry the IP is removed again.

If the Nginx option is greyed out for an agent, that agent hasn't advertised the capability, usually because nginx isn't on its PATH or the sudoers entry is missing. Re-run /opt/knocknoc-agent/knocker/knocker enable nginx on that host, then restart the agent (sudo systemctl restart knocknoc-agent) so it reconnects and advertises nginx support.

Knocker reference

Run these on the nginx host, using the agent's knocker by full path:

/opt/knocknoc-agent/knocker/knocker status nginx    # report install state (binary, sudoers, ACL dir, nginx -t)
/opt/knocknoc-agent/knocker/knocker enable nginx     # add sudoers entry + ACL dir
/opt/knocknoc-agent/knocker/knocker disable nginx    # remove the sudoers entry (ACL dir retained)
Back to top