Skip to content

Commit

Permalink
Add correct language for --rest-api-host-allowlist (#610)
Browse files Browse the repository at this point in the history 
* add correct language

* quiet linter

* Update to suggestions

* make example clearer

* add period

* Update to fix linter

* update wording

* make clearer formatting

* make linter less angry

* move description to rest doc

* make linter less angry

* remove trailing space

* clear up linter noise a bit

* Update docs/reference/rest.md

Co-authored-by: m4sterbunny <[email protected]>

* style guide edit

* Update index.md

---------

Co-authored-by: m4sterbunny <[email protected]>
  • Loading branch information
@joaniefromtheblock @m4sterbunny
joaniefromtheblock and m4sterbunny authored Oct 24, 2024
1 parent 4acfbba commit a800f3c
Show file tree
Hide file tree
Showing 2 changed files with 44 additions and 13 deletions.
28 changes: 20 additions & 8 deletions docs/reference/cli/index.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2745,7 +2745,7 @@ trusted parties.
### `rest-api-host-allowlist`

<Tabs>
<TabItem value="Syntax" label="Syntax" default>
<TabItem value="Syntax" label="Syntax" default>

```bash
--rest-api-host-allowlist=<hostname>[,<hostname>...]... or "*"
Expand All @@ -2755,36 +2755,48 @@ trusted parties.
<TabItem value="Example" label="Example" >

```bash
--rest-api-host-allowlist=medomain.com,meotherdomain.com
--rest-api-host-allowlist=localhost,127.0.0.1,10.0.0.1
```

</TabItem>
<TabItem value="Environment variable" label="Environment variable" >

```bash
TEKU_REST_API_HOST_ALLOWLIST=medomain.com,meotherdomain.com
TEKU_REST_API_HOST_ALLOWLIST=localhost,127.0.0.1,10.0.0.1
```

</TabItem>
<TabItem value="Configuration file" label="Configuration file" >

```bash
rest-api-host-allowlist: ["medomain.com", "meotherdomain.com"]
rest-api-host-allowlist: ["localhost", "127.0.0.1", "10.0.0.1"]
```

</TabItem>
</Tabs>

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`
Expand Down
29 changes: 24 additions & 5 deletions docs/reference/rest.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -37,7 +37,6 @@ You can also use tools such as [Postman] or [cURL] to interact with Teku APIs.
<Tabs>
<TabItem value="cURL request" label="cURL request" default>


```bash
curl -X GET "http://localhost:5051/eth/v1/node/identity"
```
Expand Down Expand Up @@ -67,19 +66,39 @@ curl -X GET "http://localhost:5051/eth/v1/node/identity"
</TabItem>
</Tabs>

### 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:

Expand Down

0 comments on commit a800f3c

Please sign in to comment.