Entrypoints
Opening Connections for Incoming Requests
EntryPoints are the network entry points into Traefik Hub.
They define the port which will receive the packets, and whether to listen for TCP or UDP connections.
Configuration Examples
Port 80 only
## Static configuration
entryPoints:
web:
address: ":80"
You define an entrypoint
called web
that will listen on port 80
.
Port 80 & 443
## Static configuration
entryPoints:
web:
address: ":80"
websecure:
address: ":443"
- Two entrypoints are defined: one called
web
, and the other calledwebsecure
. web
listens on port80
, andwebsecure
on port443
.
UDP on port 1704
## Static configuration
entryPoints:
streaming:
address: ":1704/udp"
Configuration
General
Entrypoints are part of the static configuration.
Address
The address defines the port, and optionally the hostname, on which to listen for incoming connections and packets. It also defines the protocol to use (TCP or UDP). If no protocol is specified, the default is TCP. The format is:
[host]:port[/tcp|/udp]
If both TCP and UDP are wanted for the same port, two entryPoints definitions are needed, such as in the example below.
Both TCP and UDP on Port 3179
## Static configuration
entryPoints:
tcp_ep:
address: ":3179"
udp_ep:
address: ":3179/udp"
Listen on Specific IP Addresses Only
entryPoints:
specificIPv4:
address: "192.168.2.7:8888"
specificIPv6:
address: "[2001:db8::1]:8888"
Full details for how to specify address
can be found in net.Listen (and net.Dial) of the doc for go.
ReusePort
Field | Description | Default | Required |
---|---|---|---|
ReusePort | The ReusePort option enables EntryPoints from the same or different processes listening on the same TCP/UDP port by utilizing the SO_REUSEPORT socket option. It also allows the kernel to act like a load balancer to distribute incoming connections between entry points. | false | No |
For example, you can use it with the transport.lifeCycle to do canary deployments against Traefik Hub itself. Like upgrading Traefik Hub version or reloading the static configuration without any service downtime.
The ReusePort
option currently works only on Linux, FreeBSD, OpenBSD and Darwin.
It will be ignored on other platforms.
There is a known bug in the Linux kernel that may cause unintended TCP connection failures when using the ReusePort
option.
For more details, see https://lwn.net/Articles/853637/.
Listen on the same port
entryPoints:
web:
address: ":80"
reusePort: true
Now it is possible to run multiple Traefik Hub processes with the same EntryPoint configuration.
Listen on the same port but bind to a different host
entryPoints:
web:
address: ":80"
reusePort: true
privateWeb:
address: "192.168.1.2:80"
reusePort: true
Requests to 192.168.1.2:80
will only be handled by routers that have privateWeb
as the entry point.
AsDefault
Field | Description | Default | Required |
---|---|---|---|
AsDefault | The AsDefault option marks the EntryPoint to be in the list of default EntryPoints. EntryPoints in this list are used (by default) on HTTP and TCP routers that do not define their own EntryPoints option. | false | No |
If there is no EntryPoint with the AsDefault
option set to true
, then the list of default EntryPoints includes all HTTP/TCP EntryPoints.
If at least one EntryPoint has the AsDefault
option set to true
,
then the list of default EntryPoints includes only EntryPoints that have the AsDefault
option set to true
.
Some built-in EntryPoints are always excluded from the list, namely: traefik
.
The AsDefault
option has no effect on UDP EntryPoints.
When a UDP router does not define the EntryPoints option, it is attached to all available UDP EntryPoints.
Defining only one EntryPoint as default:
entryPoints:
web:
address: ":80"
websecure:
address: ":443"
asDefault: true
HTTP/2
maxConcurrentStreams
Field | Description | Default | Required |
---|---|---|---|
maxConcurrentStreams | maxConcurrentStreams specifies the number of concurrent streams per connection that each client is allowed to initiate. The maxConcurrentStreams value must be greater than zero. | 250 | No |
entryPoints:
foo:
http2:
maxConcurrentStreams: 250
HTTP/3
http3
http3
enables HTTP/3 protocol on the entryPoint.
HTTP/3 requires a TCP entryPoint, as HTTP/3 always starts as a TCP connection that then gets upgraded to UDP.
In most scenarios, this entryPoint is the same as the one used for TLS traffic.
entryPoints:
name:
http3: {}
As HTTP/3 actually uses UDP, when traefik hub is configured with a TCP entryPoint on port N with HTTP/3 enabled,
the underlying HTTP/3 server that is started automatically listens on UDP port N too. As a consequence,
it means port N cannot be used by another UDP entryPoint.
Since HTTP/3 requires the use of TLS,
only routers with TLS enabled will be usable with HTTP/3.
advertisedPort
http3.advertisedPort
defines which UDP port to advertise as the HTTP/3 authority.
It defaults to the entryPoint's address port.
It can be used to override the authority in the alt-svc
header, for example if the public facing port is different from where Traefik Hub is listening.
entryPoints:
name:
http3:
advertisedPort: 443
Forwarded Headers
You can configure Traefik Hub to trust the forwarded headers information (X-Forwarded-*
).
forwardedHeaders.trustedIPs
Trusting Forwarded Headers from specific IPs.
## Static configuration
entryPoints:
web:
address: ":80"
forwardedHeaders:
trustedIPs:
- "127.0.0.1/32"
- "192.168.1.7"
forwardedHeaders.insecure
Insecure Mode (Always Trusting Forwarded Headers).
## Static configuration
entryPoints:
web:
address: ":80"
forwardedHeaders:
insecure: true
Transport
respondingTimeouts
Field | Description | Default | Required |
---|---|---|---|
respondingTimeouts | respondingTimeouts are timeouts for incoming requests to the Traefik Hub instance. This is the maximum duration for reading the entire request, including the body. Setting them has no effect for UDP entryPoints. | 0s (seconds) | No |
transport.respondingTimeouts.readTimeout
readTimeout
is the maximum duration for reading the entire request, including the body.
If zero, no timeout exists.
Can be provided in a format supported by time.ParseDuration or as raw values (digits).
If no units are provided, the value is parsed assuming seconds.
## Static configuration
entryPoints:
name:
address: ":8888"
transport:
respondingTimeouts:
readTimeout: 42
transport.respondingTimeouts.writeTimeout
Field | Description | Default | Required |
---|---|---|---|
writeTimeout | writeTimeout is the maximum duration before timing out writes of the response. It covers the time from the end of the request header read to the end of the response write. If zero, no timeout exists. | 0s (seconds) | No |
Can be provided in a format supported by time.ParseDuration or as raw values (digits). If no units are provided, the value is parsed assuming seconds.
## Static configuration
entryPoints:
name:
address: ":8888"
transport:
respondingTimeouts:
writeTimeout: 42
transport.respondingTimeouts.idleTimeout
Field | Description | Default | Required |
---|---|---|---|
idleTimeout | idleTimeout is the maximum duration an idle (keep-alive) connection will remain idle before closing itself. If zero, no timeout exists | 180s (seconds) | No |
Can be provided in a format supported by time.ParseDuration or as raw values (digits). If no units are provided, the value is parsed assuming seconds.
## Static configuration
entryPoints:
name:
address: ":8888"
transport:
respondingTimeouts:
idleTimeout: 42
lifeCycle
lifeCycle
controls the behavior of Traefik Hub during the shutdown phase
Field | Description | Default | Required |
---|---|---|---|
lifeCycle.requestAcceptGraceTimeout | Duration to keep accepting requests prior to initiating the graceful termination period (as defined by the graceTimeOut option). This option is meant to give downstream load-balancers sufficient time to take Traefik Hub out of rotation. | 0s (seconds) | No |
Can be provided in a format supported by time.ParseDuration or as raw values (digits).
If no units are provided, the value is parsed assuming seconds. The zero duration disables the request accepting grace period, i.e., Traefik Hub will immediately proceed to the grace period.
## Static configuration
entryPoints:
name:
address: ":8888"
transport:
lifeCycle:
requestAcceptGraceTimeout: 42
Field | Description | Default | Required |
---|---|---|---|
lifeCycle.graceTimeOut | Duration to give active requests a chance to finish before Traefik Hub stops. | 10s (seconds) | No |
Can be provided in a format supported by time.ParseDuration or as raw values (digits).
If no units are provided, the value is parsed assuming seconds.
In this time frame no new requests are accepted.
## Static configuration
entryPoints:
name:
address: ":8888"
transport:
lifeCycle:
graceTimeOut: 42
keepAliveMaxRequests
Field | Description | Default | Required |
---|---|---|---|
keepAliveMaxRequests | The maximum number of requests Traefik Hub can handle before sending a Connection: Close header to the client (for HTTP2, Traefik Hub sends a GOAWAY). Zero means no limit. | 0s (seconds) | No |
## Static configuration
entryPoints:
name:
address: ":8888"
transport:
keepAliveMaxRequests: 42
keepAliveMaxTime
Field | Description | Default | Required |
---|---|---|---|
keepAliveMaxTime | The maximum duration Traefik Hub can handle requests before sending a Connection: Close header to the client (for HTTP2, Traefik Hub sends a GOAWAY). Zero means no limit. | 0s (seconds) | No |
## Static configuration
entryPoints:
name:
address: ":8888"
transport:
keepAliveMaxTime: 42s
ProxyProtocol
Traefik Hub supports PROXY protocol version 1 and 2.
If PROXY protocol header parsing is enabled for the entry point, this entry point can accept connections with or without PROXY protocol headers.
If the PROXY protocol header is passed, then the version is determined automatically.
proxyProtocol.trustedIPs
Enabling PROXY protocol with Trusted IPs.
## Static configuration
entryPoints:
web:
address: ":80"
proxyProtocol:
trustedIPs:
- "127.0.0.1/32"
- "192.168.1.7"
IPs in trustedIPs
only will lead to remote client address replacement: Declare load-balancer IPs or CIDR range here.
proxyProtocol.insecure
Insecure Mode (test environment only).
In a test environment, you can configure Traefik Hub to trust every incoming connection.
Doing so, every remote client address will be replaced (trustedIPs
won't have any effect)
## Static configuration
entryPoints:
web:
address: ":80"
proxyProtocol:
insecure: true
When queuing Traefik Hub behind another load-balancer, make sure to configure PROXY protocol on both sides. Not doing so could introduce a security risk in your system (enabling request forgery).
HTTP Options
This whole section is dedicated to options, keyed by entry point, that will apply only to HTTP routing.
Redirection
Example HTTPS redirection (80 to 443):
entryPoints:
web:
address: :80
http:
redirections:
entryPoint:
to: websecure
scheme: https
websecure:
address: :443
entryPoint
This section is a convenience to enable (permanent) redirecting of all incoming requests on an entry point (for example, port 80
) to another entry point (for example, port 443
) or an explicit port (:443
).
entryPoint.to
Field | Description | Required |
---|---|---|
entryPoint.to | The target element. | Yes |
The target element, it can be:
- An entry point name (ex:
websecure
). - A port (
:443
).
entryPoints:
foo:
# ...
http:
redirections:
entryPoint:
to: websecure
entryPoint.scheme
Field | Description | Default | Required |
---|---|---|---|
entryPoint.scheme | The redirection target scheme. | https | No |
entryPoints:
foo:
# ...
http:
redirections:
entryPoint:
# ...
scheme: https
entryPoint.permanent
Field | Description | Default | Required |
---|---|---|---|
entryPoint.permanent | To apply a permanent redirection. | true | No |
entryPoints:
foo:
# ...
http:
redirections:
entryPoint:
# ...
permanent: true
entryPoint.priority
Field | Description | Default | Required |
---|---|---|---|
entryPoint.priority | Priority of the generated router. | MaxInt32-1 (2147483646) | No |
entryPoints:
foo:
# ...
http:
redirections:
entryPoint:
# ...
priority: 10
EncodeQuerySemicolons
Field | Description | Default | Required |
---|---|---|---|
encodeQuerySemicolons | The encodeQuerySemicolons option allows enabling query semicolons encoding One could use this option to avoid non-encoded semicolons to be interpreted as query parameter separators by Traefik Hub. When using this option, the non-encoded semicolons characters in query will be transmitted encoded to the backend. | false | No |
entryPoints:
websecure:
address: ':443'
http:
encodeQuerySemicolons: true
Examples
EncodeQuerySemicolons | Request Query | Resulting Request Query |
---|---|---|
false | foo=bar;baz=bar | foo=bar&baz=bar |
true | foo=bar;baz=bar | foo=bar%3Bbaz=bar |
false | foo=bar&baz=bar;foo | foo=bar&baz=bar&foo |
true | foo=bar&baz=bar;foo | foo=bar&baz=bar%3Bfoo |
Middlewares
The list of middlewares that are prepended by default to the list of middlewares of each router associated to the named entry point.
entryPoints:
websecure:
address: ':443'
http:
middlewares:
- auth@file
- strip@file
TLS
This section is about the default TLS configuration applied to all routers associated with the named entry point.
If a TLS section (that is any of its fields) is user-defined, then the default configuration does not apply at all.
The TLS section is the same as the TLS section on HTTP routers.
entryPoints:
websecure:
address: ':443'
http:
tls:
options: foobar
certResolver: leresolver
domains:
- main: example.com
sans:
- foo.example.com
- bar.example.com
- main: test.com
sans:
- foo.test.com
- bar.test.com
Example with "Let's Encrypt"
entryPoints:
websecure:
address: ':443'
http:
tls:
certResolver: leresolver
UDP Options
This whole section is dedicated to options, keyed by entry point, that will apply only to UDP routing.
Timeout
Field | Description | Default | Required |
---|---|---|---|
timeout | Timeout defines how long to wait on an idle session before releasing the related resources. The Timeout value must be greater than zero. | 3s (seconds) | No |
entryPoints:
foo:
address: ':8000/udp'
udp:
timeout: 10s