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

If validation fails or grants do not appear in the address-list, the agent error code shown in the wizard links straight to the matching troubleshooting page. The full list is also available under MikroTik error codes.

Range Topic
208000–207049 Connection, authentication, TLS, and REST API availability
208100–207149 Address-list read/write operations
208400–207449 Unexpected response parsing errors

Vendor Documentation

Back to top