# Acceso por red

Llega al agente en la dirección de su veth desde tu máquina, directamente, con una ruta estática, por el relay de la API de RouterOS o con --expose, y lee lo que dice el sondeo tras install.

Source: https://docs.jmrp.io/mikroscope/es/install/reaching-the-agent/

El agente escucha solo en la dirección de su veth, `http://172.30.10.2:9123` con los valores por
defecto, y no abre ninguna conexión saliente. Tu máquina llega a él de una de tres formas:
directamente a través del router, por el relay de la API de RouterOS, o en la dirección LAN del
router con `--expose`.

## Comparar transportes

| Vía        | Necesita                                                                   | Límites                                                                                                                                                                  |
| ---------- | -------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| directa    | una ruta desde tu máquina a la /30 a través del router                     | ninguno más allá de las dos pertenencias a listas que añade `install`                                                                                                    |
| relay      | un usuario de la API con `read,api,test`; `--transport relay`, o `auto`    | 64 512 B y 13 muestras por llamada, alrededor de 1 s en más o menos la mitad de las llamadas, sin token |
| `--expose` | `--lan-address` y un token; dos reglas de cortafuegos en el router         | alcanzable desde toda la LAN; no lo usan `record`, `forward`, el sondeo ni la lectura de salud de `doctor`                                                               |

## Directa (por defecto)

Tu máquina envía HTTP plano a la dirección del agente, y el router lo reenvía a la veth. Para que
funcione hacen falta dos cosas:

- **Que el cortafuegos lo deje pasar.** Las dos pertenencias a listas que añade `install` bastan
  para las reglas raw de descarte del cortafuegos avanzado de MikroTik
  ([verificado](https://docs.jmrp.io/mikroscope/es/about/status/#verified-direct-lists)); [Listas del
  firewall](https://docs.jmrp.io/mikroscope/es/install/firewall/) tiene las reglas y la comprobación de `doctor` sobre
  las tuyas.
- **Que tu máquina enrute la /30 hacia el router.** Una máquina cuya puerta de enlace por defecto es
  el router ya lo hace.

Con un token puesto, el transporte directo envía `Authorization: Bearer <token>`, a partir de
`--token` o `MIKROSCOPE_TOKEN`. `/healthz` nunca lo necesita.

### Ruta estática

Una máquina cuya puerta de enlace por defecto es otro router necesita una ruta para la /30 a través
de la dirección LAN del router. En Linux, con tu `--subnet` y la dirección LAN del router:

```sh
sudo ip route add 172.30.10.0/30 via 192.168.88.1
```

También sirve un prefijo más amplio que contenga la /30, como `172.30.0.0/16`
([probado](https://docs.jmrp.io/mikroscope/es/about/status/#virtual-lab)). Haz la ruta permanente de la forma en que tu
sistema guarda su configuración de red.

## Relay por la API

`record` y `forward` con `--transport relay` ejecutan `/tool fetch` en el router por la API binaria,
y el router, que sí llega a su propia veth, pide los datos al agente.

1. Crea un usuario de RouterOS con la política `read,api,test`: `/tool fetch` exige `test`
   ([verificado](https://docs.jmrp.io/mikroscope/es/about/status/#verified-test-policy)), y sin ella la llamada devuelve
   `not enough permissions (9)`. [Usuario de la API](https://docs.jmrp.io/mikroscope/es/security/api-user/) tiene las
   órdenes.
2. Pasa a la CLI `--api host:port` (`MIKROSCOPE_API_ADDR`), `--api-user` (`MIKROSCOPE_API_USER`) y
   la contraseña en `MIKROSCOPE_API_PASSWORD`. La contraseña no tiene opción.
3. Ejecuta `record` o `forward` con `--transport relay`.

Lo que el relay no puede hacer:

- **Respuestas grandes.** RouterOS trunca en silencio una respuesta de más
  de 64 512 B. El relay pide como mucho 13
  muestras por llamada y rechaza una respuesta que llegue al tope en vez de interpretarla truncada.
  `forward` avisa al arrancar cuando eso no puede seguir la cadencia del agente.
- **Llamadas rápidas.** Una llamada tarda o unos 3 ms o alrededor de 1 s, y más o menos la mitad
  tarda 1 s ([medido](https://docs.jmrp.io/mikroscope/es/about/status/#campaign-relay-fetch)).
- **Un token.** El relay solo le pasa la URL a `/tool fetch`, sin cabeceras. Todas las rutas salvo
  `/healthz` devuelven 401 sin el token, así que un agente instalado con uno necesita el transporte
  directo.

`--transport auto`, el valor por defecto, prueba primero el transporte directo. Si `/healthz` no
responde y `--api` y `--api-user` están puestos, prueba el relay; si no, falla con
``direct transport did not answer and the relay is not configured: … (or `install --expose`)``.

## Exponer en la LAN

```sh
mikroscope install --expose --lan-address 192.168.88.1
```

Guarda el token en `MIKROSCOPE_TOKEN`, que lo mantiene fuera de la línea de órdenes.

**Lo que añade `install --expose`**

- dos reglas de cortafuegos, etiquetadas
- el token pasa a ser obligatorio
- `uninstall` y `status` encuentran las dos reglas por el manifiesto y la etiqueta, con `--expose` o sin él

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

`mikroscope plan` imprime cada orden antes de escribir nada.

`--expose` añade un dst-nat desde la dirección LAN del router en el puerto del agente hacia la veth,
y un accept en forward para ese flujo colocado antes del primer drop de forward, o añadido al final
cuando la cadena forward no tiene drop. Cualquier máquina de la LAN puede entonces llegar al agente,
así que:

- `install` y `upgrade` rechazan `--expose` sin token (`--token` o `MIKROSCOPE_TOKEN`) o sin una
  `--lan-address` IPv4.
- `status` y `uninstall` no necesitan ninguna de las dos opciones: leen en el router que la
  instalación está expuesta, y `uninstall` quita las dos reglas con el resto.
- `doctor` comprueba la dirección:

Las comprobaciones que ejecuta doctor:

| Comprobación, tal como se imprime | Pasa cuando | La solución que nombra |
| --- | --- | --- |
| --lan-address <address> is the router's | con `--expose`: una interfaz del router tiene esa dirección | pasa la dirección que el router tiene en su LAN, tal como la lista `/ip/address/print` |
| --lan-address is not on the uplink | un aviso, con `--expose`: la interfaz que tiene la dirección no lleva la ruta por defecto, no está en ninguna lista `WAN` y no comparte ninguna lista de interfaces con la interfaz que lleva la ruta por defecto | pasa la dirección LAN del router: en el enlace de subida el dst-nat publicaría el agente hacia Internet |

Un cliente al que apuntes a `http://<router LAN IP>:9123` usa el camino expuesto: Prometheus,
`curl`, un navegador. Los transportes de la propia CLI no. `record`, `forward`, el sondeo tras
`install` y la lectura de salud de `doctor` construyen la dirección del agente a partir de
`--subnet` y `--port`, y ninguna opción los dirige a la dirección LAN. La lectura de salud de
`doctor` tampoco usa el relay: lee directamente o no lee.

[Exponer en la LAN](https://docs.jmrp.io/mikroscope/es/security/expose/) tiene las dos reglas, el token, y quién llega
al agente a través de ellas.

## Sondeo tras install

Después de `install` y `upgrade`, la CLI sondea el agente desde tu máquina: una conexión TCP a la
dirección y el puerto del agente, luego `GET /healthz`. Cada intento agota su tiempo a los 2 s y se
reintenta un segundo después, durante hasta 30 s. Cuando el agente responde, la CLI imprime su
versión, la cadencia, el número de secuencia, los ticks retrasados y el tiempo de ida y vuelta:

```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 4, 0 slipped, 2ms round trip
```

Un agente que compiló la CLI informa la versión, el commit y la hora de compilación de la propia
CLI. Uno que se bajó el router, o que se cargó desde un tar de una release, informa la release para
la que se compiló.

Cuando el agente no responde, la CLI pregunta al router, en una conexión más, si el contenedor está
en marcha, porque una veth solo está levantada mientras su contenedor está en marcha:

| La CLI imprime                                                                                | Significa                                                                       | Haz                                                                                                                                  |
| --------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| ``the container is not running on the router: check `/log/print where topics~"container"` `` | el contenedor se paró o nunca arrancó, así que su veth está caída               | lee el log del router; el cortafuegos todavía no es el problema                                                                      |
| `the container runs; this host cannot reach 172.30.10.2. Options: …`                          | una regla del cortafuegos o una ruta que falta se interponen entre esta máquina y la /30 | revisa las [Listas del firewall](https://docs.jmrp.io/mikroscope/es/install/firewall/), añade una [ruta estática](https://docs.jmrp.io/mikroscope/es/install/reaching-the-agent/#ruta-estática), o usa el relay o `--expose` |
| `could not ask the router whether the container runs: …`                                      | falló la conexión que lo pregunta                                               | ejecuta `mikroscope status`                                                                                                          |

En los dos casos la orden falla con `agent installed but not reachable from this host`, y todo lo
que creó se queda en el router.

## Véase también

- [Listas del firewall](https://docs.jmrp.io/mikroscope/es/install/firewall/): las pertenencias de las que depende el
  transporte directo.
- [Usuario de la API](https://docs.jmrp.io/mikroscope/es/security/api-user/): el usuario que necesita el relay, y dónde
  restringirlo.
- [Exponer en la LAN](https://docs.jmrp.io/mikroscope/es/security/expose/): las dos reglas y el token.
- [Ejecutar el colector](https://docs.jmrp.io/mikroscope/es/sinks/): lo que tira del agente una vez que es alcanzable.