# Web3Signer documentation

> An open-source, client-agnostic, Ethereum signing service written in Java that is capable of signing on multiple platforms.

This file contains all documentation content in a single document following the llmstxt.org standard.

## Build from source


## Prerequisites

- [Java JDK](https://jdk.java.net/)

:::caution Important

Web3Signer requires Java 25 or later releases.

:::

- [Git](https://git-scm.com/downloads) or [GitHub Desktop](https://desktop.github.com/)

## Installation on Linux / Unix / macOS

### Clone the Web3Signer repository

Clone the `Consensys/web3signer` repository:

```bash
git clone --recursive https://github.com/Consensys/web3signer.git
```

### Build Web3Signer

After cloning, go to the `web3signer` directory.

```bash
cd web3signer
```

Build Web3Signer with the Gradle wrapper `gradlew`:

```bash
./gradlew distTar
```

Go to the distribution directory:

```bash
cd build/distributions/
```

Expand the distribution archive:

```bash
tar -xzf web3signer-<version>.tar.gz
```

Move to the expanded folder and display the Web3Signer help to confirm installation.

```bash
cd web3signer-<version>/
bin/web3signer --help
```

## Installation on Windows

### Install Web3Signer

Clone the `Consensys/web3signer` repository:

```bat
git clone --recursive https://github.com/Consensys/web3signer.git
```

### Build Web3Signer

Go to the `web3signer` directory:

```bat
cd web3signer
```

Build Web3Signer with the Gradle wrapper `gradlew`:

```bat
./gradlew distZip
```

:::note

To run `gradlew`, you must have the **JAVA_HOME** system variable set to the Java installation directory. For example: `JAVA_HOME = C:\Program Files\Java\jdk1.8.0_181`.

:::

Go to the distribution directory:

```bat
cd build/distributions
```

Expand the distribution archive:

```bat
tar -xzf web3signer-<version>.tar.gz
```

Go to the expanded folder and display the Web3Signer help to confirm installation.

```bat
cd web3signer-<version>
bin/web3signer --help
```

---

## Install binary distribution


## Prerequisites

- [Java JDK](https://jdk.java.net/)

:::caution Important

Web3Signer requires Java 25 or later releases.

:::

## Install binaries

Download the Web3Signer [packaged binaries](https://github.com/Consensys/web3signer/releases/latest).

:::tip
View the [**Releases** page](https://github.com/Consensys/web3signer/releases) to download a specific version.
:::

Unpack the downloaded files and change into the `web3signer-<release>` directory.

Display Web3Signer command line help to confirm installation:

<Tabs>
  <TabItem value="Linux or MacOS" label="Linux or MacOS" default>

```bash
bin/web3signer --help
```

  </TabItem>
  <TabItem value="Windows" label="Windows">

```bat
bin\web3signer --help
```

  </TabItem>
</Tabs>

---

## Private key management best practices


Web3Signer manages validator keys for Ethereum 2.0 staking.
This document outlines best practices for key generation, storage, access control, and system security when using Web3Signer.
The following guidelines help protect your staked assets and supports Ethereum network integrity.

## Generate secure BLS keys

- Use cryptographically secure random number generators for key generation.
- Implement proper key rotation policies to limit the impact of potential key compromises.

## Store keys in a vault 

- Use dedicated key management solutions such as HashiCorp Vault or AWS Key Management Service (KMS).
- Implement encryption for keys at rest and in transit.

  :::note

  Currently, Web3Signer doesn't support direct encryption of keys in storage. This is a known limitation that should be addressed in future updates.

  :::

## Use environment authentication for vaults

- Use environment variables for authentication credentials instead of hardcoding them.
- Implement IAM roles and policies for cloud-based solutions, for example AWS IAM roles for EC2 instances.
- Use Kubernetes secrets or similar container orchestration tools for managing environment variables securely.
- Regularly rotate authentication credentials and limit their scope to the minimum required permissions.

## Expose validator signing API on necessary network interfaces only

- Configure Web3Signer to bind only to specific IP addresses or network interfaces.
- Use firewalls or security groups to restrict inbound traffic to the signing API.
- Implement network segmentation to isolate the signing service from other components.
- Use a reverse proxy to add another layer of security and control.

## Enable TLS authentication between validator client and Web3Signer

- Generate and use strong SSL/TLS certificates for all communications.
- Implement mutual TLS (mTLS) for bidirectional authentication.
- Regularly update and rotate TLS certificates.
- Configure proper cipher suites and TLS versions to ensure strong encryption.

## Restrict host access with `--http-host-allowlist`

- Use the `--http-host-allowlist` option to specify which hostnames are allowed to access the Web3Signer API.
- Regularly review and update the allowlist to maintain tight access control.
- Implement additional network-level access controls to complement this feature.
- Monitor and log all access attempts, especially those from non-allowlisted hosts.

## Disable the key manager API or restrict access

- If you don't need the key manager API, disable it completely using the appropriate configuration option.
- If required, implement strict access controls for the key manager API:
  - Use IP allowlisting.
  - Implement strong authentication mechanisms, for example API keys and OAuth.
  - Apply rate limiting to prevent overuse.
- Regularly audit access logs for the key manager API.

## Configure Postgres database with TLS authentication

- Enable SSL/TLS for all database connections.
- Use strong, unique client certificates for each Web3Signer instance.
- Implement proper certificate validation on both client and server sides.
- Regularly rotate database credentials and certificates.
- Use tools such as pgBouncer with TLS support for connection pooling and additional security.

## Restrict access to the key config

- Implement file system-level permissions to limit read access to only Web3Signer.
- Use encrypted file systems or volume-level encryption for additional protection.
- Implement audit logging for all access attempts to key configuration files.
- Use a secrets management solution to dynamically provide key configurations to Web3Signer.

## Run Web3Signer in a secure enclave

- Use AWS Nitro Enclaves or similar secure computing environments.
- Implement attestation mechanisms to verify the integrity of the enclave.
- Use encrypted communication channels between the enclave and other components.
- Regularly update and patch the enclave environment to address security vulnerabilities.
- Implement proper logging and monitoring solutions that respect the enclave's security boundaries.

---

## Start Web3Signer


:::note
This documentation has been updated in line with the name changes [recommended by the Ethereum
Foundation](https://blog.ethereum.org/2022/01/24/the-great-eth2-renaming/).
The execution layer is formerly "Ethereum 1.0." The consensus layer is formerly "Ethereum 2.0."
:::

**Prerequisites**:

- [Signing key configuration files] to access the required signing keys.

Web3Signer supports consensus layer clients, and execution layer clients, so you
must specify the signing mode, and the location of the signing key configuration files when starting Web3Signer.

<Tabs>
  <TabItem value="Consensus layer client" label="Consensus layer client" default>

```bash
web3signer --key-store-path=/Users/me/keyFiles/ eth2 --slashing-protection-db-url="jdbc:postgresql://localhost/web3signer" --slashing-protection-db-username=postgres --slashing-protection-db-password=password
```

  </TabItem>
  <TabItem value="Execution layer client" label="Execution layer client" >

```bash
web3signer --key-store-path=/Users/me/keyFiles/ eth1
```

  </TabItem>
</Tabs>

In the command line:

- Use the [`--key-store-path`](../reference/cli/options.md#key-config-path-key-store-path) option to specify the
  location of the signing key configuration files.
- Specify the [subcommand] to indicate which signing mode to use.
  Valid subcommands are `eth2` and `eth1`.
  You can only specify one signing mode when starting Web3Signer.

## Consensus layer considerations

Consensus layer [slashing protection] is enabled by default, and you must specify the details the
[slashing protection database], or disable slashing protection using the
[`--slashing-protection-db-enabled`](../reference/cli/subcommands.md#slashing-protection-enabled)
command line option.

:::note
Web3Signer also allows you to [bulk load signing keys] stored in Azure Key Vault.
:::

Start the client, for example [Teku] by specifying the Web3Signer details.

:::important
If Teku connects to a network other than `mainnet`, then the
[`--network`](../reference/cli/subcommands.md#network) option must be specified, and it must match
the network used by the Teku client.
:::

### Public testnets

If you are running Web3Signer `eth2` mode on a public testnet, then you must specify the `network` option.
It's important that this network matches the one you set up for your validator client.
For example, if you have [Teku set up to run on
Holesky](https://docs.teku.consensys.net/get-started/connect/testnet#sync-the-execution-layer-network)
then you must configure Web3Signer with the Holesky network under the `eth2` subcommand, as in the
following example.

```bash
web3signer --key-store-path=/Users/me/keyFiles/ eth2 --network=holesky --slashing-protection-db-url="jdbc:postgresql://localhost/web3signer" --slashing-protection-db-username=postgres --slashing-protection-db-password=password
```

See the [`--network` documentation](../reference/cli/subcommands.md#network) for more information
about this option and the supported networks.

## Confirm Web3Signer is running

Use the [`upcheck`](https://consensys.github.io/web3signer/#tag/Server-Status/operation/UPCHECK)
endpoint to confirm Web3Signer is connected and running.

<Tabs>
  <TabItem value="curl request" label="curl request" default>

```bash
curl -X GET http://localhost:9000/upcheck
```

  </TabItem>
  <TabItem value="Result" label="Result" >

```json
200 OK
```

  </TabItem>
</Tabs>

Web3Signer by default also performs a health check on the
[slashing protection database].

<!-- Links -->

[Signing key configuration files]: ../how-to/load-keys.md#use-key-configuration-files
[Teku]: https://docs.teku.consensys.net/how-to/use-external-signer/use-web3signer
[subcommand]: ../reference/cli/subcommands.md
[bulk load signing keys]: ../how-to/load-keys.md#bulk-load-keys
[slashing protection]: ../concepts/slashing-protection.md
[slashing protection database]: ../how-to/configure-slashing-protection.md

---

## Run Web3Signer from Docker

# Run Web3Signer from Docker image

A Docker image is provided to run Web3Signer in a Docker container.

## Prerequisites

- [Docker](https://docs.docker.com/install/)

- MacOS or Linux

:::caution Important

The Docker image does not run on Windows.

:::

## Run Docker image

Display the Web3Signer command line help using the Docker image:

```bash
docker run consensys/web3signer:develop --help
```

## Expose listening port

To use the default listening port (`9000`) or the port specified using `--http-listen-port`, you must expose the listening port.

To run Web3Signer exposing listening port for access:

```bash
docker run -p <listenPort>:9000 consensys/web3signer:develop [options] [subcommand] [options]
```

---

## Architecture


Web3Signer is a remote signing client comprised of three main components:

- Remote signer
- Slashing database
- APIs

## The remote signer

The remote signer [loads private keys](../how-to/load-keys.md) into memory and responds to signature requests.
If you are using a [vault](../how-to/store-keys/vaults/_category_.json) for execution layer signing, the keys stay at rest.
This component communicates with the slashing database, the APIs, and the keystore (if used), to coordinate remote signing.

## The slashing database

The [slashing database](./slashing-protection.md) is a Postgres database that tracks which keys have signed messages.
Database locking ensures that when multiple Web3Signer instances load the same keys, only one instance is permitted to sign.

## The APIs

Web3Signer supports REST and [JSON-RPC APIs](../reference/api/_category_.json) to sign consensus layer and execution layer payloads
respectively. These connections should be carefully secured. Web3Signer offers [TLS communication](../how-to/configure-tls.md).

---

## Slashing protection


Slashing refers to penalties that are applied to consensus layer validators that sign conflicting
blocks or attestations.

Web3Signer provides slashing protection to prevent validators from signing blocks and attestations
based on what it knows has already been signed.
A slashing protection database records each block and attestation signed by a validator.

Slashing protection is enabled by default, and you are responsible for [creating and maintaining]
the required PostgreSQL database, or you can disable slashing protection by setting
[`--slashing-protection-enabled`](../reference/cli/subcommands.md#slashing-protection-enabled) to `false`.

:::info

Web3Signer only supports PostgreSQL for creating the slashing protection database.

:::

Multiple Web3Signer instances can connect to the same slashing protection database.
Database locking ensures that if Web3signer instances load the same keys, only one Web3signer
instance actually signs.

<!--links-->

[creating and maintaining]: ../how-to/configure-slashing-protection.md

---

## TLS communication


Web3Signer supports TLS to secure inbound and outbound HTTP JSON-RPC requests, and communication
with HashiCorp Vault.

Private keys and certificates for client and server TLS connections must be stored in
password-protected PKCS #12 keystores.
You must configure the server (in this example, [Besu](https://besu.hyperledger.org/)) to accept TLS connections.

Use the command line options to configure TLS on [HTTP JSON-RPC requests](../how-to/configure-tls.md)
and [HashiCorp Vault](../how-to/store-keys/vaults/hashicorp.md).

---

## Configure consensus layer slashing protection


Configure [slashing protection] to prevent consensus layer validators from being penalized for
signing conflicting blocks or attestations.

Install and manage the PostgreSQL database that stores the validator signing history for one or more
Web3Signer instances.

:::note
Consensus layer [slashing protection] is enabled by default.
You therefore must configure a slashing protection database, or disable slashing protection using
the [`--slashing-protection-enabled`](../reference/cli/subcommands.md#slashing-protection-enabled)
command line option.
:::

The steps to configure slashing protection are:

1. [Install the PostgreSQL database](#install-the-postgresql-database).
1. [Load the database schema](#load-the-database-schema).
1. [Start Web3Signer and specify the database details](#start-web3signer).

## Install the PostgreSQL database

[Install the PostgreSQL database], or use [Docker] to [run the PostgreSQL database in a container].
The following example uses a Docker container.

:::caution Important
Web3Signer only supports PostgreSQL for creating the slashing protection database.
:::

As an example, create the database with the default `postgres` user, and specify the password and
database name.

```bash
docker run -e POSTGRES_PASSWORD=password -e POSTGRES_USER=postgres -e POSTGRES_DB=web3signer -p 5432:5432 postgres
```

This example uses `-p 5432:5432` to bind the default Postgres database port to the host's port.
This allows you to [connect to the database] using the `jdbc:postgresql://localhost/web3signer` URL.

:::tip
Web3Signer uses [HikariCP] to manage database connections, and uses the default configuration values.
The defaults perform well in most deployments, but you can be override them with the
[`slashing-protection-db-pool-configuration-file`](../reference/cli/subcommands.md#slashing-protection-db-pool-configuration-file)
option.
:::

## Load the database schema

Web3Signer provides a database schemas to configure the database.
Find the schemas in `/migrations/postgresql/` in the Web3Signer installation directory.

The following examples show how to load the schema using the [Flyway] database migration tool or the
PostgreSQL command line tool.

:::note
If loading each schema individually, then ensure you load them in order.
For example `V1_initial.sql`, `V2__removeUniqueConstraints.sql`, then `V3__addLowWatermark.sql`
(followed by all Vx\_\_.sql files).
Use the [Flyway] migration tool to automatically load them in order.
:::

<Tabs>

  <TabItem value="Flyway DB migration tool" label="Flyway DB migration tool" default>

```bash
flyway migrate -url="jdbc:postgresql://localhost/web3signer" \
-locations="filesystem:/Users/me/web3signer-0.2.1-SNAPSHOT/migrations/postgresql"
```

  </TabItem>
  <TabItem value="Postgres command line" label="Postgres command line" >

```bash
psql --echo-all --host=localhost --port=5432 --dbname=web3signer --username=postgres \
-f /Users/me/web3signer-0.2.1-SNAPSHOT/migrations/postgresql/postgresql/V1__initial.sql
```

  </TabItem>
</Tabs>

:::note
If using the PostgreSQL command line inside a docker container, ensure you mount the
`/migrations/postgresql/` directory to the docker container to access the schema file.
:::

## Start Web3Signer

Start Web3Signer and specify the PostgreSQL connection options.

```bash
web3signer --key-store-path=/Users/me/keys eth2 --slashing-protection-db-url="jdbc:postgresql://localhost/web3signer" \
--slashing-protection-db-username=postgres --slashing-protection-db-password=password \
--slashing-protection-pruning-enabled=true
```

:::note
If using a non-default port number for your PostgreSQL database, then [include the port number in
the database URL].
:::

Including
[`--slashing-protection-pruning-enabled=true`](../reference/cli/subcommands.md#slashing-protection-pruning-enabled)
enables [slashing protection database pruning].

Start the client, for example [Teku] by specifying the Web3Signer details.

## Import or export a slashing protection database

You can import or export the slashing protection database.
When importing, additional entries are added to the existing database.

Web3Signer supports importing or exporting using the [validator client interchange format].
Use the [`eth2 import`](../reference/cli/subcommands.md#eth2-import) and
[`eth2 export`](../reference/cli/subcommands.md#eth2-export) to import or export files.

To import a slashing protection database file into the Postgres database, run:

```bash
web3signer eth2 --slashing-protection-db-url="jdbc:postgresql://localhost/web3signer" \
--slashing-protection-db-username=postgres \
--slashing-protection-db-password=password import --from=/Users/me/my_node/interchange.json
```

To export the Postgres database to a file run:

```bash
web3signer eth2 --slashing-protection-db-url="jdbc:postgresql://localhost/web3signer" \
--slashing-protection-db-username=postgres \
--slashing-protection-db-password=password export --to=/Users/me/my_node/interchange.json
```

You must supply the Postgres database connection details when importing or exporting the slashing
protection database.

## Prune the slashing protection database

You can enable periodic pruning of the slashing protection database to manage its size.

Enable pruning by setting
[`--slashing-protection-pruning-enabled`](../reference/cli/subcommands.md#slashing-protection-pruning-enabled)
to `true`.

Web3Signer can prune the database on startup, and then after each pruning interval.
By default, this feature is disabled. You can enable pruning at startup and start pruning after the pruning interval by setting
[`--slashing-protection-pruning-at-boot-enabled`](../reference/cli/subcommands.md#slashing-protection-pruning-at-boot-enabled)
to `true`.

You can include additional optional pruning configuration options.
For example, run:

```bash
web3signer eth2 --slashing-protection-db-url="jdbc:postgresql://localhost/web3signer" \
--slashing-protection-db-username=postgres --slashing-protection-db-password=password \
--slashing-protection-pruning-enabled=true --slashing-protection-pruning-at-boot-enabled=true \
--slashing-protection-pruning-epochs-to-keep=5000 --slashing-protection-pruning-interval=18
```

:::caution Warning
Do not use slashing protection database pruning while [importing or exporting the
database](#import-or-export-a-slashing-protection-database).
:::

## Slashing protection health check

By default, Web3Signer performs a health check on the slashing protection database every 30000 milliseconds.
To change the default value, configure the
[`--slashing-protection-db-health-check-interval-milliseconds`](../reference/cli/subcommands.md#slashing-protection-db-health-check-interval-milliseconds)
command line option.

The service responds with a `200` message if healthy, and `503` if unhealthy.

You can also configure the health check timeout with the
[`--slashing-protection-db-health-check-timeout-milliseconds`](../reference/cli/subcommands.md#slashing-protection-db-health-check-timeout-milliseconds)
command line option.
The default timeout is 3000 milliseconds.

<!-- links -->

[slashing protection]: ../concepts/slashing-protection.md
[slashing protection database pruning]: #prune-the-slashing-protection-database
[Install the PostgreSQL database]: https://www.postgresql.org/download/
[Docker]: https://docs.docker.com/install/
[run the PostgreSQL database in a container]: https://hub.docker.com/_/postgres/
[Flyway]: https://flywaydb.org/documentation/
[include the port number in the database URL]: https://jdbc.postgresql.org/documentation/use/#connecting-to-the-database
[Teku]: https://docs.teku.consensys.net/how-to/use-external-signer/use-web3signer
[connect to the database]: https://jdbc.postgresql.org/documentation/use/#connecting-to-the-database
[validator client interchange format]: https://eips.ethereum.org/EIPS/eip-3076
[HikariCP]: https://github.com/brettwooldridge/HikariCP

---

## Configure TLS


Configure TLS communication from the command line to allow clients (for example [Teku], a dapp, or
curl) and Web3Signer to communicate securely.

Web3Signer provides multiple options to configure client TLS access:

- Specify one or more authorized clients using a [known clients file](#create-the-known-clients-file).
- [Allow all clients with trusted CA certificates to connect].
- [Allow any client to connect].

This example uses a known clients file to limit access to specified clients.

:::info
The [Teku tutorial] provides step-by-step instructions to configure the Teku client and Web3Signer
for TLS communication, including creating the required keystores and truststore.
:::

## Prerequisites

**Web3Signer prerequisites**:

- Web3Signer's password-protected PKCS #12 keystore.
- File containing the keystore password.

**Client prerequisites**:

- The client must be configured for TLS.
- Client's PKCS #12 keystore information.

## Create the known clients file

Create a file (in this example, `knownClients.txt`) that lists one or more clients that are trusted
to connect to Web3Signer.
The file can contain clients that use trusted CA or self-signed certificates.

The file contents use the format `<common_name> <hex-string>` where:

- `<common_name>` is the Common Name used for the client's keystore
- `<hex-string>` is the SHA-256 fingerprint of the client's keystore.

```bash
curl_client DF:65:B8:02:08:5E:91:82:0F:91:F5:1C:96:56:92:C4:1A:F6:C6:27:FD:6C:FC:31:F2:BB:90:17:22:59:5B:50
```

You can use [OpenSSL](https://www.openssl.org/) or
[keytool](https://docs.oracle.com/javase/6/docs/technotes/tools/solaris/keytool.html) to display the
client's Common Name and fingerprint.
For example:

```bash
keytool -list -v -keystore <keystore> -storetype PKCS12 -storepass <password>
```

## Start Web3Signer

```bash
web3signer --key-store-path=/Users/me/keyFiles/ \
--tls-keystore-file=/Users/me/certs/web3signerKeystore.p12 \
--tls-keystore-password-file=/Users/me/certs/password.txt \
--tls-known-clients-file=/Users/me/certs/knownClients.txt
```

The command line:

- Specifies the location of the signing key configuration files using the
  [`--key-store-path`](../reference/cli/options.md#key-config-path-key-store-path) option.
- Specifies the Web3Signer keystore using the
  [`--tls-keystore-file`](../reference/cli/options.md#tls-keystore-file) option.
- Specifies the file that contains the password to decrypt the keystore using the
  [`--tls-keystore-password-file`](../reference/cli/options.md#tls-keystore-password-file) option.
- [Specifies the clients](#create-the-known-clients-file) that are trusted to connect to Web3Signer
  using the [`tls-known-clients-file`](../reference/cli/options.md#tls-known-clients-file) option.

:::note
Use the [`--tls-allow-any-client`](../reference/cli/options.md#tls-allow-any-client) option to allow
access to any client, or [`--tls-allow-ca-clients`](../reference/cli/options.md#tls-allow-ca-clients)
to allow access to any client with a trusted CA certificate.

You can't use [`--tls-allow-any-client`](../reference/cli/options.md#tls-allow-any-client) with
[`tls-known-clients-file`](../reference/cli/options.md#tls-known-clients-file) or
[`--tls-allow-ca-clients`](../reference/cli/options.md#tls-allow-ca-clients).
:::

## Server TLS connection

Allow Web3Signer to send and receive secure HTTP JSON-RPCs from the server (for example Besu).

:::note
This can only be used when Web3Signer is eth1 mode.
:::

**Server prerequisites**:

- [The server must be configured to allow TLS communication](https://besu.hyperledger.org/private-networks/how-to/configure/tls/client-and-server).
- Server's password-protected PKCS #12 keystore information.

### Create the known servers file

Create a file (in this example, `knownServers`) that lists one or more trusted servers.
The file contents use the format `<hostname>:<port> <hex-string>` where:

- `<hostname>` is the server hostname
- `<port>` is the port used for communication
- `<hex-string>` is the SHA-256 fingerprint of the server's certificate.

```bash
localhost:8590 6C:B2:3E:F9:88:43:5E:62:69:9F:A9:9D:41:14:03:BA:83:24:AC:04:CE:BD:92:49:1B:8D:B2:A4:86:39:4C:BB
127.0.0.1:8590 6C:B2:3E:F9:88:43:5E:62:69:9F:A9:9D:41:14:03:BA:83:24:AC:04:CE:BD:92:49:1B:8D:B2:A4:86:39:4C:BB
```

:::note
Specify both hostname and IP address in the file if unsure which is used in requests.
:::

### Start Web3Signer

```bash
web3signer eth1 --downstream-http-tls-enabled \
--downstream-http-tls-keystore-file=/Users/me/my_node/keystore.pfx \
--downstream-http-tls-keystore-password-file=/Users/me/my_node/keyPassword \
--downstream-http-tls-known-servers-file=/Users/me/my_node/knownServers
```

The command line:

- Enables TLS using the
  [`--downstream-http-tls-enabled`](../reference/cli/subcommands.md#downstream-http-tls-enabled) option.
- Specifies the keystore to present during authentication using the
  [`--downstream-http-tls-keystore-file`](../reference/cli/subcommands.md#downstream-http-tls-keystore-file) option.
- Specifies the file that contains the password to decrypt the keystore using the
  [`--downstream-http-tls-keystore-password-file`](../reference/cli/subcommands.md#downstream-http-tls-keystore-password-file) option.
- [Specifies the servers](#create-the-known-servers-file) to connect to using the
  [`--downstream-http-tls-known-servers-file`](../reference/cli/subcommands.md#downstream-http-tls-known-servers-file) option.

:::note
The [`--downstream-http-tls-ca-auth-enabled`](../reference/cli/subcommands.md#downstream-http-tls-ca-auth-enabled)
option is `true` by default and allows connections to servers with trusted root CAs.
:::

<!-- links -->

[Allow all clients with trusted CA certificates to connect]: ../reference/cli/options.md#tls-allow-ca-clients
[Allow any client to connect]: ../reference/cli/options.md#tls-allow-any-client
[Teku]: https://docs.teku.consensys.net/
[Teku tutorial]: https://docs.teku.consensys.net/tutorials/configure-external-signer-tls

---

## Load signing keys


Load signing keys using a [key configuration file], or bulk load using the [`eth1` and `eth2` subcommands].
Web3Signer supports loading keys with the following methods:

| Key storage                          | Key configuration file | Bulk load with `eth1` | Bulk load with `eth2` |
|--------------------------------------|:----------------------:|:---------------------:|:---------------------:|
| [Keystore files]                     |      <Supported />     |      <Supported />     |      <Supported />     |
| **Vaults**                           |                        |                       |                       |
| [Hashicorp Vault]                    |      <Supported />     |                       |                       |
| [Azure Key Vault]                    |      <Supported />     |      <Supported />     |      <Supported />     |
| [AWS Secrets Manager]                |      <Supported />     |                       |      <Supported />     |
| [AWS KMS]                            |      <Supported />     |      <Supported />     |                       |
| [GCP Secret Manager]                 |                        |                       |      <Supported />     |

:::note
You can bulk load in combination with using key configuration files.
:::

## Use key configuration files

For each signing key, define the parameters to access the key in a [key configuration file].
You can create a separate configuration file for each key, or specify multiple configurations in a
single file by adding a triple-dash separator (`---`) between configurations.

The configuration file must be YAML-formatted, and can use any naming format, but must have the `.yaml` extension.

Place one or more key configuration files in a single directory which you specify when starting Web3Signer.
Use the [`--key-store-path`](../reference/cli/options.md#key-config-path-key-store-path) option to specify the
location of the key configuration files.

```bash
web3signer --key-store-path=/Users/me/keyFiles/ eth2
```

## Bulk load keys

### Azure Key Vault

You can bulk load keys that are stored in Azure Key Vault using the Web3Signer
[`eth1` subcommand options](../reference/cli/subcommands.md#eth1) or
[`eth2` subcommand options](../reference/cli/subcommands.md#eth2).

For `eth1` bulk loading, Web3Signer creates Azure keys connections in bulk mode. The Azure keys
connections are used to perform remote signing using SECP keys. Web3Signer does not download the private keys
for `eth1` bulk loading with Azure.

For `eth2` bulk loading, Web3Signer bulk loads the BLS keys from Azure Secrets. The bulk loading
mode supports loading multiple consensus layer keys from the same Azure secret, if keys are stored with a line
terminating character such as `\n`.
This saves cost when dealing with a large number of keys.
Up to 200 keys can be stored under a secret name.

<Tabs>

  <TabItem value="Consensus layer client" label="Consensus layer client" default>

```bash
web3signer eth2 --azure-vault-enabled=true --azure-client-id=87efaa5b-4029-4b54-98bb2e2e8a11 \
--azure-client-secret=0DgK4V_YA99RPk7.f_1op0-em_a46wSe.Z \
--azure-tenant-id=34255fb0-379b-4a1a-bd47-d211ab86df81 \
--azure-vault-name=AzureKeyVault
```

  </TabItem>
  <TabItem value="Execution layer client" label="Execution layer client" >

```bash
web3signer eth1 --azure-vault-enabled=true --azure-client-id=87efaa5b-4029-4b54-98bb2e2e8a11 \
--azure-client-secret=0DgK4V_YA99RPk7.f_1op0-em_a46wSe.Z \
--azure-tenant-id=34255fb0-379b-4a1a-bd47-d211ab86df81 \
--azure-vault-name=AzureKeyVault
```

  </TabItem>
</Tabs>

### AWS Secrets Manager

You can bulk load consensus layer keys that are stored in AWS Secrets Manager using the Web3Signer
[`eth2` subcommand options](../reference/cli/subcommands.md#eth2).

The AWS bulk load mode supports loading multiple consensus layer keys from the same secret, if keys
are stored with a line terminating character such as `\n`.
This saves cost when dealing with a large number of keys.
Up to 200 keys can be stored under a secret name.

```bash
web3signer eth2 --aws-secrets-enabled=true --aws-secrets-access-key-id=AKIA...EXAMPLE \
--aws-secrets-secret-access-key=sk...EXAMPLE \
--aws-secrets-region=us-east-2
```

### AWS Key Management Service

You can bulk load execution layer keys that are stored in the AWS Key Management Service (KMS) using
the Web3Signer [`eth1` subcommand options](../reference/cli/subcommands.md#eth1).

```bash
web3signer eth1 --aws-kms-enabled=true --aws-kms-access-key-id=AKIA...EXAMPLE \
--aws-kms-secret-access-key=sk...EXAMPLE \
--aws-secrets-region=us-east-2
```

### GCP Secret Manager

You can bulk load consensus layer keys that are stored in the GCP Secret Manager using
the Web3Signer [`eth2` subcommand options](../reference/cli/subcommands.md#eth2).

```bash
web3signer eth2 --gcp-secrets-enabled=true --gcp-project-id=AKIA...EXAMPLE
```

### Keystore files

You can bulk load consensus layer or execution layer keys that are stored as keystore files using the Web3Signer
[`eth1` subcommand options](../reference/cli/subcommands.md#eth1) or
[`eth2` subcommand options](../reference/cli/subcommands.md#eth2).

<Tabs>

  <TabItem value="Consensus layer client" label="Consensus layer client" default>

```bash
web3signer eth2 --keystores-path=/Users/me/keystores \
--keystores-passwords-path=/Users/me/passwds
```

  </TabItem>
  <TabItem value="Execution layer client" label="Execution layer client" >

```bash
web3signer eth1 --keystores-path=/Users/me/keystores \
--keystores-passwords-path=/Users/me/passwds
```

  </TabItem>
</Tabs>

Use the `eth1` or `eth2` `--keystores-password-file` or `--keystores-passwords-path` command line option to specify
keystore passwords.

<!-- Link -->

[key configuration file]: ../reference/key-config-file-params.md
[`eth1` and `eth2` subcommands]: ../reference/cli/subcommands.md
[Azure Key Vault]: #azure-key-vault
[AWS Secrets Manager]: #aws-secrets-manager
[keystore files]: #keystore-files
[AWS KMS]: #aws-key-management-service
[GCP Secret Manager]: #gcp-secret-manager
[Hashicorp Vault]: #use-key-configuration-files

---

## Manage consensus layer signing keys

## Reload new keys

If you add new keys to an existing set of validators, or modify the key configuration files, reload
the keys to ensure Web3Signer registers the new or modified keys.
Use the [`reload`](https://consensys.github.io/web3signer/#tag/Reload-Signer-Keys)
endpoint to reload the keys in Web3Signer.

<Tabs>

  <TabItem value="curl request" label="curl request" default>

```bash
curl -X POST http://localhost:9000/reload
```

  </TabItem>
  <TabItem value="Result" label="Result" >

```json
200 Call is successful
```

  </TabItem>
</Tabs>

## Manage keys using Key Manager API

You can manage your keys using the [Key Manager API
endpoints](https://consensys.github.io/web3signer/#tag/Keymanager).
You can [list keys](#list-keys), [import keystores](#import-keystores), and [delete keys](#delete-keys).

Enable the key manager API by running Web3Signer using the
[`--key-manager-api-enabled`](../reference/cli/subcommands.md#key-manager-api-enabled) subcommand option.

### List keys

List all validating public keys known to and decrypted by the keystore using the
[`list keys` endpoint](https://consensys.github.io/web3signer/#tag/Keymanager/operation/KEYMANAGER_LIST).

<Tabs>

  <TabItem value="curl request" label="curl request" default>

```bash
curl -X GET http://localhost:9000/eth/v1/keystores
```

  </TabItem>
  <TabItem value="Result" label="Result" >

```json
{
  "data": [
    {
      "validating_pubkey": "0x93247f2209abcacf57b75a51dafae777f9dd38bc7053d1af526f220a7489a6d3a2753e5f3e8b1cfe39b56f43611df74a",
      "derivation_path": "m/12381/3600/0/0/0",
      "readonly": true
    }
  ]
}
```

  </TabItem>
</Tabs>

### Import keystores

Import keystores generated by the consensus layer deposit CLI tooling using the
[`import keystores` endpoint](https://consensys.github.io/web3signer/#tag/Keymanager/operation/KEYMANAGER_IMPORT).

<Tabs>

  <TabItem value="curl request" label="curl request" default>

```bash
curl -X POST http://127.0.0.1:9000/eth/v1/keystores --header "Content-Type: application/json"
--data '{
  "keystores": [
    "{\"version\":4,\"uuid\":\"9f75a3fa-1e5a-49f9-be3d-f5a19779c6fa\",\"path\":\"m/12381/3600/0/0/0\",\"pubkey\":\"0x93247f2209abcacf57b75a51dafae777f9dd38bc7053d1af526f220a7489a6d3a2753e5f3e8b1cfe39b56f43611df74a\",\"crypto\":{\"kdf\":{\"function\":\"pbkdf2\",\"params\":{\"dklen\":32,\"c\":262144,\"prf\":\"hmac-sha256\",\"salt\":\"8ff8f22ef522a40f99c6ce07fdcfc1db489d54dfbc6ec35613edf5d836fa1407\"},\"message\":\"\"},\"checksum\":{\"function\":\"sha256\",\"params\":{},\"message\":\"9678a69833d2576e3461dd5fa80f6ac73935ae30d69d07659a709b3cd3eddbe3\"},\"cipher\":{\"function\":\"aes-128-ctr\",\"params\":{\"iv\":\"31b69f0ac97261e44141b26aa0da693f\"},\"message\":\"e8228bafec4fcbaca3b827e586daad381d53339155b034e5eaae676b715ab05e\"}}}"
  ],
  "passwords": [
    "ABCDEFGH01234567ABCDEFGH01234567"
  ],
    "slashing_protection": "{\"metadata\":{\"interchange_format_version\":\"5\",\"genesis_validators_root\":\"0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2\"},\"data\":[{\"pubkey\":\"0x93247f2209abcacf57b75a51dafae777f9dd38bc7053d1af526f220a7489a6d3a2753e5f3e8b1cfe39b56f43611df74a\",\"signed_blocks\":[],\"signed_attestations\":[]}]}"
  }'
```

  </TabItem>
  <TabItem value="Result" label="Result" >

```json
{
  "data": [
    {
      "status": "imported",
      "message": "string"
    }
  ]
}
```

  </TabItem>
</Tabs>

### Delete keys

Delete keys using the [`delete keys`
endpoint](https://consensys.github.io/web3signer/#tag/Keymanager/operation/KEYMANAGER_DELETE).

<Tabs>

  <TabItem value="curl request" label="curl request" default>

 ```bash
curl -X DELETE http://localhost:9000/eth/v1/keystores --data '{"pubkeys": ["0x93247f2209abcacf57b75a51dafae777f9dd38bc7053d1af526f220a7489a6d3a2753e5f3e8b1cfe39b56f43611df74a"]}'
```

  </TabItem>
  <TabItem value="Result" label="Result" >

```json
{
  "data": [
    {
      "status": "deleted",
      "message": "string"
    }
  ],
  "slashing_protection": "{\"metadata\":{\"interchange_format_version\":\"5\",\"genesis_validators_root\":\"0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2\"},\"data\":[{\"pubkey\":\"0x93247f2209abcacf57b75a51dafae777f9dd38bc7053d1af526f220a7489a6d3a2753e5f3e8b1cfe39b56f43611df74a\",\"signed_blocks\":[],\"signed_attestations\":[]}]}"
}
```

  </TabItem>
</Tabs>

---

## Configure logging


Web3Signer provides multiple methods to configure logging:

- [Basic](#basic-log-level-setting) - Change the log level or structured logging format.
- [Advanced](#advanced-custom-logging) - Configure the output and format of the logs.

## Basic log level setting

Use the [`--logging`](../../reference/cli/options.md#logging) command line option to specify logging verbosity.
This option changes the volume of events displayed in the log.
Valid log levels are `OFF`, `FATAL`, `ERROR`, `WARN`, `INFO`, `DEBUG`, `TRACE`, `ALL`.
The default level is `INFO`.

Use the [`--logging-format`](../../reference/cli/options.md#logging-format) option to specify the logging format.
You can select a structured logging format, which emits each log record as a JSON object in a well-defined format, making logs consistent and machine-readable.
Valid formats are `PLAIN`, `ECS`, `GCP`, `LOGSTASH`, `GELF`.
The default format is `PLAIN`, which specifies traditional pattern-based text logging.

## Advanced custom logging

You can provide your own logging configuration using the standard Log4J2 configuration mechanisms.

Web3Signer includes the Log4J JSON Template Layout library, which enables production-ready templates for each structured logging format.
Specify `JsonTemplateLayout` in your configuration file to use the Log4J templates.

The following is an example of a custom configuration file, a configuration file using the default Elastic Common Schema (ECS) template,
and a configuration file using the Google Cloud Platform (GCP) template.
For more information, see the Log4j [configuration file](https://logging.apache.org/log4j/2.x/manual/configuration.html) and
[event templates](https://logging.apache.org/log4j/2.x/manual/json-template-layout.html#event-templates) documentation.

<Tabs>
<TabItem value="Custom configuration">

```xml
<?xml version="1.0" encoding="UTF-8"?>
<Configuration level="INFO">
  <Properties>
    <Property name="root.log.level">INFO</Property>
    <Property name="dependency.log.level">INFO</Property>
  </Properties>

  <Appenders>
    <Console name="Console" target="SYSTEM_OUT">
      <PatternLayout pattern="%d{yyyy-MM-dd HH:mm:ss.SSSZZZ} | %t | %-5level | %c{1} | %msg%n"/>
    </Console>
  </Appenders>
  <Loggers>
    <Logger name="com.azure.security.keyvault.secrets.SecretAsyncClient"
      level="${dependency.log.level}" additivity="false">
      <AppenderRef ref="Console"/>
    </Logger>
    <Logger name="com.networknt.schema" level="${env:dependency.log.level}" additivity="false">
      <AppenderRef ref="Console"/>
    </Logger>
    <Logger name="org.jdbi.v3.core" level="${env:dependency.log.level}" additivity="false">
      <AppenderRef ref="Console"/>
    </Logger>
    <Logger name="com.zaxxer.hikari" level="${env:dependency.log.level}" additivity="false">
      <AppenderRef ref="Console"/>
    </Logger>
    <Logger name="io.swagger.v3" level="${env:dependency.log.level}"
      additivity="false">
      <AppenderRef ref="Console"/>
    </Logger>
    <Logger name="io.netty" level="${env:dependency.log.level}" additivity="false">
      <AppenderRef ref="Console"/>
    </Logger>
    <Root level="${sys:root.log.level}">
      <AppenderRef ref="Console"/>
    </Root>
  </Loggers>
</Configuration>
```

</TabItem>
<TabItem value="With default ECS template">

```xml
<?xml version="1.0" encoding="UTF-8"?>
<Configuration level="INFO">
  <Properties>
    <Property name="root.log.level">INFO</Property>
  </Properties>

  <Appenders>
    <Console name="Console" target="SYSTEM_OUT">
      <JsonTemplateLayout/>
    </Console>
  </Appenders>
  <Loggers>
    <Root level="${sys:root.log.level}">
      <AppenderRef ref="Console"/>
    </Root>
  </Loggers>
</Configuration>
```

</TabItem>
<TabItem value="With GCP template">

```xml
<?xml version="1.0" encoding="UTF-8"?>
<Configuration level="INFO">
  <Properties>
    <Property name="root.log.level">INFO</Property>
  </Properties>

  <Appenders>
    <Console name="Console" target="SYSTEM_OUT">
      <JsonTemplateLayout eventTemplateUri="classpath:GcpLayout.json"/>
    </Console>
  </Appenders>
  <Loggers>
    <Root level="${sys:root.log.level}">
      <AppenderRef ref="Console"/>
    </Root>
  </Loggers>
</Configuration>
```

</TabItem>
</Tabs>

To use your custom configuration, set the environment variable `JAVA_OPTS` to the location of your
configuration file.

```bash
export JAVA_OPTS="-Dlog4j.configurationFile=<path_to_file>"
```

For Bash-based executions, you can set the variable for only the scope of the program execution by
setting it before starting Web3Signer.

```bash title="Set the custom logging and start Web3Signer"
JAVA_OPTS="-Dlog4j.configurationFile=/Users/me/debug.xml" web3signer --key-store-path=/Users/me/keyFiles/ eth2
```

:::info Note
When a custom Log4j2 configuration file is provided, it takes precedence over the [logging command line options](#basic-log-level-setting).
:::

---

## Use metrics to monitor performance


Enable the [Prometheus](https://prometheus.io/) monitoring and alerting service for Web3Signer
metrics using the [`--metrics-enabled`](../../reference/cli/options.md#metrics-enabled) option.

Web3Signer provides metrics for secp256k1 and BLS12-381 key types.

## Install Prometheus

To use Prometheus with Web3Signer, install the [Prometheus main component](https://prometheus.io/download/).
On MacOS, install with [Homebrew](https://formulae.brew.sh/formula/prometheus):

```bash
brew install prometheus
```

## Setting up and running Prometheus with Web3Signer

To configure Prometheus and run with Web3Signer:

1. Configure Prometheus to poll Web3Signer.
   For example, add the following YAML fragment to the `scrape_configs` block of the `prometheus.yml` file:

    ```yml title="Example configuration"
    global:
      scrape_interval: 15s
    scrape_configs:
      - job_name: "prometheus"
        static_configs:
          - targets: ["localhost:9090"]
      - job_name: "web3signer-dev"
        scrape_timeout: 10s
        metrics_path: /metrics
        scheme: http
        static_configs:
          - targets: ["localhost:9001"]
    ```

2. [Start Teku] by specifying the Web3Signer details.

3. Start Web3Signer with the [`--metrics-enabled`](../../reference/cli/options.md#metrics-enabled) option.

    ```bash
    web3signer --key-store-path=/Users/me/keyFiles/ --metrics-enabled
    ```

    The `HTTP`, `SIGNING`, `JVM`, and `PROCESS` metrics categories are enabled by default.
    Use the [`--metrics-category`](../../reference/cli/options.md#metrics-category) command line
    option to update the available categories.

4. In another terminal, run Prometheus specifying the `prometheus.yml` file:

    ```bash
    prometheus --config.file=prometheus.yml
    ```

5. View the [Prometheus graphical interface](#view-prometheus-graphical-interface).

## Run Prometheus with Web3Signer in push mode

The [`--metrics-enabled`](../../reference/cli/options.md#metrics-enabled) option enables Prometheus
polling of Besu, but sometimes metrics are hard to poll (for example, when running inside Docker
containers with varying IP addresses). To enable Besu to push metrics to a
[Prometheus push gateway](https://github.com/prometheus/pushgateway), use
the [`--metrics-push-enabled`](../../reference/cli/options.md#metrics-push-enabled) option.

To configure Prometheus and run with Web3Signer pushing to a push gateway:

1. Configure Prometheus to read from a push gateway. For example, add the following YAML fragment to
the `scrape_configs` block of the `prometheus.yml` file:

    ```yml
    - job_name: push-gateway
      metrics_path: /metrics
      scheme: http
      static_configs:
        - targets:
            - localhost:9091
    ```

1. Start the push gateway. You can deploy the push gateway using the Docker image:

    ```bash
    docker pull prom/pushgateway
    docker run -d -p 9091:9091 prom/pushgateway
    ```

1. Start Web3Signer specifying options:
    * [`--metrics-push-enabled`](../../reference/cli/options.md#metrics-push-enabled)
    * [`--metrics-push-port`](../../reference/cli/options.md#metrics-push-enabled)
    * [`--metrics-push-host`](../../reference/cli/options.md#metrics-push-host)

1. In another terminal, run Prometheus specifying the `prometheus.yml` file:

    ```bash
    prometheus --config.file=prometheus.yml
    ```

1. View the [Prometheus graphical interface](#view-prometheus-graphical-interface).

## View Prometheus graphical interface

1. Open a web browser to `http://localhost:9090` to view the Prometheus graphical interface.

2. Choose **Graph** from the menu bar and click the **Console** tab below.

3. From the **Insert metric at cursor** drop-down, select a metric and click **Execute**.
   The values display.

The following Web3Signer metrics are available.

**HTTP API metrics:**

| Name | Definition |
| --- | --- |
| `<keytype>_malformed_request_count` | Number of requests received which had illegally formatted body. |
| `<keytype>_signing_duration` | Duration of a signing event. |
| `<keytype>_missing_identifier_count` | Number of signing requests for which no keys were available. |
| `signers_loaded_count` | Total number of SECP256k1 and BLS12-381 keys loaded. |
| `signing_private_key_retrieval_time` | Time taken to retrieve BLS signing keys. |

**Eth2 Slashing protection metrics:**

| Name | Definition |
| --- | --- |
| `permitted_signings` | The number of slashing checks which have reported 'safe to sign'. |
| `prevented_signings` | The number of prevented signings due to violation of slashing conditions. |

**Process metrics:**

| Name              | Definition                                 |
| ----------------- | ------------------------------------------ |
| `process_release` | The number of the release version running. |

## Visualize collected data

Use [Grafana] to visualize the collected data. See the sample [Web3Signer Grafana
dashboard](https://grafana.com/grafana/dashboards/13687).

<!-- Links -->

[Start Teku]: https://docs.teku.consensys.net/how-to/use-external-signer/use-web3signer
[Grafana]: https://grafana.com/docs/grafana/latest/guides/getting_started/

---

## Run Web3Signer at scale


When running Web3Signer at scale with hundreds or thousands of keys, several factors affect attestation
performance on validators. Horizontal scaling reduces request latency on Web3Signer. To maintain low
signing latency and high safety, connect multiple Web3Signer instances to the same slashing database.

The primary performance cost occurs during startup. More keys increase Web3Signer's startup time, representing
a one-time cost per restart.

When configuring your environment, consider the startup delay, the number of keys managed, and available system
resources.

Balancing these factors optimizes system performance and responsiveness. Regular monitoring and tuning
are necessary as the number of managed keys grows or network conditions change.

## Database proximity

The [slashing database](./configure-slashing-protection.md) ensures the safe management of multiple
validators. Optimizing the slashing database reduces latency and overhead, improving overall system performance.

- **Reduced geographic latency**: Strategically place Web3Signer instances to ensure minimal distance to the slashing protection database.
- **Performance tuning**: Optimize database configurations for rapid access, considering factors such as indexing and connection pooling.

## Threading model optimization

Web3Signer uses [Vertx](https://vertx.io/docs/vertx-core/java/) as its threading framework. While powerful,
Vertx requires proper configuration for optimal performance in different environments. If you encounter
request latency or blocked threads, adjust the [worker pool size](../reference/cli/options.md#vertx-worker-pool-size).

To manage concurrency, tailor Web3Signer's thread pool size to your expected load. Increase the pool
size if you observe decreased attestation performance during peak signing loads.

You can implement monitoring tools for dynamic thread adjustments based on current demand and workload.
Measure spikes and adjust the pool accordingly.

You can use the following [metrics](./monitor/metrics.md):

- `http_vertx_worker_queue_delay`: The request queue waiting time before processing.
- `http_vertx_worker_pool_completed_total`: The number of queries processed by Web3Signer.

## Load balancing

At scale, deploy multiple Web3Signer instances behind a load balancer. This setup ensures balanced
request distribution. Use an ingress load balancer to spread requests evenly across instances. This
prevents overloading of single instances. Connect all Web3Signer instances to the same slashing database.
This allows parallel signing without slashing risk.

For more information, see
the [Kiln article](https://www.kiln.fi/post/learnings-from-running-web3signer-at-scale-on-holesky) on
running Web3Signer at scale.

## Hardware recommendations

The Web3Signer team runs nodes managing 10,000 keys on various testnets. For example, a single Azure
Standard D8as v5 VM (8 vCPUs, 32 GiB memory) can host Besu, Teku, and Web3Signer simultaneously.
Your specific use case might require less powerful hardware.

![Dashboard for Web3Signer](/img/dashboard_hw.png)

Web3Signer consumes less than 2 GB of JVM heap while managing 10,000 keys in this setup.

The test configuration connects one validator client to Web3Signer. Using multiple validator
clients might change resource requirements. Distributing the same 10,000 keys across multiple clients
maintains the total number of requests to Web3Signer.

---

## Store signing keys


Web3Signer supports BLS12-381 (`Eth2`) or secp256k1 (`Eth1`) signing keys stored in the following ways:

| Key storage                          | SECP256K1     | BLS          |
|--------------------------------------|:-------------:|:------------:|
| Raw files                            | <Supported /> | <Supported /> |
| [Keystore files]                     | <Supported /> | <Supported /> |
| **Vaults**                           |               |              |
| [Hashicorp Vault]                    | <Supported /> | <Supported /> |
| [Azure Key Vault]                    | <Supported /> | <Supported /> |
| [AWS Secrets Manager]                |               | <Supported /> |
| [AWS KMS]                            | <Supported /> |               |
| [GCP Secret Manager]                 |               | <Supported /> |

Web3Signer supports `Eth1` signing from vaults, but must load private keys into memory for `Eth2` signing.
Follow [best practices](../../get-started/key-best-practices.md) when storing private keys.

After storing keys, [load keys into Web3Signer](../load-keys.md).

<!-- links -->

[Keystore files]: https://github.com/ethereum/EIPs/blob/master/EIPS/eip-2335.md
[HashiCorp Vault]: vaults/hashicorp.md
[Azure Key Vault]: vaults/azure.md
[AWS Secrets Manager]: vaults/aws/secrets-manager-consensus-layer.md
[AWS KMS]: vaults/aws/kms-execution-layer.md
[GCP Secret Manager]: vaults/gcp.md

---

## Use Web3Signer with AWS Key Management Service


Web3Signer supports execution layer signing with secp256k1 keys stored in
[AWS Key Management Service (KMS)](https://aws.amazon.com/kms/).

The [AWS KMS documentation](https://aws.amazon.com/kms/getting-started/)
provides the information you need to get started.

## Load keys from AWS KMS

Keys stored in AWS KMS can be loaded into Web3Signer by:

* Using a [key configuration file](../../../load-keys.md#use-key-configuration-files).
* Bulk loading using the [`eth1` subcommand](../../../load-keys.md#aws-key-management-service).

## Cache AWS KMS when loading multiple keys

When loading multiple keys from AWS KMS, the AWS client is created each time.
You can improve performance by caching and reusing the same AWS KMS for each key that
uses the same access key ID and region.

Set the [`eth1 --aws-connection-cache-size`](../../../../reference/cli/subcommands.md#aws-connection-cache-size-1)
option to the maximum number of AWS KMS connections to cache.
The default is `1`.

---

## Use Web3Signer with AWS Secrets Manager


Web3Signer supports consensus layer signing with BLS private keys stored as secrets in [AWS Secrets
Manager](https://aws.amazon.com/secrets-manager/).

The [AWS Secrets Manager documentation](https://docs.aws.amazon.com/secretsmanager/latest/userguide/intro.html)
provides the information you need to get started.

## Store a private key in AWS Secrets Manager

You need an AWS profile to use AWS Secrets Manager.

Use the [Create a secret](https://docs.aws.amazon.com/secretsmanager/latest/userguide/manage_create-basic-secret.html)
guide to store a new key in AWS Secrets Manager.

The following is an example of creating and storing a BLS private key in AWS Secrets Manager, using Java:

```java
final String AWS_REGION = "us-east-2";
final String SECRET_VALUE = "0x60b420####################################################25f41d";
final SecretsManagerClient secretsManagerClient =
      SecretsManagerClient.builder()
          .region(Region.of(AWS_REGION))
          .build();
final String secretNamePrefix = "web3signer-aws-integration/";
final String secretName = secretNamePrefix + UUID.randomUUID();
final CreateSecretRequest secretRequest =
      CreateSecretRequest.builder().name(secretName).secretString(SECRET_VALUE).build();
secretsManagerClient.createSecret(secretRequest);
```

You can also store multiple BLS private keys under same secret name when using
[AWS bulk loading mode](../../../load-keys.md#aws-secrets-manager).

The keys must be separated with a line terminating character such as `\n`.
This saves cost when dealing with a large number of keys. Up to 200 keys can be stored under same
secret name.

The following Java program modifies the previous example to store two BLS keys under same secret name:

```java
final String AWS_REGION = "us-east-2";
final String SECRET_VALUE = "0x60b420####################################################25f41d\n" +
           "0x73d51a####################################################85aba8";
final SecretsManagerClient secretsManagerClient =
      SecretsManagerClient.builder()
          .region(Region.of(AWS_REGION))
          .build();
final String secretNamePrefix = "web3signer-aws-integration/";
final String secretName = secretNamePrefix + UUID.randomUUID();
final CreateSecretRequest secretRequest =
      CreateSecretRequest.builder().name(secretName).secretString(SECRET_VALUE).build();
secretsManagerClient.createSecret(secretRequest);
```

Specify the following when [configuring the signing key configuration file](../../../load-keys.md#use-key-configuration-files):

- Authentication mode.
  Valid options are `ENVIRONMENT` and `SPECIFIED`.
  If using `ENVIRONMENT`, credentials are authenticated using the [default credential provider
  chain](https://docs.aws.amazon.com/sdk-for-java/v1/developer-guide/credentials.html#credentials-default).
- Secret name.
- Region to connect to.

## Cache AWS Secrets Manager when loading multiple keys

When loading multiple keys from AWS Secrets Manager, the AWS client is created each time.
You can improve performance by caching and reusing the same AWS Secrets Manager for each key that
uses the same access key ID and region.

Set the [`eth2 --aws-connection-cache-size`](../../../../reference/cli/subcommands.md#aws-connection-cache-size)
option to the maximum number of AWS Secrets Manager connections to cache.
The default is `1`.

After storing keys, [load keys into Web3Signer using a key configuration file, or bulk loading keys](../../../load-keys.md).

---

## Use Web3Signer with Azure Key Vault


Web3Signer supports using [Azure Key Vault](https://azure.microsoft.com/en-au/services/key-vault/)
to sign payloads in the following ways:

- Using Azure Key Vault to perform the signing operation. Supports SECP256K1 signing keys only.
- Fetching the keys from Azure Key Vault and signing locally.

Web3Signer supports the following authentication modes:

- [Azure Active Directory managed identity]:
  - System-assigned identities
  - User-assigned identities
- [Client secret].

:::info Important
The Azure Active Directory managed identity authentication modes can only be used when fetching keys
from Azure Key Vault and signing locally with Web3Signer.
:::

## Store a private key in Azure Key Vault

[Register Web3Signer as an application] and [add a signing key in Azure Key Vault].

Take note of the following to specify when [configuring the signing key configuration file] or
[bulk loading signing keys]:

- Vault name, which is part of the URL (for example `https://<vaultname>.vault.azure.net`).
- Client credentials, which can include:
  - Client ID
  - Client secret
  - Tenant ID

:::note
Depending on the authentication mode, not all client credentials are available.
:::

- Key name, which is the name of the secret.

After storing keys, [load keys into Web3Signer using a key configuration file, or bulk loading keys](../../load-keys.md).

<!-- links -->

[configuring the signing key configuration file]: ../../load-keys.md#use-key-configuration-files
[bulk loading signing keys]: ../../load-keys.md#azure-key-vault
[Register Web3Signer as an application]: https://docs.microsoft.com/en-us/azure/key-vault/general/authentication
[add a signing key in Azure Key Vault]: https://docs.microsoft.com/en-us/azure/key-vault/secrets/quick-create-portal#add-a-secret-to-key-vault
[Client secret]: https://docs.microsoft.com/en-us/azure/key-vault/secrets/about-secrets
[Azure Active Directory managed identity]: https://docs.microsoft.com/en-us/azure/app-service/overview-managed-identity?tabs=dotnet

---

## Use Web3Signer with Google Cloud Platform Secret Manager


Web3Signer supports consensus layer signing with BLS keys stored in
[Google Cloud Platform (GCP) Secret Manager](https://cloud.google.com/secret-manager).

The [GCP Secret Manager documentation](https://cloud.google.com/secret-manager/docs)
provides the information you need to get started.

## Authentication

Web3Signer uses [Application Default Credentials (ADC)](https://cloud.google.com/docs/authentication#adc)
to authenticate with GCP Secret Manager. ADC automatically finds credentials and manages token retrieval, enabling
the authentication code to operate across various deployment options without modification.

## Load keys from GCP Secret Manager

Load keys stored in GCP Secret Manager into Web3Signer using the [`eth2` subcommand](../../load-keys.md#gcp-secret-manager)
to bulk load keys.

---

## Use Web3Signer with HashiCorp Vault


Web3Signer supports storing the signing key in [HashiCorp Vault](https://www.hashicorp.com/en/products/vault).

## Store a private key in HashiCorp Vault

After installing [HashiCorp Vault](https://learn.hashicorp.com/vault/getting-started/install) and
[starting the server](https://learn.hashicorp.com/vault/getting-started/dev-server):

<!-- markdownlint-disable -->

1. Set the `VAULT_ADDR` environment variable using the command displayed after starting the server:

   ```bash
   export VAULT_ADDR='http://127.0.0.1:8200'
   ```

2. Copy or save the root token displayed after starting the server in a file.

3. Enable the secret mount point using [KV v2 engine](https://www.vaultproject.io/docs/secrets/kv/kv-v2).
   Using Vault CLI, enable the KV v2 `secret` mount point:

   ```bash
   vault secrets enable -path=secret kv-v2
   ```

   :::note
   Use `kv-v2` type as indicated in KV v2 doc. Web3Signer only works with v2 secrets.
   :::

   If the engine used is V2, the secret is versioned and you can see the metadata with version field:

   ```bash
   vault kv get /secret/web3signerSigningKey
   ```

<Tabs>

   <TabItem value="Result if v2 (with metadata)" label="Result if v2 (with metadata)" default>

   ```text
   ====== Metadata ======
   Key              Value
   ---              -----
   created_time     2020-11-27T10:15:59.91752Z
   deletion_time    n/a
   destroyed        false
   version          1

   ==== Data ====
   Key      Value
   ---      -----
   value    17079f966aa2d5db1678ed32467165bbbd640868e7371ade8d5812ea856d2bbf
   ```

   </TabItem>
   <TabItem value="Result if v1" label="Result if v1" >

   ```text
   ==== Data ====
   Key      Value
   ---      -----
   value    17079f966aa2d5db1678ed32467165bbbd640868e7371ade8d5812ea856d2bbf
   ```

  </TabItem>
</Tabs>

4. [Write the key in HashiCorp Vault](https://learn.hashicorp.com/vault/getting-started/first-secret)
   as a hex string (without `0x` prefix):

<Tabs>

  <TabItem value="Command" label="Command" default>

   ```bash
   vault kv put secret/web3signerSigningKey value=<Private Key without 0x prefix>
   ```

  </TabItem>
  <TabItem value="Example" label="Example" >

   ```bash
   vault kv put secret/web3signerSigningKey value=17079f966aa2d5db1678ed32467165bbbd640868e7371ade8d5812ea856d2bbf
   ```

  </TabItem>
</Tabs>

## Create the known servers file

The known servers file is required if TLS is enabled, to disable TLS set
[`tlsEnabled`](../../../reference/key-config-file-params.md#hashicorp-vault) to `false`.

Specify the location of the known servers file in the
[`tlsKnownServersPath`](../../../reference/key-config-file-params.md#hashicorp-vault) option of the
[signing key configuration file].

The file contents use the format `<hostname>:<port> <hex-string>` where:

- `<hostname>` is the server hostname.
- `<port>` is the port used for communication.
- `<hex-string>` is the SHA-256 fingerprint of the server's certificate.

```
localhost:8200 7C:B3:3E:F9:98:43:5E:62:69:9F:A9:9D:41:14:03:BA:83:24:AC:04:CE:BD:92:49:1B:8D:B2:A4:86:39:4C:BB
127.0.0.1:8200 7C:B3:3E:F9:98:43:5E:62:69:9F:A9:9D:41:14:03:BA:83:24:AC:04:CE:BD:92:49:1B:8D:B2:A4:86:39:4C:BB
```

[Start Web3Signer and specify the location of the signing key configuration file].

<!-- Links -->

[signing key configuration file]: ../../load-keys.md#use-key-configuration-files
[Start Web3Signer and specify the location of the signing key configuration file]: ../../../get-started/start-web3signer.md

<!-- markdownlint-enable -->

---

## Use the Web3Signer configuration file


Use a YAML configuration file to specify command line options in a file.

Save the configuration file and reuse it across node startups. Use the
[`--config-file`](../reference/cli/options.md#config-file) option to specify the configuration file location.

To override an option specified in the configuration file, either specify the same option on the
command line or as an [environment variable](../reference/cli/options.md#specify-options).
For options specified in more than one place, the order of precedence is command line, environment
variable, configuration file.

## YAML specification

The configuration file must be a valid YAML file composed of key/value pairs.
Each key is the same as the corresponding command line option name without the leading dashes (`--`).
For [subcommand options], prefix the key with the name of the subcommand.
For example, `eth1.network=<NETWORK>`

:::info
You can't specify subcommands in the configuration file, you can only specify a subcommand's
associated options.
You must specify the signing key subcommand on the command line.
:::

Values must conform to YAML specifications for string, numbers, arrays, and booleans.
Specific differences between the command line and the YAML file format are:

- Comma-separated lists on the command line are string arrays in the YAML file.
- Enclose file paths, hexadecimal numbers, URLs, and &lt;host:port> values in quotes.

:::tip
The [command line reference](../reference/cli/options.md) includes configuration file examples for each option.
:::

```yaml title="Sample YAML configuration file"
# Chain
eth1.chain-id: 2017

# Signing key locations
key-store-path: "/Users/me/keys"
```

Start Web3Signer with a configuration file:

```bash
web3signer --config-file=/home/me/config.yaml eth1
```

<!-- links -->

[subcommand options]: ../reference/cli/subcommands.md

---

## Load Launchpad keystores


The Staking Launchpad tool is used to create validators that participate in the consensus layer
proof-of-stake network. The tool generates an encrypted keystore file containing the validator details.
Load this keystore into Web3Signer to sign attestations and blocks with the validator details.

This tutorial uses Teku and Web3Signer to run validators created on the `holesky` testnet.

**Prerequisites**:

- [Teku installed].
- [Web3Signer installed].
- Web3Signer [slashing protection database].

## 1. Sync the Teku beacon node

Sync the Teku beacon chain node before submitting your deposit to avoid incurring inactivity
penalties if the validator is unable to perform its duties when the deposit is processed and activated.

```bash
teku --network=holesky --metrics-enabled --rest-api-enabled
```

## 2. Generate validators

This step generates a validator on the `holesky` testnet.
Use the [Holeksy Staking Launchpad](https://holesky.launchpad.ethereum.org/en/) and follow the
step-by-step process to deposit your funds and generate the keystore.

The process includes installing the consensus layer deposit CLI tool, to generate your validator
keystores locally.
Keystores are generated in the `eth2deposit-cli-<version>/validator_keys` folder.
In this example we generated a keystore named `keystore-m_12381_3600_0_0_0-1606109670.json`

:::caution important
Remember the password used to create the keystore because you'll need it later.
:::

## 3. Create password file

Create a plain text file that stores the password to decrypt the keystore.
In this example we create the `keystore-m_12381_3600_0_0_0-1606109670.txt` file in the
`eth2deposit-cli-<version>/validator_keys` directory:

```txt title="keystore-m_12381_3600_0_0_0-1606109670.txt"
validatorPassword
```

:::note
If using Linux or macOS, we recommend setting the file ownership and permission to `400` for
the user running Web3Signer.
:::

## 4. Create the key configuration file

Create a [key configuration file] for each keystore file.
The key configuration file defines the type of signing key being used, and access details.
Store all key configuration files in a single directory.
In this example, the files are stored in `Users/me/keys`:

```yaml title="validator.yaml"
type: "file-keystore"
keystoreFile: "/Users/me/eth2deposit-cli-ed5a6d3-darwin-amd64/validator_keys/validator_keys/keystore-m_12381_3600_0_0_0-1606109670.json"
keystorePasswordFile: "/Users/me/eth2deposit-cli-ed5a6d3-darwin-amd64/validator_keys/validator_keys/keystore-m_12381_3600_0_0_0-1606109670.txt"
```

:::caution important
The configuration files must be YAML-formatted.
You can use any naming format, but it must have the `.yaml` extension.
:::

## 5. Start Web3Signer

Start Web3Signer and specify the location of the key configuration files and [slashing protection database].

```bash
web3signer --key-store-path=/Users/me/keys eth2 --network=holesky --slashing-protection-db-url="jdbc:postgresql://localhost/web3signer" --slashing-protection-db-username=postgres --slashing-protection-db-password=password
```

:::note
Set the [`--slashing-protection-enabled`](../reference/cli/subcommands.md#slashing-protection-enabled)
`eth2` subcommand option to `false` to disable slashing protection.
However, we don't recommend this on Mainnet.
:::

## 5. Start Teku

Start Teku and specify the public keys of the validators that Web3Signer signs attestations and
blocks for, and specify the Web3Signer address.

```bash
teku --network=holesky \
--eth1-endpoint=http://localhost:8545 \
--validators-external-signer-public-keys=0xa99a...e44c,0xb89b...4a0b \
--validators-external-signer-url=http://localhost:9000
```

<!-- links -->

[Teku installed]: https://docs.teku.consensys.net/get-started/install/install-binaries
[Web3Signer installed]: ../get-started/install-binaries.md
[slashing protection database]: ../how-to/configure-slashing-protection.md
[key configuration file]: ../reference/key-config-file-params.md

---

## Web3Signer JSON-RPC API


<!-- markdownlint-disable-file -->

:::note
- All JSON-RPC HTTP examples use the default host and port endpoint `http://127.0.0.1:8545`.
- The examples use Besu, but you can use any Ethereum execution client.
:::

## `eth_accounts`

Returns the account address with which Web3Signer is signing transactions.

Returns multiple accounts if multiple signers are configured.

### Parameters

None

### Returns

`Array of data` - Account address with which Web3Signer is signing transactions

<Tabs>

  <TabItem value="curl HTTP request" label="curl HTTP request" default>

```bash
curl -X POST --data '{"jsonrpc":"2.0","method":"eth_accounts","params":[],"id":1}' http://127.0.0.1:8545
```

  </TabItem>
  <TabItem value="JSON result" label="JSON result" >

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": ["0xfe3b557e8fb62b89f4916b721be55ceb828dbd73"]
}
```

  </TabItem>
</Tabs>

## `eth_sign`

Calculates an Ethereum specific signature using
`sign(keccak256("\x19Ethereum Signed Message:\n" + len(message) + message)))."`

Adds a prefix to the message that makes the calculated signature recognizable as an Ethereum
specific signature.
This prevents malicious dapps from signing arbitrary data (for example, a transaction) and using the
signature to impersonate the victim.

### Parameters

`DATA` - 20-byte account address

`DATA` - Data string to sign

### Returns

`DATA` - Signature

<Tabs>

  <TabItem value="curl HTTP request" label="curl HTTP request" default>

```bash
curl -X POST --data '{"jsonrpc":"2.0","method":"eth_sign","params":["0x78e6e236592597c09d5c137c2af40aecd42d12a2", "0x2eadbe1f"], "id":1}' http://127.0.0.1:8545
```

  </TabItem>
  <TabItem value="JSON result" label="JSON result" >

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": "0xa6122e277f46fea78f3e97d3354a03ad20b2296733dfefbadc7305c80e70ce9826d44f12ab5aa488689744657491c70d3b654d7f60f8f50beefac9abcf02a4cf1b"
}
```

  </TabItem>
</Tabs>

## `eth_signTransaction`

Signs a transaction that you can submit to Besu at a later time using
[`eth_sendRawTransaction`](https://besu.hyperledger.org/public-networks/reference/api#eth_sendrawtransaction).

### Parameters

Transaction object:

| Key | Type | Required/Optional | Value |
| --- | :-- | --- | --- |
| `from` | Data, 20&nbsp;bytes | Required | Address of the sender. |
| `to` | Data, 20&nbsp;bytes | Optional for contract creation | Address of the receiver. `null` if this is a contract creation transaction. |
| `gas` | Quantity | Optional | Gas provided by the sender. The default is `90000`. |
| `gasPrice` | Quantity | Optional | Gas price provided by the sender in Wei. The default is `0`. Used only in non [EIP-1559] transactions. |
| `maxPriorityFeePerGas` | Quantity | Optional | Maximum fee, in Wei, the sender is willing to pay above the base fee. Used only in [EIP-1559] transactions. |
| `maxFeePerGas` | Quantity | Optional | Maximum total fee (base fee + priority fee), in Wei, the sender is willing to pay. Used only in [EIP-1559] transactions. |
| `nonce` | Quantity | Optional | Number of transactions made by the sender before this one. |
| `value` | Quantity | Optional | Value transferred in Wei. |
| `data` | Quantity | Optional | Compiled contract code or hash of the invoked method signature and encoded parameters. |

### Returns

`result` : `data` - The signed transaction object.

<!-- markdownlint-disable -->

<Tabs>

  <TabItem value="curl HTTP request" label="curl HTTP request" default>

```bash
curl -X POST --data '{"jsonrpc":"2.0","method":"eth_signTransaction","params":[{"from": "0xfe3b557e8fb62b89f4916b721be55ceb828dbd73","to": "0xd46e8dd67c5d32be8058bb8eb970870f07244567","gas": "0x7600","gasPrice": "0x9184e72a000","value": "0x9184e72a", "nonce":"0x46"}], "id":1}' http://127.0.0.1:8545
```

  </TabItem>
  <TabItem value="JSON result" label="JSON result" >

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": "0xa3f20717a250c2b0b729b7e5becbff67fdaef7e0699da4de7ca5895b02a170a12d887fd3b17bfdce3481f10bea41f45ba9f709d39ce8325427b57afcfc994cee1b"
}
```

  </TabItem>
</Tabs>

## `eth_signTypedData`

`eth_signTypedData` is the same as `ethsign` except a typed data structure is specified
as the object to be signed instead of a data string.

Calculates an Ethereum specific signature using
`sign(keccak256("\x19Ethereum Signed Message:\n" + len(message) + message)))."`

Adds a prefix to the message that makes the calculated signature recognizable as an Ethereum
specific signature.
This prevents malicious dapps from signing arbitrary data (for example, a transaction) and using the
signature to impersonate the victim.

The JSON schema for the typed data structure to sign is:

```json
{
  type: 'object',
  properties: {
    types: {
      type: 'object',
      properties: {
        EIP712Domain: {type: 'array'},
      },
      additionalProperties: {
        type: 'array',
        items: {
          type: 'object',
          properties: {
            name: {type: 'string'},
            type: {type: 'string'}
          },
          required: ['name', 'type']
        }
      },
      required: ['EIP712Domain']
    },
    primaryType: {type: 'string'},
    domain: {type: 'object'},
    message: {type: 'object'}
  },
  required: ['types', 'primaryType', 'domain', 'message']
}
```

### Parameters

`DATA` - 20-byte account address

`TYPEDDATA` - Typed data structure to sign

### Returns

`DATA` - Signature

<!-- markdownlint-disable -->

<Tabs>

  <TabItem value="curl HTTP request" label="curl HTTP request" default>

```bash
curl -X POST --data '{"jsonrpc":"2.0","method":"eth_signTypedData","params":["0xCD2a3d9F938E13CD947Ec05AbC7FE734Df8DD826", {"types":{"EIP712Domain":[{"name":"name","type":"string"},{"name":"version","type":"string"},{"name":"chainId","type":"uint256"},{"name":"verifyingContract","type":"address"}],"Person":[{"name":"name","type":"string"},{"name":"wallet","type":"address"}],"Mail":[{"name":"from","type":"Person"},{"name":"to","type":"Person"},{"name":"contents","type":"string"}]},"primaryType":"Mail","domain":{"name":"Ether Mail","version":"1","chainId":1,"verifyingContract":"0xCcCCccccCCCCcCCCCCCcCcCccCcCCCcCcccccccC"},"message":{"from":{"name":"Cow","wallet":"0xCD2a3d9F938E13CD947Ec05AbC7FE734Df8DD826"},"to":{"name":"Bob","wallet":"0xbBbBBBBbbBBBbbbBbbBbbbbBBbBbbbbBbBbbBBbB"},"contents":"Hello, Bob!"}}],"id":1}'
```

  </TabItem>
  <TabItem value="JSON result" label="JSON result" >

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": "0x4355c47d63924e8a72e509b65029052eb6c299d53a04e167c5775fd466751c9d07299936d304c153f6443dfa05f40ff007d72911b6f72307f996231605b915621c"
}
```

  </TabItem>
</Tabs>

## `eth_sendTransaction`

Creates and signs a transaction using the signing key.

Web3Signer submits the signed transaction to Besu using
[`eth_sendRawTransaction`](https://besu.hyperledger.org/public-networks/reference/api#eth_sendrawtransaction).

### Parameters

Transaction object:

| Key | Type | Required/Optional | Value |
| --- | :-- | --- | --- |
| `from` | Data, 20&nbsp;bytes | Required | Address of the sender. |
| `to` | Data, 20&nbsp;bytes | Optional for contract creation | Address of the receiver. `null` if this is a contract creation transaction. |
| `gas` | Quantity | Optional | Gas provided by the sender. The default is `90000`. |
| `gasPrice` | Quantity | Optional | Gas price provided by the sender in Wei. The default is `0`. Used only in non [EIP-1559] transactions. |
| `maxPriorityFeePerGas` | Quantity | Optional | Maximum fee, in Wei, the sender is willing to pay above the base fee. Used only in [EIP-1559] transactions. |
| `maxFeePerGas` | Quantity | Optional | Maximum total fee (base fee + priority fee), in Wei, the sender is willing to pay. Used only in [EIP-1559] transactions. |
| `nonce` | Quantity | Optional | Number of transactions made by the sender before this one. |
| `value` | Quantity | Optional | Value transferred in Wei. |
| `data` | Quantity | Optional | Compiled contract code or hash of the invoked method signature and encoded parameters. |

:::tip

Submitting a transaction with the same nonce as a pending transaction and a higher gas price replaces the pending transaction with the new one.

:::

### Returns

`result` : `data` - 32-byte transaction hash

<Tabs>

  <TabItem value="curl HTTP request" label="curl HTTP request" default>

```bash
curl -X POST --data '{"jsonrpc":"2.0","method":"eth_sendTransaction","params":[{"from": "0xfe3b557e8fb62b89f4916b721be55ceb828dbd73","to": "0xd46e8dd67c5d32be8058bb8eb970870f07244567","gas": "0x7600","gasPrice": "0x9184e72a000","value": "0x9184e72a"}], "id":1}' http://127.0.0.1:8545
```

  </TabItem>
  <TabItem value="JSON result" label="JSON result" >

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": "0x6052dd2131667ef3e0a0666f2812db2defceaec91c470bb43de92268e8306778"
}
```

  </TabItem>
</Tabs>

<!--links-->

[EIP-1559]: https://eips.ethereum.org/EIPS/eip-1559

---

## Web3Signer REST API


The Web3Signer REST API exposes:

- **Consensus layer (ETH2) endpoints** — use these to sign consensus layer payloads.
- **Execution layer (ETH1) endpoints** — **basic** signing only; they do **not** perform transaction
    encoding or return a full Ethereum transaction signature.

:::info Recommendation
For execution layer transactions, use the [Web3Signer JSON-RPC API](json-rpc.md) instead of the ETH1 REST endpoints.
:::

## Access the REST API

Web3Signer serves HTTP requests on a configurable host and port. The default base URL is
`http://localhost:9000`, you can configure the default base URL by setting:

- [`--http-listen-host`](../cli/options.md#http-listen-host) to the required host.
- [`--http-listen-port`](../cli/options.md#http-listen-port) to the required port

:::info Important
Your hostname must be added to the [allowlist](../cli/options.md#http-host-allowlist) to call the
REST APIs.
:::

## API reference

View the [REST API documentation] for more information about the available APIs.

<!-- Links -->

[REST API documentation]: https://consensys.github.io/web3signer/

---

## Web3Signer command line options


This reference describes the syntax of the Web3Signer Command Line Interface (CLI) options.

## Specify options

Web3Signer options can be specified:

- On the command line.
- As an environment variable. For each command line option, the equivalent environment variable is:
  - Upper-case.
  - `_` replaces `-`.
  - Has a `WEB3SIGNER_` prefix.
- In a YAML configuration file.

If you specify an option in more than one place, the order of priority is command line, environment
variable, configuration file.

## Options

### `access-logs-enabled`

<Tabs>

  <TabItem value="Syntax" label="Syntax" default>

```bash
--access-logs-enabled[=<BOOLEAN>]
```

  </TabItem>
  <TabItem value="Example" label="Example" >

```bash
--access-logs-enabled=true
```

  </TabItem>
  <TabItem value="Environment variable" label="Environment variable" >

```bash
WEB3SIGNER_ACCESS_LOGS_ENABLED=true
```

  </TabItem>
  <TabItem value="Configuration file" label="Configuration file" >

```bash
access-logs-enabled-enabled: true
```

  </TabItem>
</Tabs>

Enables or disables access logs.
The default is `false`.

### `config-file`

Path to the [YAML configuration file](../../how-to/use-configuration-file-starting-web3signer.md).
The default is `none`.

<Tabs>
  <TabItem value="Syntax" label="Syntax" default>

```bash
--config-file=<FILE>
```

  </TabItem>
  <TabItem value="Example" label="Example" >

```bash
--config-file=/home/me/me_node/config.yaml
```

  </TabItem>
  <TabItem value="Environment variable" label="Environment variable" >

```bash
WEB3SIGNER_CONFIG_FILE=/home/me/me_node/config.yaml
```

  </TabItem>
</Tabs>

### `data-path`

<Tabs>

  <TabItem value="Syntax" label="Syntax" default>

```bash
--data-path=<PATH>
```

  </TabItem>
  <TabItem value="Example" label="Example" >

```bash
--data-path=/Users/me/my_node/data
```

  </TabItem>
  <TabItem value="Environment variable" label="Environment variable" >

```bash
WEB3SIGNER_DATA_PATH=/Users/me/my_node/data
```

  </TabItem>
  <TabItem value="Configuration file" label="Configuration file" >

```bash
data-path: "/Users/me/my_node/data"
```

  </TabItem>
</Tabs>

Directory in which to store temporary files.

### `http-cors-origins`

<Tabs>

  <TabItem value="Syntax" label="Syntax" default>

```bash
--http-cors-origins=<httpListenHost>
```

  </TabItem>
  <TabItem value="Example" label="Example" >

```bash
--http-cors-origins=""http://medomain.com"
```

  </TabItem>
  <TabItem value="Environment variable" label="Environment variable" >

```bash
WEB3SIGNER_HTTP_CORS_ORIGINS=""http://medomain.com"
```

  </TabItem>
  <TabItem value="Configuration file" label="Configuration file" >

```bash
http-cors-origins=["https://meotherdomain.com"]
```

  </TabItem>
</Tabs>

A list of domain URLs for CORS validation.
You must enclose the URLs in double quotes and separate them with commas.

Listed domains can access the node using REST API.
If your client interacts with Web3Signer using a browser app, you must allow the client domains.

The default value is `none`.
If you do not allow any domains, browser apps cannot interact with your Web3Signer node.

:::tip
For testing and development purposes, use `"all"` or `"*"` to accept requests from any domain.
We don't recommend accepting requests from any domain for production environments.
:::

### `http-listen-host`

<Tabs>

  <TabItem value="Syntax" label="Syntax" default>

```bash
--http-listen-host=<httpListenHost>
```

  </TabItem>
  <TabItem value="Example" label="Example" >

```bash
--http-listen-host=8.8.8.8
```

  </TabItem>
  <TabItem value="Environment variable" label="Environment variable" >

```bash
WEB3SIGNER_HTTP_LISTEN_HOST=8.8.8.8
```

  </TabItem>
  <TabItem value="Configuration file" label="Configuration file" >

```bash
http-listen-host: "8.8.8.8"
```

  </TabItem>
</Tabs>

Host on which HTTP listens.
The default is `localhost`.

### `http-listen-port`

<Tabs>

  <TabItem value="Syntax" label="Syntax" default>

```bash
--http-listen-port=<httpListenPort>
```

  </TabItem>
  <TabItem value="Example" label="Example" >

```bash
--http-listen-port=6174
```

  </TabItem>
  <TabItem value="Environment variable" label="Environment variable" >

```bash
WEB3SIGNER_HTTP_LISTEN_PORT=6174
```

  </TabItem>
  <TabItem value="Configuration file" label="Configuration file" >

```bash
http-listen-port: 6174
```

  </TabItem>
</Tabs>

Port on which HTTP listens.
The default is 9000.

### `http-host-allowlist`

<Tabs>

  <TabItem value="Syntax" label="Syntax" default>

```bash
--http-host-allowlist=<hostname>[,<hostname>...]... or "*"
```

  </TabItem>
  <TabItem value="Example" label="Example" >

```bash
--http-host-allowlist=medomain.com,meotherdomain.com
```

  </TabItem>
  <TabItem value="Environment variable" label="Environment variable" >

```bash
WEB3SIGNER_HTTP_HOST_ALLOWLIST=medomain.com,meotherdomain.com
```

  </TabItem>
  <TabItem value="Configuration file" label="Configuration file" >

```bash
http-host-allowlist: ["medomain.com", "meotherdomain.com"]
```

  </TabItem>
</Tabs>

A comma-separated list of hostnames to allow access to the REST APIs.
By default, Web3Signer accepts access from `localhost` and `127.0.0.1`.

:::tip
To allow all hostnames, use `"*"`.
We don't recommend allowing all hostnames for production environments.
:::

### `idle-connection-timeout-seconds`

<Tabs>

  <TabItem value="Syntax" label="Syntax" default>

```bash
--idle-connection-timeout-seconds=<TIMEOUT>
```

  </TabItem>
  <TabItem value="Example" label="Example" >

```bash
--idle-connection-timeout-seconds=60
```

  </TabItem>
  <TabItem value="Environment variable" label="Environment variable" >

```bash
WEB3SIGNER_IDLE_CONNECTION_TIMEOUT_SECONDS=60
```

  </TabItem>
  <TabItem value="Configuration file" label="Configuration file" >

```bash
idle-connection-timeout-seconds: 60
```

  </TabItem>
</Tabs>

Number of seconds to wait before terminating an idle connection.
The default is 30.

### `key-config-path`, `key-store-path`

<Tabs>

  <TabItem value="Syntax" label="Syntax" default>

```bash
--key-config-path=<PATH>
```

  </TabItem>
  <TabItem value="Example" label="Example" >

```bash
--key-config-path=/Users/me/keys
```

  </TabItem>
  <TabItem value="Environment variable" label="Environment variable" >

```bash
WEB3SIGNER_KEY_CONFIG_PATH=/Users/me/keys
```

  </TabItem>
  <TabItem value="Configuration file" label="Configuration file" >

```bash
key-config-path: "/Users/me/keys"
```

  </TabItem>
</Tabs>

Path to the directory containing the [YAML files required to access keys].

### `key-store-config-file-max-size`

<Tabs>

  <TabItem value="Syntax" label="Syntax" default>

```bash
--key-store-config-file-max-size=<INTEGER>
```

  </TabItem>
  <TabItem value="Example" label="Example" >

```bash
--key-store-config-file-max-size=158000000
```

  </TabItem>
  <TabItem value="Environment variable" label="Environment variable" >

```bash
WEB3SIGNER_KEY_STORE_CONFIG_FILE_MAX_SIZE=158000000
```

  </TabItem>
  <TabItem value="Configuration file" label="Configuration file" >

```bash
key-store-config-file-max-size: 158000000
```

  </TabItem>
</Tabs>

The maximum signing key configuration file size in bytes.
This is useful when you're loading a large number of
[signing key configurations from a single file](../key-config-file-params.md)

The default size is 104857600 bytes (100 MB).

### `logging`

<Tabs>

  <TabItem value="Syntax" label="Syntax" default>

```bash
-l, --logging=<LEVEL>
```

  </TabItem>
  <TabItem value="Example" label="Example" >

```bash
--logging=DEBUG
```

  </TabItem>
  <TabItem value="Environment variable" label="Environment variable" >

```bash
WEB3SIGNER_LOGGING=DEBUG
```

  </TabItem>
  <TabItem value="Configuration file" label="Configuration file" >

```bash
logging: "DEBUG"
```

  </TabItem>
</Tabs>

Logging verbosity level.
Possible values are `OFF`, `FATAL`, `WARN`, `INFO`, `DEBUG`, `TRACE`, `ALL`.
The default is `INFO`.

### `logging-format`

<Tabs>

  <TabItem value="Syntax" label="Syntax" default>

```bash
--logging-format=<FORMAT>
```

  </TabItem>
  <TabItem value="Example" label="Example" >

```bash
--logging-format=ECS
```

  </TabItem>
  <TabItem value="Environment variable" label="Environment variable" >

```bash
WEB3SIGNER_LOGGING_FORMAT=ECS
```

  </TabItem>
  <TabItem value="Configuration file" label="Configuration file" >

```bash
logging-format: "ECS"
```

  </TabItem>
</Tabs>

Logging format.
This option includes standard JSON structured logging formats.
Possible values are:

- `PLAIN` (default) - Traditional pattern-based console logging
- `ECS` - Elastic Common Schema JSON format
- `GCP` - Google Cloud Platform JSON format
- `LOGSTASH` - Logstash JSON Event Layout V1
- `GELF` - Graylog Extended Log Format

This enables users to select the format without requiring custom Log4j2 configuration files.
This is useful in containerized and cloud environments where injecting configuration files is cumbersome.

### `metrics-enabled`

<Tabs>

  <TabItem value="Syntax" label="Syntax" default>

```bash
--metrics-enabled[=<BOOLEAN>]
```

  </TabItem>
  <TabItem value="Example" label="Example" >

```bash
--metrics-enabled=true
```

  </TabItem>
  <TabItem value="Environment variable" label="Environment variable" >

```bash
WEB3SIGNER_METRICS_ENABLED=true
```

  </TabItem>
  <TabItem value="Configuration file" label="Configuration file" >

```bash
metrics-enabled: true
```

  </TabItem>
</Tabs>

Enables the metrics exporter.
The default is `false`.

### `metrics-host`

<Tabs>

  <TabItem value="Syntax" label="Syntax" default>

```bash
--metrics-host=<HOST>
```

  </TabItem>
  <TabItem value="Example" label="Example" >

```bash
--metrics-host=186.10.10.1
```

  </TabItem>
  <TabItem value="Environment variable" label="Environment variable" >

```bash
WEB3SIGNER_METRICS_HOST=186.10.10.1
```

  </TabItem>
  <TabItem value="Configuration file" label="Configuration file" >

```bash
metrics-host: "186.10.10.1"
```

  </TabItem>
</Tabs>

The host on which [Prometheus](https://prometheus.io/) accesses metrics.
The default is `127.0.0.1`.

### `metrics-port`

<Tabs>

  <TabItem value="Syntax" label="Syntax" default>

```bash
--metrics-port=<PORT>
```

  </TabItem>
  <TabItem value="Example" label="Example" >

```bash
--metrics-port=6174
```

  </TabItem>
  <TabItem value="Environment variable" label="Environment variable" >

```bash
WEB3SIGNER_METRICS_PORT=6174
```

  </TabItem>
  <TabItem value="Configuration file" label="Configuration file" >

```bash
metrics-port: 6174
```

  </TabItem>
</Tabs>

The port (TCP) on which [Prometheus](https://prometheus.io/) accesses metrics.
The default is `9001`.

### `metrics-category`

<Tabs>

  <TabItem value="Syntax" label="Syntax" default>

```bash
--metrics-category=<metrics-category>[,metrics-category...]...
```

  </TabItem>
  <TabItem value="Example" label="Example" >

```bash
--metrics-category=HTTP,SIGNING,JVM
```

  </TabItem>
  <TabItem value="Environment variable" label="Environment variable" >

```bash
WEB3SIGNER_METRICS_CATEGORY=HTTP,SIGNING,JVM
```

  </TabItem>
  <TabItem value="Configuration file" label="Configuration file" >

```bash
metrics-category: ["HTTP", "SIGNING", "JVM"]
```

  </TabItem>
</Tabs>

A comma-separated list of categories for which to track metrics.
The defaults are `HTTP`, `SIGNING`, `ETH2_SLASHING_PROTECTION`, `JVM`, `PROCESS`.

### `metrics-host-allowlist`

<Tabs>

  <TabItem value="Syntax" label="Syntax" default>

```bash
--metrics-host-allowlist=<hostname>[,<hostname>...]... or "*"
```

  </TabItem>
  <TabItem value="Example" label="Example" >

```bash
--metrics-host-allowlist=medomain.com,meotherdomain.com
```

  </TabItem>
  <TabItem value="Environment variable" label="Environment variable" >

```bash
WEB3SIGNER_METRICS_HOST_ALLOWLIST=medomain.com,meotherdomain.com
```

  </TabItem>
  <TabItem value="Configuration file" label="Configuration file" >

```bash
metrics-host-allowlist: ["medomain.com", "meotherdomain.com"]
```

  </TabItem>
</Tabs>

A comma-separated list of hostnames to allow access to the [Web3Signer metrics].
By default, Web3Signer accepts access from `localhost` and `127.0.0.1`.

:::tip
To allow all hostnames, use `"*"`.
We don't recommend allowing all hostnames for production environments.
:::

### `metrics-push-enabled`

<Tabs>

  <TabItem value="Syntax" label="Syntax" default>

```bash
--metrics-push-enabled[=<true|false>]
```

  </TabItem>
  <TabItem value="Example" label="Example" >

```bash
--metrics-push-enabled=true
```

  </TabItem>
  <TabItem value="Environment variable" label="Environment variable" >

```bash
WEB3SIGNER_METRICS_PUSH_ENABLED=true
```

  </TabItem>
  <TabItem value="Configuration file" label="Configuration file" >

```bash
metrics-push-enabled=true
```

  </TabItem>
</Tabs>

Enables or disables [push gateway integration](../../how-to/monitor/metrics.md#run-prometheus-with-web3signer-in-push-mode).

You can't specify `--metrics-push-enabled` with [`--metrics-enabled`](#metrics-enabled). That is, you can enable either Prometheus polling or Prometheus push gateway support, but not both at once.

### `metrics-push-host`

<Tabs>

  <TabItem value="Syntax" label="Syntax" default>

```bash
--metrics-push-host=<HOST>
```

  </TabItem>
  <TabItem value="Example" label="Example" >

```bash
--metrics-push-host=127.0.0.1
```

  </TabItem>
  <TabItem value="Environment variable" label="Environment variable" >

```bash
WEB3SIGNER_METRICS_PUSH_HOST=127.0.0.1
```

  </TabItem>
  <TabItem value="Configuration file" label="Configuration file" >

```bash
metrics-push-host="127.0.0.1"
```

  </TabItem>
</Tabs>

The host of the [Prometheus Push Gateway](https://github.com/prometheus/pushgateway). The default is `127.0.0.1`. The metrics server respects the [`--metrics-host-allowlist` option](#metrics-host-allowlist).

:::note

When pushing metrics, ensure you set `--metrics-push-host` to the machine on which the push gateway is. Generally, this is a different machine to the machine on which Web3Signer is running.

:::

### `metrics-push-interval`

<Tabs>

  <TabItem value="Syntax" label="Syntax" default>

```bash
--metrics-push-interval=<INTEGER>
```

  </TabItem>
  <TabItem value="Example" label="Example" >

```bash
--metrics-push-interval=30
```

  </TabItem>
  <TabItem value="Environment variable" label="Environment variable" >

```bash
WEB3SIGNER_METRICS_PUSH_INTERVAL=30
```

  </TabItem>
  <TabItem value="Configuration file" label="Configuration file" >

```bash
metrics-push-interval=30
```

  </TabItem>
</Tabs>

The interval, in seconds, to push metrics when in `push` mode. The default is 15.

### `metrics-push-port`

<Tabs>

  <TabItem value="Syntax" label="Syntax" default>

```bash
--metrics-push-port=<PORT>
```

  </TabItem>
  <TabItem value="Example" label="Example" >

```bash
--metrics-push-port=6174
```

  </TabItem>
  <TabItem value="Environment variable" label="Environment variable" >

```bash
WEB3SIGNER_METRICS_PUSH_PORT=6174
```

  </TabItem>
  <TabItem value="Configuration file" label="Configuration file" >

```bash
metrics-push-port="6174"
```

  </TabItem>
</Tabs>

The port (TCP) of the [Prometheus Push Gateway](https://github.com/prometheus/pushgateway). The default is `9001`.

### `metrics-push-prometheus-job`

<Tabs>

  <TabItem value="Syntax" label="Syntax" default>

```bash
--metrics-push-prometheus-job=<metricsPrometheusJob>
```

  </TabItem>
  <TabItem value="Example" label="Example" >

```bash
--metrics-push-prometheus-job="my-custom-job"
```

  </TabItem>
  <TabItem value="Environment variable" label="Environment variable" >

```bash
WEB3SIGNER_METRICS_PUSH_PROMETHEUS_JOB="my-custom-job"
```

  </TabItem>
  <TabItem value="Configuration file" label="Configuration file" >

```bash
metrics-push-prometheus-job="my-custom-job"
```

  </TabItem>
</Tabs>

The job name when in `push` mode. The default is `web3signer-job`.

### `reload-timeout`

<Tabs>

  <TabItem value="Syntax" label="Syntax" default>

```bash
--reload-timeout=<MINUTES>
```

  </TabItem>
  <TabItem value="Example" label="Example" >

```bash
--reload-timeout=45
```

  </TabItem>
  <TabItem value="Environment variable" label="Environment variable" >

```bash
WEB3SIGNER_RELOAD_TIMEOUT=45
```

  </TabItem>
  <TabItem value="Configuration file" label="Configuration file" >

```bash
reload-timeout: "45"
```

  </TabItem>
</Tabs>

Maximum time, in minutes, allowed for the entire reload operation using the [`reload`](https://consensys.github.io/web3signer/#tag/Reload-Signer-Keys) endpoint.
This includes loading from all sources (for example, file system or key vaults).
The default is 30.

### `signer-load-batch-size`

<Tabs>

  <TabItem value="Syntax" label="Syntax" default>

```bash
--signer-load-batch-size=<COUNT>
```

  </TabItem>
  <TabItem value="Example" label="Example" >

```bash
--signer-load-batch-size=300
```

  </TabItem>
  <TabItem value="Environment variable" label="Environment variable" >

```bash
WEB3SIGNER_SIGNER_LOAD_BATCH_SIZE=300
```

  </TabItem>
  <TabItem value="Configuration file" label="Configuration file" >

```bash
signer-load-batch-size: "300"
```

  </TabItem>
</Tabs>

Number of signer configuration files to process per batch during parallel loading.
Reduce this number if you hit OS file descriptor limits.
The default is 500, and the minimum value is 100.

### `signer-load-parallel`

<Tabs>

  <TabItem value="Syntax" label="Syntax" default>

```bash
--signer-load-parallel[=<BOOLEAN>]
```

  </TabItem>
  <TabItem value="Example" label="Example" >

```bash
--signer-load-parallel=false
```

  </TabItem>
  <TabItem value="Environment variable" label="Environment variable" >

```bash
WEB3SIGNER_SIGNER_LOAD_PARALLEL=false
```

  </TabItem>
  <TabItem value="Configuration file" label="Configuration file" >

```bash
signer-load-parallel: false
```

  </TabItem>
</Tabs>

Enables or disables parallel processing of signer configuration files.
Set to `false` for sequential processing.
The default is `true`.

### `signer-load-sequential-threshold`

<Tabs>

  <TabItem value="Syntax" label="Syntax" default>

```bash
--signer-load-sequential-threshold=<COUNT>
```

  </TabItem>
  <TabItem value="Example" label="Example" >

```bash
--signer-load-sequential-threshold=50
```

  </TabItem>
  <TabItem value="Environment variable" label="Environment variable" >

```bash
WEB3SIGNER_SIGNER_LOAD_SEQUENTIAL_THRESHOLD=50
```

  </TabItem>
  <TabItem value="Configuration file" label="Configuration file" >

```bash
signer-load-sequential-threshold: "50"
```

  </TabItem>
</Tabs>

Minimum number of files required to use parallel processing.
Files below this threshold are processed sequentially.
The default is 100, and the minimum value is 1.

### `signer-load-timeout`

<Tabs>

  <TabItem value="Syntax" label="Syntax" default>

```bash
--signer-load-timeout=<SECONDS>
```

  </TabItem>
  <TabItem value="Example" label="Example" >

```bash
--signer-load-timeout=120
```

  </TabItem>
  <TabItem value="Environment variable" label="Environment variable" >

```bash
WEB3SIGNER_SIGNER_LOAD_TIMEOUT=120
```

  </TabItem>
  <TabItem value="Configuration file" label="Configuration file" >

```bash
signer-load-timeout: "120"
```

  </TabItem>
</Tabs>

Maximum time, in seconds, for processing each individual signer configuration file.
This applies during parallel processing of files from the file system.
The default is 60.

### `tls-keystore-file`

<Tabs>

  <TabItem value="Syntax" label="Syntax" default>

```bash
--tls-keystore-file=<keystoreFile>
```

  </TabItem>
  <TabItem value="Example" label="Example" >

```bash
--tls-keystore-file=/Users/me/my_node/certificate.pfx
```

  </TabItem>
  <TabItem value="Environment variable" label="Environment variable" >

```bash
WEB3SIGNER_TLS_KEYSTORE_FILE=/Users/me/my_node/certificate.pfx
```

  </TabItem>
  <TabItem value="Configuration file" label="Configuration file" >

```bash
tls-keystore-file: "/Users/me/my_node/certificate.pfx"
```

  </TabItem>
</Tabs>

PKCS #12 formatted keystore.
Used to enable TLS for [client connections](../../how-to/configure-tls.md).

### `tls-keystore-password-file`

<Tabs>

  <TabItem value="Syntax" label="Syntax" default>

```bash
--tls-keystore-password-file=<passwordFile>
```

  </TabItem>
  <TabItem value="Example" label="Example" >

```bash
--tls-keystore-password-file=/Users/me/my_node/password.txt
```

  </TabItem>
  <TabItem value="Environment variable" label="Environment variable" >

```bash
WEB3SIGNER_TLS_KEYSTORE_PASSWORD_FILE=/Users/me/my_node/password.txt
```

  </TabItem>
  <TabItem value="Configuration file" label="Configuration file" >

```bash
tls-keystore-password-file: "/Users/me/my_node/password.txt"
```

  </TabItem>
</Tabs>

Password file used to decrypt the keystore.

### `tls-allow-any-client`

<Tabs>

  <TabItem value="Syntax" label="Syntax" default>

```bash
--tls-allow-any-client=<BOOLEAN>
```

  </TabItem>
  <TabItem value="Example" label="Example" >

```bash
--tls-allow-any-client=true
```

  </TabItem>
  <TabItem value="Environment variable" label="Environment variable" >

```bash
WEB3SIGNER_TLS_ALLOW_ANY_CLIENT=true
```

  </TabItem>
  <TabItem value="Configuration file" label="Configuration file" >

```bash
tls-allow-any-client: true
```

  </TabItem>
</Tabs>

Allows any client to connect.
The default is `false`.

:::caution Warning
You can't use this option with [`--tls-allow-ca-clients`](#tls-allow-ca-clients) and
[`--tls-known-clients-file`](#tls-known-clients-file).
:::

### `tls-known-clients-file`

<Tabs>

  <TabItem value="Syntax" label="Syntax" default>

```bash
--tls-known-clients-file=<clientsFile>
```

  </TabItem>
  <TabItem value="Example" label="Example" >

```bash
--tls-known-clients-file=/Users/me/my_node/knownClients.txt
```

  </TabItem>
  <TabItem value="Environment variable" label="Environment variable" >

```bash
WEB3SIGNER_TLS_KNOWN_CLIENTS_FILE=/Users/me/my_node/knownClients.txt
```

  </TabItem>
  <TabItem value="Configuration file" label="Configuration file" >

```bash
tls-known-clients-file: "/Users/me/my_node/knownClients.txt"
```

  </TabItem>
</Tabs>

File containing the Common Names and SHA-256 fingerprints of
[authorized clients](../../how-to/configure-tls.md#create-the-known-clients-file).

### `tls-allow-ca-clients`

<Tabs>

  <TabItem value="Syntax" label="Syntax" default>

```bash
--tls-allow-ca-clients
```

  </TabItem>
  <TabItem value="Environment variable" label="Environment variable" >

```bash
WEB3SIGNER_TLS_ALLOW_CA_CLIENTS
```

  </TabItem>
  <TabItem value="Configuration file" label="Configuration file" >

```bash
tls-allow-ca-clients
```

  </TabItem>
</Tabs>

Allows clients signed with trusted CA certificates to connect.

### `vertx-worker-pool-size`

<Tabs>

  <TabItem value="Syntax" label="Syntax" default>

```bash title="Syntax"
--vertx-worker-pool-size=<INTEGER>
```

  </TabItem>
  <TabItem value="Example" label="Example" >

```bash
--vertx-worker-pool-size=40
```

  </TabItem>
  <TabItem value="Environment variable" label="Environment variable" >

```bash
WEB3SIGNER_VERTX_WORKER_POOL_SIZE=40
```

  </TabItem>
  <TabItem value="Configuration file" label="Configuration file" >

```bash
vertx-worker-pool-size: 40
```

  </TabItem>
</Tabs>

Vert.x worker pool size used for processing requests.
The default is `20`.

### `help`

```bash title="Syntax"
-h, --help
```

Displays the help and exits.

### `version`

```bash title="Syntax"
-V, --version
```

Displays the version and exits.

<!-- links -->

[YAML files required to access keys]: ../key-config-file-params.md
[Web3Signer metrics]: ../../how-to/monitor/metrics.md

---

## Subcommands


Use the Web3Signer subcommands to specify the platform being used:

- `web3signer [options] eth2 [Eth2 options]`
- `web3signer [options] eth2 export [Eth2 export options]`
- `web3signer [options] eth2 import [Eth2 import options]`
- `web3signer [options] eth1`
- `web3signer [options] watermark-repair [watermark repair options]`

:::note
This documentation has been updated in line with the name changes [recommended by the Ethereum
Foundation](https://blog.ethereum.org/2022/01/24/the-great-eth2-renaming/).
The `eth1` subcommands relate to the execution layer, previously called “Ethereum 1.0.”
The `eth2` subcommands relate to the consensus layer, previously called “Ethereum 2.0.”
:::

## Specify subcommand options

The subcommand must be specified on the command line, but the subcommand options can be specified:

- On the command line.
- As environment variables. For each subcommand option, the equivalent environment variable is:
  - Uppercase.
  - `_` replaces `-`.
  - Has a `WEB3SIGNER_` + `<SIGNING_OPTION>_` prefix.
- In a [YAML configuration file](../../how-to/use-configuration-file-starting-web3signer.md).

For example, you can set the `--chain-id` option for the `eth1` subcommand in an environment
variable `export WEB3SIGNER_ETH1_CHAIN_ID=2017`, but the subcommand must be specified in the
command line.

## View help

To view the command line help for the subcommands:

- [`web3signer help eth1`](#eth1)
- [`web3signer help eth2`](#eth2)
- [`web3signer help watermark-repair`](#watermark-repair)

## Options

### `eth1`

#### `aws-connection-cache-size`

<Tabs>

  <TabItem value="Syntax" label="Syntax" default>

```bash
--aws-connection-cache-size=<LONG>
```

  </TabItem>
  <TabItem value="Example" label="Example" >

```bash
--aws-connection-cache-size=5
```

  </TabItem>
  <TabItem value="Environment variable" label="Environment variable" >

```bash
WEB3SIGNER_ETH1_AWS_CONNECTION_CACHE_SIZE=5
```

  </TabItem>
  <TabItem value="Configuration file" label="Configuration file" >

```bash
eth1.aws-connection-cache-size: 5
```

  </TabItem>
</Tabs>

<!-- markdown-link-check-disable-next-line -->
When [loading multiple keys from AWS Secrets Manager](../../how-to/store-keys/vaults/aws/secrets-manager-consensus-layer.md#cache-aws-secrets-manager-when-loading-multiple-keys),
set to the maximum number of connections to cache.
The default is `1`.

#### `aws-endpoint-override`

<Tabs>

  <TabItem value="Syntax" label="Syntax" default>

```bash
--aws-endpoint-override=<ENDPOINT_URL>
```

  </TabItem>
  <TabItem value="Example" label="Example" >

```bash
--aws-endpoint-override=http://localstack:4566
```

  </TabItem>
  <TabItem value="Environment variable" label="Environment variable" >

```bash
WEB3SIGNER_ETH1_AWS_ENDPOINT_OVERRIDE=http://localstack:4566
```

  </TabItem>
  <TabItem value="Configuration file" label="Configuration file" >

```bash
eth1.aws-endpoint-override="http://localstack:4566"
```

  </TabItem>
</Tabs>

Endpoint override for AWS KMS.
Useful for local testing against LocalStack.

#### `aws-kms-access-key-id`

<Tabs>

  <TabItem value="Syntax" label="Syntax" default>

```bash
--aws-kms-access-key-id=<STRING>
```

  </TabItem>
  <TabItem value="Example" label="Example" >

```bash
--aws-kms-access-key-id=AKIA...EXAMPLE
```

  </TabItem>
  <TabItem value="Environment variable" label="Environment variable" >

```bash
WEB3SIGNER_ETH1_AWS_KMS_ACCESS_KEY_ID=AKIA...EXAMPLE
```

  </TabItem>
  <TabItem value="Configuration file" label="Configuration file" >

```bash
eth1.aws-kms-access-key-id: "AKIA...EXAMPLE"
```

  </TabItem>
</Tabs>

AWS Access Key ID to authenticate AWS KMS.
Required when [`--aws-kms-auth-mode`](#aws-kms-auth-mode) is `SPECIFIED`.

#### `aws-kms-auth-mode`

<Tabs>

  <TabItem value="Syntax" label="Syntax" default>

```bash
--aws-kms-auth-mode=<STRING>
```

  </TabItem>
  <TabItem value="Example" label="Example" >

```bash
--aws-kms-auth-mode=ENVIRONMENT
```

  </TabItem>
  <TabItem value="Environment variable" label="Environment variable" >

```bash
WEB3SIGNER_ETH1_AWS_KMS_AUTH_MODE=ENVIRONMENT
```

  </TabItem>
  <TabItem value="Configuration file" label="Configuration file" >

```bash
eth1.aws-kms-auth-mode: "ENVIRONMENT"
```

  </TabItem>
</Tabs>

Authentication mode for AWS KMS.
Options are `SPECIFIED` and `ENVIRONMENT`.
The default is `SPECIFIED`.

Set [`--aws-kms-access-key-id`](#aws-kms-access-key-id),
[`--aws-kms-secret-access-key`](#aws-kms-secret-access-key), and
[`--aws-kms-region`](#aws-kms-region) if using `SPECIFIED`.

#### `aws-kms-client-cache-size`

<Tabs>

  <TabItem value="Syntax" label="Syntax" default>

```bash
--aws-kms-client-cache-size=<LONG>
```

  </TabItem>
  <TabItem value="Example" label="Example" >

```bash
--aws-kms-client-cache-size=5
```

  </TabItem>
  <TabItem value="Environment variable" label="Environment variable" >

```bash
WEB3SIGNER_ETH1_AWS_KMS_CLIENT_CACHE_SIZE=5
```

  </TabItem>
  <TabItem value="Configuration file" label="Configuration file" >

```bash
eth1.aws-kms-client-cache-size: "5"
```

  </TabItem>
</Tabs>

AWS KMS client cache size. Set to the total number of credentials
used to access the service plus the number of regions the service is accessed from. The default is `1`.

#### `aws-kms-enabled`

<Tabs>

  <TabItem value="Syntax" label="Syntax" default>

```bash
--aws-kms-enabled=<BOOLEAN>
```

  </TabItem>
  <TabItem value="Example" label="Example" >

```bash
--aws-kms-enabled=true
```

  </TabItem>
  <TabItem value="Environment variable" label="Environment variable" >

```bash
WEB3SIGNER_ETH1_AWS_KMS_ENABLED=true
```

  </TabItem>
  <TabItem value="Configuration file" label="Configuration file" >

```bash
eth1.aws-kms-enabled: "true"
```

  </TabItem>
</Tabs>

Set to `true` to enable bulk loading from the AWS KMS. The default is `false`.

#### `aws-kms-region`

<Tabs>

  <TabItem value="Syntax" label="Syntax" default>

```bash
--aws-kms-region=<STRING>
```

  </TabItem>
  <TabItem value="Example" label="Example" >

```bash
--aws-kms-region=us-east-2
```

  </TabItem>
  <TabItem value="Environment variable" label="Environment variable" >

```bash
WEB3SIGNER_ETH1_AWS_KMS_REGION=us-east-2
```

  </TabItem>
  <TabItem value="Configuration file" label="Configuration file" >

```bash
eth1.aws-kms-region: "us-east-2"
```

  </TabItem>
</Tabs>

AWS region where AWS KMS is available.

Required when [`--aws-kms-auth-mode`](#aws-kms-auth-mode) is `SPECIFIED`.

#### `aws-kms-secret-access-key`

<Tabs>

  <TabItem value="Syntax" label="Syntax" default>

```bash
--aws-kms-secret-access-key=<STRING>
```

  </TabItem>
  <TabItem value="Example" label="Example" >

```bash
--aws-kms-secret-access-key=sk...EXAMPLE
```

  </TabItem>
  <TabItem value="Environment variable" label="Environment variable" >

```bash
WEB3SIGNER_ETH1_AWS_KMS_SECRET_ACCESS_KEY=sk...EXAMPLE
```

  </TabItem>
  <TabItem value="Configuration file" label="Configuration file" >

```bash
eth1.aws-kms-secret-access-key: "sk...EXAMPLE"
```

  </TabItem>
</Tabs>

AWS secret access key to authenticate AWS KMS.
Required when [`--aws-kms-auth-mode`](#aws-kms-auth-mode) is `SPECIFIED`.

#### `aws-kms-tag`

<Tabs>

  <TabItem value="Syntax" label="Syntax" default>

```bash
--aws-kms-tag <NAME>=<VALUE> [--aws-kms-tag <NAME>=<VALUE> ...]
```

  </TabItem>
  <TabItem value="Example" label="Example" >

```bash
--aws-kms-tag tagName1=tagValue1 --aws-kms-tag tagName2=tagValue2
```

  </TabItem>
  <TabItem value="Environment variable" label="Environment variable" >

```bash
WEB3SIGNER_ETH1_AWS_KMS_TAG="tagName1=tagValue1|tagName2=tagValue2"
```

  </TabItem>
  <TabItem value="Configuration file" label="Configuration file" >

```bash
eth1.aws-kms-tag: "tagName1=tagValue1|tagName2=tagValue2"
```

  </TabItem>
</Tabs>

Optional tag name and value filters to apply while fetching key IDs from AWS KMS.

On the command line, use `--aws-kms-tag` multiple times to specify multiple filters.
As an environment variable and in the configuration file, use a pipe `|` to specify multiple filters in a single line.
Multiple filters are applied as an `AND` operation.

#### `azure-vault-enabled`

<Tabs>

  <TabItem value="Syntax" label="Syntax" default>

```bash
--azure-vault-enabled=<BOOLEAN>
```

  </TabItem>
  <TabItem value="Example" label="Example" >

```bash
--azure-vault-enabled=true
```

  </TabItem>
  <TabItem value="Environment variable" label="Environment variable" >

```bash
WEB3SIGNER_ETH1_AZURE_VAULT_ENABLED=true
```

  </TabItem>
  <TabItem value="Configuration file" label="Configuration file" >

```bash
eth1.azure-vault-enabled: true
```

  </TabItem>
</Tabs>

Enables [bulk loading keys from Azure Key Vault](../../how-to/load-keys.md#azure-key-vault).
The default is `false`.

#### `azure-client-id`

<Tabs>

  <TabItem value="Syntax" label="Syntax" default>

```bash
--azure-client-id=<STRING>
```

  </TabItem>
  <TabItem value="Example" label="Example" >

```bash
--azure-client-id=87efaa5b-4029-4b54-98bb2e2e8a11
```

  </TabItem>
  <TabItem value="Environment variable" label="Environment variable" >

```bash
WEB3SIGNER_ETH1_AZURE_CLIENT_ID=87efaa5b-4029-4b54-98bb2e2e8a11
```

  </TabItem>
  <TabItem value="Configuration file" label="Configuration file" >

```bash
eth1.azure-client-id: "87efaa5b-4029-4b54-98bb2e2e8a11"
```

  </TabItem>
</Tabs>

ID used to authenticate with Azure Key Vault.

Required when [`--azure-vault-auth-mode`](#azure-vault-auth-mode) is `CLIENT_SECRET` or
`USER_ASSIGNED_MANAGED_IDENTITY`.

#### `azure-client-secret`

<Tabs>

  <TabItem value="Syntax" label="Syntax" default>

```bash
--azure-client-secret=<STRING>
```

  </TabItem>
  <TabItem value="Example" label="Example" >

```bash
--azure-client-secret=0DgK4V_YA99RPk7.f_1op0-em_a46wSe.Z
```

  </TabItem>
  <TabItem value="Environment variable" label="Environment variable" >

```bash
WEB3SIGNER_ETH1_AZURE_CLIENT_SECRET=0DgK4V_YA99RPk7.f_1op0-em_a46wSe.Z
```

  </TabItem>
  <TabItem value="Configuration file" label="Configuration file" >

```bash
eth1.azure-client-secret: "0DgK4V_YA99RPk7.f_1op0-em_a46wSe.Z"
```

  </TabItem>
</Tabs>

The secret used to access the vault along with the ID specified in [`azure-client-id`](#azure-client-id).

#### `azure-response-timeout`

<Tabs>

  <TabItem value="Syntax" label="Syntax" default>

```bash
--azure-response-timeout=<AZURE_RESPONSE_TIMEOUT>
```

  </TabItem>
  <TabItem value="Example" label="Example" >

```bash
--azure-response-timeout=40
```

  </TabItem>
  <TabItem value="Environment variable" label="Environment variable" >

```bash
WEB3SIGNER_ETH1_AZURE_RESPONSE_TIMEOUT=40
```

  </TabItem>
  <TabItem value="Configuration file" label="Configuration file" >

```bash
eth1.azure-response-timeout: "40"
```

  </TabItem>
</Tabs>

The response timeout used by the HTTP client (in seconds). The default is 60. You can also set the timeout using
the `timeout` field in the Azure metadata file.

#### `azure-tags`

<Tabs>

  <TabItem value="Syntax" label="Syntax" default>

```bash
--azure-tags=<TAG_NAME=TAG_VALUE>
```

  </TabItem>
  <TabItem value="Example" label="Example" >

```bash
--azure-tags=ENV=prod
```

  </TabItem>
  <TabItem value="Environment variable" label="Environment variable" >

```bash
WEB3SIGNER_ETH1_AZURE_TAGS=ENV=prod
```

  </TabItem>
  <TabItem value="Configuration file" label="Configuration file" >

```bash
eth1.azure-tags: "ENV=prod"
```

  </TabItem>
</Tabs>

Tags to filter on with Azure Key Vault.

#### `azure-tenant-id`

<Tabs>

  <TabItem value="Syntax" label="Syntax" default>

```bash
--azure-tenant-id=<STRING>
```

  </TabItem>
  <TabItem value="Example" label="Example" >

```bash
--azure-tenant-id=34255fb0-379b-4a1a-bd47-d211ab86df81
```

  </TabItem>
  <TabItem value="Environment variable" label="Environment variable" >

```bash
WEB3SIGNER_ETH1_AZURE_TENANT_ID=34255fb0-379b-4a1a-bd47-d211ab86df81
```

  </TabItem>
  <TabItem value="Configuration file" label="Configuration file" >

```bash
eth1.azure-tenant-id: "34255fb0-379b-4a1a-bd47-d211ab86df81"
```

  </TabItem>
</Tabs>

The tenant ID of the Azure Portal instance being used.

#### `azure-vault-auth-mode`

<Tabs>

  <TabItem value="Syntax" label="Syntax" default>

```bash
--azure-vault-auth-mode=<STRING>
```

  </TabItem>
  <TabItem value="Example" label="Example" >

```bash
--azure-vault-auth-mode=USER_ASSIGNED_MANAGED_IDENTITY
```

  </TabItem>
  <TabItem value="Environment variable" label="Environment variable" >

```bash
WEB3SIGNER_ETH1_AZURE_VAULT_AUTH_MODE=USER_ASSIGNED_MANAGED_IDENTITY
```

  </TabItem>
  <TabItem value="Configuration file" label="Configuration file" >

```bash
eth1.azure-vault-auth-mode: "USER_ASSIGNED_MANAGED_IDENTITY"
```

  </TabItem>
</Tabs>

Authentication mode for Azure Vault.
Options are `CLIENT_SECRET`, `SYSTEM_ASSIGNED_MANAGED_IDENTITY`, and `USER_ASSIGNED_MANAGED_IDENTITY`.
The default is `CLIENT_SECRET`.

Set [`--azure-client-id`](#azure-client-id) if using `CLIENT_SECRET` or `USER_ASSIGNED_MANAGED_IDENTITY`.

#### `azure-vault-name`

<Tabs>

  <TabItem value="Syntax" label="Syntax" default>

```bash
--azure-vault-name=<STRING>
```

  </TabItem>
  <TabItem value="Example" label="Example" >

```bash
--azure-vault-name=AzureKeyVault
```

  </TabItem>
  <TabItem value="Environment variable" label="Environment variable" >

```bash
WEB3SIGNER_ETH1_AZURE_VAULT_NAME=AzureKeyVault
```

  </TabItem>
  <TabItem value="Configuration file" label="Configuration file" >

```bash
eth1.azure-vault-name: "AzureKeyVault"
```

  </TabItem>
</Tabs>

Name of the vault to access.
Subdomain of `vault.azure.net`.

#### `chain-id`

<Tabs>

  <TabItem value="Syntax" label="Syntax" default>

```bash
--chain-id=<LONG>
```

  </TabItem>
  <TabItem value="Example" label="Example" >

```bash
--chain-id=2017
```

  </TabItem>
  <TabItem value="Environment variable" label="Environment variable" >

```bash
WEB3SIGNER_ETH1_CHAIN_ID=2017
```

  </TabItem>
  <TabItem value="Configuration file" label="Configuration file" >

```bash
eth1.chain-id: "2017"
```

  </TabItem>
</Tabs>

ID of the chain to receive the signed transactions. The Besu documentation
lists [chain IDs for public networks](https://besu.hyperledger.org/public-networks/concepts/network-and-chain-id).

#### `downstream-http-host`

<Tabs>

  <TabItem value="Syntax" label="Syntax" default>

```bash
--downstream-http-host=<downstreamHttpHost>
```

  </TabItem>
  <TabItem value="Example" label="Example" >

```bash
--downstream-http-host=192.168.05.14
```

  </TabItem>
  <TabItem value="Environment variable" label="Environment variable" >

```bash
WEB3SIGNER_ETH1_DOWNSTREAM_HTTP_HOST=192.168.05.14
```

  </TabItem>
  <TabItem value="Configuration file" label="Configuration file" >

```bash
eth1.downstream-http-host="192.168.05.14"
```

  </TabItem>
</Tabs>

Host to which received requests are forwarded.
The default is `localhost`.

#### `downstream-http-path`

<Tabs>

  <TabItem value="Syntax" label="Syntax" default>

```bash
--downstream-http-path=<downstreamHttpPath>
```

  </TabItem>
  <TabItem value="Example" label="Example" >

```bash
--downstream-http-path=/v3/d0e63ca5bb1e4eef2284422efbc51a56
```

  </TabItem>
  <TabItem value="Environment variable" label="Environment variable" >

```bash
WEB3SIGNER_ETH1_DOWNSTREAM_HTTP_PATH=/v3/d0e63ca5bb1e4eef2284422efbc51a56
```

  </TabItem>
  <TabItem value="Configuration file" label="Configuration file" >

```bash
eth1.downstream-http-path="/v3/d0e63ca5bb1e4eef2284422efbc51a56"
```

  </TabItem>
</Tabs>

Path to which received requests are forwarded.
The default is `/`.

This might be required if connecting to a cloud-based Ethereum client such as [Infura](https://infura.io/).

#### `downstream-http-port`

<Tabs>

  <TabItem value="Syntax" label="Syntax" default>

```bash
--downstream-http-port=<downstreamHttpPort>
```

  </TabItem>
  <TabItem value="Example" label="Example" >

```bash
--downstream-http-port=6174
```

  </TabItem>
  <TabItem value="Environment variable" label="Environment variable" >

```bash
WEB3SIGNER_ETH1_DOWNSTREAM_HTTP_PORT=6174
```

  </TabItem>
  <TabItem value="Configuration file" label="Configuration file" >

```bash
eth1.downstream-http-port: 6174
```

  </TabItem>
</Tabs>

Port to which received requests are forwarded.

#### `downstream-http-proxy-host`

<Tabs>

  <TabItem value="Syntax" label="Syntax" default>

```bash
--downstream-http-proxy-host=<HOST>
```

  </TabItem>
  <TabItem value="Example" label="Example" >

```bash
--downstream-http-proxy-host=192.168.05.14
```

  </TabItem>
  <TabItem value="Environment variable" label="Environment variable" >

```bash
WEB3SIGNER_ETH1_DOWNSTREAM_HTTP_PROXY_HOST=192.168.05.14
```

  </TabItem>
  <TabItem value="Configuration file" label="Configuration file" >

```bash
eth1.downstream-http-proxy-host: "192.168.05.14"
```

  </TabItem>
</Tabs>

Hostname for proxy.
There's no proxy if set to `null`.
The default is `null`.

#### `downstream-http-proxy-port`

<Tabs>

  <TabItem value="Syntax" label="Syntax" default>

```bash
--downstream-http-proxy-port=<PORT>
```

  </TabItem>
  <TabItem value="Example" label="Example" >

```bash
--downstream-http-proxy-port=8545
```

  </TabItem>
  <TabItem value="Environment variable" label="Environment variable" >

```bash
WEB3SIGNER_ETH1_DOWNSTREAM_HTTP_PROXY_PORT=8545
```

  </TabItem>
  <TabItem value="Configuration file" label="Configuration file" >

```bash
eth1.downstream-http-proxy-port: 8545
```

  </TabItem>
</Tabs>

Port for proxy.
The default is `80`.

#### `downstream-http-proxy-username`

<Tabs>

  <TabItem value="Syntax" label="Syntax" default>

```bash
--downstream-http-proxy-username=<username>
```

  </TabItem>
  <TabItem value="Example" label="Example" >

```bash
--downstream-http-proxy-username=user
```

  </TabItem>
  <TabItem value="Environment variable" label="Environment variable" >

```bash
WEB3SIGNER_ETH1_DOWNSTREAM_HTTP_PROXY_USERNAME=user
```

  </TabItem>
  <TabItem value="Configuration file" label="Configuration file" >

```bash
eth1.downstream-http-proxy-username: "user"
```

  </TabItem>
</Tabs>

Username for proxy.
There's no authentication if set to `null`.
The default is `null`.

#### `downstream-http-proxy-password`

<Tabs>

  <TabItem value="Syntax" label="Syntax" default>

```bash
--downstream-http-proxy-password=<password>
```

  </TabItem>
  <TabItem value="Example" label="Example" >

```bash
--downstream-http-proxy-password=password
```

  </TabItem>
  <TabItem value="Environment variable" label="Environment variable" >

```bash
WEB3SIGNER_ETH1_DOWNSTREAM_HTTP_PROXY_PASSWORD=password
```

  </TabItem>
  <TabItem value="Configuration file" label="Configuration file" >

```bash
eth1.downstream-http-proxy-password: "password"
```

  </TabItem>
</Tabs>

Password for proxy.
There's no authentication if set to `null`.
The default is `null`.

#### `downstream-http-request-timeout`

<Tabs>

  <TabItem value="Syntax" label="Syntax" default>

```bash
--downstream-http-request-timeout=<downstreamHttpRequestTimeout>
```

  </TabItem>
  <TabItem value="Example" label="Example" >

```bash
--downstream-http-request-timeout=3000
```

  </TabItem>
  <TabItem value="Environment variable" label="Environment variable" >

```bash
WEB3SIGNER_ETH1_DOWNSTREAM_HTTP_REQUEST_TIMEOUT=3000
```

  </TabItem>
  <TabItem value="Configuration file" label="Configuration file" >

```bash
eth1.downstream-http-request-timeout: 3000
```

  </TabItem>
</Tabs>

Timeout period (in milliseconds) for downstream requests.
The default is 5000.

#### `downstream-http-tls-enabled`

<Tabs>

  <TabItem value="Syntax" label="Syntax" default>

```bash
--downstream-http-tls-enabled=<BOOLEAN>
```

  </TabItem>
  <TabItem value="Example" label="Example" >

```bash
--downstream-http-tls-enabled=true
```

  </TabItem>
  <TabItem value="Environment variable" label="Environment variable" >

```bash
WEB3SIGNER_ETH1_DOWNSTREAM_HTTP_TLS_ENABLED=true
```

  </TabItem>
  <TabItem value="Configuration file" label="Configuration file" >

```bash
eth1.downstream-http-tls-enabled: true
```

  </TabItem>
</Tabs>

Enables or disables [TLS for server connections](../../concepts/tls.md).
The default is `false`.

#### `downstream-http-tls-keystore-file`

<Tabs>

  <TabItem value="Syntax" label="Syntax" default>

```bash
--downstream-http-tls-keystore-file=<FILE>
```

  </TabItem>
  <TabItem value="Example" label="Example" >

```bash
--downstream-http-tls-keystore-file=/Users/me/my_node/keystore.pfx
```

  </TabItem>
  <TabItem value="Environment variable" label="Environment variable" >

```bash
WEB3SIGNER_ETH1_DOWNSTREAM_HTTP_TLS_KEYSTORE_FILE=/Users/me/my_node/keystore.pfx
```

  </TabItem>
  <TabItem value="Configuration file" label="Configuration file" >

```bash
eth1.downstream-http-tls-keystore-file: /Users/me/my_node/keystore.pfx
```

  </TabItem>
</Tabs>

Keystore used to present during TLS client authentication with the downstream server.

#### `downstream-http-tls-keystore-password-file`

<Tabs>

  <TabItem value="Syntax" label="Syntax" default>

```bash
--downstream-http-tls-keystore-password-file=<FILE>
```

  </TabItem>
  <TabItem value="Example" label="Example" >

```bash
--downstream-http-tls-keystore-password-file=/Users/me/my_node/keyPassword
```

  </TabItem>
  <TabItem value="Environment variable" label="Environment variable" >

```bash
WEB3SIGNER_ETH1_DOWNSTREAM_HTTP_TLS_KEYSTORE_PASSWORD_FILE=/Users/me/my_node/keyPassword
```

  </TabItem>
  <TabItem value="Configuration file" label="Configuration file" >

```bash
eth1.downstream-http-tls-keystore-password-file: /Users/me/my_node/keyPassword
```

  </TabItem>
</Tabs>

File containing the password to decrypt the keystore.

#### `downstream-http-tls-known-servers-file`

<Tabs>

  <TabItem value="Syntax" label="Syntax" default>

```bash
--downstream-http-tls-known-servers-file=<FILE>
```

  </TabItem>
  <TabItem value="Example" label="Example" >

```bash
--downstream-http-tls-known-servers-file=/Users/me/my_node/knownServers
```

  </TabItem>
  <TabItem value="Environment variable" label="Environment variable" >

```bash
WEB3SIGNER_ETH1_DOWNSTREAM_HTTP_TLS_KNOWN_SERVERS_FILE=/Users/me/my_node/knownServers
```

  </TabItem>
  <TabItem value="Configuration file" label="Configuration file" >

```bash
eth1.downstream-http-tls-known-servers-file=/Users/me/my_node/knownServers
```

  </TabItem>
</Tabs>

File containing the hostnames, ports, and SHA256 certificate fingerprints of
[trusted servers](../../how-to/configure-tls.md#create-the-known-servers-file).

#### `downstream-http-tls-ca-auth-enabled`

<Tabs>

  <TabItem value="Syntax" label="Syntax" default>

```bash
--downstream-http-tls-ca-auth-enabled=<BOOLEAN>
```

  </TabItem>
  <TabItem value="Example" label="Example" >

```bash
--downstream-http-tls-ca-auth-enabled=false
```

  </TabItem>
  <TabItem value="Environment variable" label="Environment variable" >

```bash
WEB3SIGNER_ETH1_HTTP_TLS_CA_AUTH_ENABLED=false
```

  </TabItem>
  <TabItem value="Configuration file" label="Configuration file" >

```bash
eth1.downstream-http-tls-ca-auth-enabled: false
```

  </TabItem>
</Tabs>

Enables or disables connections to servers with trusted CAs.
The default is `true`.

#### `keystores-password-file`

<Tabs>

  <TabItem value="Syntax" label="Syntax" default>

```bash
--keystores-password-file=<FILE>
```

  </TabItem>
  <TabItem value="Example" label="Example" >

```bash
--keystores-password-file=/Users/me/passwds/keystore_passwords.txt
```

  </TabItem>
  <TabItem value="Environment variable" label="Environment variable" >

```bash
WEB3SIGNER_ETH1_KEYSTORES_PASSWORD_FILE=/Users/me/passwds/keystore_passwords.txt
```

  </TabItem>
  <TabItem value="Configuration file" label="Configuration file" >

```bash
eth1.keystores-password-file: "/Users/me/passwds/keystore_passwords.txt"
```

  </TabItem>
</Tabs>

File that contains the password used by all keystores.
Cannot be set if [`--keystores-passwords-path`](#keystores-passwords-path) is also specified.

:::note
Alternatively, use [`--keystores-passwords-path`](#keystores-passwords-path) to specify a directory
containing a separate password file for each keystore.
:::

#### `keystores-passwords-path`

<Tabs>

  <TabItem value="Syntax" label="Syntax" default>

```bash
--keystores-passwords-path=<PATH>
```

  </TabItem>
  <TabItem value="Example" label="Example" >

```bash
--keystores-passwords-path=/Users/me/passwds
```

  </TabItem>
  <TabItem value="Environment variable" label="Environment variable" >

```bash
WEB3SIGNER_ETH1_KEYSTORES_PASSWORDS_PATH=/Users/me/passwds
```

  </TabItem>
  <TabItem value="Configuration file" label="Configuration file" >

```bash
eth1.keystores-passwords-path: "/Users/me/passwds"
```

  </TabItem>
</Tabs>

Directory containing password files for corresponding keystores.
Each password file name must match the corresponding keystore filename, but with a `.txt` extension.

Cannot be set if [`--keystores-password-file`](#keystores-password-file) is also specified.

:::note
Alternatively, use [`--keystores-password-file`](#keystores-password-file) to specify a single
password file that contains the password used by all keystores.
:::

#### `keystores-path`

<Tabs>

  <TabItem value="Syntax" label="Syntax" default>

```bash
--keystores-path=<PATH>
```

  </TabItem>
  <TabItem value="Example" label="Example" >

```bash
--keystores-path=/Users/me/keystores
```

  </TabItem>
  <TabItem value="Environment variable" label="Environment variable" >

```bash
WEB3SIGNER_ETH1_KEYSTORES_PATH=/Users/me/keystores
```

  </TabItem>
  <TabItem value="Configuration file" label="Configuration file" >

```bash
eth1.keystores-path: "/Users/me/keystores"
```

  </TabItem>
</Tabs>

Directory that stores the keystore files.
Keystore files must use a `.json` file extension.

Use [`--keystores-password-file`](#keystores-password-file) or
[`--keystores-passwords-path`](#keystores-passwords-path) to specify keystore passwords.

:::caution Important
Restart Web3Signer if you want to pick up new keystores added to the directory since Web3Signer started.
:::

### `eth2`

#### `aws-connection-cache-size`

<Tabs>

  <TabItem value="Syntax" label="Syntax" default>

```bash
--aws-connection-cache-size=<LONG>
```

  </TabItem>
  <TabItem value="Example" label="Example" >

```bash
--aws-connection-cache-size=5
```

  </TabItem>
  <TabItem value="Environment variable" label="Environment variable" >

```bash
WEB3SIGNER_ETH2_AWS_CONNECTION_CACHE_SIZE=5
```

  </TabItem>
  <TabItem value="Configuration file" label="Configuration file" >

```bash
eth2.aws-connection-cache-size: 5
```

  </TabItem>
</Tabs>

When [loading multiple keys from AWS Secrets Manager](../../how-to/store-keys/vaults/aws/secrets-manager-consensus-layer.md#cache-aws-secrets-manager-when-loading-multiple-keys),
set to the maximum number of connections to cache.
The default is 1.

#### `aws-endpoint-override`

<Tabs>

  <TabItem value="Syntax" label="Syntax" default>

```bash
--aws-endpoint-override=<ENDPOINT_URL>
```

  </TabItem>
  <TabItem value="Example" label="Example" >

```bash
--aws-endpoint-override=http://localstack:4566
```

  </TabItem>
  <TabItem value="Environment variable" label="Environment variable" >

```bash
WEB3SIGNER_ETH2_AWS_ENDPOINT_OVERRIDE=http://localstack:4566
```

  </TabItem>
  <TabItem value="Configuration file" label="Configuration file" >

```bash
eth2.aws-endpoint-override="http://localstack:4566"
```

  </TabItem>
</Tabs>

Endpoint override for AWS Secrets Manager.
This is useful for local testing against LocalStack.

#### `aws-secrets-enabled`

<Tabs>

  <TabItem value="Syntax" label="Syntax" default>

```bash
--aws-secrets-enabled=<BOOLEAN>
```

  </TabItem>
  <TabItem value="Example" label="Example" >

```bash
--aws-secrets-enabled=true
```

  </TabItem>
  <TabItem value="Environment variable" label="Environment variable" >

```bash
WEB3SIGNER_ETH2_AWS_SECRETS_ENABLED=true
```

  </TabItem>
  <TabItem value="Configuration file" label="Configuration file" >

```bash
eth2.aws-secrets-enabled: true
```

  </TabItem>
</Tabs>

Enables or disables [bulk loading keys from AWS Secrets Manager](../../how-to/load-keys.md#aws-secrets-manager).
The default is `false`.

#### `aws-secrets-auth-mode`

<Tabs>

  <TabItem value="Syntax" label="Syntax" default>

```bash
--aws-secrets-auth-mode=<STRING>
```

  </TabItem>
  <TabItem value="Example" label="Example" >

```bash
--aws-secrets-auth-mode=ENVIRONMENT
```

  </TabItem>
  <TabItem value="Environment variable" label="Environment variable" >

```bash
WEB3SIGNER_ETH2_AWS_SECRETS_AUTH_MODE=ENVIRONMENT
```

  </TabItem>
  <TabItem value="Configuration file" label="Configuration file" >

```bash
eth2.aws-secrets-auth-mode: "ENVIRONMENT"
```

  </TabItem>
</Tabs>

Authentication mode for AWS Secrets Manager.
Options are `SPECIFIED` and `ENVIRONMENT`.
The default is `SPECIFIED`.

Set [`--aws-secrets-access-key-id`](#aws-secrets-access-key-id),
[`--aws-secrets-secret-access-key`](#aws-secrets-secret-access-key), and
[`--aws-secrets-region`](#aws-secrets-region) if using `SPECIFIED`.

#### `aws-secrets-access-key-id`

<Tabs>

  <TabItem value="Syntax" label="Syntax" default>

```bash
--aws-secrets-access-key-id=<STRING>
```

  </TabItem>
  <TabItem value="Example" label="Example" >

```bash
--aws-secrets-access-key-id=AKIA...EXAMPLE
```

  </TabItem>
  <TabItem value="Environment variable" label="Environment variable" >

```bash
WEB3SIGNER_ETH2_AWS_SECRETS_ACCESS_KEY_ID=AKIA...EXAMPLE
```

  </TabItem>
  <TabItem value="Configuration file" label="Configuration file" >

```bash
eth2.aws-secrets-access-key-id: "AKIA...EXAMPLE"
```

  </TabItem>
</Tabs>

AWS access key ID to authenticate AWS Secrets Manager.

Required when [`--aws-secrets-auth-mode`](#aws-secrets-auth-mode) is `SPECIFIED`.

#### `aws-secrets-secret-access-key`

<Tabs>

  <TabItem value="Syntax" label="Syntax" default>

```bash
--aws-secrets-secret-access-key=<STRING>
```

  </TabItem>
  <TabItem value="Example" label="Example" >

```bash
--aws-secrets-secret-access-key=sk...EXAMPLE
```

  </TabItem>
  <TabItem value="Environment variable" label="Environment variable" >

```bash
WEB3SIGNER_ETH2_AWS_SECRETS_SECRET_ACCESS_KEY=sk...EXAMPLE
```

  </TabItem>
  <TabItem value="Configuration file" label="Configuration file" >

```bash
eth2.aws-secrets-secret-access-key: "sk...EXAMPLE"
```

  </TabItem>
</Tabs>

AWS secret access key to authenticate AWS Secrets Manager.

Required when [`--aws-secrets-auth-mode`](#aws-secrets-auth-mode) is `SPECIFIED`.

#### `aws-secrets-region`

<Tabs>

  <TabItem value="Syntax" label="Syntax" default>

```bash
--aws-secrets-region=<STRING>
```

  </TabItem>
  <TabItem value="Example" label="Example" >

```bash
--aws-secrets-region=us-east-2
```

  </TabItem>
  <TabItem value="Environment variable" label="Environment variable" >

```bash
WEB3SIGNER_ETH2_AWS_SECRETS_REGION=us-east-2
```

  </TabItem>
  <TabItem value="Configuration file" label="Configuration file" >

```bash
eth2.aws-secrets-region: "us-east-2"
```

  </TabItem>
</Tabs>

AWS region where AWS Secrets Manager is available.

Required when [`--aws-secrets-auth-mode`](#aws-secrets-auth-mode) is `SPECIFIED`.

#### `aws-secrets-prefixes-filter`

<Tabs>

  <TabItem value="Syntax" label="Syntax" default>

```bash
--aws-secrets-prefixes-filter=<STRING>[,<STRING>,...]
```

  </TabItem>
  <TabItem value="Example" label="Example" >

```bash
--aws-secrets-prefixes-filter=prefix1,prefix2
```

  </TabItem>
  <TabItem value="Environment variable" label="Environment variable" >

```bash
WEB3SIGNER_ETH2_AWS_SECRETS_PREFIXES_FILTER=prefix1,prefix2
```

  </TabItem>
  <TabItem value="Configuration file" label="Configuration file" >

```bash
eth2.aws-secrets-prefixes-filter: ["prefix1","prefix2"]
```

  </TabItem>
</Tabs>

Optional comma-separated list of secret name prefixes filter to apply while fetching secrets from
AWS Secrets Manager.
Applied as `AND` operation with other filters.

#### `aws-secrets-tag`

<Tabs>

  <TabItem value="Syntax" label="Syntax" default>

```bash
--aws-secrets-tag <NAME>=<VALUE> [--aws-secrets-tag <NAME>=<VALUE> ...]
```

  </TabItem>
  <TabItem value="Example" label="Example" >

```bash
--aws-secrets-tag tagName1=tagValue1 --aws-secrets-tag tagName2=tagValue2
```

  </TabItem>
  <TabItem value="Environment variable" label="Environment variable" >

```bash
WEB3SIGNER_ETH2_AWS_SECRETS_TAG="tagName1=tagValue1|tagName2=tagValue2"
```

  </TabItem>
  <TabItem value="Configuration file" label="Configuration file" >

```bash
eth2.aws-secrets-tag: "tagName1=tagValue1|tagName2=tagValue2"
```

  </TabItem>
</Tabs>

Optional tag name and value filters to apply while fetching secrets from AWS Secrets Manager.

On the command line, use `--aws-secrets-tag` multiple times to specify multiple filters.
As an environment variable and in the configuration file, use a pipe `|` to specify multiple filters in a single line.
Multiple filters are applied as an `AND` operation.

#### `azure-vault-enabled`

<Tabs>

  <TabItem value="Syntax" label="Syntax" default>

```bash
--azure-vault-enabled=<BOOLEAN>
```

  </TabItem>
  <TabItem value="Example" label="Example" >

```bash
--azure-vault-enabled=true
```

  </TabItem>
  <TabItem value="Environment variable" label="Environment variable" >

```bash
WEB3SIGNER_ETH2_AZURE_VAULT_ENABLED=true
```

  </TabItem>
  <TabItem value="Configuration file" label="Configuration file" >

```bash
eth2.azure-vault-enabled: true
```

  </TabItem>
</Tabs>

Enables [bulk loading keys from Azure Key Vault](../../how-to/load-keys.md#azure-key-vault).
The default is `false`.

#### `azure-client-id`

<Tabs>

  <TabItem value="Syntax" label="Syntax" default>

```bash
--azure-client-id=<STRING>
```

  </TabItem>
  <TabItem value="Example" label="Example" >

```bash
--azure-client-id=87efaa5b-4029-4b54-98bb2e2e8a11
```

  </TabItem>
  <TabItem value="Environment variable" label="Environment variable" >

```bash
WEB3SIGNER_ETH2_AZURE_CLIENT_ID=87efaa5b-4029-4b54-98bb2e2e8a11
```

  </TabItem>
  <TabItem value="Configuration file" label="Configuration file" >

```bash
eth2.azure-client-id: "87efaa5b-4029-4b54-98bb2e2e8a11"
```

  </TabItem>
</Tabs>

ID used to authenticate with Azure Key Vault.

Required when [`--azure-vault-auth-mode`](#azure-vault-auth-mode) is `CLIENT_SECRET` or
`USER_ASSIGNED_MANAGED_IDENTITY`.

#### `azure-client-secret`

<Tabs>

  <TabItem value="Syntax" label="Syntax" default>

```bash
--azure-client-secret=<STRING>
```

  </TabItem>
  <TabItem value="Example" label="Example" >

```bash
--azure-client-secret=0DgK4V_YA99RPk7.f_1op0-em_a46wSe.Z
```

  </TabItem>
  <TabItem value="Environment variable" label="Environment variable" >

```bash
WEB3SIGNER_ETH2_AZURE_CLIENT_SECRET=0DgK4V_YA99RPk7.f_1op0-em_a46wSe.Z
```

  </TabItem>
  <TabItem value="Configuration file" label="Configuration file" >

```bash
eth2.azure-client-secret: "0DgK4V_YA99RPk7.f_1op0-em_a46wSe.Z"
```

  </TabItem>
</Tabs>

The secret used to access the vault along with the ID specified in [`azure-client-id`](#azure-client-id).

#### `azure-response-timeout`

<Tabs>

  <TabItem value="Syntax" label="Syntax" default>

```bash
--azure-response-timeout=<AZURE_RESPONSE_TIMEOUT>
```

  </TabItem>
  <TabItem value="Example" label="Example" >

```bash
--azure-response-timeout=40
```

  </TabItem>
  <TabItem value="Environment variable" label="Environment variable" >

```bash
WEB3SIGNER_ETH2_AZURE_RESPONSE_TIMEOUT=40
```

  </TabItem>
  <TabItem value="Configuration file" label="Configuration file" >

```bash
eth2.azure-response-timeout: "40"
```

  </TabItem>
</Tabs>

The response timeout used by the HTTP client (in seconds). The default is 60. You can also set the timeout using the `timeout` field in the Azure metadata file.

#### `azure-tags`

<Tabs>

  <TabItem value="Syntax" label="Syntax" default>

```bash
--azure-tags=<TAG_NAME=TAG_VALUE>
```

  </TabItem>
  <TabItem value="Example" label="Example" >

```bash
--azure-tags=ENV=prod
```

  </TabItem>
  <TabItem value="Environment variable" label="Environment variable" >

```bash
WEB3SIGNER_ETH2_AZURE_TAGS=ENV=prod
```

  </TabItem>
  <TabItem value="Configuration file" label="Configuration file" >

```bash
eth2.azure-tags: "ENV=prod"
```

  </TabItem>
</Tabs>

Tags to filter on using Azure Key Vault.

#### `azure-tenant-id`

<Tabs>

  <TabItem value="Syntax" label="Syntax" default>

```bash
--azure-tenant-id=<STRING>
```

  </TabItem>
  <TabItem value="Example" label="Example" >

```bash
--azure-tenant-id=34255fb0-379b-4a1a-bd47-d211ab86df81
```

  </TabItem>
  <TabItem value="Environment variable" label="Environment variable" >

```bash
WEB3SIGNER_ETH2_AZURE_TENANT_ID=34255fb0-379b-4a1a-bd47-d211ab86df81
```

  </TabItem>
  <TabItem value="Configuration file" label="Configuration file" >

```bash
eth2.azure-tenant-id: "34255fb0-379b-4a1a-bd47-d211ab86df81"
```

  </TabItem>
</Tabs>

The tenant ID of the Azure Portal instance being used.

#### `azure-vault-auth-mode`

<Tabs>

  <TabItem value="Syntax" label="Syntax" default>

```bash
--azure-vault-auth-mode=<STRING>
```

  </TabItem>
  <TabItem value="Example" label="Example" >

```bash
--azure-vault-auth-mode=USER_ASSIGNED_MANAGED_IDENTITY
```

  </TabItem>
  <TabItem value="Environment variable" label="Environment variable" >

```bash
WEB3SIGNER_ETH2_AZURE_VAULT_AUTH_MODE=USER_ASSIGNED_MANAGED_IDENTITY
```

  </TabItem>
  <TabItem value="Configuration file" label="Configuration file" >

```bash
eth2.azure-vault-auth-mode: "USER_ASSIGNED_MANAGED_IDENTITY"
```

  </TabItem>
</Tabs>

Authentication mode for Azure Vault.
Options are `CLIENT_SECRET`, `SYSTEM_ASSIGNED_MANAGED_IDENTITY`, and `USER_ASSIGNED_MANAGED_IDENTITY`.
The default is `CLIENT_SECRET`.

Set [`--azure-client-id`](#azure-client-id) if using `CLIENT_SECRET` or `USER_ASSIGNED_MANAGED_IDENTITY`.

#### `azure-vault-name`

<Tabs>

  <TabItem value="Syntax" label="Syntax" default>

```bash
--azure-vault-name=<STRING>
```

  </TabItem>
  <TabItem value="Example" label="Example" >

```bash
--azure-vault-name=AzureKeyVault
```

  </TabItem>
  <TabItem value="Environment variable" label="Environment variable" >

```bash
WEB3SIGNER_ETH2_AZURE_VAULT_NAME=AzureKeyVault
```

  </TabItem>
  <TabItem value="Configuration file" label="Configuration file" >

```bash
eth2.azure-vault-name: "AzureKeyVault"
```

  </TabItem>
</Tabs>

Name of the vault to access.
Subdomain of `vault.azure.net`.

#### `commit-boost-api-enabled`

<Tabs>
  <TabItem value="Syntax" label="Syntax" default>

```bash
--commit-boost-api-enabled[=<BOOLEAN>]
```

  </TabItem>
  <TabItem value="Example" label="Example">

```bash
--commit-boost-api-enabled=true
```

  </TabItem>
  <TabItem value="Environment variable" label="Environment variable">

```bash
WEB3SIGNER_ETH2_COMMIT_BOOST_API_ENABLED=true
```

  </TabItem>
  <TabItem value="Configuration file" label="Configuration file">

```bash
eth2.commit-boost-api-enabled: true
```

  </TabItem>
</Tabs>

Enables or disables the [Commit-Boost API](https://commit-boost.github.io/commit-boost-client/api).
The default is `false`.

You can specify the directory to store the generated Commit-Boost proxy keystores using
[`--proxy-keystores-path`](#proxy-keystores-path).

#### `gcp-project-id`

<Tabs>

  <TabItem value="Syntax" label="Syntax" default>

```bash
--gcp-project-id=<STRING>
```

  </TabItem>
  <TabItem value="Example" label="Example" >

```bash
--gcp-project-id=my-project
```

  </TabItem>
  <TabItem value="Environment variable" label="Environment variable" >

```bash
WEB3SIGNER_ETH2_GCP_PROJECT_ID=my-project
```

  </TabItem>
  <TabItem value="Configuration file" label="Configuration file" >

```bash
eth2.gcp-project-id: "my-project"
```

  </TabItem>
</Tabs>

Globally unique identifier for the Google Cloud Platform (GCP) project where the
secrets to be used by Web3Signer are stored.

#### `gcp-secrets-enabled`

<Tabs>

  <TabItem value="Syntax" label="Syntax" default>

```bash
--gcp-secrets-enabled=<BOOLEAN>
```

  </TabItem>
  <TabItem value="Example" label="Example" >

```bash
--gcp-secrets-enabled=true
```

  </TabItem>
  <TabItem value="Environment variable" label="Environment variable" >

```bash
WEB3SIGNER_ETH2_GCP_SECRETS_ENABLED=true
```

  </TabItem>
  <TabItem value="Configuration file" label="Configuration file" >

```bash
eth2.gcp-secrets-enabled: true
```

  </TabItem>
</Tabs>

Set to `true` to enable bulk loading from the GCP Secrets Manager service. The default is `false`.

#### `gcp-secrets-filter`

<Tabs>

  <TabItem value="Syntax" label="Syntax" default>

```bash
--gcp-secrets-filter=<STRING>
```

  </TabItem>
  <TabItem value="Example" label="Example" >

```bash
--gcp-secrets-filter=my-secrets-filter
```

  </TabItem>
  <TabItem value="Environment variable" label="Environment variable" >

```bash
WEB3SIGNER_ETH2_GCP_SECRETS_FILTER=my-secrets-filter
```

  </TabItem>
  <TabItem value="Configuration file" label="Configuration file" >

```bash
eth2.gcp-secrets-filter: "my-secrets-filter"
```

  </TabItem>
</Tabs>

Filter to use when loading secrets into Web3Signer. [List operation filtering](https://cloud.google.com/secret-manager/docs/filtering) is applied.

Only secrets matching the filter are loaded. If not specified, all secrets from the project identified by
[`--gcp-project-id`](#gcp-project-id) are loaded.

#### `key-manager-api-enabled`

<Tabs>

  <TabItem value="Syntax" label="Syntax" default>

```bash
--key-manager-api-enabled=<BOOLEAN>
```

  </TabItem>
  <TabItem value="Example" label="Example" >

```bash
--key-manager-api-enabled=true
```

  </TabItem>
  <TabItem value="Environment variable" label="Environment variable" >

```bash
WEB3SIGNER_ETH2_KEY_MANAGER_API_ENABLED=true
```

  </TabItem>
  <TabItem value="Configuration file" label="Configuration file" >

```bash
eth2.key-manager-api-enabled: true
```

  </TabItem>
</Tabs>

Enables the [key manager API](../../how-to/manage-keys.md).
The default is `false`.

#### `keystores-password-file`

<Tabs>

  <TabItem value="Syntax" label="Syntax" default>

```bash
--keystores-password-file=<FILE>
```

  </TabItem>
  <TabItem value="Example" label="Example" >

```bash
--keystores-password-file=/Users/me/passwds/keystore_passwords.txt
```

  </TabItem>
  <TabItem value="Environment variable" label="Environment variable" >

```bash
WEB3SIGNER_ETH2_KEYSTORES_PASSWORD_FILE=/Users/me/passwds/keystore_passwords.txt
```

  </TabItem>
  <TabItem value="Configuration file" label="Configuration file" >

```bash
eth2.keystores-password-file: "/Users/me/passwds/keystore_passwords.txt"
```

  </TabItem>
</Tabs>

File that contains the password used by all keystores.
Cannot be set if [`--keystores-passwords-path`](#keystores-passwords-path) is also specified.

:::note
Alternatively, use [`--keystores-passwords-path`](#keystores-passwords-path) to specify a directory
containing a separate password file for each keystore.
:::

#### `keystores-passwords-path`

<Tabs>

  <TabItem value="Syntax" label="Syntax" default>

```bash
--keystores-passwords-path=<PATH>
```

  </TabItem>
  <TabItem value="Example" label="Example" >

```bash
--keystores-passwords-path=/Users/me/passwds
```

  </TabItem>
  <TabItem value="Environment variable" label="Environment variable" >

```bash
WEB3SIGNER_ETH2_KEYSTORES_PASSWORDS_PATH=/Users/me/passwds
```

  </TabItem>
  <TabItem value="Configuration file" label="Configuration file" >

```bash
eth2.keystores-passwords-path: "/Users/me/passwds"
```

  </TabItem>
</Tabs>

Directory containing password files for corresponding keystores.
Each password file name must match the corresponding keystore filename, but with a `.txt` extension.

Cannot be set if [`--keystores-password-file`](#keystores-password-file) is also specified.

:::note
Alternatively, use [`--keystores-password-file`](#keystores-password-file) to specify a single
password file that contains the password used by all keystores.
:::

#### `keystores-path`

<Tabs>

  <TabItem value="Syntax" label="Syntax" default>

```bash
--keystores-path=<PATH>
```

  </TabItem>
  <TabItem value="Example" label="Example" >

```bash
--keystores-path=/Users/me/keystores
```

  </TabItem>
  <TabItem value="Environment variable" label="Environment variable" >

```bash
WEB3SIGNER_ETH2_KEYSTORES_PATH=/Users/me/keystores
```

  </TabItem>
  <TabItem value="Configuration file" label="Configuration file" >

```bash
eth2.keystores-path: "/Users/me/keystores"
```

  </TabItem>
</Tabs>

Directory that stores the keystore files.
Keystore files must use a `.json` file extension.

Use [`--keystores-password-file`](#keystores-password-file) or
[`--keystores-passwords-path`](#keystores-passwords-path) to specify keystore passwords.

:::caution Important
Restart Web3Signer if you want to pick up new keystores added to the directory since Web3Signer started.
:::

#### `network`

<Tabs>

  <TabItem value="Syntax" label="Syntax" default>

```bash
--network=<NETWORK>
```

  </TabItem>
  <TabItem value="Example" label="Example" >

```bash
--network=mainnet
```

  </TabItem>
  <TabItem value="Environment variable" label="Environment variable" >

```bash
WEB3SIGNER_ETH2_NETWORK=mainnet
```

  </TabItem>
  <TabItem value="Configuration file" label="Configuration file" >

```bash
eth2.network: "mainnet"
```

  </TabItem>
</Tabs>

Predefined network configuration.
Accepts a predefined network name, or file path or URL to a YAML configuration file.
See the [consensus specification] for examples.

The default is `mainnet`.

:::caution Important
If Teku connects to a network other than `mainnet`, then this option must be specified, and it must
match the [`--network` value of the connected Teku client](https://docs.teku.consensys.net/how-to/use-external-signer/use-web3signer).
:::

Possible values are:

| Network    | Chain            | Type       | Description                                      |
| :--------- | :--------------- | :--------- | :----------------------------------------------- |
| `mainnet`  | Consensus layer  | Production | Ethereum main network.                           |
| `minimal`  | Consensus layer  | Test       | Used for local testing and development networks. |
| `sepolia`  | Consensus layer  | Test       | Multi-client [permissioned](https://notes.ethereum.org/zvkfSmYnT0-uxwwEegbCqg) testnet.|
| `holesky`  | Consensus layer  | Test       | Multi-client testnet.                            |
| `hoodi`    | Consensus layer  | Test       | Multi-client testnet.                            |
| `lukso`    | Consensus layer  | Production | Lukso main network.                              |
| `gnosis`   | Consensus layer  | Production | Gnosis main network.                             |
| `chiado`   | Consensus layer  | Test       | Multi-client Gnosis testnet.                     |

#### `proxy-keystores-password-file`

<Tabs>
  <TabItem value="Syntax" label="Syntax" default>

```bash
--proxy-keystores-password-file=<FILE>
```

  </TabItem>
  <TabItem value="Example" label="Example">

```bash
--proxy-keystores-password-file=password.txt
```

  </TabItem>
  <TabItem value="Environment variable" label="Environment variable">

```bash
WEB3SIGNER_ETH2_PROXY_KEYSTORES_PASSWORD_FILE=password.txt
```

  </TabItem>
  <TabItem value="Configuration file" label="Configuration file">

```bash
eth2.proxy-keystores-password-file: "password.txt"
```

  </TabItem>
</Tabs>

The path to the password file used to encrypt or decrypt the proxy keystores
located at [`--proxy-keystores-path`](#proxy-keystores-path),
when using the [Commit-Boost API](https://commit-boost.github.io/commit-boost-client/api).

[`--commit-boost-api-enabled`](#commit-boost-api-enabled) must be set
to `true`.

#### `proxy-keystores-path`

<Tabs>
  <TabItem value="Syntax" label="Syntax" default>

```bash
--proxy-keystores-path=<PATH>
```

  </TabItem>
  <TabItem value="Example" label="Example">

```bash
--proxy-keystores-path=/home/me/proxy-keystores
```

  </TabItem>
  <TabItem value="Environment variable" label="Environment variable">

```bash
WEB3SIGNER_ETH2_PROXY_KEYSTORES_PATH=/home/me/proxy-keystores
```

  </TabItem>
  <TabItem value="Configuration file" label="Configuration file">

```bash
eth2.proxy-keystores-path: "/home/me/proxy-keystores"
```

  </TabItem>
</Tabs>

The path to a directory to store the generated proxy keystores when using the
[Commit-Boost API](https://commit-boost.github.io/commit-boost-client/api).
The Web3Signer process should have read-write access to this directory.

[`--commit-boost-api-enabled`](#commit-boost-api-enabled) must be set
to `true`.

Specify a password file for the proxy keystores using
[`--proxy-keystores-password-file`](#proxy-keystores-password-file).

#### `slashing-protection-db-health-check-interval-milliseconds`

<Tabs>

  <TabItem value="Syntax" label="Syntax" default>

```bash
--slashing-protection-db-health-check-interval-milliseconds=<INTERVAL>
```

  </TabItem>
  <TabItem value="Example" label="Example" >

```bash
--slashing-protection-db-health-check-interval-milliseconds=20000
```

  </TabItem>
  <TabItem value="Environment variable" label="Environment variable" >

```bash
WEB3SIGNER_ETH2_SLASHING_PROTECTION_DB_HEALTH_CHECK_INTERVAL_MILLISECONDS=20000
```

  </TabItem>
  <TabItem value="Configuration file" label="Configuration file" >

```bash
eth2.slashing-protection-db-health-check-interval-milliseconds: 20000
```

  </TabItem>
</Tabs>

Milliseconds between the slashing protection database health checks.
The default is 30000.

The service responds with a `200` message if healthy, and `503` if unhealthy.

#### `slashing-protection-db-health-check-timeout-milliseconds`

<Tabs>

  <TabItem value="Syntax" label="Syntax" default>

```bash
--slashing-protection-db-health-check-timeout-milliseconds=<INTERVAL>
```

  </TabItem>
  <TabItem value="Example" label="Example" >

```bash
--slashing-protection-db-health-check-timeout-milliseconds=2000
```

  </TabItem>
  <TabItem value="Environment variable" label="Environment variable" >

```bash
WEB3SIGNER_ETH2_SLASHING_PROTECTION_DB_HEALTH_CHECK_TIMEOUT_MILLISECONDS=2000
```

  </TabItem>
  <TabItem value="Configuration file" label="Configuration file" >

```bash
eth2.slashing-protection-db-health-check-timeout-milliseconds: 2000
```

  </TabItem>
</Tabs>

Milliseconds after which to fail the database health check.
For example, if the health check connects to the slashing protection database, but does not report
back in a timely manner.

The default is 3000.

#### `slashing-protection-db-password`

<Tabs>

  <TabItem value="Syntax" label="Syntax" default>

```bash
--slashing-protection-db-password=<PASSWORD>
```

  </TabItem>
  <TabItem value="Example" label="Example" >

```bash
--slashing-protection-db-password=changeme
```

  </TabItem>
  <TabItem value="Environment variable" label="Environment variable" >

```bash
WEB3SIGNER_ETH2_SLASHING_PROTECTION_DB_PASSWORD=changeme
```

  </TabItem>
  <TabItem value="Configuration file" label="Configuration file" >

```bash
eth2.slashing-protection-db-password: "changeme"
```

  </TabItem>
</Tabs>

The password to connect to the slashing protection database.

#### `slashing-protection-db-pool-configuration-file`

<Tabs>

  <TabItem value="Syntax" label="Syntax" default>

```bash
--slashing-protection-db-pool-configuration-file=<FILE>
```

  </TabItem>
  <TabItem value="Example" label="Example" >

```bash
--slashing-protection-db-pool-configuration-file=/Users/me/config/HikariConfig.properties
```

  </TabItem>
  <TabItem value="Environment variable" label="Environment variable" >

```bash
WEB3SIGNER_ETH2_SLASHING_PROTECTION_DB_POOL_CONFIGURATION_FILE=/Users/me/config/HikariConfig.properties
```

  </TabItem>
  <TabItem value="Configuration file" label="Configuration file" >

```bash
eth2.slashing-protection-db-pool-configuration-file: "/Users/me/config/HikariConfig.properties"
```

  </TabItem>
</Tabs>

[HikariCP connection pool configuration file](https://github.com/brettwooldridge/HikariCP#gear-configuration-knobs-baby).

Web3Signer uses HikariCP to manage database connections, and uses the default configuration values.
The defaults perform well in most deployments, but you can override them using this option.

#### `slashing-protection-db-url`

<Tabs>

  <TabItem value="Syntax" label="Syntax" default>

```bash
--slashing-protection-db-url=<JDBC_URL>
```

  </TabItem>
  <TabItem value="Example" label="Example" >

```bash
--slashing-protection-db-url=jdbc:postgresql://localhost/web3signer
```

  </TabItem>
  <TabItem value="Environment variable" label="Environment variable" >

```bash
WEB3SIGNER_ETH2_SLASHING_PROTECTION_DB_URL=jdbc:postgresql://localhost/web3signer
```

  </TabItem>
  <TabItem value="Configuration file" label="Configuration file" >

```bash
eth2.slashing-protection-db-url: "jdbc:postgresql://localhost/web3signer"
```

  </TabItem>
</Tabs>

The Java Database Connectivity (JDBC) URL of the slashing protection database.

:::note
If using a non-default port number for your PostgreSQL database, then [include the port number in the database URL].
:::

#### `slashing-protection-db-username`

<Tabs>

  <TabItem value="Syntax" label="Syntax" default>

```bash
--slashing-protection-db-username=<USERNAME>
```

  </TabItem>
  <TabItem value="Example" label="Example" >

```bash
--slashing-protection-db-username=postgres
```

  </TabItem>
  <TabItem value="Environment variable" label="Environment variable" >

```bash
WEB3SIGNER_ETH2_SLASHING_PROTECTION_DB_USERNAME=postgres
```

  </TabItem>
  <TabItem value="Configuration file" label="Configuration file" >

```bash
eth2.slashing-protection-db-username: "postgres"
```

  </TabItem>
</Tabs>

The username to use when connecting to the slashing protection database.

#### `slashing-protection-enabled`

<Tabs>

  <TabItem value="Syntax" label="Syntax" default>

```bash
--slashing-protection-enabled=<BOOLEAN>
```

  </TabItem>
  <TabItem value="Example" label="Example" >

```bash
--slashing-protection-enabled=false
```

  </TabItem>
  <TabItem value="Environment variable" label="Environment variable" >

```bash
WEB3SIGNER_ETH2_SLASHING_PROTECTION_ENABLED=false
```

  </TabItem>
  <TabItem value="Configuration file" label="Configuration file" >

```bash
eth2.slashing-protection-enabled: false
```

  </TabItem>
</Tabs>

Enables Web3Signer [slashing protection].
If `true`, then all signing operations are validated against historical data before signing.

The default is `true`.

#### `slashing-protection-pruning-at-boot-enabled`

<Tabs>

  <TabItem value="Syntax" label="Syntax" default>

```bash
--slashing-protection-pruning-at-boot-enabled=<BOOLEAN>
```

  </TabItem>
  <TabItem value="Example" label="Example" >

```bash
--slashing-protection-pruning-at-boot-enabled=true
```

  </TabItem>
  <TabItem value="Environment variable" label="Environment variable" >

```bash
WEB3SIGNER_ETH2_SLASHING_PROTECTION_PRUNING_AT_BOOT_ENABLED=true
```

  </TabItem>
  <TabItem value="Configuration file" label="Configuration file" >

```yaml
eth2.slashing-protection-pruning-at-boot-enabled: true
```

  </TabItem>
</Tabs>

When set to `true`, [slashing protection database pruning](../../how-to/configure-slashing-protection.md#prune-the-slashing-protection-database)
is enabled at startup and at the defined [pruning intervals](#slashing-protection-pruning-interval).

The default is `false`.

#### `slashing-protection-pruning-db-pool-configuration-file`

<Tabs>

  <TabItem value="Syntax" label="Syntax" default>

```bash
--slashing-protection-pruning-db-pool-configuration-file=<FILE>
```

  </TabItem>
  <TabItem value="Example" label="Example" >

```bash
--slashing-protection-pruning-db-pool-configuration-file=/Users/me/config/HikariConfig.properties
```

  </TabItem>
  <TabItem value="Environment variable" label="Environment variable" >

```bash
WEB3SIGNER_ETH2_SLASHING_PROTECTION_PRUNING_DB_POOL_CONFIGURATION_FILE=/Users/me/config/HikariConfig.properties
```

  </TabItem>
  <TabItem value="Configuration file" label="Configuration file" >

```bash
eth2.slashing-protection-pruning-db-pool-configuration-file: "/Users/me/config/HikariConfig.properties"
```

  </TabItem>
</Tabs>

[HikariCP connection pool configuration file](https://github.com/brettwooldridge/HikariCP#gear-configuration-knobs-baby)
used by the pruning process.

Web3Signer uses HikariCP to manage database connections, and uses the default configuration values.
The defaults perform well in most deployments, but you can override them using this option.

#### `slashing-protection-pruning-enabled`

<Tabs>

  <TabItem value="Syntax" label="Syntax" default>

```bash
--slashing-protection-pruning-enabled=<BOOLEAN>
```

  </TabItem>
  <TabItem value="Example" label="Example" >

```bash
--slashing-protection-pruning-enabled=true
```

  </TabItem>
  <TabItem value="Environment variable" label="Environment variable" >

```bash
WEB3SIGNER_ETH2_SLASHING_PROTECTION_PRUNING_ENABLED=true
```

  </TabItem>
  <TabItem value="Configuration file" label="Configuration file" >

```yaml
eth2.slashing-protection-pruning-enabled: true
```

  </TabItem>
</Tabs>

Enables [slashing protection database pruning](../../how-to/configure-slashing-protection.md#prune-the-slashing-protection-database).
The default is `false`.

#### `slashing-protection-pruning-epochs-to-keep`

<Tabs>

  <TabItem value="Syntax" label="Syntax" default>

```bash
--slashing-protection-pruning-epochs-to-keep=<LONG>
```

  </TabItem>
  <TabItem value="Example" label="Example" >

```bash
--slashing-protection-pruning-epochs-to-keep=64
```

  </TabItem>
  <TabItem value="Environment variable" label="Environment variable" >

```bash
WEB3SIGNER_ETH2_SLASHING_PROTECTION_PRUNING_EPOCHS_TO_KEEP=64
```

  </TabItem>
  <TabItem value="Configuration file" label="Configuration file" >

```yaml
eth2.slashing-protection-pruning-epochs-to-keep: 64
```

  </TabItem>
</Tabs>

Number of epochs to keep when pruning the slashing protection database.

The default is 250.

#### `slashing-protection-pruning-interval`

<Tabs>

  <TabItem value="Syntax" label="Syntax" default>

```bash
--slashing-protection-pruning-interval=<LONG>
```

  </TabItem>
  <TabItem value="Example" label="Example" >

```bash
--slashing-protection-pruning-interval=48
```

  </TabItem>
  <TabItem value="Environment variable" label="Environment variable" >

```bash
WEB3SIGNER_ETH2_SLASHING_PROTECTION_PRUNING_INTERVAL=48
```

  </TabItem>
  <TabItem value="Configuration file" label="Configuration file" >

```yaml
eth2.slashing-protection-pruning-interval: 48
```

  </TabItem>
</Tabs>

Hours between slashing protection database pruning operations.

The default is 24.

#### `slashing-protection-pruning-slots-per-epoch`

<Tabs>

  <TabItem value="Syntax" label="Syntax" default>

```bash
--slashing-protection-pruning-slots-per-epoch=<LONG>
```

  </TabItem>
  <TabItem value="Example" label="Example" >

```bash
--slashing-protection-pruning-slots-per-epoch=20
```

  </TabItem>
  <TabItem value="Environment variable" label="Environment variable" >

```bash
WEB3SIGNER_ETH2_SLASHING_PROTECTION_PRUNING_SLOTS_PER_EPOCH=20
```

  </TabItem>
  <TabItem value="Configuration file" label="Configuration file" >

```yaml
eth2.slashing-protection-pruning-slots-per-epoch: 20
```

  </TabItem>
</Tabs>

Number of slots per epoch.
This number multiplied by the number of epochs to keep determines what blocks to keep when pruning
the slashing protection database.

The default is 32 as defined on Mainnet.

### `eth2 export`

Exports the slashing protection database to a file.

#### `to`

<Tabs>

  <TabItem value="Syntax" label="Syntax" default>

```bash
--to=<FILE>
```

  </TabItem>
  <TabItem value="Example" label="Example" >

```bash
--to=/Users/me/my_node/interchange.json
```

  </TabItem>
  <TabItem value="Environment variable" label="Environment variable" >

```bash
WEB3SIGNER_ETH2_EXPORT_TO=/Users/me/my_node/interchange.json
```

  </TabItem>
  <TabItem value="Configuration file" label="Configuration file" >

```bash
eth2.export.to: /Users/me/my_node/interchange.json
```

  </TabItem>
</Tabs>

The file to export the slashing protection database to.
The exported file uses the [validator client interchange format].

### `eth2 import`

Imports a slashing protection database from a file.

#### `from`

<Tabs>

  <TabItem value="Syntax" label="Syntax" default>

```bash
--from=<FILE>
```

  </TabItem>
  <TabItem value="Example" label="Example" >

```bash
--from=/Users/me/my_node/interchange.json
```

  </TabItem>
  <TabItem value="Environment variable" label="Environment variable" >

```bash
WEB3SIGNER_ETH2_IMPORT_FROM=/Users/me/my_node/interchange.json
```

  </TabItem>
  <TabItem value="Configuration file" label="Configuration file" >

```bash
eth2.import.from: /Users/me/my_node/interchange.json
```

  </TabItem>
</Tabs>

The file to import the slashing protection database from.
The file must be formatted in the [validator client interchange format].

### `watermark-repair`

Updates the [slashing protection low or high watermark](https://eips.ethereum.org/EIPS/eip-3076) for all validators.
You can only increase the low watermark, not decrease it.
If you set the high watermark, you should set this to a future epoch and slot.
Setting a high watermark prevents the validator from signing at or beyond this point.

:::caution
We only recommend this subcommand for advanced users.
:::

#### `epoch`

<Tabs>

  <TabItem value="Syntax" label="Syntax" default>

```bash
--epoch=<LONG>
```

  </TabItem>
  <TabItem value="Example" label="Example" >

```bash
--epoch=30000
```

  </TabItem>
  <TabItem value="Environment variable" label="Environment variable" >

```bash
WEB3SIGNER_WATERMARK_REPAIR_EPOCH=30000
```

  </TabItem>
  <TabItem value="Configuration file" label="Configuration file" >

```bash
watermark-repair.epoch: 30000
```

  </TabItem>
</Tabs>

Low watermark to set the attestation source and target to.
(Sets the high watermark epoch when [`--set-high-watermark`](#set-high-watermark) is `true`.)

#### `slot`

<Tabs>

  <TabItem value="Syntax" label="Syntax" default>

```bash
--slot=<LONG>
```

  </TabItem>
  <TabItem value="Example" label="Example" >

```bash
--slot=20000
```

  </TabItem>
  <TabItem value="Environment variable" label="Environment variable" >

```bash
WEB3SIGNER_WATERMARK_REPAIR_SLOT=20000
```

  </TabItem>
  <TabItem value="Configuration file" label="Configuration file" >

```bash
watermark-repair.slot: 20000
```

  </TabItem>
</Tabs>

Low watermark to set the block slot to.
(Sets the high watermark slot when [`--set-high-watermark`](#set-high-watermark) is `true`.)

#### `remove-high-watermark`

<Tabs>

  <TabItem value="Syntax" label="Syntax" default>

```bash
--remove-high-watermark=<BOOLEAN>
```

  </TabItem>
  <TabItem value="Example" label="Example" >

```bash
--remove-high-watermark=true
```

  </TabItem>
  <TabItem value="Environment variable" label="Environment variable" >

```bash
WEB3SIGNER_REMOVE_HIGH_WATERMARK=true
```

  </TabItem>
  <TabItem value="Configuration file" label="Configuration file" >

```bash
watermark-repair.remove-high-watermark: true
```

  </TabItem>
</Tabs>

Removes the high watermark.
When set to `true`, all other `watermark-repair` options are ignored.
The default is `false`.

#### `set-high-watermark`

<Tabs>

  <TabItem value="Syntax" label="Syntax" default>

```bash
--set-high-watermark=<BOOLEAN>
```

  </TabItem>
  <TabItem value="Example" label="Example" >

```bash
--set-high-watermark=true
```

  </TabItem>
  <TabItem value="Environment variable" label="Environment variable" >

```bash
WEB3SIGNER_SET_HIGH_WATERMARK=true
```

  </TabItem>
  <TabItem value="Configuration file" label="Configuration file" >

```bash
watermark-repair.set-high-watermark: true
```

  </TabItem>
</Tabs>

Sets the high watermark to the specified [epoch](#epoch) and [slot](#slot).
(Sets the low watermark when [`--set-high-watermark`](#set-high-watermark) is `false`.)
The default is `false`.

<!-- links -->

[include the port number in the database URL]: https://jdbc.postgresql.org/documentation/head/connect.html
[slashing protection]: ../../concepts/slashing-protection.md
[validator client interchange format]: https://eips.ethereum.org/EIPS/eip-3076
[consensus specification]: https://github.com/ethereum/consensus-specs/tree/master/configs

---

## Signing key configuration file parameters


A [signing key configuration file] is a YAML file that defines the parameters to access one or more
signing keys.

:::note
You can specify multiple key configurations in a single configuration file by adding a triple-dash
separator (`---`) between configurations.

Specify a maximum file size limit for your signing key configuration file with the
[`--key-store-config-file-max-size`](cli/options.md#key-store-config-file-max-size) command line option.
The default size is 100 MB.
:::

## Raw unencrypted files

Stores the private key as an unencrypted value directly in the key configuration file.

```bash
type: "file-raw"
keyType: "SECP256K1"
privateKey: "0x25b1166a43c109cb330af8945d364722757c65ed2bfed5444b5a2f057f82d391"
```

| Key | Description |
| --- | --- |
| **type** | Type of configuration file. Use `file-raw`. |
| **keyType** | Signing key type. Valid options are `BLS` or `SECP256K1`. The default is `BLS`. |
| **privateKey** | Hexadecimal encoded private key string. |

## Keystore file

Use the private key stored in a [keystore file].

```bash
type: "file-keystore"
keyType: "SECP256K1"
keystoreFile: "95e57532ede3c1dd879061153f9cfdcdefa9dc5fb9c954a6677bc6641b8d26e39f70b660bbaa732c47277c0096e11400.json"
keystorePasswordFile: "95e57532ede3c1dd879061153f9cfdcdefa9dc5fb9c954a6677bc6641b8d26e39f70b660bbaa732c47277c0096e11400.password"
```

| Key | Description |
| --- | --- |
| **type** | Type of configuration file. Use `file-keystore`. |
| **keyType** | Signing key type. Valid options are `BLS` or `SECP256K1`. The default is `BLS`. |
| **keystoreFile** | Location of the keystore file. |
| **keystorePasswordFile** | Text file containing the password to decrypt the keystore file. |

## HashiCorp Vault

Use the private key stored in [HashiCorp Vault](../how-to/store-keys/vaults/hashicorp.md).
Supports two authentication methods:

- `TOKEN` - Authenticate using a static Vault token. This is the default.
- `KUBERNETES` - Authenticate using the pod's Kubernetes service account. Web3Signer exchanges the
  service account token for a short-lived Vault client token.

<!-- markdownlint-disable -->

<Tabs>

  <TabItem value="token" label="TOKEN" default>

```bash
type: "hashicorp"
keyType: "SECP256K1"
tlsEnabled: "true"
keyPath: "/v1/secret/data/secretPath"
keyName: "secretName"
tlsKnownServersPath: "/Users/me/project/knownhosts"
serverHost: "localhost"
serverPort: "32895"
timeout: "10000"
token: "s.MuZwBqZ0iE1HzvD64v3HMlhT"
```

  </TabItem>
  <TabItem value="kubernetes" label="KUBERNETES">

```bash
type: "hashicorp"
keyType: "SECP256K1"
tlsEnabled: "true"
keyPath: "/v1/secret/data/secretPath"
keyName: "secretName"
tlsKnownServersPath: "/Users/me/project/knownhosts"
serverHost: "localhost"
serverPort: "32895"
timeout: "10000"
authMethod: "KUBERNETES"
kubernetesRole: "web3signer-role"
```

  </TabItem>
</Tabs>

| Key | Description |
| --- | --- |
| **type** | Type of configuration file. Use `hashicorp`. |
| **keyType** | Signing key type. Valid options are `BLS` or `SECP256K1`. The default is `BLS`. |
| **tlsEnabled** | Enable or disable TLS. The default is `true`. |
| **keyPath** | Path to secret in the HashiCorp Vault containing the private key. Syntax is the same as the path used in [HashiCorp KV Secrets Engine Version 2 HTTP API](https://www.vaultproject.io/api-docs/secret/kv/kv-v2#read-secret-version) |
| **keyName** | Name of the key storing the private key in the vault. |
| **tlsKnownServersPath** | Path to the file containing a list of trusted HashiCorp Vault servers. |
| **serverHost** | Host of the HashiCorp Vault server. |
| **serverPort** | Port of the HashiCorp Vault server. |
| **timeout** | Timeout in milliseconds for requests to the HashiCorp Vault server. |
| **authMethod** | Authentication method used to access HashiCorp Vault. Valid options are `TOKEN` and `KUBERNETES`. The default is `TOKEN`. |
| **token** | The root token displayed by the HashiCorp Vault server. Required when `authMethod` is `TOKEN`. |
| **kubernetesRole** | Vault role bound to the pod's Kubernetes service account. Required when `authMethod` is `KUBERNETES`. |
| **kubernetesAuthPath** | Vault authentication mount path used for the `KUBERNETES` authentication method. The default is `kubernetes`. |
| **kubernetesServiceAccountTokenPath** | Path to the file containing the Kubernetes service account token. The default is `/var/run/secrets/kubernetes.io/serviceaccount/token`. Relative paths are resolved relative to the signing key configuration file directory. |
| **httpProtocolVersion** | Override HTTP protocol version that is used to connect to HashiCorp Vault. Valid values are `HTTP_2` and `HTTP_1_1`. The default is `HTTP_2`. |

<!-- markdownlint-enable -->

## Azure Key Vault

Use the private key stored in [Azure Key Vault](../how-to/store-keys/vaults/azure.md).
Supports two signing options:

- `azure-key` - Performs the signing in Azure Key Vault.
  Supports SECP256K1 signing keys only.
- `azure-secret` - Web3Signer fetches the keys from the vault and signs locally.
  Supports SECP256K1 and BLS12-381 signing keys.

<!-- markdownlint-disable -->

<Tabs>

   <TabItem value="azure-secret" label="azure-secret" default>
```
type: "azure-secret"
keyType: "BLS"
authenticationMode: "USER_ASSIGNED_MANAGED_IDENTITY"
clientId: "***"
tenantId: "***"
vaultName: "AzureKeyVault"
secretName: "SecretName"
```

  </TabItem>
   <TabItem value="azure-key" label="azure-key" >

```yml
type: "azure-key"
clientId: "***"
clientSecret: "***"
tenantId: "***"
vaultName: "AzureKeyVault"
keyName: "KeyName"
```

  </TabItem>
</Tabs>

| Key | Description |
| --- | --- |
| **type** | Type of configuration file. Use `azure-secret` or `azure-key`. |
| **authenticationMode** | Authentication type being used. Can only be used with the `azure-secret` type. Valid options are `CLIENT_SECRET`, `SYSTEM_ASSIGNED_MANAGED_IDENTITY`, and `USER_ASSIGNED_MANAGED_IDENTITY`. The default is `CLIENT_SECRET`. |
| **keyType** | Signing key type. Valid options are `BLS` or `SECP256K1`. The default is `SECP256K1`. |
| **clientId** | ID used to authenticate with Azure Key Vault. Required when using the `azure-key` type, or when using `azure-secret` with the `CLIENT_SECRET` or `USER_ASSIGNED_MANAGED_IDENTITY` authentication modes. |
| **clientSecret** | Secret used to access the vault. Required for the `CLIENT_SECRET` authentication mode. |
| **tenantId** | The tenant ID used to authenticate with Azure Key Vault. |
| **vaultName** | Name of the vault to access. Sub-domain of vault.azure.net. |
| **secretName** | Name of the key stored in the Azure Key Vault under Secrets settings. Required when using the `azure-secret` type. |
| **keyName** | Name of the key stored in the Azure Key Vault under Keys settings. Required when using the `azure-key` type. |

<!-- markdownlint-enable -->

## AWS Secrets Manager

Use the private key stored in [AWS Secrets Manager](../how-to/store-keys/vaults/aws/secrets-manager-consensus-layer.md).
Supports BLS keys for consensus layer signing.

```bash
type: "aws-secret"
authenticationMode: "SPECIFIED"
keyType: "BLS"
accessKeyId: "foo"
secretAccessKey: "bar"
secretName: "SecretName"
region: "us-west-2"
```

| Key | Description |
| --- | --- |
| **type** | Type of configuration file. Use `aws-secret`. |
| **authenticationMode** | Authentication type being used. Valid options are `ENVIRONMENT` and `SPECIFIED`. If using `ENVIRONMENT`, credentials are authenticated using the [default credential provider chain](https://docs.aws.amazon.com/sdk-for-java/v1/developer-guide/credentials.html#credentials-default). The default authentication type is `SPECIFIED`. |
| **keyType** | Signing key type. Use `BLS`. |
| **accessKeyId** | Your access key ID. |
| **secretAccessKey** | Your secret access key. |
| **secretName** | Name of the secret. |
| **region** | Region to connect to. |

## AWS Key Management Service

Use the private key stored in [AWS Key Management Service (KMS)](../how-to/store-keys/vaults/aws/kms-execution-layer.md).
Supports SECP256K1 keys for execution layer signing.

```bash
type: "aws-kms"
authenticationMode: "SPECIFIED"
accessKeyId: "acc_key_id"
secretAccessKey: "foo"
sessionToken: "sess_token"
kmsKeyId: "bar"
region: "us-east-2"
endpointOverride: "http://localhost:4566"
```

<!-- markdownlint-disable -->

| Key                    | Description                                                                                                                                                                                                                                                                                                                            |
|------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| **type**               | Type of configuration file. Use `aws-kms`.                                                                                                                                                                                                                                                                                             |
| **authenticationMode** | Authentication type being used. Valid options are `ENVIRONMENT` and `SPECIFIED`. If using `ENVIRONMENT`, credentials are authenticated using the [default credential provider chain](https://docs.aws.amazon.com/sdk-for-java/v1/developer-guide/credentials.html#credentials-default). The default authentication type is `SPECIFIED`. |
| **accessKeyId**        | Access key ID.                                                                                                                                                                                                                                                                                                                         |
| **secretAccessKey**    | Secret access key.                                                                                                                                                                                                                                                                                                                     |
| **sessionToken**       | Token provided by [AWS Security Token Service (STS)](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_temp_enable-regions.html). Optional depending on AWS configuration.                                                                                                                                                |
| **kmsKeyId**           | AWS Access Key ID to authenticate AWS KMS.                                                                                                                                                                                                                                                                                             |
| **region**             | Region to connect to.                                                                                                                                                                                                                                                                                                                  |
| **endpointOverride**   | Endpoint override for AWS KMS. Useful for local testing against LocalStack.                                                                                                                                                                                                                                                            |

<!-- Links -->

[signing key configuration file]: ../how-to/load-keys.md#use-key-configuration-files
[keystore file]: https://github.com/ethereum/EIPs/blob/master/EIPS/eip-2335.md

---

## Security disclosure policy


At Consensys, security is a priority. But regardless of how much effort is put into system security, there may still be vulnerabilities present.
If you discover a vulnerability, we want to know about it so we can take steps to address it as quickly as possible.
You can help us better protect our clients and our systems.

Please do the following:

- Email your findings to `security-quorum@consensys.net`. Provide sufficient information to reproduce the problem, so we can resolve it as quickly as possible.
- Do not take advantage of the vulnerability you have discovered.
- Practice responsible disclosure. That is, don’t reveal the problem to others until either:
  - We have released a fix for the disclosure, or
  - 90 days have passed, or
  - We waive responsible disclosure.

We will acknowledge receipt of your vulnerability report the next business day and send you regular updates about our progress.

---

## Web3Signer


Web3Signer is an open-source remote signing service developed under the Apache 2.0 license and written in Java.

## What can you do with Web3Signer?

Web3Signer can sign on multiple platforms using private keys stored in an external vault, or encrypted on a disk.

Web3Signer can sign payloads using secp256k1 and BLS12-381 signing keys, and supports the following platforms:

- Execution layer (formerly called Ethereum 1.0)
- Consensus layer (formerly called Ethereum 2.0).

## New to Web3Signer?

Get started by running Web3Signer with Docker or installing Web3Signer. You can:

- [Run Web3Signer from a Docker image](get-started/use-docker.md)
- [Install the binary distribution](get-started/install-binaries.md)
- [Build from source](get-started/build-from-source.md)