Entrypoints

An entrypoint is one listening socket. Everything the gateway serves arrives on one, and a route binds a domainmap to exactly one entrypoint.

Entrypoints are a boot-plane setting. They are read from the bootstrap file at start-up and are not hot-reloadable, so adding or moving a listener needs a restart. Everything in the routing plane reloads live.

gateway.svc config generate multi-port

Declaring them

entrypoints:
  - name: web
    address: ":80"
    protocol: http
    redirect: { to: websecure, scheme: https, permanent: true }

  - name: websecure
    address: ":443"
    protocol: http
    timeouts: { read: 10s, write: 0s, idle: 180s }

  - name: internal
    address: "127.0.0.1:8444"
    protocol: http
    trustedips: [127.0.0.1]

  - name: postgres
    address: ":5432"
    protocol: tcp

  - name: dns
    address: ":53"
    protocol: udp
    udp:
      backend: dns-svc

Key	Default	Meaning
name	required	How routes refer to this listener
address	required	:port, or host:port to bind one interface
protocol	http	http, tcp or udp
reuseport	true	Allow several processes to bind the same address
trustedips	none	Peers whose X-Forwarded-* headers are honoured
timeouts.read / .write / .idle	the gateway-wide timeouts:	Per-listener overrides
redirect	none	Listener-wide redirect. HTTP only
udp.backend	required for UDP	The backend this listener forwards to

Names must be unique, an address is required, and the parser reports the offending entry by name, or by index when the name itself is missing.

Redirecting a whole listener

The usual case is upgrading plain HTTP to HTTPS across a port:

- name: web
  address: ":80"
  protocol: http
  redirect: { to: websecure, scheme: https, permanent: true }

to names another entrypoint and is required. permanent defaults to true, which sends 308; set it to false for 302. redirect is valid on HTTP entrypoints only, and the target must exist.

ACME HTTP-01 needs :80 reachable

An HTTP-01 challenge is answered on the plain HTTP listener. A blanket redirect on :80 and an HTTP-01 resolver are usually configured together, and the router answers the challenge path before the redirect applies. Keep :80 reachable from the internet while a certificate is being issued or renewed.

Trusted IPs

trustedips is the list of peer addresses whose forwarded headers the gateway believes.

• From a trusted peer, X-Forwarded-Host is honoured and becomes the routing domain, and X-Real-Ip is carried through.
• From an untrusted peer, the whole X-Forwarded-* set is deleted after the origin host and client IP have been captured internally.

This is what stops a client choosing its own tenant by sending a header. See Security.

If the gateway sits behind another proxy or a load balancer that rewrites Host, that peer’s address has to be in this list or nothing will match.

Timeouts

Per-entrypoint timeouts override the gateway-wide timeouts: block, and an omitted value falls back to it rather than to a hardcoded default. The gateway-wide defaults are read: 10s, write: 0s, idle: 180s.

write is the whole-response deadline. It defaults to 0s, meaning no deadline, because a response deadline cuts server-sent events and long-lived streams. If you set it, put streaming routes on their own entrypoint that keeps it at 0s.

entrypoints:
  - name: websecure
    address: ":443"
    timeouts: { read: 10s, write: 30s, idle: 180s }

  - name: streams
    address: ":8443"
    timeouts: { read: 10s, write: 0s, idle: 600s }

TCP and UDP

A TCP or UDP entrypoint carries bytes at layer 4. That is the right tool for a database port, a message broker or DNS, and it is a different shape from the HTTP path:

	HTTP entrypoint	TCP / UDP entrypoint
Route selection	Host, path prefix, priority	the listener itself
Middleware chain	full chain	not applicable
Tenancy headers	stamped per request	not applicable
TLS	terminated, or passed through	passed through

Layer 4 carries no per-request tenant attribution, because there is no request to attribute. Give an L4 port one tenant, by binding a listener per tenant rather than expecting the gateway to tell them apart inside the stream.

UDP has no routing rules: one UDP entrypoint forwards to exactly one backend, which is why the backend is named on the listener rather than on a route.

The legacy port keys

A bootstrap with no entrypoints: block still works. The gateway synthesises two listeners from the older keys:

Key	Synthesised entrypoint
port	websecure, the public listener
internal.port	websecureinternal, the mesh listener
internal.trustedips	that listener’s trusted peers

In this mode internal.port is required, and a boot error naming it means the config is in legacy listener mode. Declaring an explicit entrypoints: list replaces both and is the clearer shape for anything beyond one public port.

See also

• Configuration: every boot key
• Security: forwarded headers and tenancy spoofing
• Usage: timeouts and streaming in context