Router Setup

Overview

Vutia manages your MikroTik router remotely through the RouterOS API. The platform connects to your router via a secure L2TP/IPSec tunnel — no public IP or port forwarding required.

How it works

Your Router

MikroTik behind
any network

L2TP/IPSec

Encrypted Tunnel

Secure private
link to platform

API

Vutia

Manages PPPoE,
hotspot, queues

Why L2TP tunnel? Most routers are behind NAT or CGNAT, making direct connections impossible. The tunnel works from any network — home, office, behind ISP CGNAT, or mobile. Your router initiates the connection outbound, so no public IP or port forwarding is needed.

Before you begin

Make sure you have the following ready:

A MikroTik router running RouterOS 6.x or 7.x
Winbox or terminal access to your router (SSH, WebFig, or Winbox app)
Internet connectivity on the router (the tunnel connects over the internet)
An active Vutia account with an ISP subscription

Estimated time: 10–15 minutes. You'll need to run a few commands on your router and paste one command from the dashboard.

1. Enable the API & open firewall

Vutia communicates with your router through the RouterOS API service on port 8728. You need to enable the API service and make sure the firewall allows access from the tunnel.

1a. Enable the API service

# Enable the API service
/ip service enable api

# Verify it's enabled (should show port 8728 without X)
/ip service print

In the output, the api row should show port 8728 without an X prefix. If you see X, the service is disabled.

Winbox: Go to IP → Services. Find the api row. If disabled (X), select it and click the checkmark to enable.

If API is disabled, the dashboard will show a "Connection refused" error when testing. This is the most common cause of connection failures. Always check this first.

1b. Allow API through the firewall

MikroTik's default firewall may block API connections from the tunnel network. You need to add a rule that allows TCP port 8728 from the 10.255.0.0/24 tunnel subnet. Place it before any drop rules.

# Check for existing drop/reject rules in the input chain
/ip firewall filter print where chain=input action=drop
/ip firewall filter print where chain=input action=reject

# Add a rule to allow API access from the tunnel (before any drop rules)
/ip firewall filter add chain=input src-address=10.255.0.0/24 dst-port=8728 protocol=tcp action=accept place-before=0 comment="Allow API from management tunnel"

Why place-before=0? Firewall rules are processed top-down. If a drop rule comes before your accept rule, the API traffic gets dropped before it reaches the accept rule. place-before=0 inserts it at the very top.

1c. Verify the port is open

After enabling the API and updating the firewall, verify port 8728 is accessible.

# Confirm the API service is listening on port 8728
/ip service print where name=api

# Check that no firewall rule is blocking it
/ip firewall filter print where dst-port=8728

The service output should show: api on port 8728, no X prefix. The firewall output should show your new accept rule. If you see a drop rule above it, move the accept rule higher.

Using API-SSL (port 8729)? If you enable SSL in the dashboard, replace 8728 with 8729 in the firewall rule above and enable the api-ssl service instead: /ip service enable api-ssl

2. Create an API user

Create a dedicated user for the platform. We recommend not using the default admin account — if the admin password changes (e.g. after a router reset), the platform loses access.

Terminal

# Create a dedicated API user with full access
/user add name=vutia-api password=YourStrongPassword group=full

# Verify the user was created
/user print

Winbox

Go to System → Users

Click + to add a new user

Set Name to vutia-api, set a strong Password, and set Group to full

Click OK

Why full group? The platform needs to manage PPPoE secrets, hotspot users, IP queues, and firewall rules. The full group grants the necessary permissions.

Tip: Write down the password — you'll enter it in the dashboard in the next step.

Password mismatch is the #1 cause of "Authentication failed" errors. If you reset your router or change the password later, you must also update it in the dashboard (Edit Router → Password).

3. Add router in dashboard

Log in to your Vutia dashboard and register the router. The platform will automatically generate L2TP tunnel credentials.

Navigate to Network → Routers in the sidebar

Click New Router

Fill in the details:

• Name — a friendly name, e.g. "Main Tower Router"
• Router Type — select "MikroTik"
• Username — the API user you created (vutia-api)
• Password — the password from Step 2

Click Create

After saving, the platform generates L2TP tunnel credentials and redirects you to the router detail page. Open the Tunnel Setup tab to continue.

Form fields reference

Field	Example	Description
Name	Main Tower Router	A friendly label you'll see in the dashboard
Router Type	MikroTik	The router platform (MikroTik, Ubiquiti, etc.)
API Port	`8728`	RouterOS API port (default, rarely needs changing)
Username	`vutia-api`	The RouterOS user from Step 2
Password	********	Stored encrypted — must match the router

4. Configure the L2TP tunnel

After creating the router, go to its Tunnel Setup tab. You'll see pre-filled MikroTik commands with your unique tunnel credentials.

On the router detail page, click the Tunnel Setup tab

Click Copy to copy the MikroTik command

Open a terminal on your MikroTik (Winbox terminal, SSH, or WebFig terminal)

Paste the command and press Enter

Wait 5–10 seconds for the tunnel to connect

The command creates an L2TP client interface on your router that connects to the Vutia server. It looks like this:

# Example (your credentials will be different)
/interface l2tp-client add name=l2tp-isp connect-to=YOUR_SERVER_IP user=router-myisp-1 password="generated-password" use-ipsec=yes ipsec-secret="shared-secret" allow=mschap2 disabled=no

Critical: The allow=mschap2 parameter is required. MikroTik does not work with CHAP or PAP for L2TP authentication. If you omit this, the tunnel will fail to connect.

About the tunnel: This tunnel is for management only. Your customers' internet traffic does NOT flow through it. If the Vutia server is briefly unreachable, your router continues serving customers normally.

5. Verify tunnel connection

After pasting the command, verify the tunnel is connected on your MikroTik.

Check the L2TP client status

/interface l2tp-client print

Look for the R flag (Running). The output should look like:

Flags: X - disabled; R - running
 0  R  name="l2tp-isp" ... connect-to=YOUR_SERVER_IP

Verify the tunnel IP

/ip address print where interface=l2tp-isp

You should see a 10.x.x.x address assigned to the tunnel interface.

Ping the server through the tunnel

/ping 10.255.0.1 count=3

You should get replies with 0% packet loss. Typical latency depends on your internet connection.

Tunnel is up! If you see the R flag, a tunnel IP, and successful pings, the tunnel is working. Proceed to the next step.

No R flag? See Troubleshooting below. Common causes: wrong credentials, missing allow=mschap2, or ISP blocking IPSec ports.

6. Test from dashboard

Once the tunnel is connected, verify the platform can reach your router's API.

Go back to your router's detail page in the Vutia dashboard

Click Test Connection in the header

If successful, you'll see the router's identity and RouterOS version

The router status changes to Online

Done! Your router is connected to Vutia. You can now provision Hotspot or PPPoE services from the router's detail page.

Quick reference

All the commands you need to run on your MikroTik, in order.

# === Router Setup for Vutia ===

# 1. Enable API service
/ip service enable api

# 2. Allow API through firewall (before any drop rules)
/ip firewall filter add chain=input src-address=10.255.0.0/24 dst-port=8728 protocol=tcp action=accept place-before=0 comment="Allow API from management tunnel"

# 3. Create dedicated API user
/user add name=vutia-api password=YOUR_PASSWORD group=full

# 4. Paste the L2TP command from the Tunnel Setup tab
#    (copied from your dashboard after adding the router)

# === Verify ===
/ip service print
/ip firewall filter print where dst-port=8728
/user print
/interface l2tp-client print
/ping 10.255.0.1 count=3

Understanding connection errors

When you click Test Connection in the dashboard, the platform classifies any errors into specific categories with actionable guidance. Here's what each error means and how to fix it.

Authentication failed

Error: "Invalid user name or password"

Meaning: The platform connected to the router's API port, but the username or password is wrong.

Fix:

1. Verify the password on the router: try logging into Winbox with the same credentials
2. If the router was recently reset, the password may have reverted to the default
3. Edit the router in the dashboard and update the password to match
4. Check the username is exactly correct (case-sensitive)

Connection timed out

Error: "Connection timed out after 5 seconds"

Meaning: The platform tried to connect but received no response within the timeout window.

Fix:

1. Is the L2TP tunnel connected? Check: /interface l2tp-client print — look for the R flag
2. Is the tunnel IP assigned? Check: /ip address print where interface=l2tp-isp
3. Is the API service enabled? Check: /ip service print
4. Are firewall rules blocking API access? Check: /ip firewall filter print where dst-port=8728

Connection refused

Error: "Connection refused on port 8728"

Meaning: The router is reachable but the API service is not running on the expected port.

Fix:

1. Enable the API: /ip service enable api
2. If using SSL, make sure the dashboard has "Use SSL" enabled and port set to 8729
3. If the API port has been changed, update it in the dashboard

Router unreachable

Error: "Could not establish connection"

Meaning: The platform cannot reach the router at all. The tunnel may be disconnected.

Fix:

1. Check tunnel status on the router: /interface l2tp-client print
2. If no R flag, the tunnel is down. Check internet connectivity: /ping 8.8.8.8
3. Check the tunnel command was pasted correctly (credentials, server IP)
4. Some ISPs block IPSec (UDP ports 500/4500). Try from a different network.

Troubleshooting

L2TP tunnel not connecting (no R flag)

First, check the L2TP logs for specific errors:

/log print where topics~"l2tp"

Common causes and fixes:

• Wrong credentials — Double-check the L2TP username, password, and IPSec secret match exactly what's shown in the Tunnel Setup tab. Re-copy and paste the command.
• Missing allow=mschap2 — MikroTik requires MS-CHAPv2 authentication. Remove the old L2TP client and paste the command again:
```
/interface l2tp-client remove [find name=l2tp-isp]
# Then paste the command from the Tunnel Setup tab again
```
• ISP blocking IPSec — Some ISPs block UDP ports 500 and 4500 (used by IPSec). Try connecting from a different network (e.g., mobile hotspot) to confirm.
• No internet — Verify basic connectivity:
```
/ping 8.8.8.8 count=3
```
• DNS resolution failure — If the server IP doesn't resolve, add a DNS server:
```
/ip dns set servers=8.8.8.8,1.1.1.1
```

Tunnel connected but dashboard shows "Connection timed out"

The tunnel is up but the API isn't reachable through it. Check:

1. Is API enabled?
```
/ip service print
```
The api line should show port 8728 without an X prefix.

2. Firewall blocking the tunnel IP?

/ip firewall filter print where action=drop

If there's a drop rule that catches traffic from the tunnel interface, add an accept rule before it:

/ip firewall filter add chain=input src-address=10.255.0.0/24 dst-port=8728 protocol=tcp action=accept place-before=0 comment="Allow API from tunnel"

3. Can the server reach the router? From the router, ping the server tunnel IP:
```
/ping 10.255.0.1 count=3
```

"Authentication failed" after router reset

When a MikroTik is reset to factory defaults, all user accounts revert to the default admin user (usually with no password or a different password).

To fix:

1. Log into the router via Winbox or terminal

2. Re-create the API user:

/user add name=vutia-api password=YourNewPassword group=full

3. In the Vutia dashboard, edit the router and update the password
4. Click Test Connection to verify

Tip: After a reset you'll also need to re-enable the API service and re-paste the L2TP tunnel command.

"Connection refused" on port 8728

The API service is disabled or not running. Fix:

/ip service enable api
/ip service print

If the API port was changed from the default, update it in the dashboard (Edit Router → API Port).

Multiple L2TP client entries after re-pasting the command

If you pasted the tunnel command multiple times, you may have duplicate entries. Clean up:

# List all L2TP clients
/interface l2tp-client print

# Remove all and re-add (paste the command from Tunnel Setup tab)
/interface l2tp-client remove [find]

Then paste the command from the Tunnel Setup tab one more time.

Router shows online but actions fail

If the router shows as online but hotspot/PPPoE setup fails:

• Check the API user has full group permissions: /user print
• Some actions (like hotspot provisioning) take longer. Wait a moment and try again.
• Check the router's logs for errors: /log print