Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add correct language for --rest-api-host-allowlist #610

Merged
merged 20 commits into from
Oct 24, 2024
Merged

Add correct language for --rest-api-host-allowlist #610

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
20 commits
Select commit Hold shift + click to select a range
1e50d02
add correct language
joaniefromtheblock Oct 4, 2024
f869875
quiet linter
joaniefromtheblock Oct 4, 2024
6b4a696
Update to suggestions
joaniefromtheblock Oct 10, 2024
a574449
Merge branch 'main' into update-allowlist-flag
joaniefromtheblock Oct 10, 2024
1756598
make example clearer
joaniefromtheblock Oct 10, 2024
f0cb295
add period
joaniefromtheblock Oct 10, 2024
f63f2e9
Update to fix linter
joaniefromtheblock Oct 10, 2024
b334ac1
Merge branch 'main' into update-allowlist-flag
joaniefromtheblock Oct 15, 2024
c6ec397
Merge branch 'main' into update-allowlist-flag
joaniefromtheblock Oct 18, 2024
539484a
update wording
joaniefromtheblock Oct 18, 2024
51d46ba
Merge branch 'main' into update-allowlist-flag
joaniefromtheblock Oct 18, 2024
1942582
make clearer formatting
joaniefromtheblock Oct 21, 2024
cf78f88
make linter less angry
joaniefromtheblock Oct 21, 2024
2fcb6ec
move description to rest doc
joaniefromtheblock Oct 21, 2024
d770f2e
make linter less angry
joaniefromtheblock Oct 21, 2024
73ddab2
remove trailing space
joaniefromtheblock Oct 22, 2024
bf55ee3
clear up linter noise a bit
joaniefromtheblock Oct 22, 2024
2eeeaf4
Update docs/reference/rest.md
joaniefromtheblock Oct 22, 2024
234dd9f
style guide edit
joaniefromtheblock Oct 23, 2024
088047a
Update index.md
joaniefromtheblock Oct 23, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
28 changes: 20 additions & 8 deletions docs/reference/cli/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2745,7 +2745,7 @@
### `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 @@
<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.
joaniefromtheblock marked this conversation as resolved.
Show resolved Hide resolved
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.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I have question: not yet clear to me whether the example above is necessary, i.e. the moment you add a specified value, you then override both defaults and need to provide these explicitly (as per the example line 2772 above) OR whether the example is providing unnecessary data which are served by default...?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@m4sterbunny if they provide the option without values, they should get an error


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.

Check failure on line 2791 in docs/reference/cli/index.md

View workflow job for this annotation

GitHub Actions / Spelling 

[vale] reported by reviewdog 🐶
[Microsoft.Quotes] Punctuation should be inside the quotes.

Raw Output:
{"message": "[Microsoft.Quotes] Punctuation should be inside the quotes.", "location": {"path": "docs/reference/cli/index.md", "range": {"start": {"line": 2791, "column": 29}}}, "severity": "ERROR"}
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
To allow all hostnames, use "*". We don't recommend allowing all hostnames for production environments.
To allow all hostnames, use "*". However, we don't recommend this for production environments.

Copy link
Contributor Author

@joaniefromtheblock joaniefromtheblock Oct 22, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Other parts of the doc use the original wording, so I repeated it for consistency. I think being more specific instead of using 'this' could be more helpful.


:::

:::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
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -37,7 +37,6 @@
<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 @@
</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`. |

Check failure on line 78 in docs/reference/rest.md

View workflow job for this annotation

GitHub Actions / Lint

Line length 

docs/reference/rest.md:78:201 MD013/line-length Line length [Expected: 200; Actual: 206] https://github.com/DavidAnson/markdownlint/blob/v0.35.0/doc/md013.md
| 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. |

Check failure on line 79 in docs/reference/rest.md

View workflow job for this annotation

GitHub Actions / Lint

Line length 

docs/reference/rest.md:79:201 MD013/line-length Line length [Expected: 200; Actual: 241] https://github.com/DavidAnson/markdownlint/blob/v0.35.0/doc/md013.md
| 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. |

Check failure on line 80 in docs/reference/rest.md

View workflow job for this annotation

GitHub Actions / Lint

Line length 

docs/reference/rest.md:80:201 MD013/line-length Line length [Expected: 200; Actual: 248] https://github.com/DavidAnson/markdownlint/blob/v0.35.0/doc/md013.md
| 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. |

Check failure on line 81 in docs/reference/rest.md

View workflow job for this annotation

GitHub Actions / Lint

Line length 

docs/reference/rest.md:81:201 MD013/line-length Line length [Expected: 200; Actual: 251] https://github.com/DavidAnson/markdownlint/blob/v0.35.0/doc/md013.md

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

Check warning on line 86 in docs/reference/rest.md

View workflow job for this annotation

GitHub Actions / Spelling 

[vale] reported by reviewdog 🐶
[Microsoft.Adverbs] Remove 'separately' if it's not important to the meaning of the statement.

Raw Output:
{"message": "[Microsoft.Adverbs] Remove 'separately' if it's not important to the meaning of the statement.", "location": {"path": "docs/reference/rest.md", "range": {"start": {"line": 86, "column": 89}}}, "severity": "WARNING"}

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
Loading