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:
Detiene el proceso actual.
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
Consulta la proposal (gov proposal ) y anota el campo Name y Height.
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
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