Start adding docs

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).

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