From 1e50d02257b270cf2cc4a7cb33670102219e100a Mon Sep 17 00:00:00 2001 From: Joan E <153745173+joaniefromtheblock@users.noreply.github.com> Date: Fri, 4 Oct 2024 01:33:42 +0000 Subject: [PATCH 01/16] add correct language --- docs/reference/cli/index.md | 22 ++++++++++++---------- 1 file changed, 12 insertions(+), 10 deletions(-) diff --git a/docs/reference/cli/index.md b/docs/reference/cli/index.md index e0c430cf5..071fd644f 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,32 +2755,34 @@ trusted parties. ```bash ---rest-api-host-allowlist=medomain.com,meotherdomain.com +--rest-api-host-allowlist=localhost,127.0.0.1,192.168.1.3 ``` - ```bash -TEKU_REST_API_HOST_ALLOWLIST=medomain.com,meotherdomain.com +TEKU_REST_API_HOST_ALLOWLIST=localhost,127.0.0.1,192.168.1.3 ``` - ```bash -rest-api-host-allowlist: ["medomain.com", "meotherdomain.com"] +rest-api-host-allowlist: ["localhost", "127.0.0.1", "192.168.1.3"] ``` - -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. + +You can listen on all addresses using `--rest-api-listen-address="*"` but restrict responses to specific hosts with this flag. + +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. + :::warning -Only trusted parties should access the REST API. +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. From f869875f5e86bf459389bf115984045a8fbb54eb Mon Sep 17 00:00:00 2001 From: Joan E <153745173+joaniefromtheblock@users.noreply.github.com> Date: Thu, 3 Oct 2024 21:37:21 -0400 Subject: [PATCH 02/16] quiet linter --- docs/reference/cli/index.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/reference/cli/index.md b/docs/reference/cli/index.md index 071fd644f..1993d9923 100644 --- a/docs/reference/cli/index.md +++ b/docs/reference/cli/index.md @@ -2772,14 +2772,13 @@ rest-api-host-allowlist: ["localhost", "127.0.0.1", "192.168.1.3"] -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. +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. You can listen on all addresses using `--rest-api-listen-address="*"` but restrict responses to specific hosts with this flag. 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. - :::warning Only trusted parties should access the REST API` From 6b4a696e30a94ecc7c132914f7d60c07e50bc76c Mon Sep 17 00:00:00 2001 From: Joan E <153745173+joaniefromtheblock@users.noreply.github.com> Date: Thu, 10 Oct 2024 15:38:15 -0400 Subject: [PATCH 03/16] Update to suggestions --- docs/reference/cli/index.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/docs/reference/cli/index.md b/docs/reference/cli/index.md index 1993d9923..e3c196515 100644 --- a/docs/reference/cli/index.md +++ b/docs/reference/cli/index.md @@ -2757,24 +2757,27 @@ trusted parties. ```bash --rest-api-host-allowlist=localhost,127.0.0.1,192.168.1.3 ``` + ```bash TEKU_REST_API_HOST_ALLOWLIST=localhost,127.0.0.1,192.168.1.3 ``` + ```bash rest-api-host-allowlist: ["localhost", "127.0.0.1", "192.168.1.3"] ``` + 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. -You can listen on all addresses using `--rest-api-listen-address="*"` but restrict responses to specific hosts with this flag. +You can listen on all addresses using `--rest-api-interface="*"` but restrict responses to specific hosts with this flag. 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. From 17565982d585ed744740b2a73be4247af123eb08 Mon Sep 17 00:00:00 2001 From: Joan E <153745173+joaniefromtheblock@users.noreply.github.com> Date: Thu, 10 Oct 2024 16:21:38 -0400 Subject: [PATCH 04/16] make example clearer --- docs/reference/cli/index.md | 15 +++++++++++---- 1 file changed, 11 insertions(+), 4 deletions(-) diff --git a/docs/reference/cli/index.md b/docs/reference/cli/index.md index e3c196515..90ac1edfd 100644 --- a/docs/reference/cli/index.md +++ b/docs/reference/cli/index.md @@ -2755,29 +2755,36 @@ trusted parties. ```bash ---rest-api-host-allowlist=localhost,127.0.0.1,192.168.1.3 +--rest-api-host-allowlist=localhost,127.0.0.1,10.0.0.1 ``` ```bash -TEKU_REST_API_HOST_ALLOWLIST=localhost,127.0.0.1,192.168.1.3 +TEKU_REST_API_HOST_ALLOWLIST=localhost,127.0.0.1,10.0.0.1 ``` ```bash -rest-api-host-allowlist: ["localhost", "127.0.0.1", "192.168.1.3"] +rest-api-host-allowlist: ["localhost", "127.0.0.1", "10.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. +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. You can listen on all addresses using `--rest-api-interface="*"` but restrict responses to specific hosts with this flag. +When you configure the interface to listen on all available IPs (`rest-api-interface: "0.0.0.0"`) and allow all hosts +(`["*"]`), you enable connections from any address, such as `localhost` (127.0.0.1) or a specific network IP like `10.0.0.1`. +If you instead set the API to listen only on a specific IP, like `10.0.0.1`, and still allow all hosts, only that IP can connect, and any attempts from `localhost` will fail. + +Configuring the interface to listen on all IPs but restricting the allowlist to `localhost` allows only `localhost` to connect, but other IPs, like `10.0.0.1`, receive a 403 error. +If the API listens on 10.0.0.1 but only allows `localhost`, neither can connect - `localhost` can't reach the server, and `10.0.0.1` is blocked. 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. From f0cb29564c15a06e5ddb1dfb2e75f42bfad49a47 Mon Sep 17 00:00:00 2001 From: Joan E <153745173+joaniefromtheblock@users.noreply.github.com> Date: Thu, 10 Oct 2024 16:22:51 -0400 Subject: [PATCH 05/16] add period --- docs/reference/cli/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/reference/cli/index.md b/docs/reference/cli/index.md index 90ac1edfd..e096c7fe9 100644 --- a/docs/reference/cli/index.md +++ b/docs/reference/cli/index.md @@ -2791,7 +2791,7 @@ If you specify values, the server will only respond to requests where the Host h :::warning -Only trusted parties should access the REST API` +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. From f63f2e958c43408bf17c2a0e4ee7912511c70a05 Mon Sep 17 00:00:00 2001 From: Joan E <153745173+joaniefromtheblock@users.noreply.github.com> Date: Thu, 10 Oct 2024 16:38:08 -0400 Subject: [PATCH 06/16] Update to fix linter --- docs/reference/cli/index.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/reference/cli/index.md b/docs/reference/cli/index.md index e096c7fe9..4989cb172 100644 --- a/docs/reference/cli/index.md +++ b/docs/reference/cli/index.md @@ -2775,15 +2775,15 @@ rest-api-host-allowlist: ["localhost", "127.0.0.1", "10.0.0.1"] -A comma-separated list of hostnames or IP addresses from which the REST API server will respond. +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. You can listen on all addresses using `--rest-api-interface="*"` but restrict responses to specific hosts with this flag. -When you configure the interface to listen on all available IPs (`rest-api-interface: "0.0.0.0"`) and allow all hosts -(`["*"]`), you enable connections from any address, such as `localhost` (127.0.0.1) or a specific network IP like `10.0.0.1`. -If you instead set the API to listen only on a specific IP, like `10.0.0.1`, and still allow all hosts, only that IP can connect, and any attempts from `localhost` will fail. +When you configure the interface to listen on all available IP addresses (`rest-api-interface: "0.0.0.0"`) and allow all hosts +(`["*"]`), you enable connections from any address, such as `localhost` (127.0.0.1) or a specific network IP such as `10.0.0.1`. +If you instead set the API to listen only on a specific IP, such as `10.0.0.1`, and still allow all hosts, only that IP can connect, and any attempts from `localhost` will fail. -Configuring the interface to listen on all IPs but restricting the allowlist to `localhost` allows only `localhost` to connect, but other IPs, like `10.0.0.1`, receive a 403 error. +Configuring the interface to listen on all IP addresses but restricting the allowlist to `localhost` allows only `localhost` to connect, and other IP addresses, such as `10.0.0.1`, receive a 403 error. If the API listens on 10.0.0.1 but only allows `localhost`, neither can connect - `localhost` can't reach the server, and `10.0.0.1` is blocked. By default, Teku's REST API server responds only to requests where the Host header matches `localhost` or `127.0.0.1`. From 539484afabc6ceefa1a22bd1d12ab6f574ce9979 Mon Sep 17 00:00:00 2001 From: Joan E <153745173+joaniefromtheblock@users.noreply.github.com> Date: Fri, 18 Oct 2024 00:22:37 +0000 Subject: [PATCH 07/16] update wording --- docs/reference/cli/index.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/reference/cli/index.md b/docs/reference/cli/index.md index 4989cb172..451c48572 100644 --- a/docs/reference/cli/index.md +++ b/docs/reference/cli/index.md @@ -2778,9 +2778,9 @@ rest-api-host-allowlist: ["localhost", "127.0.0.1", "10.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. -You can listen on all addresses using `--rest-api-interface="*"` but restrict responses to specific hosts with this flag. +You can configure the API to listen on all network interfaces using `rest-api-interface="0.0.0.0"` and allow connections from specific addresses by setting `rest-api-host-allowlist`. When you configure the interface to listen on all available IP addresses (`rest-api-interface: "0.0.0.0"`) and allow all hosts -(`["*"]`), you enable connections from any address, such as `localhost` (127.0.0.1) or a specific network IP such as `10.0.0.1`. +(`rest-api-host-allowlist: ["*"]`), you enable connections from any address, such as `localhost` (127.0.0.1) or a specific network IP such as `10.0.0.1`. If you instead set the API to listen only on a specific IP, such as `10.0.0.1`, and still allow all hosts, only that IP can connect, and any attempts from `localhost` will fail. Configuring the interface to listen on all IP addresses but restricting the allowlist to `localhost` allows only `localhost` to connect, and other IP addresses, such as `10.0.0.1`, receive a 403 error. From 1942582c3da59e382139071ff65b71f62d0d6792 Mon Sep 17 00:00:00 2001 From: Joan E <153745173+joaniefromtheblock@users.noreply.github.com> Date: Mon, 21 Oct 2024 08:35:47 -0400 Subject: [PATCH 08/16] make clearer formatting --- docs/reference/cli/index.md | 24 ++++++++++++++---------- 1 file changed, 14 insertions(+), 10 deletions(-) diff --git a/docs/reference/cli/index.md b/docs/reference/cli/index.md index 451c48572..0ea1b38b3 100644 --- a/docs/reference/cli/index.md +++ b/docs/reference/cli/index.md @@ -2778,24 +2778,28 @@ rest-api-host-allowlist: ["localhost", "127.0.0.1", "10.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. -You can configure the API to listen on all network interfaces using `rest-api-interface="0.0.0.0"` and allow connections from specific addresses by setting `rest-api-host-allowlist`. -When you configure the interface to listen on all available IP addresses (`rest-api-interface: "0.0.0.0"`) and allow all hosts -(`rest-api-host-allowlist: ["*"]`), you enable connections from any address, such as `localhost` (127.0.0.1) or a specific network IP such as `10.0.0.1`. -If you instead set the API to listen only on a specific IP, such as `10.0.0.1`, and still allow all hosts, only that IP can connect, and any attempts from `localhost` will fail. +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. -Configuring the interface to listen on all IP addresses but restricting the allowlist to `localhost` allows only `localhost` to connect, and other IP addresses, such as `10.0.0.1`, receive a 403 error. -If the API listens on 10.0.0.1 but only allows `localhost`, neither can connect - `localhost` can't reach the server, and `10.0.0.1` is blocked. +::: tip -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. +To allow all hostnames, use "*". We don't recommend allowing all hostnames for production environments. + +::: + +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`: + +- When you configure the interface to listen on all available IP addresses (`rest-api-interface: "0.0.0.0"`) and allow all hosts +(`rest-api-host-allowlist: ["*"]`), it enables connections from any address, such as `localhost` (127.0.0.1) or a specific network IP such as `10.0.0.1`. +- If you set the API to listen only on a specific IP address, such as `rest-api-interface="10.0.0.1"`, and still allow all hosts (`rest-api-host-allowlist: ["*"]`), only that IP address can connect, and any attempts from `localhost` will fail. +- Configuring the interface to listen on all IP addresses (`rest-api-interface: "0.0.0.0"`) but restricting the allowlist to `localhost` (`rest-api-host-allowlist: ["127.0.0.1"]`) allows only `localhost` to connect, and other IP addresses, such as `10.0.0.1`, will receive a 403 error. +- If the API listens on `10.0.0.1` (`rest-api-interface: "10.0.0.1"`) but only allows `localhost` (`rest-api-host-allowlist: ["127.0.0.1"]`), neither can connect - `localhost` can't reach the server, and `10.0.0.1` is blocked. :::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` From cf78f88e0a9c6e7e785524c06fc8155cfabef3f6 Mon Sep 17 00:00:00 2001 From: Joan E <153745173+joaniefromtheblock@users.noreply.github.com> Date: Mon, 21 Oct 2024 08:39:39 -0400 Subject: [PATCH 09/16] make linter less angry --- docs/reference/cli/index.md | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/docs/reference/cli/index.md b/docs/reference/cli/index.md index 0ea1b38b3..53c09230f 100644 --- a/docs/reference/cli/index.md +++ b/docs/reference/cli/index.md @@ -2791,9 +2791,12 @@ You can configure the API to listen on all network interfaces using [`rest-api-i - When you configure the interface to listen on all available IP addresses (`rest-api-interface: "0.0.0.0"`) and allow all hosts (`rest-api-host-allowlist: ["*"]`), it enables connections from any address, such as `localhost` (127.0.0.1) or a specific network IP such as `10.0.0.1`. -- If you set the API to listen only on a specific IP address, such as `rest-api-interface="10.0.0.1"`, and still allow all hosts (`rest-api-host-allowlist: ["*"]`), only that IP address can connect, and any attempts from `localhost` will fail. -- Configuring the interface to listen on all IP addresses (`rest-api-interface: "0.0.0.0"`) but restricting the allowlist to `localhost` (`rest-api-host-allowlist: ["127.0.0.1"]`) allows only `localhost` to connect, and other IP addresses, such as `10.0.0.1`, will receive a 403 error. -- If the API listens on `10.0.0.1` (`rest-api-interface: "10.0.0.1"`) but only allows `localhost` (`rest-api-host-allowlist: ["127.0.0.1"]`), neither can connect - `localhost` can't reach the server, and `10.0.0.1` is blocked. +- If you set the API to listen only on a specific IP address, such as `rest-api-interface="10.0.0.1"`, + and still allow all hosts (`rest-api-host-allowlist: ["*"]`), only that IP address can connect, and any attempts from `localhost` will fail. +- Configuring the interface to listen on all IP addresses (`rest-api-interface: "0.0.0.0"`) but restricting the allowlist to `localhost` (`rest-api-host-allowlist: ["127.0.0.1"]`) + allows only `localhost` to connect, and other IP addresses, such as `10.0.0.1`, will receive a 403 error. +- If the API listens on `10.0.0.1` (`rest-api-interface: "10.0.0.1"`) but only allows `localhost` (`rest-api-host-allowlist: ["127.0.0.1"]`), neither can connect + - `localhost` can't reach the server, and `10.0.0.1` is blocked. :::warning From 2fcb6ec59faaed71b0ad18890e4e17a0265c1e15 Mon Sep 17 00:00:00 2001 From: Joan E <153745173+joaniefromtheblock@users.noreply.github.com> Date: Mon, 21 Oct 2024 23:07:40 +0000 Subject: [PATCH 10/16] move description to rest doc --- docs/reference/cli/index.md | 14 +++----------- docs/reference/rest.md | 12 ++++++++++++ 2 files changed, 15 insertions(+), 11 deletions(-) diff --git a/docs/reference/cli/index.md b/docs/reference/cli/index.md index 53c09230f..d244d0ad8 100644 --- a/docs/reference/cli/index.md +++ b/docs/reference/cli/index.md @@ -2781,22 +2781,14 @@ 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. -::: tip +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. ::: -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`: - -- When you configure the interface to listen on all available IP addresses (`rest-api-interface: "0.0.0.0"`) and allow all hosts -(`rest-api-host-allowlist: ["*"]`), it enables connections from any address, such as `localhost` (127.0.0.1) or a specific network IP such as `10.0.0.1`. -- If you set the API to listen only on a specific IP address, such as `rest-api-interface="10.0.0.1"`, - and still allow all hosts (`rest-api-host-allowlist: ["*"]`), only that IP address can connect, and any attempts from `localhost` will fail. -- Configuring the interface to listen on all IP addresses (`rest-api-interface: "0.0.0.0"`) but restricting the allowlist to `localhost` (`rest-api-host-allowlist: ["127.0.0.1"]`) - allows only `localhost` to connect, and other IP addresses, such as `10.0.0.1`, will receive a 403 error. -- If the API listens on `10.0.0.1` (`rest-api-interface: "10.0.0.1"`) but only allows `localhost` (`rest-api-host-allowlist: ["127.0.0.1"]`), neither can connect - - `localhost` can't reach the server, and `10.0.0.1` is blocked. :::warning diff --git a/docs/reference/rest.md b/docs/reference/rest.md index eb8458f75..1f5cd71c5 100644 --- a/docs/reference/rest.md +++ b/docs/reference/rest.md @@ -67,6 +67,18 @@ 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 (e.g., `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` cannot 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. From d770f2ee74941ff937bf65048ea2f6b5935be234 Mon Sep 17 00:00:00 2001 From: Joan E <153745173+joaniefromtheblock@users.noreply.github.com> Date: Mon, 21 Oct 2024 23:14:11 +0000 Subject: [PATCH 11/16] make linter less angry --- docs/reference/cli/index.md | 6 ++++-- docs/reference/rest.md | 21 ++++++++++++++------- 2 files changed, 18 insertions(+), 9 deletions(-) diff --git a/docs/reference/cli/index.md b/docs/reference/cli/index.md index d244d0ad8..a05ded43c 100644 --- a/docs/reference/cli/index.md +++ b/docs/reference/cli/index.md @@ -2781,7 +2781,10 @@ 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. +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 @@ -2789,7 +2792,6 @@ To allow all hostnames, use "*". We don't recommend allowing all hostnames for p ::: - :::warning Only trusted parties should access the REST API. diff --git a/docs/reference/rest.md b/docs/reference/rest.md index 1f5cd71c5..9f13fadfc 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" ``` @@ -69,8 +68,10 @@ 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`: - +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 | |---------------|-----------|-----------|--------| @@ -81,17 +82,23 @@ You can use the [`rest-api-host-allowlist`](cli/index.md#rest-api-host-allowlist ## 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: From 73ddab2299d1c63d5baec89133bda51df416a474 Mon Sep 17 00:00:00 2001 From: Joan E <153745173+joaniefromtheblock@users.noreply.github.com> Date: Tue, 22 Oct 2024 01:14:17 -0400 Subject: [PATCH 12/16] remove trailing space --- docs/reference/cli/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/reference/cli/index.md b/docs/reference/cli/index.md index a05ded43c..63437dae8 100644 --- a/docs/reference/cli/index.md +++ b/docs/reference/cli/index.md @@ -2782,7 +2782,7 @@ By default, Teku's REST API server responds only to requests where the `Host` he 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`. +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. From bf55ee3637f741b18fb5bb2d82dd2c0ddd9e013b Mon Sep 17 00:00:00 2001 From: Joan E <153745173+joaniefromtheblock@users.noreply.github.com> Date: Tue, 22 Oct 2024 01:16:41 -0400 Subject: [PATCH 13/16] clear up linter noise a bit --- docs/reference/rest.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/reference/rest.md b/docs/reference/rest.md index 9f13fadfc..11051f7ef 100644 --- a/docs/reference/rest.md +++ b/docs/reference/rest.md @@ -69,7 +69,7 @@ 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. +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`: @@ -88,7 +88,7 @@ The [validator client API](../how-to/use-external-signer/manage-keys.md) allows 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). +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). @@ -97,7 +97,7 @@ teku --validator-api-enabled --validator-api-keystore-file=validator_keystore.p1 ``` 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 [`--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: From 2eeeaf41376f06ae427a0c9d7a610a0dc94c370e Mon Sep 17 00:00:00 2001 From: Joan E <153745173+joaniefromtheblock@users.noreply.github.com> Date: Tue, 22 Oct 2024 09:50:14 -0400 Subject: [PATCH 14/16] Update docs/reference/rest.md Co-authored-by: m4sterbunny --- docs/reference/rest.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/reference/rest.md b/docs/reference/rest.md index 11051f7ef..852575320 100644 --- a/docs/reference/rest.md +++ b/docs/reference/rest.md @@ -78,7 +78,7 @@ which hosts can connect using `rest-api-host-allowlist`: | 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 (e.g., `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` cannot reach the server, and `10.0.0.1` is blocked. | +| 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 From 234dd9f2c1586d0af1bfa62304177521178aeb8b Mon Sep 17 00:00:00 2001 From: Joan E <153745173+joaniefromtheblock@users.noreply.github.com> Date: Wed, 23 Oct 2024 19:16:02 -0400 Subject: [PATCH 15/16] style guide edit --- docs/reference/rest.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/reference/rest.md b/docs/reference/rest.md index 852575320..a39cab528 100644 --- a/docs/reference/rest.md +++ b/docs/reference/rest.md @@ -77,7 +77,7 @@ which hosts can connect using `rest-api-host-allowlist`: |---------------|-----------|-----------|--------| | 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 (e.g., `10.0.0.1`) will receive a 403 error. | +| 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 From 088047a0eba236d49ccf15abec26a454dade343d Mon Sep 17 00:00:00 2001 From: Joan E <153745173+joaniefromtheblock@users.noreply.github.com> Date: Wed, 23 Oct 2024 19:18:31 -0400 Subject: [PATCH 16/16] Update index.md