# Cosmovisor ## 1.¿Qué es Cosmovisor? Cosmovisor es un wrapper escrito en Go que ejecuta el proceso daemon de tu cadena (p. ej. osmosisd, kava, celestia-app, etc.) y automatiza las actualizaciones de software on‑chain. Cuando la red alcanza la altura de upgrade definida en una gov proposal Cosmovisor: 1. Detiene el proceso actual.
2. Cambia al binario nuevo (ubicado en el directorio upgrades/\/bin/).
Reinicia el nodo con el nuevo binario sin intervención manual.
Ventajas: * Cero tiempo de inactividad (si el binario está preparado a tiempo). * Gestión centralizada de binarios y backups. * Menor riesgo de olvidarse del upgrade y quedar fuera del set. ### 2 – Requisitos previos | Componente | Requisito | | ------------------ | ------------------------------------------------------ | | Go | 1.22.11 o superior (recomendado ≥ 1.22.x) | | Binario del daemon | Compilado para tu cadena (ej.: osmosisd, kava) | | HOME del nodo | \~/.\ (ej.: \~/.osmosisd) | | Espacio libre | 10 MB + (n × tamaño de binarios) | | Permisos | Usuario sin privilegios sudo para ejecutar el servicio | \ Nota: Cosmovisor no compila binarios; solo los cambia. Debes preparar cada binario de upgrade manualmente o permitir la descarga automática. ## 3.Instalación ### 3.1.Instalar Cosmovisor 1.4+ go install cosmossdk.io/tools/cosmovisor/cmd/cosmovisor\@v1.4.0
Comprueba: cosmovisor version # debería mostrar v1.4.0 ### 3.2.Estructura de directorios .cosmovisor/ ├── genesis/ │ └── bin/ │ └── \ └── upgrades/ └── \/ └── bin/ └── \
* genesis/bin: binario usado al arrancar desde génesis.\
upgrades/: cada subcarpeta corresponde al nombre de la propuesta de upgrade (v29, mars\_3, etc.).\
### 3.3.Preparar estructura ``` DAEMON_NAME=osmosisd # cambia al tuyo eval DAEMON_HOME="$HOME/.${DAEMON_NAME}" mkdir -p $DAEMON_HOME/cosmovisor/genesis/bin mkdir -p $DAEMON_HOME/cosmovisor/upgrades cp $(which $DAEMON_NAME) $DAEMON_HOME/cosmovisor/genesis/bin/ ``` ## 4.Variables de entorno Añádelas a \~/.profile o al archivo del servicio: | Variable | Descripción | Valor recomendado | | --------------------------------- | ---------------------------------------- | ----------------------- | | DAEMON\_NAME | Nombre del binario | osmosisd, kava, etc. | | DAEMON\_HOME | Carpeta de datos | \~/.osmosisd, \~/.kava | | DAEMON\_RESTART\_AFTER\_UPGRADE | Reiniciar tras upgrade | true | | DAEMON\_ALLOW\_DOWNLOAD\_BINARIES | Descarga binarios de release | false (mejor seguridad) | | DAEMON\_LOG\_BUFFER\_SIZE | Buffer bytes | 512 | | UNSAFE\_SKIP\_BACKUP | Omitir backup de datos antes del upgrade | false (por defecto) | | DAEMON\_PREUPGRADE\_MAX\_RETRIES | Reintentos de script pre-upgrade | 0 (ilimitado) | Ejemplo: `echo "export DAEMON_NAME=osmosisd" >> ~/.profile` `echo "export DAEMON_HOME=$HOME/.osmosisd" >> ~/.profile` `...` `source ~/.profile` ## 5.Servicio systemd genérico ``` [Unit] Description=Cosmovisor daemon (%i) After=network-online.target [Service] User=%u Environment="DAEMON_NAME=%i" Environment="DAEMON_HOME=%h/.%i" Environment="DAEMON_RESTART_AFTER_UPGRADE=true" Environment="DAEMON_ALLOW_DOWNLOAD_BINARIES=false" Environment="DAEMON_LOG_BUFFER_SIZE=512" Environment="UNSAFE_SKIP_BACKUP=false" ExecStart=%h/go/bin/cosmovisor run start Restart=always RestartSec=3 LimitNOFILE=infinity LimitNPROC=infinity [Install] WantedBy=multi-user.target ``` Guarda como y habilita: `sudo systemctl daemon-reload` `sudo systemctl enable cosmovisor@osmosisd # reemplaza osmosisd` `sudo systemctl start cosmovisor@osmosisd` ## 6.Preparar un upgrade paso a paso 1. Consulta la proposal (gov proposal ) y anota el campo Name y Height. 2. Crea la carpeta: ``` UPGRADE="v30" mkdir -p $DAEMON_HOME/cosmovisor/upgrades/$UPGRADE/bin ``` \ 3\. Compila o descarga el nuevo binario: `cd ~/osmosis && git fetch && git checkout v30.0.0 && make build` `cp build/osmosisd $DAEMON_HOME/cosmovisor/upgrades/$UPGRADE/bin/` \ 4\. Verifica: `$DAEMON_HOME/cosmovisor/upgrades/$UPGRADE/bin/osmosisd version`
5. Reinicia (opcional): sudo systemctl restart cosmovisor\@osmosisd. Cosmovisor detectará automáticamente la altura y hará switch. ## 7. Descarga automática de binarios Si estableces DAEMON\_ALLOW\_DOWNLOAD\_BINARIES=true, Cosmovisor buscará el binario en GitHub Releases del repositorio oficial. Requisitos: * La propuesta debe incluir Info con la URL del release.\
El nombre del asset debe coincidir con \-\-\-\. Ventaja: sin compilación manual. Desventaja: confías en la firma mantenedor. ## 8.Scripts pre‑upgrade y post‑upgrade (v1.4+) Coloca scripts ejecutables en: * `$DAEMON_HOME/cosmovisor/upgrades//pre-upgrade.sh`\
* `$DAEMON_HOME/cosmovisor/upgrades//post-upgrade.sh`\
El script debe devolver exit 0 en caso de éxito. Cosmovisor aborta el upgrade si falla. Ejemplos de uso: * Pre‑upgrade: migrar base de datos, exportar snapshot.\
* Post‑upgrade: limpiar archivos obsoletos, reiniciar servicios auxiliares. ## 9.Monitorización y logs | Recurso | Comando | | ----------------------- | ------------------------------------- | | Logs tiempo real | journalctl -u cosmovisor\@osmosisd -f | | Ver versión activa | osmosisd version | | Revisar altura de chain | \`osmosisd status | | Health‑check REST | curl localhost:1317/node\_info | Incluye métricas Prometheus (--metrics) para alertas sobre upgrades. ## 10.Solución de problemas | Síntoma | Posible causa | Solución | | ------------------------------- | ------------------------------------------------------- | ------------------------------------------------ | | Nodo no arranca tras upgrade | Ruta binario incorrecta | Verifica permisos y nombre de la carpeta upgrade | | Cosmovisor no cambia de versión | Altura incorrecta o Info malformado | Comprueba número de bloque y JSON de proposal | | Descarga binario falla | DAEMON\_ALLOW\_DOWNLOAD\_BINARIES=true sin asset válido | Sube asset correcto o compila manual | \ 11 – Buenas prácticas de seguridad ---------------------------------- * Compila binarios en máquina limpia o usa cosign para verificar firmas.\
* Desactiva UNSAFE\_SKIP\_BACKUP salvo que tengas snapshots externos.\
* Sígnalos con checksum SHA256 y almacena en /usr/local/bin read‑only.\
* Mantén tu firewall: solo expón 26656 y puertos RPC locales.\
## 12 – Resumen rápido (TL;DR) \ \# instalar cosmovisor go install cosmossdk.io/tools/cosmovisor/cmd/cosmovisor\@v1.4.0 \# preparar directorios\mkdir -p \~/.daemon/cosmovisor/{genesis,upgrades}/ cp $(which daemon) \~/.daemon/cosmovisor/genesis/bin/ \# crear servicio systemd sudo systemctl enable --now cosmovisor\@daemon \# añadir binario upgrade antes del height mkdir -p \~/.daemon/cosmovisor/upgrades/vX/bin && cp newbin \~/.daemon/cosmovisor/upgrades/vX/bin/