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/