Skip to content

cosmovisor-configuration.md

Latest commit

 

History

History
110 lines (87 loc) · 6.07 KB

cosmovisor-configuration.md

File metadata and controls

110 lines (87 loc) · 6.07 KB

Cosmovisor Configuration Guide

💬 Cosmovisor is a process manager for Cosmos SDK application binaries that automates application binary switch at chain upgrades. It polls the upgrade-info.json file that is created by the x/upgrade module at upgrade height, and then can automatically download the new binary, stop the current binary, switch from the old binary to the new one, and finally restart the node with the new binary.

This guide explains the key configuration options for Cosmovisor when running a cheqd node. You can configure these settings via:

  • Environment variables

  • A config.toml file under $DAEMON_HOME/cosmovisor/ (by default) or any other location passed to cosmovisor with --cosmovisor-config flag

Note: Environment variables always take precedence over values set in the config file, if the --cosmovisor-config flag is not passed.

The cheqd node's interactive installer sets most of these parameters for you in both the daemon service configuration file (cheqd-cosmovisor.service) and as a system-wide environment variable. It will also create a config.toml file, for consistency purposes. Understanding these settings helps with troubleshooting and advanced setups.

Configuration Parameters

Parameter Default Value Required Description Set by Installer
DAEMON_HOME /home/cheqd/.cheqdnode Yes Location of the cosmovisor/ directory. ✅
DAEMON_NAME cheqd-noded Yes Name of the node binary. Usually doesn’t need to change. ✅
DAEMON_ALLOW_DOWNLOAD_BINARIES true No Allows Cosmovisor to auto-download upgrade binaries. Recommended to be true. ✅
DAEMON_DOWNLOAD_MUST_HAVE_CHECKSUM true No Ensures downloaded binaries have checksums. Always true in cheqd upgrade plans. ✅
DAEMON_RESTART_AFTER_UPGRADE true No Automatically restarts node after an upgrade. ✅
DAEMON_RESTART_DELAY 30s No Delay before restart after upgrade. 0s is fine for most setups. ✅
DAEMON_SHUTDOWN_GRACE 30s No Grace period for clean shutdown. Helps with safe unattended upgrades. ✅
DAEMON_POLL_INTERVAL 300s No How often to check for upgrade plans. ❌
DAEMON_DATA_BACKUP_DIR DAEMON_HOME No Custom directory for pre-upgrade backups. Requires extra storage. ❌
UNSAFE_SKIP_BACKUP true No Set to false to enable auto-backups (slower and storage-heavy). ✅
DAEMON_PREUPGRADE_MAX_RETRIES 0 No Max retries for pre-upgrade hook (exit code 31). ❌
COSMOVISOR_DISABLE_LOGS false No Disable Cosmovisor logs (not the node logs). ❌
COSMOVISOR_COLOR_LOGS true No Enables colored logs for easier readability. ❌.
COSMOVISOR_TIMEFORMAT_LOGS kitchen No Time format for logs (e.g., 3:04PM). Other formats: rfc3339, unix, etc. ❌
COSMOVISOR_CUSTOM_PREUPGRADE '' No Path to a custom pre-upgrade script. It should be located under $DAEMON_HOME/cosmovisor/. ❌
COSMOVISOR_DISABLE_RECASE false No Enforces exact case matching for upgrade plan directories. ❌

📝 Additional Notes

  • Backups: Enabling backups can use significant disk space and time. Use with caution, especially on non-pruned nodes.
  • Custom Pre-upgrade Scripts: Use COSMOVISOR_CUSTOM_PREUPGRADE for advanced automation (e.g., state export).
  • Log Time Format: kitchen is human-readable. See Go time formats for more options.

🔧 Example: systemd Service File

To set Cosmovisor parameters at the service level, you can edit the systemd service file, typically located at /usr/lib/systemd/system/cheqd-cosmovisor.service. Here is an example with custom values:

[Unit]
Description=Service for running cheqd-noded daemon
After=network.target
Documentation=https://docs.cheqd.io/node

[Service]
Environment="DAEMON_HOME=/home/cheqd/.cheqdnode"
Environment="DAEMON_NAME=cheqd-noded"
Environment="DAEMON_ALLOW_DOWNLOAD_BINARIES=true"
Environment="DAEMON_RESTART_AFTER_UPGRADE=true"
Environment="DAEMON_POLL_INTERVAL=300s"
Environment="UNSAFE_SKIP_BACKUP=false"
Environment="DAEMON_RESTART_DELAY=30s"
Environment="DAEMON_DOWNLOAD_MUST_HAVE_CHECKSUM=true"
Environment="DAEMON_SHUTDOWN_GRACE=30s"

Type=simple
User=cheqd
ExecStart=/usr/bin/cosmovisor run start
Restart=on-failure
RestartSec=30
StartLimitBurst=5
StartLimitInterval=60
TimeoutSec=120
StandardOutput=journal
StandardError=journal
SyslogIdentifier=cosmovisor
LimitNOFILE=65535

[Install]
WantedBy=multi-user.target

If you decide to use config.toml file instead, feel free to remove environment variables from daemon service file and add --cosmovisor-config to your config file, i.e. ExecStart=/usr/bin/cosmovisor run start --cosmovisor-config /home/cheqd/.cheqdnode/cosmovisor/config.toml.

⚠️ Important: If you manually modify this file, the cheqd installer may overwrite your changes. When prompted during future installs, decline the update to preserve your custom settings.

🛠 Example: config.toml File

daemon_home = '/home/cheqd/.cheqdnode'
daemon_name = 'cheqd-noded'
daemon_allow_download_binaries = true
daemon_download_must_have_checksum = true
daemon_restart_after_upgrade = true
daemon_restart_delay = '30s'
daemon_shutdown_grace = '30s'
daemon_poll_interval = '300s'
unsafe_skip_backup = true
daemon_data_backup_dir = '/home/cheqd/.cheqdnode'
daemon_preupgrade_max_retries = 0
daemon_grpc_address = 'localhost:9090'
cosmovisor_disable_logs = false
cosmovisor_color_logs = true
cosmovisor_timeformat_logs = 'kitchen'
cosmovisor_custom_preupgrade = ''
cosmovisor_disable_recase = false

⚠️ Reminder: Like the service file, custom config.toml changes can be overwritten by the installer. Decline updates if you’ve made manual modifications.

For further details, refer to the official Cosmovisor documentation.