Un ejercicio de respuesta a incidentes de 5 minutos que podés correr en tu propio nodo.
El aviso de BTCPay Server del 7 de agosto es claro: actualiza a la 2.4.2 y listo. El update regenera tus macaroons automáticamente.
Es cierto, pero solo para las puertas que BTCPay controla.
Si expones tu nodo LND por tu cuenta (un reverse proxy propio, un puerto reenviado, tu propio túnel Tor), ese macaroon robado sigue vivo después del update. BTCPay no puede rotar una credencial en una puerta que no sabe que existe. Y ese es exactamente el tipo de configuración que suelen tener los operadores avanzados.
Este tutorial es para dos casos:
- (a) Expones LND por tu cuenta, además de por BTCPay.
- (b) Todavía no pudiste actualizar y quieres rotar como medida temporal.
¿Ya actualizaste a 2.4.2 en una instalación estándar y no expones LND por tu cuenta? Los macaroons ya se rotaron solos, no necesitas correr este tutorial. Sigue igual con el resto del checklist de abajo (revisar actividad sospechosa, mover fondos del hot wallet, etc.).
Primero, tranquilidad: los macaroons son credenciales de acceso, no las llaves de tus fondos. Rotarlos no mueve monedas, no cierra canales, y no cambia la identidad de tu nodo. Tu seed queda intacta.
Qué vas a hacer
- Identificar el macaroon actual y comprobar que funciona.
- Borrar los macaroons y la base de datos de la root key.
- Reiniciar LND desde el host.
- Verificar que la nueva credencial funciona y la vieja es rechazada, mismo nodo, mismos fondos.
Requisitos previos
- Un BTCPay Server corriendo con el contenedor de LND (bitcoin): btcpayserver_lnd_bitcoin.
- Acceso por shell al host.
El modelo mental (lee esto primero)
Un macaroon es un token firmado. LND no guarda el token como fuente de verdad, guarda una root key en macaroons.db y hornea macaroons a partir de ella cuando se necesitan.
Ese único hecho define todo el procedimiento:
Borrar los archivos .macaroon no hace nada. LND vuelve a hornear copias idénticas byte a byte a partir de la root key en el siguiente arranque. Para rotar de verdad, hay que destruir la root key macaroons.db para forzar a LND a generar una nueva.
Borra los tokens y la clave. No solo los tokens.
Paso 1 — Capturar el estado "antes"
Entra al nodo y comprueba que la credencial actual es válida.
docker exec -it btcpayserver_lnd_bitcoin bash
# ---- ahora dentro del contenedor ----
cd /root/.lnd
alias li='lncli --macaroonpath /root/.lnd/admin.macaroon'
# Identifica el macaroon actual
sha256sum admin.macaroon
# Guarda una copia para probar que después muere.
cp admin.macaroon OLD.bak
# Comprueba que funciona: el nodo responde.
li getinfo | grep identity_pubkey
Anota el identity_pubkey. Tiene que ser idéntico al final. Si cambia, rotaste el nodo, no la credencial — ese es un resultado distinto (e incorrecto).
Paso 2 — Rotar: borrar los macaroons y la root key
Sigues dentro del contenedor.
rm -f *.macaroon \
data/chain/bitcoin/regtest/*.macaroon \
data/chain/bitcoin/regtest/macaroons.db
ls OLD.bak # nuestra copia guardada sobrevive
exit
Explicación: "Borrar solo los archivos .macaroon no hace nada, LND vuelve a hornear copias idénticas a partir de la root key. La root key vive en macaroons.db, así que también tiene que irse."
Nota sobre las rutas: las rutas de los macaroons codifican tu red. Este ejemplo es regtest. En un nodo real, cambia a mainnet (data/chain/bitcoin/mainnet/...). Verifica tu ruta real con ls data/chain/bitcoin/.
Paso 3 — Reiniciar LND desde el host
En el host:
docker restart btcpayserver_lnd_bitcoin
Explicación: "LND mantiene macaroons.db abierta, y es el PID 1 de su propio contenedor, no se puede reiniciar de forma limpia desde adentro. El reinicio viene desde afuera. Al arrancar sin root key, LND genera una nueva y regenera sus macaroons."
Dale unos segundos para que se desbloquee y vuelva a estar activo.
Paso 4 — Verificar: la nueva funciona, la vieja está muerta, el nodo no cambió
Entra de nuevo y compara lado a lado.
docker exec -it btcpayserver_lnd_bitcoin bash
cd /root/.lnd
alias li='lncli --macaroonpath /root/.lnd/admin.macaroon'
# Huella NUEVA — debe ser DISTINTA a la del Paso 1
sha256sum admin.macaroon
# La vieja, para comparar lado a lado
sha256sum OLD.bak
# La credencial NUEVA funciona — y es el MISMO nodo
li getinfo | grep identity_pubkey
# La credencial VIEJA es rechazada: "signature mismatch" = MUERTA
lncli --macaroonpath /root/.lnd/OLD.bak getinfo
# Limpieza
rm -f OLD.bak
exit
Explicación: "Nueva huella, la root key rotó de verdad. El nuevo macaroon funciona. La copia robada ahora es rechazada con un signature mismatch. Mismo pubkey, así que los canales y los fondos nunca se movieron. BTCPay y RTL ya se reconectaron solos."
Criterios de éxito:
Chequeo
Resultado esperado
sha256sum admin.macaroon
Distinto al del Paso 1
Nuevo macaroon con getinfo
Funciona
identity_pubkey
Igual al del Paso 1
OLD.bak getinfo
Error signature mismatch
Si se cumplen las cuatro: la cerradura cambió, la llave robada es chatarra, y el nodo nunca se movió.
Reconectar tus clientes
La conexión interna de LND de BTCPay y RTL (incluido) normalmente se reconectan solos. Todo lo que use un macaroon exportado tiene que volver a emparejarse con el nuevo:
- Zeus / wallets móviles — vuelve a escanear el nuevo QR de conexión.
- RTL (independiente), scripts, APIs — sube el nuevo admin.macaroon (o un macaroon de bakery con permisos acotados).
- Cualquier integración personalizada que tenga el macaroon viejo en hex/base64 — actualízala.
La credencial vieja ahora es inválida en todos lados, así que todo lo que no actualices va a fallar en la autenticación hasta que lo vuelvas a emparejar. Ese es justamente el objetivo.
Dónde entra esto en la respuesta completa
Rotar el macaroon es un paso. Para el incidente del 7 de agosto, la lista completa es:
- Actualizar a 2.4.2 — Panel de Admin → Server → Maintenance → Update. Confirma la versión en el pie de página y que LND quedó en la 0.21.1. En una instalación estándar, esto ya regenera los macaroons automáticamente. (¿No puedes actualizar ahora? Apaga el servidor, un servidor apagado no se puede explotar.)
- Rotar macaroons + macaroons.db manualmente — este tutorial. Necesario solo si expones LND por tu cuenta (proxy, Tor o puerto propio) o mientras no puedes actualizar todavía.
- Rotar la autenticación en cada backend de Lightning y actualizar las integraciones.
- Sacar los fondos de cualquier hot wallet on-chain creada por BTCPay, y después recrearla.
- Actualizar NBXplorer a 2.6.10 si lo usas.
En la mayoría de los casos, el update ya cambia la cerradura por ti. Los pasos manuales de rotación son para las puertas que BTCPay no puede ver ni cerrar por sí solo.
Alerta de estafa
Después de los avisos públicos, aparecen estafas de "te ayudo a migrar tus fondos". La regla nunca cambia:
Ninguna parte legítima, ni BTCPay, ni nadie te va a pedir jamás tu seed, clave privada, contraseña o macaroons.
Verifica cada instrucción contra los canales oficiales antes de actuar.
Preguntas que este tutorial responde de antemano:
- "¿Pierdo mis canales de Lightning si regenero los macaroons?" — No. Los macaroons son credenciales de acceso, no llaves de fondos. Los canales y los balances quedan intactos.
- "¿Afecta esto a mi hardware wallet?" — No. Este es un problema del operador del servidor, separado de cualquier incidente de hardware wallet.
