> ## Documentation Index
> Fetch the complete documentation index at: https://e-gurl.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Mikrotik integration

# MikroTik RouterOS Integration

DNS-MNS now includes comprehensive integration with **MikroTik RouterOS**, allowing you to configure and manage DNS settings directly on your MikroTik router from the command line.

## Overview

MikroTik routers are popular in Iran for their flexibility and powerful networking features. This integration enables you to:

* **Configure DNS servers** on your MikroTik router with the best performing servers
* **Enable DoH/DoT** (DNS over HTTPS/TLS) on RouterOS 7+ for encrypted DNS
* **Manage static DNS entries** for local network resolution
* **Backup and restore** DNS configurations
* **Test connectivity** to DNS servers from the router's perspective

## Prerequisites

### Router Requirements

* MikroTik router running RouterOS 6.x or 7.x
* API service enabled on the router
* Network connectivity between your computer and the router

### Enable API on Your Router

Connect to your router via Winbox or SSH and run:

```bash theme={null}
# Enable API (port 8728)
/ip service enable api

# Enable API-SSL (port 8729) for secure connections
/ip service enable api-ssl

# Verify services are running
/ip service print
```

### Firewall Configuration

If you have a firewall on your router, allow access to the API ports:

```bash theme={null}
# Allow API from your local network
/ip firewall filter add chain=input protocol=tcp dst-port=8728 src-address=192.168.88.0/24 action=accept comment="Allow API"
/ip firewall filter add chain=input protocol=tcp dst-port=8729 src-address=192.168.88.0/24 action=accept comment="Allow API-SSL"
```

## Quick Start

### 1. Detect Your Router

Find MikroTik routers on your network:

```bash theme={null}
dns-mns mikrotik detect
```

### 2. Check Router Status

View detailed information about your router:

```bash theme={null}
dns-mns mikrotik status --address 192.168.88.1 --username admin
```

### 3. Configure DNS

Set the best DNS servers on your router:

```bash theme={null}
dns-mns mikrotik configure \
  --address 192.168.88.1 \
  --username admin \
  --servers 1.1.1.1,8.8.8.8
```

## CLI Commands

### `mikrotik detect`

Detects MikroTik routers on the local network.

```bash theme={null}
# Detect routers
dns-mns mikrotik detect

# JSON output
dns-mns mikrotik detect --json
```

### `mikrotik status`

Shows detailed router and DNS status.

```bash theme={null}
# Basic status
dns-mns mikrotik status --address 192.168.88.1 --username admin

# With password (for scripting)
dns-mns mikrotik status \
  --address 192.168.88.1 \
  --username admin \
  --password yourpassword

# Use secure API-SSL
dns-mns mikrotik status \
  --address 192.168.88.1 \
  --username admin \
  --tls

# JSON output
dns-mns mikrotik status --address 192.168.88.1 --username admin --json
```

### `mikrotik configure`

Configures DNS settings on the router.

```bash theme={null}
# Set DNS servers
dns-mns mikrotik configure \
  --address 192.168.88.1 \
  --username admin \
  --servers 1.1.1.1,8.8.8.8

# Enable DoH (RouterOS 7+ only)
dns-mns mikrotik configure \
  --address 192.168.88.1 \
  --username admin \
  --doh https://cloudflare-dns.com/dns-query

# Enable DoT (RouterOS 7+ only)
dns-mns mikrotik configure \
  --address 192.168.88.1 \
  --username admin \
  --dot 1.1.1.1

# Combine options
dns-mns mikrotik configure \
  --address 192.168.88.1 \
  --username admin \
  --servers 1.1.1.1,8.8.8.8 \
  --doh https://cloudflare-dns.com/dns-query
```

### `mikrotik test`

Tests connectivity to DNS servers from the router.

```bash theme={null}
# Test default servers
dns-mns mikrotik test \
  --address 192.168.88.1 \
  --username admin

# Test specific servers
dns-mns mikrotik test \
  --address 192.168.88.1 \
  --username admin \
  --servers 1.1.1.1,9.9.9.9,208.67.222.222
```

### `mikrotik flush`

Flushes the DNS cache on the router.

```bash theme={null}
dns-mns mikrotik flush \
  --address 192.168.88.1 \
  --username admin
```

### `mikrotik backup`

Creates a backup of the current DNS configuration.

```bash theme={null}
# Create backup
dns-mns mikrotik backup \
  --address 192.168.88.1 \
  --username admin

# JSON output
dns-mns mikrotik backup \
  --address 192.168.88.1 \
  --username admin \
  --json
```

### `mikrotik restore`

Restores DNS configuration from a backup file.

```bash theme={null}
dns-mns mikrotik restore \
  --address 192.168.88.1 \
  --username admin \
  /path/to/backup.json
```

### `mikrotik static`

Manages static DNS entries.

```bash theme={null}
# List static entries
dns-mns mikrotik static list \
  --address 192.168.88.1 \
  --username admin

# Add static entry
dns-mns mikrotik static add \
  --address 192.168.88.1 \
  --username admin \
  --name myserver.local \
  --ip 192.168.88.100 \
  --comment "My local server"

# Remove static entry
dns-mns mikrotik static remove \
  --address 192.168.88.1 \
  --username admin \
  --name myserver.local
```

## Interactive Menu

You can also access MikroTik integration through the interactive menu:

```bash theme={null}
dns-mns
```

Then select option **12) MikroTik Integration**.

## RouterOS Version Support

### RouterOS 6.x (Legacy)

* Basic DNS server configuration
* Static DNS entries
* DNS cache management
* **No DoH/DoT support**

### RouterOS 7.x (Modern)

* All RouterOS 6.x features
* DNS over HTTPS (DoH)
* DNS over TLS (DoT)
* Certificate validation for DoH

## Security Considerations

### Password Security

* **Never commit passwords** to version control
* Use environment variables for passwords in scripts
* Consider using API-SSL (`--tls` flag) for encrypted connections

### Example with Environment Variable

```bash theme={null}
export MIKROTIK_PASSWORD="yourpassword"

dns-mns mikrotik status \
  --address 192.168.88.1 \
  --username admin \
  --password "$MIKROTIK_PASSWORD"
```

### API Access Control

Limit API access to specific IP addresses:

```bash theme={null}
# On your MikroTik router
/ip service set api address=192.168.88.0/24
/ip service set api-ssl address=192.168.88.0/24
```

## Troubleshooting

### Connection Refused

**Problem:** `failed to connect to 192.168.88.1: connection refused`

**Solution:**

1. Verify the router is reachable: `ping 192.168.88.1`
2. Enable API service: `/ip service enable api`
3. Check firewall rules

### Authentication Failed

**Problem:** `login failed: invalid user name or password`

**Solution:**

1. Verify username and password
2. Check if the user has API access permissions
3. Try logging in via Winbox to confirm credentials

### DoH/DoT Not Working

**Problem:** `DoH requires RouterOS 7.x or later`

**Solution:**

1. Check RouterOS version: `/system resource print`
2. Upgrade to RouterOS 7.x if needed
3. Verify certificate configuration for DoH

### Certificate Issues with DoH

**Problem:** DoH fails with certificate validation errors

**Solution:**

```bash theme={null}
# Install certificates on your router
/tool fetch url=https://cacerts.digicert.com/DigiCertGlobalRootCA.crt.pem
/certificate import file-name=DigiCertGlobalRootCA.crt.pem
```

## Best Practices

### 1. Always Backup First

Before making changes, create a backup:

```bash theme={null}
dns-mns mikrotik backup --address 192.168.88.1 --username admin
```

### 2. Test DNS Servers

Test servers from the router's perspective:

```bash theme={null}
dns-mns mikrotik test --address 192.168.88.1 --username admin
```

### 3. Use Secure Connections

Whenever possible, use API-SSL:

```bash theme={null}
dns-mns mikrotik status --address 192.168.88.1 --username admin --tls
```

### 4. Flush Cache After Changes

After changing DNS settings, flush the cache:

```bash theme={null}
dns-mns mikrotik flush --address 192.168.88.1 --username admin
```

## Common Use Cases

### Use Case 1: Gaming Optimization

Configure the fastest DNS servers for gaming:

```bash theme={null}
# Use gaming-optimized DNS
dns-mns mikrotik configure \
  --address 192.168.88.1 \
  --username admin \
  --servers 1.1.1.1,1.0.0.1
```

### Use Case 2: Bypass Censorship with DoH

Use DoH to bypass DNS-based censorship:

```bash theme={null}
dns-mns mikrotik configure \
  --address 192.168.88.1 \
  --username admin \
  --doh https://cloudflare-dns.com/dns-query
```

### Use Case 3: Local Network with Static Entries

Set up local domain resolution:

```bash theme={null}
# Add static entries for local servers
dns-mns mikrotik static add \
  --address 192.168.88.1 \
  --username admin \
  --name nas.local \
  --ip 192.168.88.10 \
  --comment "Network Attached Storage"

dns-mns mikrotik static add \
  --address 192.168.88.1 \
  --username admin \
  --name printer.local \
  --ip 192.168.88.20 \
  --comment "Office Printer"
```

## API Reference

### Connection Options

| Flag         | Default        | Description             |
| ------------ | -------------- | ----------------------- |
| `--address`  | `192.168.88.1` | Router IP address       |
| `--username` | `admin`        | Router username         |
| `--password` | (empty)        | Router password         |
| `--tls`      | `false`        | Use API-SSL (port 8729) |
| `--port`     | (auto)         | Custom API port         |

<Note>
  When using `--tls`, the API client's `InsecureSkipVerify` setting controls certificate validation. By default, certificate verification is enabled for security. Only disable verification if you're using self-signed certificates and understand the security implications.
</Note>

### Global Flags

| Flag         | Description            |
| ------------ | ---------------------- |
| `--json`     | Output in JSON format  |
| `--no-color` | Disable colored output |

## Further Reading

* [MikroTik RouterOS Documentation](https://help.mikrotik.com/docs/)
* [RouterOS API Reference](https://help.mikrotik.com/docs/spaces/ROS/pages/47579160/API)
* [DNS over HTTPS in RouterOS 7](https://help.mikrotik.com/docs/spaces/ROS/pages/37748767/DNS)

## Getting Help

If you encounter issues with the MikroTik integration:

1. Run with diagnostics: `dns-mns diagnose`
2. Check router logs: `/log print`
3. Verify API service: `/ip service print`
4. Open an issue with the output of `dns-mns mikrotik status --json`