cosmovisor

package module
v0.0.0-...-14c45c5 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Mar 11, 2024 License: Apache-2.0 Imports: 20 Imported by: 0

README

Cosmosvisor Quick Start

cosmovisor is a small process manager for Cosmos SDK application binaries that monitors the governance module via stdout for incoming chain upgrade proposals. If it sees a proposal that gets approved, cosmovisor 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.

Note: If new versions of the application are not set up to run in-place store migrations, migrations will need to be run manually before restarting cosmovisor with the new binary. For this reason, we recommend applications adopt in-place store migrations.

Installation

To install cosmovisor, run the following command:

go get github.com/reapchain/cosmos-sdk/cosmovisor/cmd/cosmovisor

Command Line Arguments And Environment Variables

All arguments passed to cosmovisor will be passed to the application binary (as a subprocess). cosmovisor will return /dev/stdout and /dev/stderr of the subprocess as its own. For this reason, cosmovisor cannot accept any command-line arguments other than those available to the application binary, nor will it print anything to output other than what is printed by the application binary.

cosmovisor reads its configuration from environment variables:

  • 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/.gaiad, $HOME/.regend, $HOME/.simd, etc.).
  • DAEMON_NAME is the name of the binary itself (e.g. gaiad, regend, simd, etc.).
  • 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.
  • DAEMON_RESTART_AFTER_UPGRADE (optional), if set to true, will restart the subprocess with the same command-line arguments and flags (but with the new binary) after a successful upgrade. By default, cosmovisor stops running after an upgrade and requires the system administrator to manually restart it. Note that cosmovisor will not auto-restart the subprocess if there was an error.

Folder Layout

$DAEMON_HOME/cosmovisor is expected to belong completely to cosmovisor and the subprocesses that are controlled by it. The folder content is organized as follows:

.
├── current -> genesis or upgrades/<name>
├── genesis
│   └── bin
│       └── $DAEMON_NAME
└── upgrades
    └── <name>
        └── bin
            └── $DAEMON_NAME

The cosmovisor/ directory incudes a subdirectory for each version of the application (i.e. genesis or upgrades/<name>). Within each subdirectory is the application binary (i.e. bin/$DAEMON_NAME) and any additional auxiliary files associated with each binary. current is a symbolic link to the currently active directory (i.e. genesis or upgrades/<name>). The name variable in upgrades/<name> is the URI-encoded name of the upgrade as specified in the upgrade module plan.

Please note that $DAEMON_HOME/cosmovisor only stores the application binaries. The cosmovisor binary itself can be stored in any typical location (e.g. /usr/local/bin). The application will continue to store its data in the default data directory (e.g. $HOME/.gaiad) or the data directory specified with the --home flag. $DAEMON_HOME is independent of the data directory and can be set to any location. If you set $DAEMON_HOME to the same directory as the data directory, you will end up with a configuation like the following:

.gaiad
├── config
├── data
└── cosmovisor

Usage

The system administrator is responsible for:

  • installing the cosmovisor binary
  • configuring the host's init system (e.g. systemd, launchd, etc.)
  • appropriately setting the environmental variables
  • manually installing the genesis folder
  • manually installing the upgrades/<name> folders

cosmovisor will set the current link to point to genesis at first start (i.e. when no current link exists) and then handle switching binaries at the correct points in time so that the system administrator can prepare days in advance and relax at upgrade time.

In order to support downloadable binaries, a tarball for each upgrade binary will need to be packaged up and made available through a canonical URL. Additionally, a tarball that includes the genesis binary and all available upgrade binaries can be packaged up and made available so that all the necessary binaries required to sync a fullnode from start can be easily downloaded.

The DAEMON specific code and operations (e.g. tendermint config, the application db, syncing blocks, etc.) all work as expected. The application binaries' directives such as command-line flags and environment variables also work as expected.

Auto-Download

Generally, cosmovisor requires that the system administrator place all relevant binaries on disk before the upgrade happens. However, for people who don't need such control and want an easier setup (maybe they are syncing a non-validating fullnode and want to do little maintenance), there is another option.

If DAEMON_ALLOW_DOWNLOAD_BINARIES is set to true, and no local binary can be found when an upgrade is triggered, cosmovisor will attempt to download and install the binary itself. The plan stored in the upgrade module has an info field for arbitrary JSON. This info is expected to be outputed on the halt log message. There are two valid formats to specify a download in such a message:

  1. Store an os/architecture -> binary URI map in the upgrade plan info field as JSON under the "binaries" key. For example:
{
  "binaries": {
    "linux/amd64":"https://example.com/gaia.zip?checksum=sha256:aec070645fe53ee3b3763059376134f058cc337247c978add178b6ccdfb0019f"
  }
}
  1. Store a link to a file that contains all information in the above format (e.g. if you want to specify lots of binaries, changelog info, etc. without filling up the blockchain). For example:
https://example.com/testnet-1001-info.json?checksum=sha256:deaaa99fda9407c4dbe1d04bd49bab0cc3c1dd76fa392cd55a9425be074af01e

When cosmovisor is triggered to download the new binary, cosmovisor will parse the "binaries" field, download the new binary with go-getter, and unpack the new binary in the upgrades/<name> folder so that it can be run as if it was installed manually.

Note that for this mechanism to provide strong security guarantees, all URLs should include a SHA 256/512 checksum. This ensures that no false binary is run, even if someone hacks the server or hijacks the DNS. go-getter will always ensure the downloaded file matches the checksum if it is provided. go-getter will also handle unpacking archives into directories (in this case the download link should point to a zip file of all data in the bin directory).

To properly create a sha256 checksum on linux, you can use the sha256sum utility. For example:

sha256sum ./testdata/repo/zip_directory/autod.zip

The result will look something like the following: 29139e1381b8177aec909fab9a75d11381cab5adf7d3af0c05ff1c9c117743a7.

You can also use sha512sum if you would prefer to use longer hashes, or md5sum if you would prefer to use broken hashes. Whichever you choose, make sure to set the hash algorithm properly in the checksum argument to the URL.

Example: SimApp Upgrade

The following instructions provide a demonstration of cosmovisor using the simulation application (simapp) shipped with the Cosmos SDK's source code. The following commands are to be run from within the cosmos-sdk repository.

First, check out the latest v0.42 release:

git checkout v0.42.7

Compile the simd binary:

make build

Reset ~/.simapp (never do this in a production environment):

./build/simd unsafe-reset-all

Configure the simd binary for testing:

./build/simd config chain-id test
./build/simd config keyring-backend test
./build/simd config broadcast-mode block

Initialize the node and overwrite any previous genesis file (never do this in a production environment):

./build/simd init test --chain-id test --overwrite

Set the minimum gas price to 0stake in ~/.simapp/config/app.toml:

minimum-gas-prices = "0stake"

Create a new key for the validator, then add a genesis account and transaction:

./build/simd keys add validator
./build/simd add-genesis-account validator 1000000000stake --keyring-backend test
./build/simd gentx validator 1000000stake --chain-id test
./build/simd collect-gentxs

Set the required environment variables:

export DAEMON_NAME=simd
export DAEMON_HOME=$HOME/.simapp

Set the optional environment variable to trigger an automatic restart:

export DAEMON_RESTART_AFTER_UPGRADE=true

Create the folder for the genesis binary and copy the simd binary:

mkdir -p $DAEMON_HOME/cosmovisor/genesis/bin
cp ./build/simd $DAEMON_HOME/cosmovisor/genesis/bin

For the sake of this demonstration, amend voting_period in genesis.json to a reduced time of 20 seconds (20s):

cat <<< $(jq '.app_state.gov.voting_params.voting_period = "20s"' $HOME/.simapp/config/genesis.json) > $HOME/.simapp/config/genesis.json

Next, we will hardcode a modification in simapp to simulate a code change. In simapp/app.go, find the line containing the UpgradeKeeper initialization. It should look like the following:

app.UpgradeKeeper = upgradekeeper.NewKeeper(skipUpgradeHeights, keys[upgradetypes.StoreKey], appCodec, homePath)

After that line, add the following:

app.UpgradeKeeper.SetUpgradeHandler("test1", func(ctx sdk.Context, plan upgradetypes.Plan) {
	// Add some coins to a random account
	addr, err := sdk.AccAddressFromBech32("cosmos18cgkqduwuh253twzmhedesw3l7v3fm37sppt58")
	if err != nil {
		panic(err)
	}
	err = app.BankKeeper.AddCoins(ctx, addr, sdk.Coins{sdk.Coin{Denom: "stake", Amount: sdk.NewInt(345600000)}})
	if err != nil {
		panic(err)
	}
})

Now recompile the simd binary with the added upgrade handler:

make build

Create the folder for the upgrade binary and copy the simd binary:

mkdir -p $DAEMON_HOME/cosmovisor/upgrades/test1/bin
cp ./build/simd $DAEMON_HOME/cosmovisor/upgrades/test1/bin

Start cosmosvisor:

cosmovisor start

Open a new terminal window and submit an upgrade proposal along with a deposit and a vote (these commands must be run within 20 seconds of each other):

./build/simd tx gov submit-proposal software-upgrade test1 --title upgrade --description upgrade --upgrade-height 20 --from validator --yes
./build/simd tx gov deposit 1 10000000stake --from validator --yes
./build/simd tx gov vote 1 yes --from validator --yes

The upgrade will occur automatically at height 20.

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func DoUpgrade 

func DoUpgrade(cfg *Config, info *UpgradeInfo) error

DoUpgrade will be called after the log message has been parsed and the process has terminated. We can now make any changes to the underlying directory without interference and leave it in a state, so we can make a proper restart

func DownloadBinary 

func DownloadBinary(cfg *Config, info *UpgradeInfo) error

DownloadBinary will grab the binary and place it in the proper directory

func EnsureBinary 

func EnsureBinary(path string) error

EnsureBinary ensures the file exists and is executable, or returns an error

func GetDownloadURL 

func GetDownloadURL(info *UpgradeInfo) (string, error)

GetDownloadURL will check if there is an arch-dependent binary specified in Info

func LaunchProcess 

func LaunchProcess(cfg *Config, args []string, stdout, stderr io.Writer) (bool, error)

LaunchProcess runs a subprocess and returns when the subprocess exits, either when it dies, or *after* a successful upgrade.

func MarkExecutable 

func MarkExecutable(path string) error

MarkExecutable will try to set the executable bits if not already set Fails if file doesn't exist or we cannot set those bits

func OSArch 

func OSArch() string

Types

type Config 

type Config struct {
	Home                  string
	Name                  string
	AllowDownloadBinaries bool
	RestartAfterUpgrade   bool
	LogBufferSize         int
}

Config is the information passed in to control the daemon

func GetConfigFromEnv 

func GetConfigFromEnv() (*Config, error)

GetConfigFromEnv will read the environmental variables into a config and then validate it is reasonable

func (*Config) CurrentBin 

func (cfg *Config) CurrentBin() (string, error)

CurrentBin is the path to the currently selected binary (genesis if no link is set) This will resolve the symlink to the underlying directory to make it easier to debug

func (*Config) GenesisBin 

func (cfg *Config) GenesisBin() string

GenesisBin is the path to the genesis binary - must be in place to start manager

func (*Config) Root 

func (cfg *Config) Root() string

Root returns the root directory where all info lives

func (*Config) SetCurrentUpgrade 

func (cfg *Config) SetCurrentUpgrade(upgradeName string) error

SetCurrentUpgrade sets the named upgrade to be the current link, returns error if this binary doesn't exist

func (*Config) SymLinkToGenesis 

func (cfg *Config) SymLinkToGenesis() (string, error)

Symlink to genesis

func (*Config) UpgradeBin 

func (cfg *Config) UpgradeBin(upgradeName string) string

UpgradeBin is the path to the binary for the named upgrade

func (*Config) UpgradeDir 

func (cfg *Config) UpgradeDir(upgradeName string) string

UpgradeDir is the directory named upgrade

type UpgradeConfig 

type UpgradeConfig struct {
	Binaries map[string]string `json:"binaries"`
}

UpgradeConfig is expected format for the info field to allow auto-download

type UpgradeInfo 

type UpgradeInfo struct {
	Name string
	Info string
}

UpgradeInfo is the details from the regexp

func WaitForUpdate 

func WaitForUpdate(scanner *bufio.Scanner) (*UpgradeInfo, error)

WaitForUpdate will listen to the scanner until a line matches upgradeRegexp. It returns (info, nil) on a matching line It returns (nil, err) if the input stream errored It returns (nil, nil) if the input closed without ever matching the regexp

func WaitForUpgradeOrExit 

func WaitForUpgradeOrExit(cmd *exec.Cmd, scanOut, scanErr *bufio.Scanner) (*UpgradeInfo, error)

WaitForUpgradeOrExit listens to both output streams of the process, as well as the process state itself When it returns, the process is finished and all streams have closed.

It returns (info, nil) if an upgrade should be initiated (and we killed the process) It returns (nil, err) if the process died by itself, or there was an issue reading the pipes It returns (nil, nil) if the process exited normally without triggering an upgrade. This is very unlikely to happened with "start" but may happened with short-lived commands like `gaiad export ...`

type WaitResult 

type WaitResult struct {
	// contains filtered or unexported fields
}

WaitResult is used to wrap feedback on cmd state with some mutex logic. This is needed as multiple go-routines can affect this - two read pipes that can trigger upgrade As well as the command, which can fail

func (*WaitResult) AsResult 

func (u *WaitResult) AsResult() (*UpgradeInfo, error)

AsResult reads the data protected by mutex to avoid race conditions

func (*WaitResult) SetError 

func (u *WaitResult) SetError(myErr error)

SetError will set with the first error using a mutex don't set it once info is set, that means we chose to kill the process

func (*WaitResult) SetUpgrade 

func (u *WaitResult) SetUpgrade(up *UpgradeInfo)

SetUpgrade sets first non-nil upgrade info, ensure error is then nil pass in a command to shutdown on successful upgrade

Source Files

View all Source files

Directories

Path Synopsis
cmd
cosmovisor

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.