# Instalar con la CLI

Instala el agente con mikroscope install por ssh, qué comprueba y escribe en orden, cómo marca lo que es suyo, y las opciones y variables que lee.

Source: https://docs.jmrp.io/mikroscope/es/install/

`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**

  ```sh
  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`.

- **Desde el código fuente**

  ```sh
  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](https://docs.jmrp.io/mikroscope/es/install/offline/).

## Antes de instalar

- El router cumple los [Requisitos](https://docs.jmrp.io/mikroscope/es/install/prerequisites/): 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](https://docs.jmrp.io/mikroscope/es/install/routes/) compara
  las rutas.

## Pasos de la instalación

1. **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.

2. **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.

3. **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.

4. **Pregunta** `write the objects above to the router? [y/N]`. `--yes` se salta la pregunta.

5. **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.

6. **Escribe.** Primero el manifiesto de la instalación, luego cada objeto, una conexión por
   escritura:

   ```text
     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.

7. **Sondea el agente** desde tu equipo y dice qué transporte funciona:

   ```text
   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](https://docs.jmrp.io/mikroscope/es/install/reaching-the-agent/).

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](https://docs.jmrp.io/mikroscope/es/install/layout/) tiene dónde vive cada objeto, qué
lleva la envlist y los ajustes del contenedor. [Listas del firewall](https://docs.jmrp.io/mikroscope/es/install/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](https://docs.jmrp.io/mikroscope/es/about/status/#verified-find-quoting)).
- 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](https://docs.jmrp.io/mikroscope/es/security/installer/) enumera qué más rechaza el
instalador.

`upgrade` y `uninstall` están en [Actualizar y desinstalar](https://docs.jmrp.io/mikroscope/es/install/upgrade/).

## Comprobar la instalación

```sh
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:

```text
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](https://docs.jmrp.io/mikroscope/es/reference/port-names/)).
- Si el agente no responde, imprime `agent: not reachable from this host` con el error, y aun así
  sale con 0.

## Resumen de órdenes

```sh
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`](https://github.com/jmrplens/mikroscope/blob/main/.env.example) las documenta. La CLI no lee `.env` por su cuenta:

```sh
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](https://docs.jmrp.io/mikroscope/es/reference/cli/#opciones-de-los-verbos-de-despliegue)
tiene cada opción, y [Variables de entorno](https://docs.jmrp.io/mikroscope/es/reference/environment/) 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](https://docs.jmrp.io/mikroscope/es/cost/#ssh-cost) tiene la medición.

## Véase también

- [Requisitos](https://docs.jmrp.io/mikroscope/es/install/prerequisites/): la arquitectura, el paquete y el paso de
  device-mode, y lo que comprueba `doctor`.
- [Actualizar y desinstalar](https://docs.jmrp.io/mikroscope/es/install/upgrade/): una versión nueva, y quitar todo lo
  que creó la instalación.
- [Métodos de instalación](https://docs.jmrp.io/mikroscope/es/install/routes/): las otras formas de instalar, sin ssh o
  sin registro.
- [Acceso por red](https://docs.jmrp.io/mikroscope/es/install/reaching-the-agent/): el sondeo, y directo, relé y
  `--expose`.
- [Salvaguardas del instalador](https://docs.jmrp.io/mikroscope/es/security/installer/): lo que el instalador se niega a
  construir o a retirar.