Instalar el agente

Esta página responde a dos preguntas: qué le hace mikroscope install a tu router y cómo recuperas el router después. install pone una imagen del agente de 6,1 MiB en un contenedor del router; uninstall la vuelve a quitar. En RB5009UG+S+, RouterOS 7.24.2, 2026-09-12, un ciclo completo con guion doctor → install → status → upgrade → uninstall (make roundtrip, que pasa --ephemeral a doctor, install y upgrade) dejó el /export del router idéntico byte a byte, salvo sus líneas de cabecera #. Cada objeto que crea install lleva el comentario mikroscope:<name> (managed by mikroscope), salvo la envlist y el fichero de la imagen, que no lo admiten; la envlist lleva la etiqueta en su entrada MIKROSCOPE_TAG. No se escribe nada antes de listarlo; la eliminación selecciona por esa etiqueta más la identidad del objeto, nunca por patrón, y se verifica con recuentos de propiedad.

Antes de la primera instalación

En el router tienen que cumplirse tres cosas, y la herramienta no puede conseguir ninguna por ti: una arquitectura capaz de ejecutar contenedores con RouterOS 7.24 o posterior, el paquete container y device-mode container=yes — esto último exige pulsar un botón físico o un ciclo de alimentación. Lo que necesita el router cubre las tres. mikroscope doctor las comprueba en solo lectura, en una conexión ssh, e imprime la orden exacta o el paso físico para lo que falte.

Hay una decisión que va antes de la primera instalación y no después: de dónde sale la imagen del agente. Un checkout la compila, --agent-tar toma la que publica la release, --remote-image hace que el router se la baje, y plan --rsc escribe un script que instala sin esta CLI. Cuatro formas de instalar expone las cuatro.

Qué hace install, en orden

Consigue la imagen del agente. Desde un checkout, la CLI la compila: go build ./cmd/mikroscope-agent para linux/<arch> (--arch, por defecto arm64) con CGO_ENABLED=0, empaquetado en un tar de imagen sin Docker, y la ruta de compilación es relativa, así que ejecútalo desde el checkout. --agent-tar toma en su lugar el tar que publica la release, y lo comprueba antes de subirlo. --remote-image se salta este paso entero: el router se baja la imagen él mismo y no se sube nada. Cuatro formas de instalar es la elección, con lo que necesita cada ruta.
Imprime el plan. Una línea de opciones (un token aparece como token=(set), nunca su valor), la etiqueta y luego cada orden de RouterOS numerada, con la subida por scp y su tamaño antes del paso del contenedor. Termina con nothing above has been written yet. mikroscope plan e install --dry-run se detienen aquí, antes de cualquier conexión ssh.
Ejecuta doctor. Cualquier requisito que falte detiene la instalación con N prerequisite(s) missing; nothing was written. --no-doctor se salta este paso.
Pregunta write the objects above to the router? [y/N]. --yes se salta la pregunta.
Pregunta al router por todos los pasos a la vez. Una conexión pregunta, para cada paso, si el objeto de mikroscope está y si el efecto existe con cualquier otro propietario. Un paso que ya es nuestro imprime ok … (already present) y se salta; un efecto que existe sin la etiqueta detiene la instalación, nombrándolo; uno ausente se crea, con una conexión por escritura.
Sube la imagen y crea el contenedor. El tar sube con scp; después una sola orden escribe la envlist, añade el contenedor, espera hasta 15 s a que el contenedor aparezca y luego 3 s más (RouterOS extrae la imagen al añadirlo), borra el tar y arranca el contenedor. Con --remote-image no hay subida ni tar al que esperar o que borrar: el contenedor se añade con remote-image= y se arranca. En cualquier caso el contenedor se añade con privileged=, que RouterOS conoce desde 7.24: en una 7.x anterior este es el paso que falla, y --privileged=false es la forma de pasar.
Sondea el agente desde tu máquina y dice qué transporte funciona: Llegar al agente.

Un segundo install en un router donde todos los pasos ya son nuestros no crea nada y pasa directamente al sondeo.

Lo que install escribe en tu router

una veth
una dirección
una pertenencia a lista de interfaces
una entrada de address-list
una envlist
el tar de la imagen, salvo que --remote-image haga que el router se la baje
el contenedor

Cada objeto lleva el comentario mikroscope:<name> (managed by mikroscope)

mikroscope plan imprime cada orden antes de escribir nada.

uninstall elimina por etiqueta exacta más identidad, nunca por patrón, y falla nombrando el paso si queda algo.

Dónde vive cada uno de esos objetos, qué lleva la envlist y qué ajustes del contenedor se escriben está en Dónde va cada cosa. Por qué dos de ellos son pertenencias a listas del cortafuegos está en Las dos trampas del cortafuegos.

Cómo se decide la propiedad

La etiqueta es lo único con lo que casa una eliminación, junto con la identidad propia del objeto: la veth por nombre, la dirección por interfaz, una pertenencia a lista por lista e interfaz, una entrada de address-list por lista y dirección. Ni /container/envs ni /file admiten comentario, así que la envlist se firma con una entrada MIKROSCOPE_TAG cuyo valor es la etiqueta exacta, y la imagen subida cuenta como de mikroscope solo mientras exista esa marca. El agente ignora la entrada.

Cada find entrecomilla sus atributos de dirección y puerto. Sin comillas, RouterOS los interpreta como valores tipados y la comparación con el valor guardado sale vacía — un dst-port=9123 sin comillas no casa con nada (verificado en RB5009UG+S+, RouterOS 7.24.2, 2026-09-11).

Por ssh, RouterOS informa de un error como texto con código de salida 0 y abandona el resto de una línea unida con ; en el primero. Por eso una escritura que imprime algo se trata como un fallo. Si el paso del contenedor falla tras la subida, el tar subido se retira (undo removed the uploaded …), porque sin la marca contaría como ajeno para siempre. Qué más rechaza el instalador está en Lo que el instalador rechaza.

Actualizar

Lo que sustituye upgrade

una imagen nueva y el contenedor
la envlist, reescrita con las opciones que recibe upgrade
los objetos de red se quedan

Cada objeto lleva el comentario mikroscope:<name> (managed by mikroscope)

mikroscope plan imprime cada orden antes de escribir nada.

mikroscope upgrade consigue la imagen igual que install —compilándola desde el checkout, con --agent-tar, o con --remote-image y ninguna imagen—, comprueba que todos los pasos están (si no, nothing to upgrade: run install first), pide confirmación, quita el paso del contenedor, espera a la eliminación asíncrona de RouterOS, vuelve a crear el paso con la imagen nueva y sondea el agente. A diferencia de install, no imprime ningún plan ni ejecuta doctor: su pregunta es la misma write the objects above to the router? [y/N] sin nada listado encima. mikroscope plan con las mismas opciones muestra la orden del contenedor que va a escribir.

La envlist pertenece al paso del contenedor, así que upgrade la vuelve a escribir a partir de las opciones que recibe el propio upgrade. --port, --rate, --buffer, --memory-max, --mem-limit-mb, --capture-mb, --triggers, --floor-hz, --privileged, --ephemeral y --expose no leen ninguna variable de entorno: pásalas otra vez o vuelven a sus valores por defecto. Esa es también la forma de cambiarlas sin tocar los objetos de red. Dos omisiones no son inocuas. Un upgrade sin --ephemeral vuelve a crear el contenedor con la imagen y la raíz en la flash interna y start-on-boot=yes. Un upgrade de una instalación con --expose hecho sin --expose y sin token (--token o MIKROSCOPE_TOKEN) vuelve a crear el agente sin token, mientras las dos reglas del cortafuegos hacia la LAN se quedan.

Desinstalar

Lo que elimina uninstall

una veth
una dirección
una pertenencia a lista de interfaces
una entrada de address-list
una envlist
el tar de la imagen, salvo que --remote-image haga que el router se la baje
el contenedor

Cada objeto lleva el comentario mikroscope:<name> (managed by mikroscope)

mikroscope plan imprime cada orden antes de escribir nada.

uninstall elimina por etiqueta exacta más identidad, nunca por patrón, y falla nombrando el paso si queda algo.

mikroscope uninstall ejecuta las eliminaciones de la más reciente a la más antigua. Una eliminación que falla o imprime algo se informa como skip con lo que dijo el router, y el resto continúa. Un paso cuyo selector no encuentra nada imprime gone igualmente, y por eso decide el recuento, no la salida de la eliminación. Después pregunta el recuento de propiedad de cada paso en una conexión, imprime una línea por paso y o bien termina con verified: nothing mikroscope created remains on the router o bien falla con uninstall left objects behind, nombrando los pasos que siguen presentes.

La eliminación del contenedor espera, porque RouterOS no lo hace: /container/remove vuelve antes de que el contenedor haya desaparecido, y un /file/remove de la imagen lanzado entretanto no hizo nada, en silencio (RB5009UG+S+, RouterOS 7.24.2, 2026-09-11). Así que para el contenedor, lo quita, espera hasta 20 s a que desaparezca, reintenta la eliminación del tar durante hasta 15 s y quita la marca solo cuando el fichero ya no está. Si sigue, la marca se queda y el recuento lo dice.

Estado

mikroscope status imprime el recuento de propiedad de cada paso, desde una conexión. Cuando no hay nada instalado termina con la línea verified y no sondea nada. Si no, sondea el /healthz del agente con un tiempo de espera de 3 s e imprime su versión, cadencia, secuencia y secuencia más antigua, tiempo en marcha, ticks retrasados y tiempo de ida y vuelta, y después una línea sobre la placa: si esta compilación sabe convertir en ella los nombres de puerto del kernel (eth0, eth1, …) en los de RouterOS. Donde no sabe, la línea pide la medida que añadiría la placa; Puertos de RouterOS y nombres del kernel muestra cómo tomarla. Si el agente no responde, imprime agent: not reachable from this host con el error, y ninguna línea de placa; status sale igualmente con código 0.

El día a día

mikroscope doctor                      # solo lectura
mikroscope plan                        # todas las órdenes, nada escrito
mikroscope install [--ephemeral]       # doctor, confirmación, escrituras, sondeo
mikroscope status                      # recuentos de propiedad + salud del agente
mikroscope upgrade                     # imagen nueva, solo el contenedor
mikroscope uninstall                   # quita y verifica
mikroscope image --arch arm64          # el tar, para cargarlo a mano
mikroscope plan --rsc --out install.rsc # las mismas escrituras, como script de RouterOS

--router acepta user@host o un alias de la configuración de ssh y lo exige toda orden que se conecta.

Opciones y entorno

Para estas órdenes, las opciones que toman su valor por defecto de una variable son --router, --ssh-port, --ssh-key, --name, --veth, --subnet, --iface-list, --addr-list, --disk, --arch, --token, --lan-address, --agent-tar y --remote-image (MIKROSCOPE_ROUTER, MIKROSCOPE_SSH_PORT y así sucesivamente); .env.example las documenta. La CLI no lee .env por sí misma:

set -a; . ./.env; set +a

Cada valor que llega a una orden de RouterOS se acota antes de la primera conexión: nombres, discos, la arquitectura, la sintaxis de memoria, los caracteres del token, los rangos de puerto y de cadencia, la referencia del registro, la subred, que debe ser una /30 IPv4 dada en su dirección de red, y --triggers, sobre el que decide el propio analizador del agente: una condición desconocida, un umbral incorrecto, una comilla o un punto y coma hacen fallar la orden con código 2 sin escribir nada. El agente vuelve a analizar TRIGGERS al arrancar, porque una envlist se puede editar a mano en el router; un valor que rechace allí hace que termine y registre bad configuration. La lista completa está en Órdenes y opciones y Variables de entorno.

Lo que ssh le cuesta al router

Cada conexión ssh le cuesta al RB5009 un 20–27 % de CPU mientras dura. Por eso la CLI agrupa cada lectura en una sola conexión — doctor es una, status es una, las preguntas de estado de install son una — y cada escritura cuesta una más, además de la subida por scp. ssh nunca es un camino de datos: record y forward llegan al agente por HTTP o por la API de RouterOS.