Instalación rápida

mikroscope ejecuta un agente en un contenedor de RouterOS que muestrea el kernel del router a 10 Hz y responde por HTTP en el lado del router de una /30. La CLI de tu ordenador lo instala, e install escribe estos objetos, que uninstall retira:

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.

install no escribe nada fuera del router: el colector y los dashboards de Grafana son un paso aparte y opcional (Verlo en Grafana).

Requisitos

Requisito	Valor
RouterOS	7.24 o posterior
Arquitectura	arm64, arm o x86_64; ni MIPS, ni TILE, ni PPC
Paquete container	instalado y habilitado
Device mode	container=yes, confirmado pulsando un botón o cortando la alimentación

También necesitas un ordenador con acceso ssh al router como usuario administrador, con una clave o un agente ssh: la CLI ejecuta ssh en modo batch y no puede responder a una petición de contraseña. Requisitos tiene el detalle y lo que comprueba doctor.

Instalar la CLI

curl -fsSL https://raw.githubusercontent.com/jmrplens/mikroscope/main/install.sh | bash

En PowerShell, en Windows:

irm https://raw.githubusercontent.com/jmrplens/mikroscope/main/install.ps1 | iex

El script instala la versión más reciente y rechaza un archivo cuyo SHA-256 no sea el que publicó la versión. Instalar la CLI tiene los mismos pasos a mano.

Comprobar el router

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

doctor lee el router y no escribe nada. Imprime una línea por comprobación, marcada ok, MISSING o WARN, y termina con doctor: every prerequisite is met. Tras una línea MISSING viene su arreglo:

  MISSING interface list LAN exists (found=0)
          fix: --iface-list none: no firewall rule here needs the veth in an interface list. Or create it: `/interface/list/add name=LAN`

Aplica el arreglo, o añade la opción que nombra a esta orden y a install más abajo, y vuelve a ejecutar doctor hasta que no quede nada MISSING. Una línea WARN no detiene la instalación.

Device mode te necesita junto al router

Tras /system/device-mode/update container=yes, pulsa el botón reset o mode, o corta la alimentación, en menos de 5 minutos. En CHR, apaga y enciende la máquina virtual. Ninguna sesión ssh ni llamada a la API puede dar este paso.

Un router que ssh no ha visto nunca

La CLI ejecuta ssh en modo batch, así que una clave de host que aún no está en known_hosts la detiene. Añade --ssh-option StrictHostKeyChecking=accept-new a la primera orden, o conéctate una vez con ssh tú mismo.

Instalar el agente

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

install hace las mismas comprobaciones, lee la arquitectura del router e imprime cada orden de RouterOS que va a ejecutar, terminando con nothing above has been written yet. Después pregunta write the objects above to the router? [y/N]. Tras las escrituras sondea el agente desde tu ordenador:

install done: 6 step(s) created
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

El router descarga la imagen de Docker Hub por su cuenta: no se sube nada y no se toca /container/config. Si el sondeo no alcanza al agente, dice si el contenedor está en marcha; Acceso por red tiene las tres formas de llegar a él.

Verificar

mikroscope status --router admin@192.168.88.1

status lee el manifiesto de la instalación en el router, imprime cuántos objetos tiene cada paso y sondea el agente:

agent: 1.6.1 (<commit>) built <time>, 10 Hz, seq 14 (oldest 1), up 1s, 0 slipped, 1ms round trip

Desde un equipo de la LAN del router, curl http://172.30.10.2:9123/healthz responde {"ok":true,…}.

Verlo en Grafana

Es opcional, y nada de esto escribe en el router. Los dashboards leen un almacén, y quien lo llena es el colector, mikroscope forward: trae las muestras del agente y las escribe en los destinos que indiques. Con un InfluxDB 3 y un Grafana ya en marcha, arráncalo y déjalo funcionando:

export MIKROSCOPE_INFLUX_TOKEN=…   # el token del almacén; omítelo si el almacén no pide autenticación
mikroscope forward --influx http://localhost:8181 --influx-db mikroscope

Cuando hayan llegado muestras, ejecuta dashboards publish desde otra terminal con el mismo MIKROSCOPE_INFLUX_TOKEN, las opciones de destino del colector y tu Grafana. Crea la fuente de datos del almacén, publica su dashboard y termina:

export GRAFANA_TOKEN=…   # un token de cuenta de servicio de Grafana con el rol Admin
mikroscope dashboards publish --influx http://localhost:8181 --influx-db mikroscope --grafana http://localhost:3000

folder "mikroscope" (<uid>) created
influxdb: datasource mikroscope-influxdb (influxdb) created
influxdb: dashboard http://localhost:3000/d/mikroscope-influxdb/…

• Demasiado pronto. Si se ejecuta antes de que el almacén tenga una muestra, publica los valores compilados por defecto e imprime could not ask the datasource which measurements it holds. Vuelve a ejecutarlo cuando hayan llegado datos y sustituye el dashboard.
• Desde el colector. Añade --grafana http://localhost:3000 a forward, con GRAFANA_TOKEN en su entorno, y publica de la misma forma en cada arranque, antes de recoger.
• Otra dirección. Cuando Grafana llega a InfluxDB por una dirección distinta de la del colector, pasa esa dirección en --grafana-datasource-url. Con Grafana en un contenedor, localhost es el propio contenedor: usa el nombre de InfluxDB en la red de Docker, como http://influxdb:8181, o la dirección del host en la LAN.
• Los paneles de interfaces necesitan además la capa de la API de RouterOS.

Configurar en Grafana cubre Prometheus y los demás almacenes, la importación a mano y la comprobación de cada panel.

Otras formas de instalar

• Generador de scripts: rellena un formulario y pega el script en el terminal del router. Sin CLI.
• Script de RouterOS: mikroscope plan --rsc escribe la misma instalación como un único script.
• Instalación manual: terminal: cada orden, de una en una.
• Instalación manual: WebFig y Winbox: los mismos objetos, desde los menús.
• Instalación sin conexión: el tar de la imagen, para un router que no llega a un registro.
• Desde el código fuente: un agente compilado desde tu copia del repositorio.
• Actualizar y desinstalar: una versión nueva, o quitarlo todo.

Métodos de instalación los compara.

Siguientes pasos

• Primera grabación: graba una ventana, márcala y dibújala.
• Ejecutar el colector: envía las muestras a Prometheus, InfluxDB 3 o nueve destinos más.
• Configurar en Grafana: los dashboards de Prometheus y los demás almacenes, desde el colector, la CLI o a mano.
• Dashboards: lo que muestra cada sección y cada panel.

Limitaciones

• Se suma a la API de RouterOS y no la sustituye: el tráfico por interfaz viene de la API, porque el contenedor solo ve su propia red.
• El kernel cuenta el tiempo de CPU en ticks de 10 ms, así que una muestra de 100 ms resuelve un núcleo en pasos de 10 %.
• Una fuente que una placa no tiene falta en la salida; nunca vale cero.

Cómo funciona tiene la lista completa.

Véase también

• Cómo funciona: el agente, la veth, el colector y los destinos.
• Coste del agente: lo que el agente le cuesta al router, y cómo medirlo en el tuyo.
• Preguntas frecuentes: respuestas cortas, cada una enlazada a la página con el detalle.
• Comparado con alternativas: SNMP, mktxp, The Dude y el resto.