Instalar con la CLI

mikroscope install pone el agente en el router por ssh. Comprueba el router, lee su arquitectura, enumera cada orden de RouterOS, pregunta, escribe y sondea el agente. Elige de dónde sale la imagen:

Descarga del registro
Desde el código fuente

mikroscope install --router admin@192.168.88.1 --remote-image jmrplens/mikroscope-agent:1.6.1

El router descarga del registro la imagen de su propia arquitectura. No se compila ni se sube nada, y no se toca /container/config. La misma imagen está en GHCR como ghcr.io/jmrplens/mikroscope-agent:1.6.1.

git clone https://github.com/jmrplens/mikroscope
cd mikroscope
make build
bin/mikroscope install --router admin@192.168.88.1

Sin --remote-image ni --agent-tar, la CLI compila el agente desde la copia del repositorio: go build ./cmd/mikroscope-agent para la arquitectura del router con CGO_ENABLED=0, empaquetado en un tar de imagen sin Docker y subido con scp. Necesita Go 1.27 y ejecutarse desde la copia; sin Go en el PATH se detiene antes de enumerar nada y nombra las otras dos rutas.

Un router que no llega a un registro usa el tar de imagen publicado: Instalación sin conexión.

Antes de instalar

El router cumple los Requisitos: RouterOS 7.24 o posterior, el paquete container y device-mode container=yes. Ejecuta mikroscope doctor --router admin@192.168.88.1 con las mismas opciones con las que vas a instalar; no escribe nada y nombra el arreglo de lo que falte.
ssh llega al router como usuario administrador con una clave o un agente ssh. Para un router que aún no está en known_hosts, añade --ssh-option StrictHostKeyChecking=accept-new.
Elige de dónde sale la imagen: Métodos de instalación compara las rutas.

Pasos de la instalación

Lee el router. install hace las comprobaciones de doctor en una conexión y lee allí la arquitectura del router (--arch auto, el valor por defecto). Una comprobación MISSING la detiene con N prerequisite(s) missing; nothing was written; un WARN se imprime y no la detiene. --no-doctor se salta las comprobaciones; la arquitectura necesita entonces una conexión propia, o ninguna con --remote-image, donde el router la elige del índice de la imagen.
Consigue la imagen. Con --remote-image no se trae nada. Con --agent-tar comprueba que el tar es una imagen del agente de mikroscope para la arquitectura del router e imprime using mikroscope-agent-amd64.tar: linux/amd64, agent <size> KiB. Sin ninguna de las dos, la compila desde la copia del repositorio.
Imprime el plan. Una línea de opciones (un token aparece como token=(set), nunca su valor), la etiqueta, y después cada orden de RouterOS numerada, primero el manifiesto de la instalación. El paso del contenedor nombra la subida con su tamaño, o the router pulls <image> (nothing is uploaded). Termina con nothing above has been written yet. mikroscope plan e install --dry-run se detienen aquí sin conectarse, y suponen arm64 donde la arquitectura importa.
Pregunta write the objects above to the router? [y/N]. --yes se salta la pregunta.
Comprueba todos los pasos a la vez. Una conexión pregunta, por cada paso, si el objeto de mikroscope está y si otra cosa ya lo ocupa. Un paso que ya es de esta instalación imprime ok … (already present) y se salta. Un paso que ocupa otra cosa detiene la instalación antes de la primera escritura.
Escribe. Primero el manifiesto de la instalación, luego cada objeto, una conexión por escritura:
```
  new   install manifest mikroscope/mikroscope.manifest.txt
  new   veth interface veth-mikroscope
  new   router address 172.30.10.1
  new   interface-list membership LAN
  new   address-list membership LANs
  pull  the router pulls registry-1.docker.io/jmrplens/mikroscope-agent:1.6.1 itself
  new   container mikroscope
install done: 6 step(s) created
```
En la ruta del tar, el paso del contenedor sube el tar (up uploading mikroscope.tar (<size> KiB)), espera a que RouterOS lo extraiga, hasta --extract-timeout (120 s por defecto), y después borra el tar y arranca el contenedor. Si la extracción no ha terminado para entonces, se detiene y deja el tar, que uninstall retira.
Sondea el agente desde tu equipo y dice qué transporte funciona:
```
probing http://172.30.10.2:9123/healthz from this host …
  direct transport ok: agent 1.6.1 (<commit>) built <time>, 10 Hz, seq 7, 0 slipped, 2ms round trip
```
Cuando el sondeo falla, pregunta al router si el contenedor está en marcha antes de sugerir nada más: Acceso por red.

Un segundo install en un router donde todos los pasos ya son de esta instalación no crea nada y pasa directamente al sondeo.

Lo que install escribe en tu router

el manifiesto de la instalación, un fichero mikroscope/<name>.manifest.txt en el disco de la instalación que lista las opciones y cada objeto de abajo
una veth
una dirección
una pertenencia a lista de interfaces, salvo con --iface-list none
una entrada de address-list, salvo con --addr-list none
una envlist
el tar de la imagen, que se borra en cuanto el contenedor está extraído, salvo que --remote-image haga que el router se la baje
el contenedor, y su raíz mikroscope/<name> en el mismo disco

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.

Almacenamiento y ajustes del contenedor tiene dónde vive cada objeto, qué lleva la envlist y los ajustes del contenedor. Listas del firewall explica las dos pertenencias a listas.

Etiquetas de propiedad

Cada objeto que crea install lleva el comentario mikroscope:<name> (managed by mikroscope), y el manifiesto de la instalación enumera cada uno con su identidad: la veth por nombre, la dirección por interfaz, una pertenencia a lista por lista e interfaz, una entrada de lista de direcciones por lista y dirección. Un borrado compara la etiqueta y esa identidad, nunca un patrón.

/container/envs y /file no llevan comentario. La envlist va firmada con una entrada MIKROSCOPE_TAG cuyo valor es la etiqueta exacta, que el agente ignora, y el manifiesto con su línea tag=.
Cada find pone entre comillas sus valores de dirección y de puerto. Sin comillas, RouterOS los compara como valores tipados y un dst-port=9123 sin comillas no encuentra nada (verificado).
RouterOS puede informar de un error por ssh con estado de salida 0, y abandona el resto de una línea unida con ; en el primero. Así que una escritura que imprime algo cuenta como fallo. Si el paso del contenedor falla después de una subida, el tar se retira (undo removed the uploaded …).

Salvaguardas del instalador enumera qué más rechaza el instalador.

upgrade y uninstall están en Actualizar y desinstalar.

Comprobar la instalación

mikroscope status --router admin@192.168.88.1

status lee la forma de la instalación de su manifiesto, o de sus objetos etiquetados si se hizo sin él, e imprime la cuenta de propiedad de cada paso desde una conexión:

install on the router (manifest mikroscope/mikroscope.manifest.txt): veth veth-mikroscope, subnet 172.30.10.0/30, lists LAN/LANs, port 9123, pulled from registry-1.docker.io/jmrplens/mikroscope-agent:1.6.1
  manifest mikroscope/mikroscope.manifest.txt: the plan comes from it
  1     install manifest mikroscope/mikroscope.manifest.txt
  1     veth interface veth-mikroscope
  1     router address 172.30.10.1
  1     interface-list membership LAN
  1     address-list membership LANs
  8     container mikroscope
agent: 1.6.1 (<commit>) built <time>, 10 Hz, seq 14 (oldest 1), up 1s, 0 slipped, 1ms round trip

Cuando no hay nada instalado, termina con verified: nothing mikroscope created remains on the router y no sondea nada.
Si no, sondea /healthz con un límite de 3 s e imprime la versión del agente, la tasa, la secuencia y la secuencia más antigua, el tiempo en marcha, los ticks perdidos y el tiempo de ida y vuelta, y después una línea sobre la placa: si esta versión traduce en ella los nombres de puerto del kernel a los de RouterOS (Nombres de puertos).
Si el agente no responde, imprime agent: not reachable from this host con el error, y aun así sale con 0.

Resumen de órdenes

mikroscope doctor                          # read-only: prerequisites, then the running agent's ring
mikroscope plan                            # every command, nothing written
mikroscope install                         # checks, listing, confirmation, writes, probe
mikroscope status                          # the install's shape, ownership counts, agent health
mikroscope upgrade --remote-image …        # a new image; the container step and anything missing
mikroscope uninstall --yes                 # removes everything the install created (without --yes: lists)
mikroscope image --arch arm64              # the image tar, for side-loading by hand
mikroscope plan --rsc --out install.rsc    # the same install, as a RouterOS script

--router acepta usuario@equipo o un alias de la configuración de ssh, y lo necesita cada verbo que se conecta.

Opciones y variables

Estas opciones toman su valor por defecto de una variable MIKROSCOPE_*: --router, --ssh-port, --ssh-key, --ssh-option, --name, --veth, --subnet, --iface-list, --addr-list, --disk, --arch, --token, --lan-address, --agent-tar y --remote-image. El fichero .env.example las documenta. La CLI no lee .env por su cuenta:

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

status, upgrade y uninstall leen la forma de la instalación del router, así que una opción de forma que omitas toma el valor instalado. Una opción o una variable que contradiga la instalación se rechaza, nombrando los dos valores, antes de escribir nada.

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 tasa, la referencia del registro, la subred (una /30 IPv4 en su dirección de red) y --triggers, que comprueba el propio analizador del agente. Un valor fuera de límites hace fallar el verbo con estado de salida 2 y no escribe nada. El agente vuelve a analizar TRIGGERS al arrancar, porque una envlist se puede editar a mano en el router, y un valor que rechace ahí lo hace salir y registrar bad configuration. CLI tiene cada opción, y Variables de entorno cada variable.

Conexiones SSH

Cada conexión ssh le cuesta CPU al router mientras dura, así que la CLI agrupa cada lectura en una sola conexión: doctor es una, status es una, y las preguntas de install sobre todos los pasos son una. Cada escritura añade otra, más la subida con scp en la ruta del tar. ssh nunca es una ruta de datos: record y forward llegan al agente por HTTP o por la API de RouterOS. Coste de SSH tiene la medición.

Escrito y mantenido por José Manuel Requena Plens (jmrplens)jmrp.ioGitHub