Table of Contents

Troubleshooting MikroTik Integration Issues

Jennifer Trower Updated by Jennifer Trower

Read Time: 4 mins

MikroTik integration with Sonar relies on a small number of specific configurations being correct. This article highlights the operational issues that most often occur after setup, including API connection problems, port conflicts, Address List changes, bridge and NAT configuration, and queue or speed changes not applying.

For initial setup, see MikroTik as an Inline Device: Integration With Sonar and the related MikroTik articles.

Permissions

Before getting started with troubleshooting, your user roles will need to be adjusted to account for the permissions required to view and diagnose MikroTik integration issues.

If you're a Super Admin, you already have full access, and no changes are needed. To learn more, see the Roles and Permissions article.
Entity Permission Why It's Required
Inline Device View all inline devices View the MikroTik device record in Sonar, including its IP, port, and connection settings.
Inline Device Update an inline device Update the MikroTik integration settings, such as port or credentials, when diagnosis identifies a mismatch.
Service Mapping View all integration service mappings View how Sonar service changes are mapped into MikroTik configuration via the Device Mapper.
Field Mapping View all integration field mappings View the Device Mapper field configuration for translating Sonar fields to MikroTik fields.
IP Assignment View all IP assignments Verify IP assignments and pool configuration when subscribers are not routing or not receiving dynamic addresses.
Inventory View all inventory Review inventory attached to the MikroTik when diagnosing device-side issues.
Account View accounts and related entities Review affected subscriber accounts and account-level logs when diagnosing routing or address assignment issues.

Troubleshooting Steps

Start with the symptom that best matches what you are seeing.

Symptom-to-Cause Quick Reference

Symptom Most Likely Cause Go To
Validation failed on first connect Validation false-negative Step 1
Sonar cannot reach the MikroTik API API user, port, or allowed-from IP Step 2
MikroTik became unreachable after configuration Address List was modified Step 3
Subscribers are connected but not routing Bridge or NAT order issue Step 4
Subscribers are not receiving dynamic addresses Address Pool or DHCP lease script Step 5
Speed or queue changes from Sonar not applying API user permissions or device mapper Step 6
Step 1: “Validation Failed” on First Connect

Use this step when you are first validating credentials and Sonar returns a Validation Failed message with the status “This is not a compatible RouterOS service.”

This is a known false-negative. The MikroTik API can take a moment to respond on first connection.

To troubleshoot:

  1. Wait two minutes.
  2. Refresh the page.
  3. Validation usually succeeds on retry without any configuration change.

If the message continues after multiple retries, continue to Step 2.

Step 2: Sonar Cannot Reach the MikroTik API

Use this step when Sonar cannot connect to the MikroTik API at all, or only intermittently.

Three pieces must be correct for the API connection to work.

To troubleshoot:

  1. Navigate to System > Users on the MikroTik.
  2. Confirm the user dedicated to Sonar exists and is in the write group.
  3. Confirm the Allowed Address field on the user matches Sonar's current egress IPs.
  4. Confirm the API port is not blocked by any firewall between the MikroTik and Sonar.
  5. Confirm the port configured in Sonar's MikroTik integration matches the API port in use.

If you have changed Winbox or API ports from their defaults (8291 and 8729 respectively), make sure the new port values are configured in Sonar's integration settings.

Step 3: MikroTik Became Unreachable After Configuration

Use this step when the MikroTik is no longer reachable on its management interface, often shortly after an Address List edit.

Do not delete or modify the existing 192.168.122.x Address List on the MikroTik. Deleting or modifying it will render the MikroTik unreachable. Recovery requires direct console access and starting the configuration over.

If this has already happened, console access is required to restore configuration.

Step 4: Subscribers Are Connected but Not Routing

Use this step when subscribers receive IP addresses and can connect to the gateway, but cannot reach the internet.

This is usually a bridge or NAT configuration order issue.

To troubleshoot:

  1. Confirm a bridge exists and is properly assigning subscriber interfaces.
  2. Confirm a NAT masquerade rule exists and is scoped to your subscriber IPAM supernet.
  3. Confirm the NAT rule was added after the bridge was in place, not before.
  4. Confirm a default gateway route exists pointing to your upstream.

If the bridge and NAT were configured in the wrong order, remove and re-add the NAT rule with the bridge already in place.

Step 5: Subscribers Are Not Receiving Dynamic Addresses

Use this step when subscribers expecting dynamic DHCP leases either receive no address or receive an address that does not sync to Sonar.

To troubleshoot:

  1. Confirm the DHCP pool in MikroTik points to the correct IPAM-backed pool.
  2. Confirm the Address Pool setting is not still set to static-only from initial setup. For dynamic leases, change it to the configured pool.
  3. Confirm the DHCP lease script is installed. For more information, see Troubleshooting DHCP and DHCP Delivery.
Step 6: Speed or Queue Changes from Sonar Are Not Applying

Use this step when speed changes or queue updates made in Sonar do not apply on the MikroTik.

To troubleshoot:

  1. Confirm the API user has write group permissions.
  2. In Sonar, confirm the device has a Device Mapper configured. For more information, see Building a Device Mapper.
  3. Confirm the queue tree and PCQ structure on the MikroTik matches what Sonar expects. For more information, see MikroTik: Controlling Speeds.
  4. Test by manually changing a queue on the MikroTik using the same API user from a workstation. If manual API calls work but Sonar's do not, gather logs and open a support ticket.

When to Open a Support Ticket

Open a support ticket after completing the relevant troubleshooting step if the issue continues.

Include the following information:

  1. The symptom you are seeing.
  2. The step in this article you completed.
  3. MikroTik model and RouterOS version.
  4. The API port being used and confirmation it is open from Sonar's egress IPs.
  5. Whether the API user is in the write group and what its Allowed Address field contains.
  6. A snippet of the relevant Sonar log.
  7. Any recent configuration changes on the MikroTik.

How did we do?

Troubleshooting DHCP: Why Isn't My Subscriber Getting an Address?

Using Multiple Network Devices in Sonar

Contact