diff --git a/book/src/validator-manager-move.md b/book/src/validator-manager-move.md new file mode 100644 index 0000000000..41a7dc2ab1 --- /dev/null +++ b/book/src/validator-manager-move.md @@ -0,0 +1,95 @@ +# 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 some experience with the Linux command line. + +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. + +### 1. Configure the Source VC + +The source VC needs to have the following flags: + +- `--http` +- `--unencrypted-http-transport` +- `--http-address 127.0.0.1` +- `--http-port 5062` +- `--http-allow-keystore-export` + +Therefore, the source VC command might look like: + +```bash +lighthouse \ + vc \ + --http \ + --unencrypted-http-transport \ + --http-address 127.0.0.1 \ + --http-port 5062 \ + --http-allow-keystore-export +``` + +### 2. Configure the Destination VC + +The destination VC needs to have the same flags as the source VC. + +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 + +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 + +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 +source host on its file-system. + +On the **source host**, find the location of the `api-token.txt` file and copy the contents. The +location of the file varies, but it is located in the "validator directory" of your data directory, +alongside validator keystores. For example: `~/.lighthouse/mainnet/validators/api-token.txt`. + +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 +between the **desination host** and the **source host**. + +```bash +ssh dest-host +ssh -L 6062:localhost:5062 src-host +``` + +It's important that you leave this session open throughout the rest of this tutorial. If you close +this terminal window then the connection between the destination and source host will be lost. + +---- + +### N. Setup a `screen` Session + +We will use the GNU `screen` application to run multiple, persistent sessions on the destination +host. If you don't like screen feel free to use an equivalent (e.g., `tmux`). + +On the **destination host** run: + +``` +screen +# press "enter" when prompted +``` + +Create a new screen by pressing `Ctrl+A` then `c`. Switch back to the previous screen (`0`) by +pressing `Ctrl+A` and then `"` (use the up/down arrows and enter to select a screen). diff --git a/book/src/validator-manager.md b/book/src/validator-manager.md new file mode 100644 index 0000000000..0b12beffde --- /dev/null +++ b/book/src/validator-manager.md @@ -0,0 +1,40 @@ +# Validator Manager + +[Ethereum Launchpad]: https://launchpad.ethereum.org/en/ +[Import Validators]: #import-validators + +## Introduction + +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 is generally superior to the account manager for the following +(non-exhaustive) reasons: + +- The validator manager generates deposit files compatible with the [Ethereum Launchpad](). +- Changes made with the validator manager do not require downtime for the VC. +- 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. + +## Commands + +### Create Validators + +The `lighthouse validator-manager validators create` command accepts a mnemonic and produces a JSON +file containing validator keystores that can be imported with the [Import +Validators]() command. + +For users that want to add validators to a VC from an existing mnemonic, this is the first half the +process which generates a *validator specifications* JSON file for the new validators. The second +half of the process is to upload those validator specifications to a VC (see [Import Validators](). +The command is split into two steps so that security-conscious validators can generate the validator +specifications on an "air-gapped" computer which is not connected to the Internet. Then, the +validator specifications file can be transferred to a VC for import. This means that the VC never +has access to the mnemonic, just the keystores with which it is concerned. + +### Import Validators