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.

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

Open
wants to merge 7 commits into
base: main
Choose a base branch
from
Open
Changes from all commits
Commits
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
23 changes: 17 additions & 6 deletions docs/reference/cli/index.md
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,28 +2755,39 @@ 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.

You can listen on all addresses using `--rest-api-interface="*"` but restrict responses to specific hosts with this flag.
Copy link
Contributor

Choose a reason for hiding this comment

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

interface is 0.0.0.0

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`.
Comment on lines +2782 to +2783
Copy link
Contributor

Choose a reason for hiding this comment

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

allow all hosts (rest-api-host-allowlist)
I believe the ["*"] is specific to configuration file syntax for allowlist...

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

:::warning

Expand Down
Loading