The convergence of networking hardware and virtualization has led to a complex landscape where MikroTik RouterOS, traditionally a firmware-based operating system for RouterBOARD hardware, is being adapted for containerized deployment. This transition is not a native "Dockerization" of the RouterOS kernel but rather a sophisticated application of virtualization wrappers and emulation layers. The ability to deploy RouterOS within a Docker container allows network engineers to create reproducible lab environments, perform unit testing for API-driven automation, and integrate network function virtualization (NFV) into modern CI/CD pipelines. Understanding the distinction between running a container on RouterOS and running RouterOS in a container is critical for any technical implementation.
RouterOS as a Container Host
MikroTik has introduced a native capability in RouterOS v7.x that transforms the router into a container host. This feature, accessed via the /container sub-menu, allows the RouterOS operating system to manage and execute Linux containers.
The technical implementation involves a specific container package that must be installed on the RouterOS device. Once enabled, the system can pull images from standard industry providers, including Docker Hub, Google Container Registry (GCR), and Quay.
The impact of this feature is a paradigm shift in how MikroTik devices are used. Instead of relying solely on the built-in RouterOS tools, administrators can deploy third-party software—such as monitoring agents, custom DNS servers, or lightweight web servers—directly on the router hardware.
This functionality creates a symbiotic relationship between the networking layer and the application layer. By hosting containers on the router, the need for an external server for basic services is eliminated, reducing hardware footprint and simplifying the network topology.
Running RouterOS Inside Docker Containers
Unlike the native container host feature, running RouterOS inside a Docker container requires a virtualization layer because RouterOS is not a native Linux application. The current ecosystem relies on wrapping a Cloud Hosted Router (CHR) virtual machine within a container using QEMU (Quick Emulator).
Technical Mechanism of QEMU Wrappers
The process involves taking a RouterOS CHR virtual machine disk (VMDK) and encapsulating it within a Docker image. When the container starts, it initiates a QEMU process that emulates the x86_64 hardware environment required by the CHR.
On Linux systems with KVM (Kernel-based Virtual Machine) support, this emulation can be highly efficient. However, on Apple Silicon (M1/M2/M3) platforms, the behavior changes. Docker pulls an arm64 image, but since RouterOS CHR is exclusively x86_64, QEMU must perform full emulation. This results in a performance penalty compared to amd64 systems where KVM acceleration is available.
The real-world consequence for the user is a variable boot time and execution speed. Users should expect a 30-60 second delay after starting the container before the RouterOS environment is fully booted and accessible.
This approach allows the RouterOS environment to exist as a portable artifact. It can be distributed via Docker Hub and deployed instantly without the need to configure a full VMware or VirtualBox environment, making it ideal for ephemeral testing.
Comparative Analysis of Available Docker Images
Several community-driven images exist to facilitate the deployment of RouterOS in Docker. These images vary in their target use case and configuration.
| Image Provider | Primary Focus | Key Features | Architecture Support |
|---|---|---|---|
| cnsoluciones/mikrotik | Lab and Testing | Wide port mapping, privileged mode | amd64 |
| evilfreelancer/docker-routeros | API Development | VNC access, QEMU based | amd64, arm64 |
| mkv28/mikrotik-routeros | General Testing | Portainer compatibility, VNC | amd64 |
The cnsoluciones/mikrotik image is specifically designed for laboratory use. It emphasizes a wide range of exposed ports to simulate a full-featured router. The evilfreelancer/docker-routeros image is optimized for developers working with the routeros-api-php library, providing a controlled environment for unit testing. The mkv28/mikrotik-routeros image offers streamlined deployment for users utilizing Portainer for container orchestration.
Deployment and Configuration Guide
Deploying RouterOS in a container requires specific privileges because the guest OS needs to manipulate network interfaces and kernel-level functions.
Docker Compose Implementation
Using Docker Compose is the recommended method for ensuring reliable host access and inter-container networking. A standard configuration requires privileged: true and the addition of NET_ADMIN capabilities to allow the container to manage network traffic.
The following configuration demonstrates a comprehensive deployment based on the cnsoluciones/mikrotik image:
yaml
services:
routeros:
container_name: "mikrotik"
image: cnsoluciones/mikrotik:7.16.2
privileged: true
ports:
- "21:21"
- "22:22"
- "23:23"
- "80:80"
- "443:443"
- "1194:1194"
- "1450:1450"
- "8291:8291"
- "8728:8728"
- "8729:8729"
- "13231:13231"
cap_add:
- NET_ADMIN
devices:
- /dev/net/tun
The inclusion of /dev/net/tun is a technical requirement for VPN services such as OpenVPN and WireGuard, as it allows the creation of tunnel interfaces. Without this device mapping, the container cannot establish the necessary virtual network links.
Manual Docker Run Execution
For quick testing, a single docker run command can be used. The mkv28/mikrotik-routeros implementation provides a clear example of this method:
bash
docker run -d --name mikrotik-routeros -p 2222:22 -p 8728:8728 -p 8729:8729 -p 7777:80 -p 8291:8291 -p 5900:5900 --device /dev/net/tun --privileged --cap-add=NET_ADMIN mkv28/mikrotik-routeros:latest
In this command, the mapping 7777:80 indicates that the host's port 7777 is mapped to the container's port 80. Users can modify the left side of the mapping to avoid port conflicts on the host machine.
Network Port Mapping and Service Access
Accessing a containerized RouterOS instance requires a precise understanding of which ports are exposed. Because the container acts as a gateway, the internal ports of RouterOS must be mapped to the external ports of the Docker host.
Default Management Ports
The following table details the critical ports required for managing a RouterOS container:
| Service | Internal Port | Purpose |
|---|---|---|
| SSH | 22 | Secure Shell management |
| Telnet | 23 | Unencrypted remote access |
| WWW | 80 | Web-based configuration (WebFig) |
| WWW-SSL | 443 | Secure Web-based configuration |
| WinBox | 8291 | Proprietary MikroTik GUI management |
| API | 8728 | Programmatic access for automation |
| API-SSL | 8729 | Secure programmatic access |
Specialized Networking Ports
Beyond management, specific ports are required for networking services. These must be explicitly mapped in the Docker configuration to function.
- OpenVPN: Port
1194(TCP/UDP). This allows the container to act as an OpenVPN server. - L2TP: Port
1450or1701. Used for Layer 2 Tunneling Protocol. - WireGuard: Port
13231. The modern, high-performance VPN protocol. - PPTP: Port
1723. An older VPN protocol. - IPSec: Ports
50,51,500/udp, and4500/udp.
Failure to map these ports results in the "silent failure" of the service; the service will appear active inside the RouterOS console, but no external traffic will reach it.
Advanced Integration and CI/CD Workflows
The ability to run RouterOS in Docker enables complex automation workflows that were previously impossible without dedicated hardware or heavy VM snapshots.
Integration with GitHub Actions
A sophisticated implementation involves using GitHub Actions to run RouterOS CHR within a GitHub runner. The process follows a specific sequence:
- A build starts in a standard GitHub container.
- QEMU is initialized to provide the x86 architecture.
- Docker Compose is used to build and run the
EvilFreelancer/docker-routerosimage. - JavaScript-based REST API calls are sent to the running CHR to perform tasks such as schema extraction via
/console/inspect. - The CHR instance is destroyed when the GitHub Action completes.
This allows for the automated testing of RouterOS configurations and the extraction of API schemas in a clean, isolated environment.
Containerlab and VR Network Lab
For larger-scale network simulations, tools like Containerlab and VR Network Lab are employed. Containerlab wraps CHR in a Docker container to create complex network topologies.
The VR Network Lab project allows for the creation of Docker images directly from MikroTik CHR VMDKs. This is particularly useful for creating "digital twins" of existing networks. While the CHR model limits unlicensed users to 1MB/s speeds, this is often sufficient for configuration testing and network automation verification.
Technical Constraints and Performance Analysis
Despite the flexibility of Docker, there are significant technical limitations when running RouterOS in a containerized environment.
The Kernel Limitation
A primary constraint is that RouterOS is not a native Linux application; it is a complete operating system. In a standard container, there is no "native" kernel for the guest OS. Therefore, the RouterOS "container" is actually a VM running inside a container.
This means that many functions in RouterOS, which are essentially user-interface wrappers for Linux kernel functions (such as the firewall being a UI for iptables), must be executed within the QEMU environment.
Performance and Scalability
The performance of a containerized RouterOS is inherently lower than a bare-metal installation or a native VM.
- Throughput: Unlicensed CHR is limited to 1MB/s.
- Latency: The QEMU virtualization layer introduces overhead.
- Resource Consumption: Running multiple instances of QEMU inside Docker can lead to high CPU and RAM usage, limiting the scalability for large-scale digital twins.
For production environments requiring high throughput, a real Docker image (where the router functions are implemented as userland executables) would be more scalable. However, MikroTik has not yet released such a native image, as the RouterOS architecture is deeply tied to the kernel.
Troubleshooting and Common Issues
Deploying RouterOS in Docker often leads to specific technical hurdles related to networking and permissions.
Permission Denied Errors
Users frequently encounter errors when starting the container if privileged: true is not set. This is because the RouterOS process requires the ability to modify the host's network stack, which is prohibited in standard Docker containers for security reasons.
Networking Connectivity Issues
A common issue is the inability to reach the RouterOS instance via WinBox or SSH. This is typically caused by:
- Incorrect port mapping: Ensure the left side of the
portsmapping indocker-compose.ymlmatches the port used in the client software. - Missing TUN device: If VPNs are not working, verify that
--device /dev/net/tunis included in the run command. - Slow Boot: Users attempting to connect immediately after
docker runmay find the service unavailable. Waiting 30-60 seconds for the QEMU guest to boot is mandatory.
Final Technical Analysis
The current state of MikroTik in Docker is a bridge between traditional networking and modern DevOps. The ability to host containers on RouterOS (v7.x) provides an edge-computing capability, allowing the router to handle light application logic. Conversely, running RouterOS in Docker (via QEMU) provides an essential tool for developers and network architects to simulate environments without hardware.
The technical trade-off is clear: the QEMU-in-Docker approach provides portability and ease of deployment at the cost of performance and kernel-level efficiency. For lab environments, API unit testing, and CI/CD integration, this is an acceptable trade-off. However, for production-grade routing, the virtualization layer remains a bottleneck.
The evolution of this ecosystem likely points toward more integrated "cloud-native" routing images. Until such a time, the combination of Docker Compose, QEMU, and CHR VMDKs remains the gold standard for simulating MikroTik environments in a containerized world.