Skip to main content

MikroTik

Knocknoc integrates with MikroTik RouterOS to dynamically control network access.

The Knocknoc agent maintains a firewall address-list on the MikroTik device. As users authenticate and grants expire, the agent adds and removes entries in the list. Existing firewall rules reference the address-list by name; access is granted in seconds.

If you would prefer a poll-based integration where the router fetches a Knocknoc-hosted feed on its own schedule, use the EDL (Passive) Knoc type instead. RouterOS can also fetch address-lists from a URL on a timer.

Requirements

  • RouterOS v7.0 or newer (REST API was added in v7)
  • The www-ssl service enabled in IP > Services so the agent can reach https://<router>/rest/
  • A user account with permission to read and modify address lists (not rules)

Authentication

The Knocknoc agent authenticates to RouterOS with a username and password via HTTP basic auth. Use a dedicated service account so the credentials can be rotated and audited independently of administrator accounts.

Create a service user

  1. Log into RouterOS via Winbox or WebFig as an administrator
  2. Open System > Users > Groups
  3. Click New:
    • Name: knocknoc
    • Policies: enable api, rest-api, read, write, and policy. Disable everything else (no ftp, local, telnet, etc.). The rest-api policy is required on RouterOS v7.1+ to use the REST endpoints.
  4. Click OK to save the group
  5. Switch to System > Users > Users
  6. Click New:
    • Name: e.g., knocknoc-agent
    • Group: knocknoc
    • Password: a strong random value; you will paste it into Knocknoc
    • Allowed Address: restrict to the IP of the host running the Knocknoc agent if possible
  7. Click OK to save the user

Setup

Step 1: Enable the REST API

  1. In RouterOS, go to IP > Services
  2. Confirm www-ssl is enabled. Note the port (default 443)
  3. Restrict the Available From list to the agent host's IP if you have not already

Step 2: Create the Address-List and Firewall Rule

The agent will write to a single firewall address-list. You can pre-create entries or let Knocknoc add them on the first grant. The list itself exists implicitly the moment its first entry is added.

Decide a name (e.g., knocknoc-users). Then create a firewall rule that references it:

  1. In RouterOS, go to IP > Firewall > Filter Rules

  2. Click New

  3. Configure the rule:

    • Chain: forward (for transit traffic) or input (for traffic to the router itself)
    • Src. Address List: knocknoc-users (the same name you will enter in Knocknoc)
    • Dst. Address / Dst. Port / Protocol: whatever fits your policy
    • Action: Action > accept

  4. Click OK

  5. Make sure the rule sits above any default drop rule for the same chain

For IPv6, repeat under IPv6 > Firewall > Filter Rules using IPv6 > Firewall > Address Lists.

Step 3: Configure the Knocknoc Backend

In the Knocknoc admin wizard, create a Knoc and choose the Application type, Active mode, MikroTik vendor. Fill in:

Field Value
RouterOS URL https://<router-host> (include the port if non-default)
Insecure Tick only if the router uses a self-signed certificate
Username The service account name (knocknoc-agent)
Password The password set above
Address-list name knocknoc-users (must match the firewall rule)

Click Validate connection to confirm the agent can reach the device and read the address-list, then save.

Troubleshooting

The Knocknoc agent reports structured error codes when MikroTik operations fail. You can find more details on resolving these issues here.

Vendor Documentation

Back to top