Container

Container

MikroTik’s Container feature allows you to run Linux containerized environments directly on RouterOS v7.x devices. Containers are compatible with images from Docker Hub, Google Container Registry (GCR), Quay, and other providers, enabling you to run familiar containerized applications on your MikroTik hardware.

Overview

The Container feature in RouterOS provides a lightweight virtualization solution that allows you to run containerized applications alongside your router’s core networking functions. Unlike full virtual machines, containers share the host operating system’s kernel while maintaining isolated user spaces for each application.

Key Capabilities

• Run standard Docker-compatible container images on RouterOS
• Isolate applications in their own environments
• Configure networking for containers with flexible topologies
• Mount external storage for persistent data
• Set environment variables and startup parameters
• Configure auto-restart and boot persistence
• Access container shells for debugging and management

Architecture

Containers in RouterOS operate through several interconnected components:

Component	Purpose
Container package	Core software enabling container functionality
veth interfaces	Virtual ethernet connections between containers and router network
Container config	Registry and resource management settings
Environment variables	Configuration passed to containerized applications
Mounts	Persistent storage mappings between router and containers

Requirements

Before using containers, ensure your environment meets these requirements:

Hardware Requirements

Requirement	Details
Architecture	arm, arm64, or x86
RouterOS version	RouterOS v7.4 or later
Storage	External disk (USB, SATA, NVMe) recommended
Disk performance	100MB/s sequential read/write, 10K random IOPS

Software Requirements

The Container package must be installed on your RouterOS device. Devices with EN7562CT CPU (such as hEX Refresh) only support arm32v5 images, limiting available container options.

Device Mode

Containers require enabling Device Mode on your RouterOS device:

/system/device-mode/update container=yes

After executing this command, you must confirm the change by pressing the reset button or performing a cold reboot (for x86 devices).

Container Configuration

The global container configuration controls registry access and resource limits:

/container/config/

Configuration Properties

Property	Description	Default
registry-url	External registry for downloading images	https://lscr.io/
tmpdir	Temporary extraction directory	-
memory-high	RAM usage soft limit in bytes	unlimited
username	Registry authentication username (RouterOS v7.8+)	-
password	Registry authentication password (RouterOS v7.8+)	-

Setting Configuration

/container/config/set registry-url=https://registry-1.docker.io tmpdir=disk1/tmp
/container/config/set memory-high=512M

Container Properties

Individual containers are configured under /container:

/container/print

Container Properties Reference

Property	Description
auto-restart-interval	Interval for automatic restart on failure (e.g., ”10s”)
cmd	Default executable for container
comment	Short description for identification
dns	Custom DNS servers for container
domain-name	DNS domain name
entrypoint	Executable to run at container startup (e.g., “/bin/sh”)
envlist	Environment variables list reference
file	Path to imported tar.gz container image
hostname	Container hostname for identification
interface	veth interface for network connectivity
logging	Enable container output logging to RouterOS log
start-on-boot	Auto-start container on device boot
mounts	Volume mount references
remote-image	Image name from registry
root-dir	Container storage location
stop-signal	Linux signal for graceful shutdown (default: 15)
workdir	Working directory for container process
devices	Physical device passthrough
cpu-list	CPU core affinity
user	User and group for container process
memory-high	RAM usage hard limit

Adding Container Images

There are three methods to add container images to RouterOS.

Option A: Pull from Registry

Download images directly from Docker Hub or other registries:

/container/config/set registry-url=https://registry-1.docker.io tmpdir=disk1/tmp
/container/add remote-image=pihole/pihole interface=veth1 root-dir=disk1/images/pihole name=pihole

Option B: Import from Local File

Import pre-downloaded container archives:

/container/add file=disk1/pihole.tar interface=veth1 root-dir=disk1/images/pihole name=pihole

Option C: Build Custom Images

Build and import custom containers using Podman or Docker:

podman pull --arch=arm64 docker.io/pihole/pihole
podman save pihole > pihole.tar

Upload to router and import:

/container/add file=disk1/pihole.tar interface=veth1 root-dir=disk1/images/pihole name=pihole

Managing Containers

Starting and Stopping

/container/start pihole
/container/stop pihole
/container/restart pihole

Viewing Status

/container/print detail

Accessing Container Shell

Execute commands inside a running container:

/container/shell pihole

With specific user and command:

/container/shell nextcloud user=www-data cmd="php /var/www/html/cron.php" no-sh

Modifying Running Containers

/container/set pihole logging=yes start-on-boot=yes

Environment Variables

Configure container behavior through environment variables:

/container/envs/add list=ENV_PIHOLE key=TZ value="Europe/Riga"
/container/envs/add list=ENV_PIHOLE key=FTLCONF_webserver_api_password value="mysecurepassword"

Creating Environment Lists

Environment variables are organized in named lists:

/container/envs/print

Persistent Storage

Mount router storage into containers for persistent data:

/container/mounts/add name=MOUNT_PIHOLE src=disk1/volumes/pihole dst=/etc/pihole

Multiple mounts can be referenced when creating containers:

/container/add remote-image=pihole/pihole interface=veth1 root-dir=disk1/images/pihole mounts=MOUNT_PIHOLE,MOUNT_PIHOLE_DNSMASQ envlist=ENV_PIHOLE name=pihole

Networking Configuration

Containers connect to the router network through veth (virtual ethernet) interfaces.

Creating veth Interfaces

/interface/veth/add name=veth1 address=172.17.0.2/24 gateway=172.17.0.1

Multiple addresses including IPv6:

/interface/veth/add address=172.17.0.3/16,fd8d:5ad2:24:2::2/64 gateway=172.17.0.1 gateway6=fd8d:5ad2:24:2::1 name=veth2

Bridge with NAT

All containers share a single veth interface with NAT for outbound traffic:

/interface/veth/add name=veth1 address=172.17.0.2/24 gateway=172.17.0.1
/interface/bridge/add name=containers
/ip/address/add address=172.17.0.1/24 interface=containers
/interface/bridge/port/add bridge=containers interface=veth1
/ip/firewall/nat/add chain=srcnat action=masquerade src-address=172.17.0.0/24
/ip/firewall/nat/add action=dstnat chain=dstnat dst-address=192.168.88.1 dst-port=80 protocol=tcp to-addresses=172.17.0.2 to-ports=80

Isolated Networks

Create separate network segments for different container groups:

/interface/veth/add name=veth1 address=172.17.0.2/24 gateway=172.17.0.1
/interface/veth/add name=veth2 address=172.18.0.2/24 gateway=172.18.0.1
/interface/bridge/add name=containers1
/interface/bridge/add name=containers2
/ip/address/add address=172.17.0.1/24 interface=containers1
/ip/address/add address=172.18.0.1/24 interface=containers2
/interface/bridge/port/add bridge=containers1 interface=veth1
/interface/bridge/port/add bridge=containers2 interface=veth2
/ip/firewall/nat/add chain=srcnat action=masquerade src-address=172.17.0.0/24
/ip/firewall/nat/add chain=srcnat action=masquerade src-address=172.18.0.0/24

Layer2 (Bridge) Mode

Attach containers directly to your Layer2 network:

/interface/veth/add name=veth1 address=192.168.88.2/24 gateway=192.168.88.1
/interface/bridge/port/add bridge=bridge interface=veth1

This exposes all container ports to the network. Only use when required for broadcast-based service discovery.

IPv4 and IPv6 Dual Stack

Enable dual-stack networking for containers:

/ip/address/add address=172.17.0.1/24 interface=containers
/ip/firewall/nat/add action=masquerade chain=srcnat src-address=172.17.0.0/24
/ipv6/address/add address=fd8d:5ad2:24:2::1 interface=containers
/ipv6/firewall/nat/add action=masquerade chain=srcnat src-address=fd8d:5ad2:24:2::/64
/interface/veth/add address=172.17.0.2/24,fd8d:5ad2:24:2::2/64 gateway=172.17.0.1 gateway6=fd8d:5ad2:24:2::1 name=veth1

Example: Running Pi-hole

Complete example for running a Pi-hole ad-blocking container:

Prerequisites

1. RouterOS v7.4+ with Container package installed
2. External storage device (HDD, SSD, or USB drive)
3. Device mode enabled

Configuration

/system/device-mode/update container=yes

/interface/veth/add name=veth1 address=172.17.0.2/24 gateway=172.17.0.1
/interface/bridge/add name=containers
/ip/address/add address=172.17.0.1/24 interface=containers
/interface/bridge/port/add bridge=containers interface=veth1
/ip/firewall/nat/add chain=srcnat action=masquerade src-address=172.17.0.0/24
/ip/firewall/nat/add action=dstnat chain=dstnat dst-address=192.168.88.1 dst-port=80 protocol=tcp to-addresses=172.17.0.2 to-ports=80

/container/envs/add list=ENV_PIHOLE key=TZ value="Europe/Riga"
/container/envs/add list=ENV_PIHOLE key=FTLCONF_webserver_api_password value="mysecurepassword"
/container/envs/add list=ENV_PIHOLE key=DNSMASQ_USER value="root"

/container/mounts/add name=MOUNT_PIHOLE_PIHOLE src=disk1/volumes/pihole/pihole dst=/etc/pihole
/container/mounts/add name=MOUNT_PIHOLE_DNSMASQD src=disk1/volumes/pihole/dnsmasq.d dst=/etc/dnsmasq.d

/container/config/set registry-url=https://registry-1.docker.io tmpdir=disk1/tmp
/container/add remote-image=pihole/pihole interface=veth1 root-dir=disk1/images/pihole mounts=MOUNT_PIHOLE_PIHOLE,MOUNT_PIHOLE_DNSMASQD envlist=ENV_PIHOLE name=pihole logging=yes start-on-boot=yes

/container/start pihole

Access the Pi-hole web interface at http://192.168.88.1/admin/

Tips and Tricks

Storage Recommendations

Containers consume significant disk space. Always use external storage (USB, SATA, NVMe) for container images and data:

/container/add remote-image=pihole/pihole root-dir=disk1/images/pihole ...

Memory Limits

Control container RAM usage to prevent resource exhaustion:

/container/config/set memory-high=200M

Boot Persistence

Ensure containers start automatically after router reboot:

/container/set pihole start-on-boot=yes

Troubleshooting with Logs

Enable logging to debug container issues:

/container/set pihole logging=yes
/log print

Privilege Escalation

Some containers require elevated privileges:

/container/set pihole user=0:0

Device Passthrough

Pass physical devices to containers:

/container/set pihole devices="/dev/kvm,/dev/net/tun"

Security Considerations

Danger

Running containers introduces significant security considerations:

• Containers require physical access or device-mode enablement
• Compromised routers can install malicious containers
• Third-party container images may contain vulnerabilities
• Containers can be exploited to gain root access
• Even after removal, backdoors may persist in RouterOS
• Vulnerabilities in primary/secondary RouterBOOT may be injectable

Best Practices

• Use trusted container images from verified publishers
• Regularly update container images to patch vulnerabilities
• Isolate containers in separate network segments
• Use firewall rules to restrict container network access
• Avoid running containers with root privileges when possible
• Monitor container resource usage and activity
• Consider using read-only mounts where applicable

Related Documentation

• Container Resource Limits — CPU affinity, memory limits, and runtime monitoring
• VETH Interfaces — virtual ethernet interface details
• nginx Reverse Proxy — centralized HTTP/HTTPS ingress using nginx
• Prometheus — metrics monitoring container
• AdGuard Home — DNS filtering and ad blocking
• Home Assistant — home automation platform
• Containerized App Management — one-click app deployment via /app