From f431a454b018c6f436969a96406fb7604765d326 Mon Sep 17 00:00:00 2001 From: ermyas Date: Thu, 11 Nov 2021 09:30:53 +1100 Subject: [PATCH] Update CLI reference documentation (#303) * Add missing category in metrics-categories cli option * Fix wrong default for validators-external-signer-timeout * Add alias for data-path in import and export commands * Fix wrong default for log-include-validator-duties-enabled option * Fix wrong default for metrics-interface option * Add default value for log-file-name-pattern option * Add data-validator-path option to slashing-protection commands * Add validators-early-attestations-enabled option to vc command * Add external signer keystore options to vc command * Add external signer keystore options to voluntary-exit command * Add validators-graffiti-file option to vc command * Add external signer trust store options to vc command * Add external signer truststore options to voluntary-exit command * Fix linter errors * Apply suggestions from code review * update syntax and address reviewer comments Co-authored-by: Alexandra Tran <12214231+alexandratran@users.noreply.github.com> Co-authored-by: Alexandra Tran --- docs/Reference/CLI/CLI-Syntax.md | 7 +- .../CLI/Subcommands/Migrate-Database.md | 22 +- .../CLI/Subcommands/Slashing-Protection.md | 94 +++++++-- .../CLI/Subcommands/Validator-Client.md | 198 +++++++++++++++++- .../CLI/Subcommands/Voluntary-Exit.md | 118 ++++++++++- 5 files changed, 405 insertions(+), 34 deletions(-) diff --git a/docs/Reference/CLI/CLI-Syntax.md b/docs/Reference/CLI/CLI-Syntax.md index cfb47061d..ec3b95e83 100644 --- a/docs/Reference/CLI/CLI-Syntax.md +++ b/docs/Reference/CLI/CLI-Syntax.md @@ -575,7 +575,7 @@ The default Docker image location is `/root/.local/share/teku/logs`. log-file-name-pattern: "tekuL_%d{yyyy-MM-dd}.log" ``` -Filename pattern to apply when creating log files. +Filename pattern to apply when creating log files. The default pattern is `teku_%d{yyyy-MM-dd}.log` ### log-include-events-enabled @@ -726,8 +726,7 @@ default, Teku accepts access from `localhost` and `127.0.0.1`. metrics-categories: ["BEACON", "JVM", "PROCESS"] ``` -Categories for which to track metrics. Options are `JVM`, `PROCESS`, `BEACON`, `EVENTBUS`, -`EXECUTOR`, `LIBP2P`, `NETWORK`, `STORAGE`, `STORAGE_HOT_DB`, `STORAGE_FINALIZED_DB`, +Categories for which to track metrics. Options are `JVM`, `PROCESS`, `BEACON`, `DISCOVERY`, `EVENTBUS`, `EXECUTOR`, `LIBP2P`, `NETWORK`, `STORAGE`, `STORAGE_HOT_DB`, `STORAGE_FINALIZED_DB`, `REMOTE_VALIDATOR`, `VALIDATOR`, `VALIDATOR_PERFORMANCE`. All categories are enabled by default. ### metrics-interface @@ -1752,7 +1751,7 @@ using Teku to sign blocks and attestations always uses its built-in slashing pro validators-external-signer-timeout: 2000 ``` -Timeout in milliseconds for requests to the external signer. The default is 1000. +Timeout in milliseconds for requests to the external signer. The default is 5000. ### validators-external-signer-truststore diff --git a/docs/Reference/CLI/Subcommands/Migrate-Database.md b/docs/Reference/CLI/Subcommands/Migrate-Database.md index cead3c6e6..3f60afc35 100644 --- a/docs/Reference/CLI/Subcommands/Migrate-Database.md +++ b/docs/Reference/CLI/Subcommands/Migrate-Database.md @@ -19,13 +19,13 @@ title: Database migration subcommand options --config-file= ``` -=== "Command Line" +=== "Example" ```bash --config-file=/home/me/me_node/config.yaml ``` -=== "Environment Variable" +=== "Environment variable" ```bash TEKU_CONFIG_FILE=/home/me/me_node/config.yaml @@ -42,19 +42,19 @@ The default is `none`. --data-base-path= ``` -=== "Command Line" +=== "Example" ```bash --data-base-path=/home/me/me_node ``` -=== "Environment Variable" +=== "Environment variable" ```bash TEKU_DATA_BASE_PATH=/home/me/me_node ``` -=== "Configuration File" +=== "Configuration file" ```bash data-base-path: "/home/me/me_node" @@ -76,19 +76,19 @@ The default Docker image location is `/root/.local/share/teku`. --data-beacon-path= ``` -=== "Command Line" +=== "Example" ```bash --data-beacon-path=/home/me/me_node ``` -=== "Environment Variable" +=== "Environment variable" ```bash TEKU_DATA_BEACON_PATH=/home/me/me_node ``` -=== "Configuration File" +=== "Configuration file" ```bash data-beacon-path: "/home/me/me_node" @@ -105,19 +105,19 @@ is specified using [`--data-base-path`](#data-base-path-data-path). --network= ``` -=== "Command Line" +=== "Example" ```bash --network=mainnet ``` -=== "Environment Variable" +=== "Environment variable" ```bash TEKU_NETWORK=mainnet ``` -=== "Configuration File" +=== "Configuration file" ```bash network: "mainnet" diff --git a/docs/Reference/CLI/Subcommands/Slashing-Protection.md b/docs/Reference/CLI/Subcommands/Slashing-Protection.md index 368737580..881d4c68d 100644 --- a/docs/Reference/CLI/Subcommands/Slashing-Protection.md +++ b/docs/Reference/CLI/Subcommands/Slashing-Protection.md @@ -60,6 +60,39 @@ Path to the Teku data directory. The default directory is OS-dependent: * Unix/Linux: `$XDG_DATA_HOME/teku` if `$XDG_DATA_HOME` is set; otherwise `~/.local/share/teku` * Windows: `%localappdata%\teku`. +### data-validator-path + +=== "Syntax" + + ```bash + teku slashing-protection import --data-validator-path= + ``` + +=== "Example" + + ```bash + teku slashing-protection import --data-validator-path=/home/me/me_validator + ``` + +=== "Environment variable" + + ```bash + TEKU_DATA_VALIDATOR_PATH=/home/me/me_validator + ``` + +=== "Configuration file" + + ```bash + data-validator-path: "/home/me/me_validator" + ``` + +Path to the validator client data. +The default is `/validator` where `` is specified using [`--data-path`](#data-path). + +!!! info + + Teku imports slashing protection data into a `slashprotection` directory under the validator client data directory. + ### from === "Syntax" @@ -128,6 +161,39 @@ Path to the Teku data directory. The default directory is OS-dependent: * Unix/Linux: `$XDG_DATA_HOME/teku` if `$XDG_DATA_HOME` is set; otherwise `~/.local/share/teku` * Windows: `%localappdata%\teku`. +### data-validator-path + +=== "Syntax" + + ```bash + teku slashing-protection export --data-validator-path= + ``` + +=== "Example" + + ```bash + teku slashing-protection export --data-validator-path=/home/me/me_validator + ``` + +=== "Environment variable" + + ```bash + TEKU_DATA_VALIDATOR_PATH=/home/me/me_validator + ``` + +=== "Configuration file" + + ```bash + data-validator-path: "/home/me/me_validator" + ``` + +Path to the validator client data. +The default is `/validator` where `` is specified using [`--data-path`](#data-path). + +!!! info + + Teku exports slashing protection data from the `slashprotection` directory under the validator client data directory. + ### to === "Syntax" @@ -158,7 +224,7 @@ Repairs corrupted slashing-protection data files used by Teku. teku slashing-protection repair --checking-only-enabled[=] ``` -=== "Command Line" +=== "Example" ```bash teku slashing-protection repair --checking-only-enabled=false @@ -175,7 +241,7 @@ You can specify which files are checked using [`--config-file`](#config-file_2), teku slashing-protection repair --config-file= ``` -=== "Command Line" +=== "Example" ```bash teku slashing-protection repair --config-file=/home/me/me_node/config.yaml @@ -184,18 +250,18 @@ You can specify which files are checked using [`--config-file`](#config-file_2), Path to the YAML configuration file. The default is `none`. -### data-base-path, data-path +### data-path === "Syntax" ```bash - teku slashing-protection repair --data-base-path= + teku slashing-protection repair --data-path= ``` -=== "Command Line" +=== "Example" ```bash - teku slashing-protection repair --data-base-path=/home/me/me_node + teku slashing-protection repair --data-path=/home/me/me_node ``` Path to the Teku data directory. The default directory is OS-dependent: @@ -214,14 +280,18 @@ The default Docker image location is `/root/.local/share/teku`. teku slashing-protection repair --data-validator-path= ``` -=== "Command Line" +=== "Example" ```bash teku slashing-protection repair --data-validator-path=/home/me/me_validator ``` -Path to validator client data. The default is `/validator` where `` -is specified using [`--data-base-path`](#data-base-path-data-path). +Path to validator client data. +The default is `/validator` where `` is specified using [`--data-path`](#data-path). + +!!! info + + The slashing protection data is stored in a `slashprotection` directory under the validator client data directory. ### network @@ -231,7 +301,7 @@ is specified using [`--data-base-path`](#data-base-path-data-path). teku slashing-protection repair --network= ``` -=== "Command Line" +=== "Example" ```bash teku slashing-protection repair --network=mainnet @@ -260,7 +330,7 @@ bootnodes, and the address of the Ethereum 1.0 deposit contract. teku slashing-protection repair --slot= ``` -=== "Command Line" +=== "Example" ```bash teku slashing-protection repair --slot=1028 @@ -281,7 +351,7 @@ slot, or after when the validators stopped performing duties. teku slashing-protection repair --update-all-enabled[=] ``` -=== "Command Line" +=== "Example" ```bash teku slashing-protection repair --update-all-enabled=false diff --git a/docs/Reference/CLI/Subcommands/Validator-Client.md b/docs/Reference/CLI/Subcommands/Validator-Client.md index 7e02b7236..b015845cc 100644 --- a/docs/Reference/CLI/Subcommands/Validator-Client.md +++ b/docs/Reference/CLI/Subcommands/Validator-Client.md @@ -304,7 +304,7 @@ The default Docker image location is `/root/.local/share/teku/logs`. log-file-name-pattern: "tekuL_%d{yyyy-MM-dd}.log" ``` -Filename pattern to apply when creating log files. +Filename pattern to apply when creating log files. The default pattern is `teku_%d{yyyy-MM-dd}.log` ### log-include-events-enabled @@ -361,7 +361,7 @@ validators and attestations. The default is `true`. log-include-validator-duties-enabled: true ``` -Specify whether to log details of validator event duties. The default is `false`. +Specify whether to log details of validator event duties. The default is `true`. !!! note Logs could become noisy when running many validators. @@ -455,8 +455,7 @@ default, Teku accepts access from `localhost` and `127.0.0.1`. metrics-categories: ["BEACON", "JVM", "PROCESS"] ``` -Categories for which to track metrics. Options are `JVM`, `PROCESS`, `BEACON`, `EVENTBUS`, -`EXECUTOR`, `LIBP2P`, `NETWORK`, `STORAGE`, `STORAGE_HOT_DB`, `STORAGE_FINALIZED_DB`, +Categories for which to track metrics. Options are `JVM`, `PROCESS`, `BEACON`, `DISCOVERY`, `EVENTBUS`, `EXECUTOR`, `LIBP2P`, `NETWORK`, `STORAGE`, `STORAGE_HOT_DB`, `STORAGE_FINALIZED_DB`, `REMOTE_VALIDATOR`, `VALIDATOR`, `VALIDATOR_PERFORMANCE`. All categories are enabled by default. ### metrics-interface @@ -485,7 +484,7 @@ Categories for which to track metrics. Options are `JVM`, `PROCESS`, `BEACON`, ` metrics-interface: "192.168.10.101" ``` -Host on which Prometheus accesses Teku metrics. The default is `0.0.0.0`. +Host on which Prometheus accesses Teku metrics. The default is `127.0.0.1`. ### metrics-port @@ -602,6 +601,102 @@ When specifying file names, Teku expects that the files exist. The path separator is operating system dependent, and should be `;` in Windows rather than `:`. +### validators-early-attestations-enabled + +=== "Syntax" + + ```bash + teku vc --validators-early-attestations-enabled[=] + ``` + +=== "Example" + + ```bash + teku vc --validators-early-attestations-enabled=false + ``` + +=== "Environment variable" + + ```bash + TEKU_VALIDATORS_EARLY_ATTESTATIONS_ENABLED=false + ``` + +=== "Configuration file" + + ```bash + validators-early-attestations-enabled: false + ``` + +Specify whether to use Teku's built-in early attestation production, which creates an +attestation once a block is received. The default is `true`. + +Set this option to `false` if running a validator client connected to a load balanced beacon node +(including most hosted beacon nodes such as [Infura]), and validator effectiveness is poor. + +!!! note + + Delaying attestation production increases the chances of generating a correct + attestation when using a load balanced beacon node, but it increases the risk of inclusion delays. + +### validators-external-signer-keystore + +=== "Syntax" + + ```bash + teku vc --validators-external-signer-keystore= + ``` + +=== "Example" + + ```bash + teku vc --validators-external-signer-keystore=teku_client_keystore.p12 + ``` + +=== "Environment variable" + + ```bash + TEKU_VALIDATORS_EXTERNAL_KEYSTORE=teku_client_keystore.p12 + ``` + +=== "Configuration file" + + ```bash + validators-external-signer-keystore: "teku_client_keystore.p12" + ``` + +The keystore that Teku presents to the external signer for TLS authentication. Teku can use +PKCS12 or JKS keystore types. + +Use the PKCS12 keystore type if connecting to Web3Signer. + +### validators-external-signer-keystore-password-file + +=== "Syntax" + + ```bash + teku vc --validators-external-signer-keystore-password-file= + ``` + +=== "Example" + + ```bash + teku vc --validators-external-signer-keystore-password-file=keystore_pass.txt + ``` + +=== "Environment variable" + + ```bash + TEKU_VALIDATORS_EXTERNAL_KEYSTORE_PASSWORD_FILE=keystore_pass.txt + ``` + +=== "Configuration file" + + ```bash + validators-external-signer-keystore-password-file: "keystore_pass.txt" + ``` + +Password file used to decrypt the keystore. + ### validators-external-signer-public-keys === "Syntax" @@ -695,7 +790,64 @@ using Teku to sign blocks and attestations always uses its built-in slashing pro validators-external-signer-timeout: 2000 ``` -Timeout in milliseconds for requests to the external signer. The default is 1000. +Timeout in milliseconds for requests to the external signer. The default is 5000. + +### validators-external-signer-truststore + +=== "Syntax" + + ```bash + teku vc --validators-external-signer-truststore= + ``` + +=== "Example" + + ```bash + teku vc --validators-external-signer-truststore=websigner_truststore.p12 + ``` + +=== "Environment variable" + + ```bash + TEKU_VALIDATORS_EXTERNAL_TRUSTSTORE=websigner_truststore.p12 + ``` + +=== "Configuration file" + + ```bash + validators-external-signer-truststore: "websigner_truststore.p12" + ``` + +PKCS12 or JKS keystore used to trust external signer's self-signed certificate or CA certificate +which signs the external signer's certificate. + +### validators-external-signer-truststore-password-file + +=== "Syntax" + + ```bash + teku vc --validators-external-signer-truststore-password-file= + ``` + +=== "Example" + + ```bash + teku vc --validators-external-signer-truststore-password-file=truststore_pass.txt + ``` + +=== "Environment variable" + + ```bash + TEKU_VALIDATORS_EXTERNAL_TRUSTSTORE_PASSWORD_FILE=truststore_pass.txt + ``` + +=== "Configuration file" + + ```bash + validators-external-signer-truststore-password-file: "truststore_pass.txt" + ``` + +Password file used to decrypt the [keystore](#validators-external-signer-truststore). ### validators-external-signer-url @@ -755,6 +907,40 @@ Graffiti to add when creating a block. Gets converted to bytes and padded to Byt The same graffiti is used for all validators started with this beacon node. +### validators-graffiti-file + +=== "Syntax" + + ```bash + teku vc --validators-graffiti-file= + ``` + +=== "Example" + + ```bash + teku vc --validators-graffiti-file=/Users/me/mynode/graffiti.txt + ``` + +=== "Environment variable" + + ```bash + TEKU_VALIDATORS_GRAFFITI_FILE=/Users/me/mynode/graffiti.txt + ``` + +=== "Configuration file" + + ```bash + validators-graffiti-file: "/Users/me/mynode/graffiti.txt" + ``` + +File containing the validator graffiti to add when creating a block. The file content is +converted to `bytes` and padded to `Bytes32`. The same graffiti is used for all validators started +with this beacon node. + +You can overwrite the file while Teku is running to update the graffiti. + +This option takes precedence over [`--validators-graffiti`](#validators-graffiti). + ### validators-keystore-locking-enabled === "Syntax" diff --git a/docs/Reference/CLI/Subcommands/Voluntary-Exit.md b/docs/Reference/CLI/Subcommands/Voluntary-Exit.md index 30f7df897..d51c7a0e5 100644 --- a/docs/Reference/CLI/Subcommands/Voluntary-Exit.md +++ b/docs/Reference/CLI/Subcommands/Voluntary-Exit.md @@ -165,6 +165,65 @@ When specifying file names, Teku expects that the files exist. The path separator is operating system dependent, and should be `;` in Windows rather than `:`. +### validators-external-signer-keystore + +=== "Syntax" + + ```bash + teku voluntary-exit --validators-external-signer-keystore= + ``` + +=== "Example" + + ```bash + teku voluntary-exit --validators-external-signer-keystore=teku_client_keystore.p12 + ``` + +=== "Environment variable" + + ```bash + TEKU_VALIDATORS_EXTERNAL_KEYSTORE=teku_client_keystore.p12 + ``` + +=== "Configuration file" + + ```bash + validators-external-signer-keystore: "teku_client_keystore.p12" + ``` + +The keystore that Teku presents to the external signer for TLS authentication. Teku can use +PKCS12 or JKS keystore types. + +Use the PKCS12 keystore type if connecting to Web3Signer. + +### validators-external-signer-keystore-password-file + +=== "Syntax" + + ```bash + teku voluntary-exit --validators-external-signer-keystore-password-file= + ``` + +=== "Example" + + ```bash + teku voluntary-exit --validators-external-signer-keystore-password-file=keystore_pass.txt + ``` + +=== "Environment variable" + + ```bash + TEKU_VALIDATORS_EXTERNAL_KEYSTORE_PASSWORD_FILE=keystore_pass.txt + ``` + +=== "Configuration file" + + ```bash + validators-external-signer-keystore-password-file: "keystore_pass.txt" + ``` + +Password file used to decrypt the keystore. + ### validators-external-signer-public-keys === "Syntax" @@ -220,7 +279,64 @@ List of public keys of validators that you wish to voluntarily exit when using a validators-external-signer-timeout: 2000 ``` -Timeout in milliseconds for requests to the external signer. The default is 1000. +Timeout in milliseconds for requests to the external signer. The default is 5000. + +### validators-external-signer-truststore + +=== "Syntax" + + ```bash + teku voluntary-exit --validators-external-signer-truststore= + ``` + +=== "Example" + + ```bash + teku voluntary-exit --validators-external-signer-truststore=websigner_truststore.p12 + ``` + +=== "Environment variable" + + ```bash + TEKU_VALIDATORS_EXTERNAL_TRUSTSTORE=websigner_truststore.p12 + ``` + +=== "Configuration file" + + ```bash + validators-external-signer-truststore: "websigner_truststore.p12" + ``` + +PKCS12 or JKS keystore used to trust external signer's self-signed certificate or CA certificate +which signs the external signer's certificate. + +### validators-external-signer-truststore-password-file + +=== "Syntax" + + ```bash + teku voluntary-exit --validators-external-signer-truststore-password-file= + ``` + +=== "Example" + + ```bash + teku voluntary-exit --validators-external-signer-truststore-password-file=truststore_pass.txt + ``` + +=== "Environment variable" + + ```bash + TEKU_VALIDATORS_EXTERNAL_TRUSTSTORE_PASSWORD_FILE=truststore_pass.txt + ``` + +=== "Configuration file" + + ```bash + validators-external-signer-truststore-password-file: "truststore_pass.txt" + ``` + +Password file used to decrypt the keystore. ### validators-external-signer-url