Instalar el agente para Linux

Un solo comando instala el agente, y esta página es lo que ocurre dentro de él: primero las condiciones de uso, después qué se comprueba antes de escribir nada, cada pregunta y qué responde un Enter, las variables de entorno y las opciones de un despliegue desatendido, una instalación a mano y un host sin systemd.

Instalación

Un comando, como root. Lee la versión actual de los metadatos públicos, descarga con tu clave la versión compilada para tu arquitectura, la verifica contra SHA256SUMS, la instala en /usr/local/bin/reportedip-agent y después configura el host.

curl -fsSL https://reportedip.com/agent/install.sh | REPORTEDIP_KEY=<YOUR-KEY> sh

La clave va en el entorno porque se necesita dos veces, una para la descarga con licencia y otra para registrar el host, y pegarla dos veces es la forma en que una clave acaba con un formato equivocado en el historial del shell. Omite la variable y el script pregunta por la clave, con el eco del terminal apagado para que no se quede en el historial de la pantalla. La pregunta lee el terminal y no la entrada estándar, porque en la forma de arriba la entrada estándar es el propio script, y poder abrir ese terminal es a la vez la comprobación de si hay alguien a quien preguntar: una ejecución desde cron, desde una unidad de systemd o desde una herramienta de automatización no tiene terminal, no se le pregunta y se detiene con la línea que nombra la variable. El script es sh POSIX a propósito: tiene que funcionar en hosts donde bash no es el shell predeterminado. Se detiene con un motivo nombrado y no instala nada si no se ejecuta como root, si la plataforma no es Linux, si la arquitectura no es amd64 ni arm64, si no existe ni curl ni wget, y si falta sha256sum.

Las dos vías de descarga están separadas a propósito. Los metadatos de versión se obtienen sin la clave y los archivos con licencia con ella, de modo que la clave nunca va a un destino de redirección que solo sirve metadatos públicos. Del archivo de sumas se comprueba únicamente la línea de tu propia arquitectura, porque el archivo también incluye la otra.

Qué comprueba install antes de escribir

Tres cosas se comprueban antes de que el primer byte llegue al disco, en el orden en que un error resulta más barato de encontrar. Primero los argumentos, porque una errata en una opción es el mismo error en todos los hosts y no tiene nada que ver con lo que esta máquina puede hacer: un --notify-email mal escrito creaba antes los directorios y se rechazaba después. Luego el host, impreso como un bloque con nombre, porque quien lanza esto debe enterarse de que el agente no puede correr aquí antes de que lo manden a buscar una clave. Luego las preguntas de la sección siguiente. La clave al final, porque es el único paso que cuesta una ida y vuelta por la red y porque una clave recién tecleada debe someterse al servidor de inmediato.

requirements:
  ok   systemd      running as pid 1
  ok   firewall     ipset and iptables found, nft as well; auto takes ipset, set backend: nftables in the config if this host's rules live in nftables

Cada línea lleva una de tres marcas. ok está cumplida, warn falta y no detiene la ejecución, y STOP es la única marca que alguna vez significa que la instalación terminó ahí. Solo systemd es un requisito duro, y se lee en /run/systemd/system, el directorio que systemd crea cuando es pid 1, y no en la presencia de systemctl: una imagen de contenedor puede llevar el binario sin arrancar nunca el gestor, y ese es justo el host que antes recibía una instalación completa que nunca podía arrancar. Un backend de cortafuegos ausente se informa como warn y no detiene nada, porque el modo de solo notificar es una forma admitida de usar el agente, y la línea nombra el paquete que hay que instalar, apt install ipset iptables o apt install nftables. La clave se somete a verify-key antes de escribir la configuración, y a propósito sin el identificador de instalación: una prueba no debe dejar atrás una fila en el registro de hosts para un host que quizá nunca se instale. Solo un 401 o un 403 detienen la ejecución, y entonces no hay nada en el disco. Todo lo demás, un fallo de DNS, un proxy, un cortafuegos aún sin abrir, imprime una línea y la instalación continúa, porque una instalación sin red es legítima y la sincronización lo reintenta por sí misma. Lo que install.sh rechaza por su cuenta antes de todo esto figura más arriba.

Qué pregunta, y qué responde la tecla Enter

Cuatro preguntas, y solo por lo que no le dieron: la clave, la dirección a la que se envía por correo un estado averiado, si un acierto de la lista de la comunidad se descarta o solo se registra, y si este host también bloquea lo que atrapa en sus propios registros. A una ejecución que recibió los cuatro valores como opciones o como variables de entorno no se le pregunta nada, y así corre un despliegue desatendido, ni más lento ni más hablador que antes. Todo lo que el instalador puede averiguar por sí mismo, los puertos ssh, las fuentes de registro, el backend del cortafuegos, lo averigua en lugar de preguntarlo.

  api key (from your account on https://reportedip.com):
  email for the state mails of this host, Enter for none: ops@example.org
  blocking: the community list is loaded into the kernel either way. What the rules do
            with a match is the question, and this host is set up to deny it: drop is what
            an Enter here writes, so the first sync already stops what the list names.
            log is the other answer, and the one to give for a host you want to watch
            before it denies anything: it counts every match and lets the packet through.
            Neither answer is final. mode: log or mode: drop in the config is one word, and
            the next sync run rebuilds the rules. Your own addresses, the session you are
            sitting in and everything in the whitelist are never blocked in either mode.
  drop or log, Enter for drop:
  local bans: the second switch, and the half that replaces fail2ban. The list above comes
            from the community; this is about the addresses this host catches in its own
            logs, and it is on unless you say otherwise. Every entry has a timeout the
            kernel enforces, so a stopped agent leaves no permanent ban, whitelist add is
            the way out of one, and in mode: log they are recorded and only logged.
  ban what this host finds itself [Y/n]:
  ok   key          accepted, role <your role>, reports today <used>/<limit> (account-wide)
wrote /etc/reportedip-agent/config.yaml (lists [ssh mail web ftp edge], ssh ports [22022], 10 log sources, mode drop)
this host denies every match of the community list and bans what it finds in its own logs
state mails go to ops@example.org; change notify.email in the config to stop or redirect them
units installed; sync timer and log watcher enabled; run: reportedip-agent sync && reportedip-agent status

La clave se lee con el eco del terminal apagado, así que se queda fuera del historial de la pantalla y no aparece en ninguna línea de la salida. En las otras tres preguntas, un Enter es una respuesta válida y toma cada vez el valor por omisión: sin dirección de correo, mode: drop, bloqueos locales activados. Un host preparado con tres Enter descarta por tanto lo que nombra la lista de la comunidad y bloquea lo que encuentra en sus propios registros, y para eso está el agente. Lo que lo hace seguro no es la respuesta, es la lista blanca: las direcciones de este host, la sesión en la que corre la instalación, RFC1918 y todo lo que hay en whitelist.conf no se bloquean ni se notifican nunca, en ningún modo, y reportedip-agent whitelist add surte efecto sin sincronización. Las dos últimas preguntas están en la instalación sencilla y no detrás de una opción, porque son los dos valores que deciden si el host hace algo, y porque la diferencia no se ve en systemctl status.

reportedip-agent install --expert, o REPORTEDIP_EXPERT=1, pregunta el resto. Ocho grupos, cada uno detrás de una puerta [y/N] que un Enter se salta, y dentro de un grupo cada valor muestra su valor por omisión entre corchetes: el feed junto con el backend del cortafuegos, la escalera de bloqueos, los umbrales de detección, el umbral de una sola fuente de eventos, los límites de funcionamiento junto con el registro, la entrega del correo incluido un servidor smtp para un host sin MTA local, los puertos de la lista ssh, y las fuentes de registro detectadas, donde se puede quitar una y añadir una que la detección no vio. Cada respuesta se comprueba contra el rango que acepta el lector de configuración antes de poder escribirse, así que un 0 en min_hits vuelve como 0 is outside 1 to 10000 y se pregunta otra vez, y la configuración terminada pasa después por la misma validación que aplica el agente al releer el archivo, lo que hace imposible una clase de fallo: una respuesta que deja un host registrado con un agente que se niega a arrancar. El grupo de los bloqueos imprime la escalera que acaba de construir, así que time_minutes 45 con escalate 3 y max_time_minutes 20160 responde 45 min, 135 min, 405 min, 1215 min, 3645 min, 10935 min, 14 d (ceiling). mode y ban.enabled no se preguntan por segunda vez, ya se respondieron arriba. Una ejecución experta que se salta todos los grupos escribe byte por byte el mismo archivo que una sencilla. Ninguna pregunta ofrece el modo experto, se llega a él por la opción y por la variable y por nada más, y sin terminal es un error y no una vuelta silenciosa a la vía sencilla.

Sin terminal no se pregunta nada, y esa es la situación de cron, de una unidad de systemd, de una herramienta de automatización y de la integración continua. Un detalle cuenta ahí: < /dev/null por sí solo no vuelve una ejecución no interactiva, porque el terminal de control sobrevive a una entrada estándar redirigida. setsid lo quita, y eso es lo que hacen esos invocadores.

Qué hace realmente el instalador

Todo lo que sigue es idempotente. El mismo comando en un host que ya tiene el agente actualiza el binario y deja la configuración exactamente como estaba.

1. Muestra las condiciones de uso y espera un yes, salvo que REPORTEDIP_ACCEPT_TERMS=1 esté definida. Sin terminal y sin la variable el script se detiene aquí, antes de la clave y antes de cualquier descarga.
2. Lee https://reportedip.com/agent/latest sin la clave y extrae de ahí la versión. Ese archivo es el mismo JSON que el propio agente consulta para las actualizaciones.
3. Descarga reportedip-agent_linux_<arch> y SHA256SUMS con la cabecera X-Key en un directorio temporal que se borra en cualquier vía de salida.
4. Verifica la suma de comprobación y no instala nada si hay discrepancia.
5. Instala el binario con modo 0755 en /usr/local/bin/reportedip-agent y muestra la versión que acaba de dejar.
6. Reinicia reportedip-agent.service si esa unidad está activa. Esto importa en una actualización: el demonio watch seguiría ejecutando el código antiguo hasta el siguiente reinicio de la máquina. La unidad de sincronización es de tipo oneshot y toma el binario nuevo por sí misma en su siguiente arranque.
7. Ejecuta la configuración del host, salvo que REPORTEDIP_NO_SETUP=1 esté definida o que /etc/reportedip-agent/config.yaml ya exista. En el segundo caso lo dice y deja la configuración en paz.

La configuración del host es el paso que escribe archivos, y es lo mismo que sudo REPORTEDIP_KEY=<YOUR-KEY> reportedip-agent install. Por orden, una vez superados los términos de uso, las opciones, los requisitos y las preguntas:

• Detecta el puerto SSH a partir de sshd -T, de SSH_CONNECTION y de los procesos sshd que escuchan, y toma la unión de los tres. Si no encuentra nada, se detiene y pide --ssh-port en vez de suponer 22.
• Decide cuáles de las cinco listas del feed se configuran. ssh y edge están siempre activas. mail, web y ftp se añaden cuando una unidad correspondiente está activa o un puerto correspondiente escucha: un host sin servidor web no recibe por tanto una lista web. Un puerto solo cuenta cuando algo de fuera podría alcanzarlo: un socket asociado únicamente a 127.0.0.1 o a ::1 no es superficie de ataque, y no se trata como tal. Esa es la diferencia entre un servidor de correo y un agente de entrega local que solo acepta correo de su propia máquina, y entre un servidor de nombres y el resolutor local que ocupa 127.0.0.53:53 en un host Debian normal.
• Detecta las fuentes de registro y las escribe de forma explícita en la configuración. La detección ocurre una vez, en la instalación, y el resultado permanece en el archivo: un servicio detenido por mantenimiento nunca debe desactivar una fuente en silencio. En un host con panel de control se configuran tanto los patrones por sitio del panel como los registros por omisión del servidor web, y no solo el primero de los dos. No son dos vistas del mismo tráfico: una petición que no alcanza ningún host virtual con su propio access_log cae en el registro por omisión, y eso es exactamente lo que produce un escáner que recorre direcciones en vez de nombres de host. En un host de producción medido eso fueron 20.453 líneas de 466 direcciones distintas en un solo día. Se toma cada registro por omisión que exista, porque nginx delante de Apache es la disposición habitual de un panel y los dos escriben el suyo, y uno vacío cuenta también, porque un registro está vacío hasta que alguien llama a la puerta. /var/log/apache2/other_vhosts_access.log se deja fuera a propósito: sus líneas empiezan por el host virtual, así que la dirección queda en el segundo campo mientras el detector lee el primero, y una fuente que no puede notificar nada mientras doctor llama sano al host es peor que ninguna fuente.
• Llama a verify-key y muestra tu rol y los informes consumidos hoy frente al límite diario. Es la última de las tres comprobaciones y ocurre antes de crear el primer directorio, así que una clave equivocada no cuesta nada en el disco. Un 401 o un 403 aquí significa que la clave está mal, y ese es el único fallo que conviene corregir de inmediato.
• Crea /etc/reportedip-agent y /var/lib/reportedip-agent, el segundo con modo 0700, y corrige el modo de un directorio que ya estuviera.
• Escribe /etc/reportedip-agent/config.yaml con modo 0600. mode y ban.enabled llevan las respuestas de las preguntas de arriba, y sin nada pasado y nada teclado eso es mode: drop y ban.enabled: true, los dos valores que la pregunta de arriba imprimió como su valor por omisión. Las dos líneas que siguen al archivo dicen con palabras qué hace el host a partir de ahora, porque la diferencia no se ve en systemctl status. Una configuración existente nunca se sobrescribe: una segunda ejecución no pregunta nada, dice the key was ignored because the config already exists; edit api_key in /etc/reportedip-agent/config.yaml to change it, y relee los dos interruptores del archivo que conservó, así que puede decir it says mode: drop and ban.enabled: true, so that is what this host does; nothing here changed either value. No borres el archivo para conseguir una instalación nueva, salvo que quieras perder esas dos decisiones; apártalo en su lugar.
• Escribe la lista blanca automática en el directorio de estado: la dirección desde la que venía tu sesión SSH, más cada dirección de interfaz del host. La dirección de sesión de una ejecución anterior se conserva, para que una segunda ejecución desde otra sesión no retire la dirección en la que confiaba la primera. Las direcciones de interfaz se vuelven a determinar en cada ejecución, para que una dirección eliminada no se quede colgando.
• Genera el identificador de instalación, un UUID v4 aleatorio en /var/lib/reportedip-agent/install-id. Esa es desde ese momento la identidad de este servidor frente a la API, y sigue siendo esa identidad aunque el nombre del host viaje a su lado.
• Advierte de tres cosas que no puede arreglar por ti: una tabla de nftables inet reportedip que dejó el script de shell documentado, sea cual sea el backend; en un host nuevo, conjuntos de ipset llamados rip-* que el agente no creó, casi siempre ese mismo script lanzado desde un cron, cuya lista blanca hay que adoptar y cuyo cron hay que desactivar antes de la primera sincronización; y un nginx que lee cabeceras de Cloudflare sin set_real_ip_from. La fuente web contaría entonces direcciones de Cloudflare en lugar de las del visitante.
• Escribe las tres unidades de systemd en /etc/systemd/system, ejecuta daemon-reload, activa reportedip-agent-sync.service, y activa e inicia reportedip-agent-sync.timer y reportedip-agent.service.
• Con las unidades ya en su sitio, llama a verify-key por segunda vez, ahora con el identificador de instalación, lo que registra el host, y vuelve a mostrar el rol y los informes de hoy. Un 401 o un 403 en este punto termina la ejecución con código de salida 1: el host ya está instalado y lo que hay que corregir es api_key en la configuración.

Las variables de entorno de install.sh

# Binary only, no host setup: for an image or for Ansible. The
# terms of use are asked before the download, so the variable goes
# here as well.
curl -fsSL https://reportedip.com/agent/install.sh \
  | REPORTEDIP_ACCEPT_TERMS=1 REPORTEDIP_KEY=<YOUR-KEY> REPORTEDIP_NO_SETUP=1 sh

# Later, on the running host, or from your playbook. The key goes
# in the environment and not in an argument, because
# /proc/<pid>/cmdline can be read by every local user of the host.
# sudo clears the environment, so the variable goes in front of it.
sudo REPORTEDIP_KEY=<YOUR-KEY> reportedip-agent install --accept-terms

Instalación a mano

El paso de configuración es un comando propio. Ejecútalo cuando REPORTEDIP_NO_SETUP=1 solo haya dejado el binario, cuando la detección haya adivinado algo que quieras corregir, o cuando un despliegue tenga que responder todas las preguntas de antemano. Lo que llega como opción no se pregunta: --key, --notify-email, --mode log|drop, --ban y --no-ban, --log-level debug|info|warn|error, --admin-ip, --ssh-port, --accept-terms y --expert para las preguntas más finas. --key sigue funcionando e imprime una línea que dice que su valor está en la lista de procesos, donde cualquier usuario local de este host puede leerlo mientras dure la ejecución; pasa la clave como REPORTEDIP_KEY en su lugar. sudo borra el entorno por omisión, así que la variable va delante de sudo y no detrás. En un host que aún no tiene configuración, la ejecución empieza por las condiciones de uso y solo continúa tras un yes; la aceptación queda registrada en /var/lib/reportedip-agent/terms-accepted con la versión del texto y la hora, y doctor muestra esa línea. A un host ya configurado no se le vuelve a preguntar y solo se le indica dónde están las condiciones.

# The key goes in the environment. sudo clears the environment by
# default, so the variable belongs in front of sudo; behind it the
# install finds no key and exits 2.
sudo REPORTEDIP_KEY=<YOUR-KEY> reportedip-agent install

# The detection could not find the SSH port (socket activation,
# a non-standard unit, a port from an include file):
sudo REPORTEDIP_KEY=<YOUR-KEY> reportedip-agent install --ssh-port 2222

# The session address is not where you administer this host from
# (a jump host, a console, a serial connection):
sudo REPORTEDIP_KEY=<YOUR-KEY> reportedip-agent install --admin-ip 203.0.113.0/24

# Arm the state mails at the same time:
sudo REPORTEDIP_KEY=<YOUR-KEY> reportedip-agent install --notify-email ops@example.org

# A rollout that answers everything, so nothing is asked and no
# terminal is needed. Works the same as five environment variables:
# REPORTEDIP_ACCEPT_TERMS, REPORTEDIP_KEY, REPORTEDIP_NOTIFY_EMAIL,
# REPORTEDIP_MODE, REPORTEDIP_BAN
sudo REPORTEDIP_KEY=<YOUR-KEY> reportedip-agent install --accept-terms \
  --notify-email ops@example.org --mode drop --ban

# Everything the four questions do not cover, asked one group at a time:
sudo REPORTEDIP_KEY=<YOUR-KEY> reportedip-agent install --expert

--admin-ip acepta una sola dirección o un rango CIDR y ocupa el lugar de la dirección de sesión adivinada; las direcciones que ejecuciones anteriores de la instalación escribieron en la lista blanca automática siguen en ella. Merece la pena siempre que la sesión SSH no sea representativa, porque la dirección adivinada es lo que se interpone entre tú y tu propia regla de bloqueo el primer día. Toda la ejecución de instalación tiene un plazo de cinco minutos, así que un nft o un systemctl colgado termina en un error y no en un proceso que tengas que interrumpir.

Un host sin systemd

install no se ejecuta aquí. La orden escribe las unidades de systemd y las activa, así que rechaza un host donde systemd no es el pid 1 y no escribe nada, en vez de dejar atrás una configuración que nunca arranca nada. Con el binario es otra cosa: nada en él depende de systemd, y doctor informa del gestor ausente en vez de fallar. Lo que queda es una preparación a mano, y en un host así hay que preparar dos cosas.

# 1. The feed sync, from cron. Every 15 minutes is safe on any
#    plan: the agent skips a fetch its own plan interval does
#    not allow yet, so nothing is requested too often.
*/15 * * * * root /usr/local/bin/reportedip-agent sync >/dev/null 2>&1
@reboot      root sleep 120 && /usr/local/bin/reportedip-agent sync

# 2. The watch daemon, from your init system. It runs in the
#    foreground, logs to stderr and stops on SIGTERM.
/usr/local/bin/reportedip-agent watch

La entrada para el arranque no es opcional. Los plazos de caducidad de ipset no sobreviven a un reinicio, y los conjuntos tampoco: sin una sincronización tras el arranque, el host vuelve a levantarse sin reglas y sin bloqueos restaurados. En un host con systemd ese camino lo cubre reportedip-agent-sync.service, activado para multi-user.target, que se ejecuta después de cada servicio de cortafuegos y sin retardo aleatorio. En un host sin journald deja log_file definido, porque allí stderr puede no llevar a ninguna parte.

Dos consecuencias de esto se pasan por alto con facilidad. sync necesita un /etc/reportedip-agent/config.yaml que nadie ha escrito por ti, porque la orden que escribe uno es la orden que aquí no se ejecuta. Y sin el identificador de instalación que genera esa misma orden, este host no tiene identidad frente a la API, así que nunca aparece en Agent Servers y no ocupa ninguna licencia de servidor.

Última actualización: 30. septiembre 2026 · Mantenido por el equipo de ReportedIP