Enabling Validator client API
Last updated
Last updated
slingnode.ethereum role disables validator client API by default. They can be easily enabled using variables described on this page.
All clients except Teku serve the API over plain text HTTP. Teku is the only client that requires HTTPS for API access. The role generates a self-signed certificate, refer to Teku validator client API access for details.
The API requests are authenticated using a bearer token. All clients except Nimbus auto-generate the token and save it in a client specific location within their data directory - refer to Bearer token section for details.
The table below shows summary of the relevant client features:
| Client | Protocol | Auto-generated token | ETH2 Key manager API |
|---|---|---|---|
Since the APIs are served over plain text HTTP protocol (except Teku) it is recommended to use either a reverse proxy (such as Nginx) with TLS or SSH tunneling to enable access from remote hosts. Refer to Exposing the validator API port to host for details.
To enable the validator API set the following variable to true:
This will enable the validator API and expose the default port (TCP 7500) to the Docker network - meaning the API will be accessible only from other containers connected to the same network.
Note Lodestar is an exception and uses a different variable, refer to Lodestar section below for details.
Refer to Exposing ports page for general overview of how this is implemented in the role.
In order to make the API accessible from the Docker host, set the following variable to true:
This will expose the port to the host and map it to the host's loop-back interface (127.0.0.1) as shown below:
With this configuration you can install and configure either a reverse proxy or SSH tunnel to enable secure remote access to the API.
Configuration outlined in this section is suitable only if you run your servers on a private network behind a network firewall (or security groups), otherwise sensitive APIs will be exposed to the Internet even if your server has FirewallD or UFW enabled due to how Docker modifies Iptables. See Docker & host firewall for details.
Refer to Exposing ports page for general overview of how this is implemented in the role.
To expose the port to remote hosts and make them accessible you can override the following variable and set it to:
This will map the container port to the host's "all interfaces" IP address, as shown below:
The default API port (7500) can be changed by overriding the following variable:
All clients except Nimbus auto-generate the token and save it in a client specific location. The table below summarizes the Docker host location of the token for each client:
All clients except Nimbus generate the bearer token automatically, refer to the client documentation for details. slingnode.ethereum will generate the token (if it doesn't exist) for Nimbus and will save it in the following location on the Docker host:
If the token already exist the generation task is skipped. If you want to re-generate the token, you can override the following variables and set them to true:
This tells the role to create new a token and restart the validator container.
NOTE: you need to remove the above variables from your playbook when the chagne has been completed, otherwise the token will be generated and the container restarted every time the role runs.
Teku enforces HTTPS for the API. It requires a certificate with a valid Subject or Subject Alternative Name (SAN) to enable access - otherwise a SNI error will be returned.
slingnode.ethereum generates the certificate automatically when it deploys Teku validator. By default the following DNS names are in included in the SAN extension (in addition to 127.0.0.1 in the subject).
The default configuration will allow access from the Docker host and Docker network. If you want to allow access using IP address or a fully qualified domain name, you can add additional alternative names as shown below (validator and localhost can be remove if they aren't needed):
NOTE: This is a self-signed certificate which will not be trusted by browsers and other tools (such as curl).
If you try to access the API using a hostname or IP that is not included in the certificate you will receive the following error:
If the certificate already exist the generation task is skipped. If you want to re-generate the certificate, you can override the following variables and set them to true:
This tells the role to create new a certificate and restart the validator container.
NOTE: you need to remove the above variables from your playbook otherwise the certificate will be generated and the container restarted every time the role runs.
Validator APIs are disabled by default for all clients except Lodestar. Lodestar cannot be started with the Validator API (key manager APIs) disabled when there's no existing keystore - meaning that in order to start it with the APIs disabled the keystore would have to be imported using CLI beforehand. To workaround this the role starts Lodestar Validator with the APIs enabled. Lodestar uses a different variable than the other clients to control if the APIs are enabled.
For client specific implementation details refer to the official documentation.
| Client | Token location on Docker host |
|---|---|
Lighthouse
HTTP
yes
yes
Prysm
HTTP
yes
yes
Teku
HTTPS
yes
yes
Nimbus
HTTP
no
yes
Lodestar
HTTP
yes
yes
Lighthouse
{{ blockchain_root_path }}/validator/lighthouse/validators/api-token.txt
Prysm
{{ blockchain_root_path }}/validator/prysm/auth-token
Teku
{{ blockchain_root_path }}/validator/teku/validator/key-manager/validator-api-bearer
Nimbus
{{ blockchain_root_path }}/validator/nimbus/api-token.txt
Lodestar
{{ blockchain_root_path }}/validator/lodestar/validator-db/api-token.txt
