diff --git a/book/src/validator-manager-create.md b/book/src/validator-manager-create.md index 0cb85b90f3f..0bdb078b248 100644 --- a/book/src/validator-manager-create.md +++ b/book/src/validator-manager-create.md @@ -6,7 +6,7 @@ The `lighthouse validator-manager create` command derives validators from a mnemonic and produces two files: - `validators.json`: the keystores and passwords for the newly generated - validators in JSON format. + validators, in JSON format. - `deposits.json`: a JSON file of the same format as [staking-deposit-cli](https://github.com/ethereum/staking-deposit-cli) which can be used for deposit submission via the [Ethereum Staking @@ -29,9 +29,9 @@ an internet-connected host. The `create` and `import` commands are recommended for advanced users who are familiar with command line tools and the practicalities of managing sensitive -key information. **We recommend that novice users follow the workflow on -[Ethereum Staking Launchpad][] rather than using the `move` and `create` -tools.** +cryptographic material. **We recommend that novice users follow the workflow on +[Ethereum Staking Launchpad][] rather than using the `create` and `import` +commands.** ## Simple Example @@ -48,11 +48,11 @@ lighthouse \ --output-path ./ ``` -The `--suggested-fee-recipient` flag may be omitted to use whatever default -value the VC uses. It does not necessarily need to be idential to -`--eth1-withdrawal-address`. +> The `--suggested-fee-recipient` flag may be omitted to use whatever default +> value the VC uses. It does not necessarily need to be idential to +> `--eth1-withdrawal-address`. -Import the validators to a running VC with: +Then, import the validators to a running VC with: ```bash lighthouse \ @@ -62,8 +62,8 @@ lighthouse \ --vc-token ``` -Be sure to remove `./validators.json` after the import is successful since it -contains unencrypted validator keystores. +> Be sure to remove `./validators.json` after the import is successful since it +> contains unencrypted validator keystores. ## Detailed Guide @@ -78,7 +78,7 @@ host. This would help protect the mnemonic from being exposed to the Internet. Run the `create` command, subsituting `
` for an execution address that you control. This is where all the staked ETH and rewards will ultimately reside, so it's very important that this address is secure, acessible and -backed-up. +backed-up. The `create` command: ```bash lighthouse \ @@ -114,7 +114,7 @@ slashing! The command will create two files: -- `./deposits.json`: this file does not contain sensitive information and may be uploaded to the [Ethereum Staking Launchpad]. +- `./deposits.json`: this file does *not* contain sensitive information and may be uploaded to the [Ethereum Staking Launchpad]. - `./validators.json`: this file contains **sensitive unencrypted validator keys, do not share it with anyone or upload it to any website**. ### 2. Import the validators @@ -172,4 +172,4 @@ shared with anyone. The validators will now go through 3-4 epochs of [doppelganger protection](./validator-doppelganger.md) and will automatically start performing -their duties when they are deposited and activated. \ No newline at end of file +their duties when they are deposited and activated. The guide is complete. \ No newline at end of file diff --git a/book/src/validator-manager-move.md b/book/src/validator-manager-move.md index b3ce6298201..7c1f5728e4f 100644 --- a/book/src/validator-manager-move.md +++ b/book/src/validator-manager-move.md @@ -10,27 +10,26 @@ operation is *comprehensive*; it will: - Enable the validators on the dest VC. - Generally result in very little or no validator downtime. -It is capable of moving all validators on the src VC, a number of validators or -specific validators from one VC to another. +It is capable of moving all validators on the src VC, a count of validators or +a list of pubkeys. The `move` command is only guaranteed to work between two Lighthouse VCs (i.e., -there is no guarantee that the commands will work between Lighthouse and Teku or -another client). +there is no guarantee that the commands will work between Lighthouse and Teku, for instance). The `move` command only supports moving validators using a keystore on the local file system, it does not support `Web3Signer` validators. Although all efforts are taken to avoid it, it's possible for the `move` command -to fail in a way removes the validator from the src VC without adding it to the +to fail in a way that removes the validator from the src VC without adding it to the dest VC. Therefore, it is recommended to **never use the `move` command without -having a backup of all validator keystores (e.g., the mnemonic).** +having a backup of all validator keystores (e.g. the mnemonic).** ## Simple Example The following command will move all validators from the VC running at `http://localhost:6062` to the VC running at `http://localhost:5062`. -``` +```bash lighthouse \ validator-manager \ move \ @@ -38,7 +37,7 @@ lighthouse \ --src-vc-token ~/src-token.txt \ --dest-vc-url http://localhost:5062 \ --dest-vc-token ~/.lighthouse/mainnet/validators/api-token.txt \ - --validators all \ + --validators all ``` ## Detailed Guide @@ -52,11 +51,18 @@ There will be two VCs in this example: - The *source* VC which contains the validators/keystores to be moved. - The *destination* VC which is to take the validators/keystores from the source. -The example will assume the source VC is accessible at `src-host` and the destination VC is -accessible at `dest-host`. Replace these values with your own hostnames or IP addresses. +There will be two hosts in this example: + +- Host 1 (*"source host"*): Is running the `src-vc`. +- Host 2 (*"destination host"*): Is running the `dest-vc`. + +The example will assume that all commands are run on Host 1. It also assumes +that Host 1 is able to SSH to Host 2. -The example assumes that the reader is currently logged into `dest-host` via SSH -and that the reader can SSH from `dest-host` to `src-host`. +In reality, many host configurations are possible. For example: + +- Both VCs on the same host. +- Both VCs on different hosts and the `validator-manager` being used on a third host. ### 1. Configure the Source VC @@ -102,25 +108,16 @@ lighthouse \ --enable-doppelganger-protection ``` -The `--enable-doppelganger-protection` flag is not *strictly* required, however -it is recommended for an additional layer of safety. It will result in 3-4 -epochs of downtime for the validator after it is moved, which is generally an -inconsequential cost in lost rewards or penalties. - -Optionally, users can add the `--http-store-passwords-in-secrets-dir` flag if they'd like to have -the import validator keystore passwords stored in separate files rather than in the -`valdiator-definitions.yml` file. If you don't know what this means, you can safely omit the flag. - -### 3. Configure SSH +> The `--enable-doppelganger-protection` flag is not *strictly* required, however +> it is recommended for an additional layer of safety. It will result in 3-4 +> epochs of downtime for the validator after it is moved, which is generally an +> inconsequential cost in lost rewards or penalties. +> +> Optionally, users can add the `--http-store-passwords-in-secrets-dir` flag if they'd like to have +> the import validator keystore passwords stored in separate files rather than in the +> `valdiator-definitions.yml` file. If you don't know what this means, you can safely omit the flag. -For this example to work, the `dest-host` host must be able to SSH to the `src-host` host. This -configuration is out-of-scope of this article, however it probably involves adding a public key to -the `.ssh/authorized_keys` file on the `dest-host` host. - -You will know this is complete when you can SSH to the `dest-host` from your PC and then run `ssh -src-host` successfully. - -### 4. Obtain the Source API Token +### 3. Obtain the Source API Token The VC API is protected by an *API token*. This is stored in a file on each of the hosts. Since we'll be running our command on the destination host, it will need to have the API token for the @@ -151,7 +148,7 @@ this terminal window then the connection between the destination and source host With the SSH tunnel established between the `dest-host` and `src-host`, from the **destination host** run the command to move the validators: -``` +```bash lighthouse \ validator-manager \ move \ @@ -159,11 +156,20 @@ lighthouse \ --src-vc-token ~/src-token.txt \ --dest-vc-url http://localhost:5062 \ --dest-vc-token ~/.lighthouse/mainnet/validators/api-token.txt \ - --validators all \ + --validators all ``` The command will provide information about the progress of the operation and -emit `Done.` when the operation has completed successfully. +emit `Done.` when the operation has completed successfully. For example: + +```bash +Running validator manager for mainnet network +Validator client is reachable at http://localhost:5062/ and reports 2 validators +Validator client is reachable at http://localhost:6062/ and reports 0 validators +Moved keystore 1 of 2 +Moved keystore 2 of 2 +Done. +``` Once the operation completes successfully, there is nothing else to be done. The validators have been removed from the `src-host` and enabled at the `dest-host`. diff --git a/book/src/validator-manager.md b/book/src/validator-manager.md index 2c087527000..52243a31b9b 100644 --- a/book/src/validator-manager.md +++ b/book/src/validator-manager.md @@ -5,15 +5,15 @@ ## Introduction -The `lighthouse validator-manager` tool provides utilities for managing validators on a running +The `lighthouse validator-manager` tool provides utilities for managing validators on a *running* Lighthouse Validator Client. The validator manager performs operations via the HTTP API of the validator client (VC). Due to limitations of the [keymanager-APIs](https://ethereum.github.io/keymanager-APIs/), only Lighthouse VCs are fully supported by this command. -The validator manager tool is similar to the `lighthouse account-manager` tool, except the latter -creates files that will be read by the VC next time it starts rather than making instant changes to -a live VC. +The validator manager tool is similar to the `lighthouse account-manager` tool, +except the latter creates files that will be read by the VC next time it starts +whilst the former makers instant changes to a live VC. The `account-manager` is ideal for importing keys created with the [staking-deposit-cli](https://github.com/ethereum/staking-deposit-cli). On the @@ -26,10 +26,10 @@ The `validator-manager` boasts the following features: - One-line command to arbitrarily move validators between two VCs, maintaining the slashing protection database. - Generates deposit files compatible with the [Ethereum Staking Launchpad](). - Generally involves zero or very little downtime. -- The "key cache" is preserved whenever a validator is added with the validator manager, this - prevents long waits at start up when a new validator is added. +- The "key cache" is preserved whenever a validator is added with the validator + manager, preventing long waits at start up when a new validator is added. -### Validator Manager Documentation +## Guides -- [Creating and importing validators using the `create` and `import` commands](./validator-manager-create.md) -- [Moving validators between two VCs using the `move` command](./validator-manager.md) \ No newline at end of file +- [Creating and importing validators using the `create` and `import` commands.](./validator-manager-create.md) +- [Moving validators between two VCs using the `move` command.](./validator-manager-move.md) \ No newline at end of file