Skip to main content

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​

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.

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>

Sets logging verbosity. Log levels are OFF, FATAL, WARN, INFO, DEBUG, TRACE, ALL. The default is INFO.

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.

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.

swagger-ui-enabled​

--swagger-ui-enabled[=<BOOLEAN>]

Set to true to interact with APIs using Swagger UI. The default is false.

Access Swagger UI at http:<interface>:<port>/swagger-ui where:

The default location is http://localhost:9000/swagger-ui.

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.