--- sidebar_label: Options description: Web3Signer command line options reference sidebar_position: 1 --- > For AI agents: a documentation index is available at [/llms.txt](/llms.txt). Append `.md` to any documentation URL to get the markdown source. # Web3Signer command line options import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; 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` ```bash --access-logs-enabled[=] ``` ```bash --access-logs-enabled=true ``` ```bash WEB3SIGNER_ACCESS_LOGS_ENABLED=true ``` ```bash access-logs-enabled-enabled: true ``` 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`. ```bash --config-file= ``` ```bash --config-file=/home/me/me_node/config.yaml ``` ```bash WEB3SIGNER_CONFIG_FILE=/home/me/me_node/config.yaml ``` ### `data-path` ```bash --data-path= ``` ```bash --data-path=/Users/me/my_node/data ``` ```bash WEB3SIGNER_DATA_PATH=/Users/me/my_node/data ``` ```bash data-path: "/Users/me/my_node/data" ``` Directory in which to store temporary files. ### `http-cors-origins` ```bash --http-cors-origins= ``` ```bash --http-cors-origins=""http://medomain.com" ``` ```bash WEB3SIGNER_HTTP_CORS_ORIGINS=""http://medomain.com" ``` ```bash http-cors-origins=["https://meotherdomain.com"] ``` 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` ```bash --http-listen-host= ``` ```bash --http-listen-host=8.8.8.8 ``` ```bash WEB3SIGNER_HTTP_LISTEN_HOST=8.8.8.8 ``` ```bash http-listen-host: "8.8.8.8" ``` Host on which HTTP listens. The default is `localhost`. ### `http-listen-port` ```bash --http-listen-port= ``` ```bash --http-listen-port=6174 ``` ```bash WEB3SIGNER_HTTP_LISTEN_PORT=6174 ``` ```bash http-listen-port: 6174 ``` Port on which HTTP listens. The default is 9000. ### `http-host-allowlist` ```bash --http-host-allowlist=[,...]... or "*" ``` ```bash --http-host-allowlist=medomain.com,meotherdomain.com ``` ```bash WEB3SIGNER_HTTP_HOST_ALLOWLIST=medomain.com,meotherdomain.com ``` ```bash http-host-allowlist: ["medomain.com", "meotherdomain.com"] ``` 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` ```bash --idle-connection-timeout-seconds= ``` ```bash --idle-connection-timeout-seconds=60 ``` ```bash WEB3SIGNER_IDLE_CONNECTION_TIMEOUT_SECONDS=60 ``` ```bash idle-connection-timeout-seconds: 60 ``` Number of seconds to wait before terminating an idle connection. The default is 30. ### `key-config-path`, `key-store-path` ```bash --key-config-path= ``` ```bash --key-config-path=/Users/me/keys ``` ```bash WEB3SIGNER_KEY_CONFIG_PATH=/Users/me/keys ``` ```bash key-config-path: "/Users/me/keys" ``` Path to the directory containing the [YAML files required to access keys]. ### `key-store-config-file-max-size` ```bash --key-store-config-file-max-size= ``` ```bash --key-store-config-file-max-size=158000000 ``` ```bash WEB3SIGNER_KEY_STORE_CONFIG_FILE_MAX_SIZE=158000000 ``` ```bash key-store-config-file-max-size: 158000000 ``` 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` ```bash -l, --logging= ``` ```bash --logging=DEBUG ``` ```bash WEB3SIGNER_LOGGING=DEBUG ``` ```bash logging: "DEBUG" ``` Logging verbosity level. Possible values are `OFF`, `FATAL`, `WARN`, `INFO`, `DEBUG`, `TRACE`, `ALL`. The default is `INFO`. ### `logging-format` ```bash --logging-format= ``` ```bash --logging-format=ECS ``` ```bash WEB3SIGNER_LOGGING_FORMAT=ECS ``` ```bash logging-format: "ECS" ``` 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` ```bash --metrics-enabled[=] ``` ```bash --metrics-enabled=true ``` ```bash WEB3SIGNER_METRICS_ENABLED=true ``` ```bash metrics-enabled: true ``` Enables the metrics exporter. The default is `false`. ### `metrics-host` ```bash --metrics-host= ``` ```bash --metrics-host=186.10.10.1 ``` ```bash WEB3SIGNER_METRICS_HOST=186.10.10.1 ``` ```bash metrics-host: "186.10.10.1" ``` The host on which [Prometheus](https://prometheus.io/) accesses metrics. The default is `127.0.0.1`. ### `metrics-port` ```bash --metrics-port= ``` ```bash --metrics-port=6174 ``` ```bash WEB3SIGNER_METRICS_PORT=6174 ``` ```bash metrics-port: 6174 ``` The port (TCP) on which [Prometheus](https://prometheus.io/) accesses metrics. The default is `9001`. ### `metrics-category` ```bash --metrics-category=[,metrics-category...]... ``` ```bash --metrics-category=HTTP,SIGNING,JVM ``` ```bash WEB3SIGNER_METRICS_CATEGORY=HTTP,SIGNING,JVM ``` ```bash metrics-category: ["HTTP", "SIGNING", "JVM"] ``` A comma-separated list of categories for which to track metrics. The defaults are `HTTP`, `SIGNING`, `ETH2_SLASHING_PROTECTION`, `JVM`, `PROCESS`. ### `metrics-host-allowlist` ```bash --metrics-host-allowlist=[,...]... or "*" ``` ```bash --metrics-host-allowlist=medomain.com,meotherdomain.com ``` ```bash WEB3SIGNER_METRICS_HOST_ALLOWLIST=medomain.com,meotherdomain.com ``` ```bash metrics-host-allowlist: ["medomain.com", "meotherdomain.com"] ``` 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` ```bash --metrics-push-enabled[=] ``` ```bash --metrics-push-enabled=true ``` ```bash WEB3SIGNER_METRICS_PUSH_ENABLED=true ``` ```bash metrics-push-enabled=true ``` 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` ```bash --metrics-push-host= ``` ```bash --metrics-push-host=127.0.0.1 ``` ```bash WEB3SIGNER_METRICS_PUSH_HOST=127.0.0.1 ``` ```bash metrics-push-host="127.0.0.1" ``` 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` ```bash --metrics-push-interval= ``` ```bash --metrics-push-interval=30 ``` ```bash WEB3SIGNER_METRICS_PUSH_INTERVAL=30 ``` ```bash metrics-push-interval=30 ``` The interval, in seconds, to push metrics when in `push` mode. The default is 15. ### `metrics-push-port` ```bash --metrics-push-port= ``` ```bash --metrics-push-port=6174 ``` ```bash WEB3SIGNER_METRICS_PUSH_PORT=6174 ``` ```bash metrics-push-port="6174" ``` The port (TCP) of the [Prometheus Push Gateway](https://github.com/prometheus/pushgateway). The default is `9001`. ### `metrics-push-prometheus-job` ```bash --metrics-push-prometheus-job= ``` ```bash --metrics-push-prometheus-job="my-custom-job" ``` ```bash WEB3SIGNER_METRICS_PUSH_PROMETHEUS_JOB="my-custom-job" ``` ```bash metrics-push-prometheus-job="my-custom-job" ``` The job name when in `push` mode. The default is `web3signer-job`. ### `reload-timeout` ```bash --reload-timeout= ``` ```bash --reload-timeout=45 ``` ```bash WEB3SIGNER_RELOAD_TIMEOUT=45 ``` ```bash reload-timeout: "45" ``` 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` ```bash --signer-load-batch-size= ``` ```bash --signer-load-batch-size=300 ``` ```bash WEB3SIGNER_SIGNER_LOAD_BATCH_SIZE=300 ``` ```bash signer-load-batch-size: "300" ``` 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` ```bash --signer-load-parallel[=] ``` ```bash --signer-load-parallel=false ``` ```bash WEB3SIGNER_SIGNER_LOAD_PARALLEL=false ``` ```bash signer-load-parallel: false ``` Enables or disables parallel processing of signer configuration files. Set to `false` for sequential processing. The default is `true`. ### `signer-load-sequential-threshold` ```bash --signer-load-sequential-threshold= ``` ```bash --signer-load-sequential-threshold=50 ``` ```bash WEB3SIGNER_SIGNER_LOAD_SEQUENTIAL_THRESHOLD=50 ``` ```bash signer-load-sequential-threshold: "50" ``` 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` ```bash --signer-load-timeout= ``` ```bash --signer-load-timeout=120 ``` ```bash WEB3SIGNER_SIGNER_LOAD_TIMEOUT=120 ``` ```bash signer-load-timeout: "120" ``` 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` ```bash --tls-keystore-file= ``` ```bash --tls-keystore-file=/Users/me/my_node/certificate.pfx ``` ```bash WEB3SIGNER_TLS_KEYSTORE_FILE=/Users/me/my_node/certificate.pfx ``` ```bash tls-keystore-file: "/Users/me/my_node/certificate.pfx" ``` PKCS #12 formatted keystore. Used to enable TLS for [client connections](../../how-to/configure-tls.md). ### `tls-keystore-password-file` ```bash --tls-keystore-password-file= ``` ```bash --tls-keystore-password-file=/Users/me/my_node/password.txt ``` ```bash WEB3SIGNER_TLS_KEYSTORE_PASSWORD_FILE=/Users/me/my_node/password.txt ``` ```bash tls-keystore-password-file: "/Users/me/my_node/password.txt" ``` Password file used to decrypt the keystore. ### `tls-allow-any-client` ```bash --tls-allow-any-client= ``` ```bash --tls-allow-any-client=true ``` ```bash WEB3SIGNER_TLS_ALLOW_ANY_CLIENT=true ``` ```bash tls-allow-any-client: true ``` 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` ```bash --tls-known-clients-file= ``` ```bash --tls-known-clients-file=/Users/me/my_node/knownClients.txt ``` ```bash WEB3SIGNER_TLS_KNOWN_CLIENTS_FILE=/Users/me/my_node/knownClients.txt ``` ```bash tls-known-clients-file: "/Users/me/my_node/knownClients.txt" ``` 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` ```bash --tls-allow-ca-clients ``` ```bash WEB3SIGNER_TLS_ALLOW_CA_CLIENTS ``` ```bash tls-allow-ca-clients ``` Allows clients signed with trusted CA certificates to connect. ### `vertx-worker-pool-size` ```bash title="Syntax" --vertx-worker-pool-size= ``` ```bash --vertx-worker-pool-size=40 ``` ```bash WEB3SIGNER_VERTX_WORKER_POOL_SIZE=40 ``` ```bash vertx-worker-pool-size: 40 ``` 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. [YAML files required to access keys]: ../key-config-file-params.md [Web3Signer metrics]: ../../how-to/monitor/metrics.md