# 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/
--- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.ethernodes.io/guias-y-otros/deplega-tu-nodo/cosmovisor.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.