Cosmovisor

Fecha de última actualización: 19 mayo 2025

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/<name>/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

~/.<daemon> (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/[email protected]

Comprueba:

cosmovisor version # debería mostrar v1.4.0

3.2.Estructura de directorios

.cosmovisor/

├── genesis/

│ └── bin/

│ └── <daemon>

└── upgrades/

└── <upgrade-name>/

└── bin/

└── <daemon>

  • 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 [email protected] 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

  1. 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 <daemon>-<version>-<os>-<arch>.

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/<name>/pre-upgrade.sh

  • $DAEMON_HOME/cosmovisor/upgrades/<name>/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/[email protected]

# 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/

Last updated