Skip to content

Document dual-stack support and :: bind-ip default #303

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

Open
tillrohrmann wants to merge 2 commits into
base: restate-1.7
Choose a base branch
from
Open

Document dual-stack support and :: bind-ip default #303

Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
fe054ae
Document dual-stack support and :: bind-ip default
tillrohrmann Jun 4, 2026
02b03b8
Clarify when :: dual-stack binding works in IPv4-only environments
tillrohrmann Jun 4, 2026
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
34 changes: 30 additions & 4 deletions docs/server/networking.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -95,7 +95,7 @@ These options apply to all services unless overridden per-service:

| Option | Default | Description |
|--------|---------|-------------|
| `bind-ip` | `0.0.0.0` | Local interface IP to bind on |
| `bind-ip` | `::` | Local interface IP to bind on. The default `::` (IPv6 unspecified) creates a dual-stack socket on most systems. See [Dual-Stack and IPv6](#dual-stack-and-ipv6) |
| `bind-port` | `5122` | Port for the fabric service |
| `use-random-ports` | `false` | Use random available ports instead of defaults |
| `advertised-host` | Auto-detected | Hostname to advertise to peers |
Expand All @@ -110,7 +110,7 @@ use-random-ports = true

### Per-Service Configuration

Each service can override the global settings. Use `bind-port` to change just the port while keeping the default bind IP (`0.0.0.0`):
Each service can override the global settings. Use `bind-port` to change just the port while keeping the default bind IP (`::`):

```toml restate.toml
# Fabric service (node-to-node) - uses global bind-ip with custom port
Expand All @@ -135,6 +135,32 @@ bind-address = "192.168.1.10:9070"
bind-address = "192.168.1.10:8080"
```

### Dual-Stack and IPv6

@tillrohrmann tillrohrmann Jun 4, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

Maybe this is a bit too detailed in terms of what's interesting to users. @gvdongen do you have a recommendation for whether to keep or remove this section?

@gvdongen gvdongen Jun 9, 2026 •
edited
Loading

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

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

You could put it as a collapsed section and call it "Advanced: Dual-stack and IPv6" and put it at the bottom of the section.

You can collapse it with <Accordion title="..."> ... </Accordion>


<Info>
The default `bind-ip` changed from `0.0.0.0` to `::` in Restate Server 1.7.0.
</Info>

By default, Restate binds to `::` (the IPv6 unspecified address). On most systems this creates a dual-stack socket that accepts both IPv6 and IPv4 connections, so the server is reachable regardless of which address family clients or peers use. This makes Restate work out of the box in IPv4-only, IPv6-only, and dual-stack environments, including IPv6-only Kubernetes clusters where binding to `0.0.0.0` would fail.

Restate also detects the host's publicly routable IP address to derive [advertised addresses](#advertised-addresses). This detection prefers IPv6 and falls back to IPv4 when IPv6 is not available.

If you set `bind-ip` explicitly, your value takes precedence and this default does not apply. To restore the previous IPv4-only behavior, set:

```toml restate.toml
bind-ip = "0.0.0.0"
```

Or via environment variable:

```bash
RESTATE_BIND_IP=0.0.0.0
```

<Note>
On the rare Linux systems configured with `net.ipv6.bindv6only=1`, binding to `::` accepts IPv6 connections only. Set `bind-ip = "0.0.0.0"` if you need to accept IPv4 connections on such hosts.
</Note>

### Environment Variable Overrides

All networking options can be set via environment variables:
Expand Down Expand Up @@ -289,7 +315,7 @@ When using random ports:
### Local Development (Default)

No configuration needed. Restate listens on:
- TCP: `0.0.0.0:8080` (ingress), `0.0.0.0:9070` (admin), `0.0.0.0:5122` (fabric)
- TCP: `[::]:8080` (ingress), `[::]:9070` (admin), `[::]:5122` (fabric). The default `::` bind address accepts both IPv6 and IPv4 connections on most systems (see [Dual-Stack and IPv6](#dual-stack-and-ipv6))
- Unix: `restate-data/<node-name>/*.sock`

### Multi-Node Cluster
Expand Down Expand Up @@ -364,7 +390,7 @@ Networking options can also be set via command-line flags:
```bash
restate-server \
--listen-mode=tcp \
--bind-ip=0.0.0.0 \
--bind-ip=:: \
--bind-port=5122 \
--advertised-host=my-host.example.com
```
Expand Down
Loading