|
| 1 | +--- |
| 2 | +layout: default |
| 3 | +title: Upgrade Pax-daemon |
| 4 | +parent: CosmosDaemon |
| 5 | +--- |
| 6 | + |
| 7 | +# Upgrade paxd |
| 8 | + |
| 9 | +A guide on how to updgrade the pax network. |
| 10 | + |
| 11 | +## Cosmovisor |
| 12 | + |
| 13 | +Cosmovisor is the recomended way to upgrade your validator node. |
| 14 | +More info on [Cosmosvisor](https://docs.cosmos.network/main/build/tooling/cosmovisor) |
| 15 | + |
| 16 | +### Start Cosmovisor |
| 17 | + |
| 18 | +Cosmosvisor is a wrapper around paxd that listens to upgrade planes being passed on the network. A upgrade plan contains a upgradeheigth and binary path. |
| 19 | + |
| 20 | +Cosmosvisor will use the binary path to download the new binary if autoupdate has been passed in the starting arguments. This is not the recomendede way of doing it. |
| 21 | + |
| 22 | +Recomended way of doing the upgrade is to download the new binary manuley and place it in the correct place in the cosmovisor folder structure |
| 23 | + |
| 24 | +Cosmovisor sets up the folder strukture by its self. |
| 25 | +``` |
| 26 | +. |
| 27 | +├── current -> genesis or upgrades/<name> |
| 28 | +├── genesis |
| 29 | +│ └── bin |
| 30 | +│ └── $DAEMON_NAME |
| 31 | +└── upgrades |
| 32 | +│ └── <name> |
| 33 | +│ ├── bin |
| 34 | +│ │ └── $DAEMON_NAME |
| 35 | +│ └── upgrade-info.json |
| 36 | +└── preupgrade.sh (optional) |
| 37 | +``` |
| 38 | + |
| 39 | +### Cosmovisor init |
| 40 | +Post v1 versions of Cosmovisor have a command that will create the directories and copy the `paxd` binary into the proper directory. To create the directories and copy the binary, run this command: |
| 41 | + |
| 42 | +``` |
| 43 | +cosmovisor init $HOME/go/bin/paxd |
| 44 | +``` |
| 45 | +Once you're done, check the folder structure looks correct using a tool like `tree`. |
| 46 | + |
| 47 | +### Cosmovisor config |
| 48 | + |
| 49 | +In the .profile file, usually located at ~/.profile, add: |
| 50 | + |
| 51 | +``` |
| 52 | +export DAEMON_NAME=paxd |
| 53 | +export DAEMON_HOME=$HOME/.pax |
| 54 | +``` |
| 55 | +Then source your profile to have access to these variables: |
| 56 | + |
| 57 | +``` |
| 58 | +source ~/.profile |
| 59 | +``` |
| 60 | +You can confirm success like so: |
| 61 | + |
| 62 | +``` |
| 63 | +echo $DAEMON_NAME |
| 64 | +``` |
| 65 | +It should return paxd. |
| 66 | + |
| 67 | +`cosmovisor` reads its configuration from environment variables: |
| 68 | + |
| 69 | +- `DAEMON_HOME` is the location where the `cosmovisor/` directory is kept that contains the genesis binary, the upgrade binaries, and any additional auxiliary files associated with each binary (e.g. `$HOME/.pax`, `$HOME/.unigrid`, etc.). |
| 70 | +- `DAEMON_NAME` is the name of the binary itself (e.g. `paxd`, etc.). |
| 71 | +- `DAEMON_ALLOW_DOWNLOAD_BINARIES` (_optional_), if set to `true`, will enable auto-downloading of new binaries (for security reasons, this is intended for full nodes rather than validators). By default, `cosmovisor` will not auto-download new binaries. |
| 72 | +- `DAEMON_DOWNLOAD_MUST_HAVE_CHECKSUM` (_optional_, default = `false`), if `true` cosmovisor will require that a checksum is provided in the upgrade plan for the binary to be downloaded. If `false`, cosmovisor will not require a checksum to be provided, but still check the checksum if one is provided. |
| 73 | +- `DAEMON_RESTART_AFTER_UPGRADE` (_optional_, default = `true`), if `true`, restarts the subprocess with the same command-line arguments and flags (but with the new binary) after a successful upgrade. Otherwise (`false`), `cosmovisor` stops running after an upgrade and requires the system administrator to manually restart it. Note restart is only after the upgrade and does not auto-restart the subprocess after an error occurs. |
| 74 | +- `DAEMON_RESTART_DELAY` (_optional_, default none), allow a node operator to define a delay between the node halt (for upgrade) and backup by the specified time. The value must be a duration (e.g. `1s`). |
| 75 | +- `DAEMON_SHUTDOWN_GRACE` (_optional_, default none), if set, send interrupt to binary and wait the specified time to allow for cleanup/cache flush to disk before sending the kill signal. The value must be a duration (e.g. `1s`). |
| 76 | +- `DAEMON_POLL_INTERVAL` (_optional_, default 300 milliseconds), is the interval length for polling the upgrade plan file. The value must be a duration (e.g. `1s`). |
| 77 | +- `DAEMON_DATA_BACKUP_DIR` option to set a custom backup directory. If not set, `DAEMON_HOME` is used. |
| 78 | +- `UNSAFE_SKIP_BACKUP` (defaults to `false`), if set to `true`, upgrades directly without performing a backup. Otherwise (`false`, default) backs up the data before trying the upgrade. The default value of false is useful and recommended in case of failures and when a backup needed to rollback. We recommend using the default backup option `UNSAFE_SKIP_BACKUP=false`. |
| 79 | +- `DAEMON_PREUPGRADE_MAX_RETRIES` (defaults to `0`). The maximum number of times to call [pre-upgrade](https://docs.cosmos.network/main/build/building-apps/app-upgrade#pre-upgrade-handling) in the application after exit status of `31`. After the maximum number of retries, Cosmovisor fails the upgrade. |
| 80 | +- `COSMOVISOR_DISABLE_LOGS` (defaults to `false`). If set to true, this will disable Cosmovisor logs (but not the underlying process) completely. This may be useful, for example, when a Cosmovisor subcommand you are executing returns a valid JSON you are then parsing, as logs added by Cosmovisor make this output not a valid JSON. |
| 81 | +- `COSMOVISOR_COLOR_LOGS` (defaults to `true`). If set to true, this will colorise Cosmovisor logs (but not the underlying process). |
| 82 | +- `COSMOVISOR_TIMEFORMAT_LOGS` (defaults to `kitchen`). If set to a value (`layout|ansic|unixdate|rubydate|rfc822|rfc822z|rfc850|rfc1123|rfc1123z|rfc3339|rfc3339nano|kitchen`), this will add timestamp prefix to Cosmovisor logs (but not the underlying process). |
| 83 | +- `COSMOVISOR_CUSTOM_PREUPGRADE` (defaults to ``). If set, this will run $DAEMON_HOME/cosmovisor/$COSMOVISOR_CUSTOM_PREUPGRADE prior to upgrade with the arguments [ upgrade.Name, upgrade.Height ]. Executes a custom script (separate and prior to the chain daemon pre-upgrade command) |
| 84 | +- `COSMOVISOR_DISABLE_RECASE` (defaults to `false`). If set to true, the upgrade directory will expected to match the upgrade plan name without any case changes |
| 85 | + |
| 86 | +## Set up service |
| 87 | +Commands sent to Cosmovisor are sent to the underlying binary. For example, `cosmovisor` version is the same as typing `paxd version`. |
| 88 | + |
| 89 | +Nevertheless, just as we would manage `paxd` using a process manager, we would like to make sure Cosmovisor is automatically restarted if something happens, for example an error or reboot. |
| 90 | + |
| 91 | +First, create the service file: |
| 92 | + |
| 93 | +``` |
| 94 | +sudo nano /etc/systemd/system/paxd.service |
| 95 | +```` |
| 96 | +Change the contents of the below to match your setup - `cosmovisor` is likely at `~/go/bin/cosmovisor` regardless of which installation path you took above, but it's worth checking. |
| 97 | +
|
| 98 | +Note `cosmovisor run start` is only for the latest versions of cosmovisor. For earlier versions that line should be: |
| 99 | +
|
| 100 | +``` |
| 101 | +ExecStart=/home/<your-user>/go/bin/cosmovisor start |
| 102 | +```` |
| 103 | +``` |
| 104 | +[Unit] |
| 105 | +Description=Pax Daemon (cosmovisor) |
| 106 | +After=network-online.target |
| 107 | +
|
| 108 | +[Service] |
| 109 | +User=<your-user> |
| 110 | +ExecStart=/home/<your-user>/go/bin/cosmovisor run start |
| 111 | +Restart=always |
| 112 | +RestartSec=3 |
| 113 | +Environment="DAEMON_NAME=paxd" |
| 114 | +Environment="DAEMON_HOME=/home/<your-user>/.pax" |
| 115 | +Environment="DAEMON_ALLOW_DOWNLOAD_BINARIES=false" |
| 116 | +Environment="DAEMON_RESTART_AFTER_UPGRADE=true" |
| 117 | +Environment="DAEMON_LOG_BUFFER_SIZE=512" |
| 118 | +
|
| 119 | +[Install] |
| 120 | +WantedBy=multi-user.target |
| 121 | +``` |
| 122 | +> A description of what the environment variables do can be found here. Change them depending on your setup. |
| 123 | +
|
| 124 | +
|
| 125 | +In addition, the same issue can be fixed by reducing the log via env variable. If you are unsure, ask on Discord. |
| 126 | +
|
| 127 | +## Modules |
| 128 | +
|
| 129 | +When doing an upgrade to a module do the following |
| 130 | +
|
| 131 | +### Create a new UpgradeHandler |
| 132 | +
|
| 133 | +When upgrading paxd you need to add a UpgradeHandler that handels state changes and initates new params. |
| 134 | +
|
| 135 | +Make a new folder under upgrades named the new version number. |
| 136 | +
|
| 137 | + |
| 138 | +
|
| 139 | +### Propose an upgrade |
| 140 | +
|
| 141 | +A upgrade is proposed and voted on. If the vote is passed it will trigger |
0 commit comments