|
|
@@ -0,0 +1,213 @@
|
|
|
+## Cluster Software Installation and Updates
|
|
|
+Currently users are required to build the solana cluster software themselves
|
|
|
+from the git repository and manually update it, which is error prone and
|
|
|
+inconvenient.
|
|
|
+
|
|
|
+This document proposes an easy to use software install and updater that can be
|
|
|
+used to deploy pre-built binaries for supported platforms. Users may elect to
|
|
|
+use binaries supplied by Solana or any other party they trust. Deployment of
|
|
|
+updates is managed using an on-chain update manifest program.
|
|
|
+
|
|
|
+### Motivating Examples
|
|
|
+#### Fetch and run a pre-built installer
|
|
|
+
|
|
|
+With a well-known release URL, a pre-built binary can be obtained for supported
|
|
|
+platforms:
|
|
|
+
|
|
|
+```bash
|
|
|
+$ curl -o solana-install https://github.com/solana-labs/solana/releases/download/v1.2.3/solana-install-x86_64-apple-darwin
|
|
|
+$ chmod +x ./solana-install
|
|
|
+$ ./solana-install --help
|
|
|
+```
|
|
|
+
|
|
|
+Note: future enhancements should include building wrapper in the style of
|
|
|
+https://rustup.rs/ to make bootstrapping an install even easier.
|
|
|
+
|
|
|
+#### Build and run the installer from source
|
|
|
+
|
|
|
+If a pre-built binary is not available for a given platform, building the
|
|
|
+installer from source is always an option:
|
|
|
+```bash
|
|
|
+$ git clone https://github.com/solana-labs/solana.git
|
|
|
+$ cd solana/install
|
|
|
+$ cargo run -- --help
|
|
|
+```
|
|
|
+
|
|
|
+#### Deploy a new update to a cluster
|
|
|
+Given a solana release tarball (as created by `ci/publish-tarball.sh`) that has already been uploaded to a publicly accessible URL,
|
|
|
+the following commands will deploy the update:
|
|
|
+```bash
|
|
|
+$ solana-keygen -o update-manifest.json # <-- only generated once, the public key is shared with users
|
|
|
+$ solana-install deploy http://example.com/path/to/solana-release.tar.bz2 update-manifest.json
|
|
|
+```
|
|
|
+
|
|
|
+Note: Supporting IPFS download URLs in the future would be attractive.
|
|
|
+
|
|
|
+#### Run a validator node that auto updates itself
|
|
|
+
|
|
|
+```bash
|
|
|
+$ solana-install init --pubkey 92DMonmBYXwEMHJ99c9ceRSpAmk9v6i3RdvDdXaVcrfj # <-- pubkey is obtained from whoever is deploying the updates
|
|
|
+$ export PATH=~/.local/share/solana-install/bin:$PATH
|
|
|
+$ solana-keygen ... # <-- runs the latest solana-keygen
|
|
|
+$ solana-install run solana-fullnode ... # <-- runs a fullnode, restarting it as necesary when an update is applied
|
|
|
+```
|
|
|
+
|
|
|
+### Update Manifest on-chain program
|
|
|
+The Update Manifest program is used to advertise the deployment of new release tarballs
|
|
|
+on a solana cluster. Each instance of this program describes a logical update
|
|
|
+channel for a given target triple (eg, `x86_64-apple-darwin`). The public key
|
|
|
+of each program instance is well-known between the entity deploying new updates
|
|
|
+and users consuming those updates.
|
|
|
+
|
|
|
+The update tarball itself is hosted elsewhere, off-chain and can be fetched from
|
|
|
+the specified `download_url`.
|
|
|
+
|
|
|
+```rust,ignore
|
|
|
+use solana_sdk::signature::Signature;
|
|
|
+
|
|
|
+/// Information required to download and apply a given update
|
|
|
+pub struct UpdateManifest {
|
|
|
+ pub target: String, // Target triple (TARGET)
|
|
|
+ pub commit: String, // git sha1 of this update, must match the commit sha1 in the release tar.bz2
|
|
|
+ pub timestamp_secs: u64, // When the release was deployed (seconds since UNIX EPOC)
|
|
|
+ pub download_url: String, // Download URL to the release tar.bz2
|
|
|
+ pub download_signature: Signature, // Signature of the release tar.bz2 file, verify with the Account public key
|
|
|
+}
|
|
|
+
|
|
|
+/// Userdata of an Update Manifest program Account.
|
|
|
+pub struct SignedUpdateManifest {
|
|
|
+ pub manifest: UpdateManifest,
|
|
|
+ pub manifest_signature: Signature, // Signature of UpdateInfo, verify with the Account public key
|
|
|
+}
|
|
|
+```
|
|
|
+
|
|
|
+Note that the `manifest` field itself contains a corresponding signature
|
|
|
+(`manifest_signature`) to guard against man-in-the-middle attacks between the
|
|
|
+`solana-install` tool and the solana cluster RPC API.
|
|
|
+
|
|
|
+To guard against rollback attacks, `solana-install` will refuse to install an
|
|
|
+update with an older `timestamp_secs` than what is currently installed.
|
|
|
+
|
|
|
+### solana-install Tool
|
|
|
+
|
|
|
+The `solana-install` tool is used by the user to install and update their cluster software.
|
|
|
+
|
|
|
+It manages the following files and directories in the user's home directory:
|
|
|
+* `~/.config/solana/updater.json` - user configuration and information about currently installed software version
|
|
|
+* `~/.local/share/solana-install/bin` - a symlink to the current release. eg, `~/.local/share/solana-update/<update-pubkey>-<manifest_signature>/bin`
|
|
|
+* `~/.local/share/solana-install/<update-pubkey>-<manifest_signature>/` - contents of the release
|
|
|
+* `~/.local/share/solana-install/<update-pubkey>-<manifest_signature>.tmp/` - temporary directory used while downloading a new release
|
|
|
+
|
|
|
+#### Command-line Interface
|
|
|
+```bash
|
|
|
+$ solana-install --help
|
|
|
+solana-install 0.13.0
|
|
|
+The solana cluster software installer
|
|
|
+
|
|
|
+USAGE:
|
|
|
+ solana-install [SUBCOMMAND]
|
|
|
+
|
|
|
+FLAGS:
|
|
|
+ -h, --help Prints help information
|
|
|
+
|
|
|
+SUBCOMMANDS:
|
|
|
+ deploy deploys a new update
|
|
|
+ help Prints this message or the help of the given subcommand(s)
|
|
|
+ info displays information about the current installation
|
|
|
+ init initializes a new installation
|
|
|
+ run Runs a program while periodically checking and applying software updates. The program will be
|
|
|
+ restarted upon a successful software update
|
|
|
+ update checks for an update, and if available downloads and applies it
|
|
|
+```
|
|
|
+
|
|
|
+##### init
|
|
|
+```bash
|
|
|
+$ solana-install init --help
|
|
|
+solana-install-init
|
|
|
+initializes a new installation
|
|
|
+
|
|
|
+USAGE:
|
|
|
+ solana-install init [OPTIONS]
|
|
|
+
|
|
|
+FLAGS:
|
|
|
+ -h, --help Prints help information
|
|
|
+
|
|
|
+OPTIONS:
|
|
|
+ -u, --url <URL> JSON RPC URL for the solana cluster [default: https://api.testnet.solana.com/]
|
|
|
+ -p, --pubkey <PUBKEY> Public key of the update manifest [default: Solana-managed update manifest]
|
|
|
+```
|
|
|
+
|
|
|
+##### info
|
|
|
+```bash
|
|
|
+$ solana-install info --help
|
|
|
+solana-install-info
|
|
|
+displays information about the current installation
|
|
|
+
|
|
|
+USAGE:
|
|
|
+ solana-install info [FLAGS]
|
|
|
+
|
|
|
+FLAGS:
|
|
|
+ -h, --help Prints help information
|
|
|
+ -l only display local information, don't check the cluster for new updates
|
|
|
+```
|
|
|
+
|
|
|
+##### deploy
|
|
|
+```bash
|
|
|
+$ solana-install deploy --help
|
|
|
+solana-install-deploy
|
|
|
+deploys a new update
|
|
|
+
|
|
|
+USAGE:
|
|
|
+ solana-install deploy <URL> <PATH>
|
|
|
+
|
|
|
+FLAGS:
|
|
|
+ -h, --help Prints help information
|
|
|
+
|
|
|
+ARGS:
|
|
|
+ <URL> URL to the solana release archive
|
|
|
+ <PATH> Keypair file for the update manifest (/path/to/keypair.json)
|
|
|
+```
|
|
|
+
|
|
|
+##### update
|
|
|
+```bash
|
|
|
+$ solana-install update --help
|
|
|
+solana-install-update
|
|
|
+checks for an update, and if available downloads and applies it
|
|
|
+
|
|
|
+USAGE:
|
|
|
+ solana-install update
|
|
|
+
|
|
|
+FLAGS:
|
|
|
+ -h, --help Prints help information
|
|
|
+```
|
|
|
+
|
|
|
+##### run
|
|
|
+```bash
|
|
|
+$ solana-install run --help
|
|
|
+solana-install-run
|
|
|
+Runs a program while periodically checking and applying software updates. The program will be restarted upon a
|
|
|
+successful software update
|
|
|
+
|
|
|
+USAGE:
|
|
|
+ solana-install run <program_name> [program_arguments]...
|
|
|
+
|
|
|
+FLAGS:
|
|
|
+ -h, --help Prints help information
|
|
|
+
|
|
|
+ARGS:
|
|
|
+ <program_name> program to run
|
|
|
+ <program_arguments>... arguments to supply to the program
|
|
|
+```
|
|
|
+
|
|
|
+### Release Archive Contents
|
|
|
+A release archive is expected to be a tar file compressed with
|
|
|
+bzip2 with the following internal structure:
|
|
|
+
|
|
|
+* `/version.yml` - a simple YAML file containing the fields (1) `"commit"` - the git
|
|
|
+ sha1 for this release, and (2) `"target"` - the target tuple. Any additional
|
|
|
+ fields are ignored.
|
|
|
+* `/bin/` -- directory containing available programs in the release.
|
|
|
+ `solana-install` will symlink this directory to
|
|
|
+ `~/.local/share/solana-install/bin` for use by the `PATH` environment
|
|
|
+ variable.
|
|
|
+* `...` -- any additional files and directories are permitted
|
Michael Vines