diff --git a/docs/reference/cli/index.md b/docs/reference/cli/index.md index e0c430cf5..63437dae8 100644 --- a/docs/reference/cli/index.md +++ b/docs/reference/cli/index.md @@ -2745,7 +2745,7 @@ trusted parties. ### `rest-api-host-allowlist` - + ```bash --rest-api-host-allowlist=[,...]... or "*" @@ -2755,36 +2755,48 @@ trusted parties. ```bash ---rest-api-host-allowlist=medomain.com,meotherdomain.com +--rest-api-host-allowlist=localhost,127.0.0.1,10.0.0.1 ``` ```bash -TEKU_REST_API_HOST_ALLOWLIST=medomain.com,meotherdomain.com +TEKU_REST_API_HOST_ALLOWLIST=localhost,127.0.0.1,10.0.0.1 ``` ```bash -rest-api-host-allowlist: ["medomain.com", "meotherdomain.com"] +rest-api-host-allowlist: ["localhost", "127.0.0.1", "10.0.0.1"] ``` -A comma-separated list of hostnames to allow access to the REST API. -By default, Teku accepts access from `localhost` and `127.0.0.1`. +A comma-separated list of hostnames or IP addresses from which the REST API server will respond. +This flag restricts the server's responding addresses, but not the client access. + +By default, Teku's REST API server responds only to requests where the `Host` header matches `localhost` or `127.0.0.1`. +If you specify values, the server will only respond to requests where the `Host` header matches one of the specified hosts or IP addresses. + +You can configure the API to listen on all network interfaces using [`rest-api-interface="0.0.0.0"`](#rest-api-interface) +and allow connections from specific addresses by setting `rest-api-host-allowlist`. +See [configure the API for network interfaces and host allowlist](../rest.md#configure-the-api-for-network-interfaces-and-host-allowlist) +for more information. + +:::tip + +To allow all hostnames, use "*". We don't recommend allowing all hostnames for production environments. + +::: :::warning Only trusted parties should access the REST API. Do not directly expose these APIs publicly on production nodes. -We don't recommend allowing all hostnames (`"*"`) for production environments. - ::: ### `rest-api-interface` diff --git a/docs/reference/rest.md b/docs/reference/rest.md index eb8458f75..a39cab528 100644 --- a/docs/reference/rest.md +++ b/docs/reference/rest.md @@ -37,7 +37,6 @@ You can also use tools such as [Postman] or [cURL] to interact with Teku APIs. - ```bash curl -X GET "http://localhost:5051/eth/v1/node/identity" ``` @@ -67,19 +66,39 @@ curl -X GET "http://localhost:5051/eth/v1/node/identity" +### Configure the API for network interfaces and host allowlist + +You can use the [`rest-api-host-allowlist`](cli/index.md#rest-api-host-allowlist) and [`rest-api-interface`](cli/index.md#rest-api-interface) +options to control which hosts and network interfaces Teku's REST API responds to. +Configure the API to listen on specific IP addresses or all interfaces with `rest-api-interface` and control +which hosts can connect using `rest-api-host-allowlist`: + +| Configuration | Interface | Allowlist | Result | +|---------------|-----------|-----------|--------| +| Listen on all IP addresses and allow all hosts | `rest-api-interface="0.0.0.0"` | `rest-api-host-allowlist=["*"]` | Enables connections from any address, such as `localhost` (`127.0.0.1`) or `10.0.0.1`. | +| Listen on a specific IP address (`10.0.0.1`) and allow all hosts | `rest-api-interface="10.0.0.1"` | `rest-api-host-allowlist=["*"]` | Only the specified IP (`10.0.0.1`) can connect, and attempts from `localhost` (`127.0.0.1`) will fail. | +| Listen on all IP addresses but allow only `localhost` | `rest-api-interface="0.0.0.0"` | `rest-api-host-allowlist=["127.0.0.1"]` | Only `localhost` (`127.0.0.1`) can connect; other IP addresses (for example `10.0.0.1`) will receive a 403 error. | +| Listen on a specific IP address (`10.0.0.1`) but allow only `localhost` (`127.0.0.1`) | `rest-api-interface="10.0.0.1"` | `rest-api-host-allowlist=["127.0.0.1"]` | Neither can connect. `localhost` can't reach the server, and `10.0.0.1` is blocked. | + ## Enable the validator client API -The [validator client API](../how-to/use-external-signer/manage-keys.md) allows you to call the [key manager API endpoints](https://ethereum.github.io/keymanager-APIs/) and is enabled separately from the REST API methods. +The [validator client API](../how-to/use-external-signer/manage-keys.md) allows you to call the +[key manager API endpoints](https://ethereum.github.io/keymanager-APIs/) and is enabled separately from the REST API methods. -Enable the validator client API service from the command line by including the [`--validator-api-enabled`](cli/index.md#validator-api-enabled) command line option. +Enable the validator client API service from the command line by including the +[`--validator-api-enabled`](cli/index.md#validator-api-enabled) command line option. -When enabling the validator client API, you must [create a keystore](../how-to/use-external-signer/manage-keys.md#create-a-keystore). Set the keystore using [`--validator-api-keystore-file`](cli/index.md#validator-api-keystore-file) and the password file for the keystore using [`--validator-api-keystore-password-file`](cli/index.md#validator-api-keystore-password-file). +When enabling the validator client API, you must [create a keystore](../how-to/use-external-signer/manage-keys.md#create-a-keystore). +Set the keystore using [`--validator-api-keystore-file`](cli/index.md#validator-api-keystore-file) and the password file for the +keystore using [`--validator-api-keystore-password-file`](cli/index.md#validator-api-keystore-password-file). ```bash title="Example" teku --validator-api-enabled --validator-api-keystore-file=validator_keystore.p12 --validator-api-keystore-password-file=validator_keystore_pass.txt ``` -The [OpenAPI specifications](https://swagger.io/specification/) for the validator client API are available at `/swagger-docs` when the [`--validator-api-docs-enabled`](cli/index.md#validator-api-docs-enabled) option is set to `true`. The `/swagger-docs` endpoint defines the API if code generators are in use. +The [OpenAPI specifications](https://swagger.io/specification/) for the validator client API are available at `/swagger-docs` when +the [`--validator-api-docs-enabled`](cli/index.md#validator-api-docs-enabled) option is set to `true`. +The `/swagger-docs` endpoint defines the API if code generators are in use. When enabling the API documentation endpoint, specify: