Skip to main content
Version: development

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​

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

Enables or disables access logs. The default is false.

config-file​

Path to the YAML configuration file. The default is none.

--config-file=<FILE>

data-path​

--data-path=<PATH>

Directory in which to store temporary files.

http-cors-origins​

--http-cors-origins=<httpListenHost>

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​

--http-listen-host=<httpListenHost>

Host on which HTTP listens. The default is localhost.

http-listen-port​

--http-listen-port=<httpListenPort>

Port on which HTTP listens. The default is 9000.

http-host-allowlist​

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

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​

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

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

key-config-path, key-store-path​

--key-config-path=<PATH>

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

key-store-config-file-max-size​

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

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

The default size is 104857600 bytes (100 MB).

logging​

-l, --logging=<LEVEL>

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

logging-format​

--logging-format=<FORMAT>

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​

--metrics-enabled[=<BOOLEAN>]

Enables the metrics exporter. The default is false.

metrics-host​

--metrics-host=<HOST>

The host on which Prometheus accesses metrics. The default is 127.0.0.1.

metrics-port​

--metrics-port=<PORT>

The port (TCP) on which Prometheus accesses metrics. The default is 9001.

metrics-category​

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

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

metrics-host-allowlist​

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

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​

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

Enables or disables push gateway integration.

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

metrics-push-host​

--metrics-push-host=<HOST>

The host of the Prometheus Push Gateway. The default is 127.0.0.1. The metrics server respects the --metrics-host-allowlist option.

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​

--metrics-push-interval=<INTEGER>

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

metrics-push-port​

--metrics-push-port=<PORT>

The port (TCP) of the Prometheus Push Gateway. The default is 9001.

metrics-push-prometheus-job​

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

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

reload-timeout​

--reload-timeout=<MINUTES>

Maximum time, in minutes, allowed for the entire reload operation using the reload endpoint. This includes loading from all sources (for example, file system or key vaults). The default is 30.

signer-load-batch-size​

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

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​

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

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

signer-load-sequential-threshold​

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

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​

--signer-load-timeout=<SECONDS>

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​

--tls-keystore-file=<keystoreFile>

PKCS #12 formatted keystore. Used to enable TLS for client connections.

tls-keystore-password-file​

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

Password file used to decrypt the keystore.

tls-allow-any-client​

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

Allows any client to connect. The default is false.

Warning

You can't use this option with --tls-allow-ca-clients and --tls-known-clients-file.

tls-known-clients-file​

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

File containing the Common Names and SHA-256 fingerprints of authorized clients.

tls-allow-ca-clients​

--tls-allow-ca-clients

Allows clients signed with trusted CA certificates to connect.

vertx-worker-pool-size​

Syntax
--vertx-worker-pool-size=<INTEGER>

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

help​

Syntax
-h, --help

Displays the help and exits.

version​

Syntax
-V, --version

Displays the version and exits.