diff --git a/book/src/validator-manager-move.md b/book/src/validator-manager-move.md index 67cd4b44aa1..2abe4cf1ed8 100644 --- a/book/src/validator-manager-move.md +++ b/book/src/validator-manager-move.md @@ -1,7 +1,47 @@ # Moving Validators -This document describes the steps to move validators between two validator clients (VCs) which are -able to SSH between each other. This guides assumes experience with the Linux command line and SSH +The `lighthouse validator-manager move` command uses the VC HTTP API to move +validators from one VC (the "src" VC) to another VC (the "dest" VC). The move +operation is *comprehensive*; it will: + +- Disable the validators the src VC. +- Remove the validator keystores from the src VC file system. +- Export the slashing database records for the appropriate validators from the src VC to the dest VC. +- 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. + +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). + +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 +dest VC. Therefore, it is recommended to **never use the `move` command without +having a backup of all validator keystores (e.g., the mnemonic).** + +## Simple Example + +``` +lighthouse \ + validator-manager \ + move \ + --src-vc-url http://localhost:6062 \ + --src-vc-token ~/src-token.txt \ + --dest-vc-url http://localhost:5062 \ + --dest-vc-token ~/.lighthouse/mainnet/validators/api-token.txt \ + --validators all \ +``` + +## Guide + +This guide describes the steps to move validators between two validator clients (VCs) which are +able to SSH between each other. This guide assumes experience with the Linux command line and SSH connections. There will be two VCs in this example: @@ -9,8 +49,11 @@ 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. -This 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. +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. + +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`. ### 1. Configure the Source VC @@ -38,6 +81,14 @@ lighthouse \ The destination VC needs to have the following flags: +- `--http` +- `--unencrypted-http-transport` +- `--http-address 127.0.0.1` +- `--http-port 5062` +- `--enable-doppelganger-protection` + +Therefore, the destination VC command might look like: + ```bash lighthouse \ vc \ @@ -45,8 +96,14 @@ lighthouse \ --unencrypted-http-transport \ --http-address 127.0.0.1 \ --http-port 5062 \ + --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. @@ -73,7 +130,6 @@ alongside validator keystores. For example: `~/.lighthouse/mainnet/validators/ap Copy the contents of that file into a new file on the **destination host** at `~/src-token.txt`. The API token should be similar to `api-token-0x03eace4c98e8f77477bb99efb74f9af10d800bd3318f92c33b719a4644254d4123`. - ### 4. Create an SSH Tunnel In one terminal window, SSH to the **destination host** and establish a reverse-SSH connection @@ -103,4 +159,14 @@ lighthouse \ --validators all \ ``` -TODO +The command will provide information about the progress of the operation and +emit `Done.` when the operation has completed successfully. + +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`. +If the `--enable-doppelganger-protection` flag was used it may take 3-4 epochs +for the validators to start attesting and producing blocks on the `dest-host`. + +Any errors encounted during the operation should include information on how to +proceed. Assistance is also available on our +[Discord](https://discord.gg/cyAszAh). \ No newline at end of file