Lo que necesita el router

Esta página enumera lo que tiene que estar listo antes de que mikroscope install pueda escribir nada: tres cosas en el router que la herramienta no puede hacer por ti, los recursos y las listas del cortafuegos que comprueba, y lo que necesita la máquina desde la que lo ejecutas. mikroscope doctor lo comprueba todo en solo lectura, en una conexión ssh, e imprime la orden exacta o el paso físico para lo que falte.

Un paso exige tus manos en el router

device-mode container=yes no se puede activar en remoto. Tras la orden, RouterOS espera cinco minutos a que alguien pulse el botón de reset o el de modo, o haga un ciclo de alimentación del equipo. Ninguna sesión ssh, llamada a la API ni opción de esta herramienta puede dar ese paso. Cuenta con estar junto al router.

Un equipo capaz de ejecutar contenedores

El router debe ejecutar RouterOS 7.24 o posterior en una de tres arquitecturas: arm64, arm (RouterOS de 32 bits en la línea renovada hEX) o x86_64. Ni MIPS ni TILE.

7.24 es el suelo porque el paso del contenedor escribe privileged=, un atributo que RouterOS añadió en esa versión. doctor imprime la versión y no comprueba nada contra ella, así que en una 7.x anterior la instalación llega hasta el contenedor y falla ahí con el error de RouterOS sobre un parámetro privileged desconocido —y una escritura que imprime algo cuenta como fallo, de modo que la instalación se detiene y se lleva de vuelta el tar que había subido—. --privileged=false es la forma de pasar, al precio de todo lo que oculta el espacio de nombres de usuario del contenedor: Lo que aporta privileged lo enumera.

Dile a la CLI cuál con --arch: arm64 (por defecto), arm o amd64. doctor la compara con el architecture-name del router y, si no coinciden, nombra la opción con la que volver a ejecutar.

Tu equipo	architecture-name	--arch	La compilación del agente
RB5009, CCR2004, hAP ax³ y otros ARM de 64 bits	arm64	arm64	linux/arm64
hEX Refresh / hEX S (2025), cualquier placa EN7562CT	arm	arm	linux/arm/v5
Otros ARM de 32 bits (hAP ac², hAP ax², …)	arm	arm	linux/arm/v5 o v7
CHR y RouterOS x86	x86_64	amd64	linux/amd64

El ARM de 32 bits no es una cosa, son dos. La documentación de contenedores de MikroTik dice que los equipos con CPU EN7562CT —la serie hEX Refresh— «solo admiten imágenes de contenedor arm32v5», mientras que sus demás placas ARM de 32 bits ejecutan un espacio de usuario ARMv7. Un binario ARMv5 funciona en las dos; uno ARMv7 no arranca en las primeras, y falla con un exec format error en el registro del contenedor después de una instalación correcta. Por eso --goarm vale 5 por defecto, que es el nivel que arranca en todas partes, y la imagen declara la variante que le corresponde. --goarm 7 compila la ARMv7 para una placa donde se quiera ese juego de instrucciones; lo que cuesta la diferencia no se ha medido, porque este proyecto no tiene hardware ARM.

--remote-image hace desaparecer la pregunta: el índice publicado lleva linux/amd64, linux/arm64, linux/arm/v7 y linux/arm/v5, y el router elige el suyo.

El paquete container

Descarga el paquete container para tu arquitectura y tu versión de RouterOS desde mikrotik.com, súbelo al router y reinicia; después /system/package/enable container. Esa es la solución que imprime doctor, y solo da el paquete por presente cuando está instalado y no deshabilitado.

device-mode container=yes

MikroTik protege los contenedores tras un paso físico:

1. Ejecuta, en la consola del router:

   /system/device-mode/update container=yes

2. La consola responde:

   update: please activate by turning power off or pressing reset or mode button in 5m00s

3. En esos cinco minutos, pulsa el botón de reset o el de modo, o haz un ciclo de alimentación del router. Si nadie lo hace, el cambio se cancela.

Tras tres intentos fallidos el router dice too many unsuccessful attempts … to reset attempt-count y necesita un ciclo de alimentación antes de aceptar otro.

Lo que comprueba doctor

doctor imprime device: con la placa, la versión de RouterOS y la arquitectura, y después una línea por comprobación marcada ok o MISSING, con lo que encontró entre paréntesis y, si falta algo, una línea fix:. Termina con doctor: every prerequisite is met, o falla con N prerequisite(s) missing; nothing was written. install ejecuta primero las mismas comprobaciones salvo que pases --no-doctor.

Las comprobaciones que ejecuta doctor

Comprobación, tal como se imprime	Pasa cuando	La solución que nombra
registry-url is https://<host>	con --remote-image, /container/config registry-url nombra el host de registro de la referencia. Sin --remote-image doctor no lo pregunta: el ajuste es global del equipo y mikroscope nunca lo escribe	/container/config/set registry-url=https://<host> en el router, que afecta a todos sus contenedores, o instalar desde un tar con --agent-tar
container package installed and enabled	existe un paquete container con disabled=no	descargar, subir, reiniciar; después /system/package/enable container
device-mode container=yes	/system/device-mode informa container=yes	/system/device-mode/update container=yes y, en menos de 5 minutos, el botón reset o mode, o un ciclo de alimentación
architecture matches --arch <arch>	el architecture-name del router es el que corresponde a --arch (arm64, arm, x86_64)	volver a ejecutar con el --arch que nombra
free memory ≥ <--memory-max>	free-memory es al menos lo que pide --memory-max, 64 MiB por defecto	liberar memoria en el router, o pedir menos con --memory-max
free flash ≥ <size> (image tar + extracted root)	sin --disk: free-hdd-space es al menos el doble de la imagen más 4 MiB	liberar flash, o instalar con --disk tmpfs o --ephemeral donde exista un disco tmpfs
disk <disk> exists	con --disk o --ephemeral: existe un disco con ese slot; su espacio libre no se comprueba	/disk/add type=tmpfs tmpfs-max-size=64M slot=tmpfs para un disco en RAM, o nombrar un disco existente con --disk
interface list <list> exists (raw rule trap)	existe la lista --iface-list (por defecto LAN)	/interface/list/add name=…, o pasar la lista que usa tu regla de descarte in-interface-list=!…
address list <list> has entries (raw rule trap)	la lista --addr-list (por defecto LANs) tiene al menos una entrada	pasar la lista que usa tu regla drop local if not from default IP range; una lista vacía vale solo si no hay tal regla
veth name <veth> is free or ours	siempre se informa ok, con el recuento encontrado	ninguna: una colisión la detecta el propio install

La comprobación de flash usa el tamaño real del tar dentro de install. doctor por sí solo supone una imagen de 7 MiB, así que pide 18.0 MiB. El doble de la imagen porque el tar y la raíz extraída de él conviven en el disco hasta que install borra el tar; con --remote-image no se sube ningún tar, así que la comprobación pide solo los 4 MiB de margen. El umbral de memoria sigue a --memory-max: pide al menos lo que pide esa opción, que por defecto son 64 MiB, de modo que --memory-max 128M en un router con 70 MiB libres se detecta aquí y no en un contenedor que no arranca.

La comprobación de registry-url solo se ejecuta con --remote-image, y solo cuando la referencia lleva un host de registro. /container/config es global al equipo y compartido con cualquier otro contenedor que tenga, así que mikroscope lee ese ajuste y nunca lo escribe. RouterOS lo trae puesto en https://registry-1.docker.io, así que la referencia de Docker Hub, --remote-image jmrplens/mikroscope-agent:1.0.0, no necesita fijar nada ahí en un router sin tocar, y la de GHCR es la que exige cambiar antes el ajuste. Cuatro formas de instalar tiene la orden para ponerlo a mano.

Las dos comprobaciones de listas existen por dos reglas raw del cortafuegos que descartan cada paquete que envía un contenedor; Las dos trampas del cortafuegos las explica. doctor marca como ausente una address-list vacía incluso en un router que no tiene esa regla; ahí, --no-doctor es la forma de pasar, y con ella te saltas también todas las demás comprobaciones.

Lo que necesita tu máquina

• ssh al router con un usuario que pueda escribir, tu propio acceso de administrador. La CLI ejecuta el ssh del sistema con BatchMode=yes y ConnectTimeout=15, así que no puede responder a una petición de contraseña: usa una clave o un agente ssh. --router acepta user@host o un alias de la configuración de ssh; --ssh-port y --ssh-key (MIKROSCOPE_SSH_PORT, MIKROSCOPE_SSH_KEY) recurren a tu configuración de ssh cuando no tienen valor. La imagen sube con scp, en las dos rutas que suben una. La ruta del script de RouterOS no necesita ssh en absoluto.
• Una imagen del agente, por una de cuatro rutas. La CLI puede compilar una (go build ./cmd/mikroscope-agent desde un checkout, lo que exige Go 1.27), tomar el tar que publica la release (--agent-tar, sin toolchain y sin checkout), o dejar que el router se baje la imagen él mismo (--remote-image, sin subir nada). La cuarta ruta no necesita ni CLI en tu máquina: plan --rsc escribe un script de RouterOS que pegas en el router. Cuatro formas de instalar tiene las órdenes, lo que necesita cada ruta y cómo verificar una descarga.
• Una forma de llegar al agente una vez en marcha: una ruta a la /30 del contenedor a través del router, el relay por la API de RouterOS, o --expose. Consulta Llegar al agente.
• Un usuario de la API de RouterOS, solo para el transporte relay, --log-markers y la capa de la API del colector. Se queda en tu máquina; su política está en El usuario de la API.

Sin probar

Una instalación en arm o x86_64: todas las instalaciones hasta ahora se hicieron en un único RB5009 arm64, y el hEX S que probará RouterOS de 32 bits no ha llegado. Cualquier RouterOS que no sea 7.24.2. El paso del contenedor escribe privileged=, que RouterOS añadió en 7.24, y entradas de envlist con key=, donde name= falla en 7.24.2; no se probó cómo acepta una 7.x anterior cualquiera de las dos.

Véase también

• Instalar el agente: lo que hace install una vez esto está listo.
• Cuatro formas de instalar: las cuatro rutas por las que la imagen del agente llega al router, y cómo verificar una descarga.
• Las dos trampas del cortafuegos: por qué existen las dos comprobaciones de listas.
• Dónde va cada cosa: el disco al que se refiere la comprobación de flash, y --ephemeral.