WildFly Full 26.1 Model Reference

  1. home
  2. subsystem=undertow
  3. server
  4. http-listener

http listener

Provided capabilities(2)

Attributes (49)

  • allow-encoded-slash If a request comes in with encoded / characters (i.e. %2F), will these be decoded.
    • Attribute Value
    Default Value false
    Type BOOLEAN
    Nillable true
    Expressions Allowed true
    Storage configuration
    Access Type read-write
    Restart Required no-services
  • allow-equals-in-cookie-value If this is true then Undertow will allow non-escaped equals characters in unquoted cookie values. Unquoted cookie values may not contain equals characters. If present the value ends before the equals sign. The remainder of the cookie value will be dropped.
  • allow-unescaped-characters-in-url If this is true Undertow will accept non-encoded characters that are disallowed by the URI specification. This defaults to false, and in general should not be needed as most clients correctly encode characters. Note that setting this to true can be considered a security risk, as allowing non-standard characters can allow request smuggling attacks in some circumstances.
    • Attribute Value
    Default Value false
    Type BOOLEAN
    Nillable true
    Expressions Allowed true
    Storage configuration
    Access Type read-write
    Restart Required no-services
  • always-set-keep-alive If this is true then a Connection: keep-alive header will be added to responses, even when it is not strictly required by the specification.
    • Attribute Value
    Default Value true
    Type BOOLEAN
    Nillable true
    Expressions Allowed true
    Storage configuration
    Access Type read-write
    Restart Required no-services
  • buffer-pipelined-data If we should buffer pipelined requests.
    • Attribute Value
    Default Value false
    Type BOOLEAN
    Nillable true
    Expressions Allowed true
    Storage configuration
    Access Type read-write
    Restart Required no-services
  • buffer-pool The listeners buffer pool
    • Attribute Value
    Default Value default
    Capability reference
    Type STRING
    Nillable true
    Expressions Allowed false
    Storage configuration
    Access Type read-write
    Restart Required all-services
  • bytes-received The number of bytes that have been received by this listener
    • Attribute Value
    Type LONG
    Nillable false
    Expressions Allowed false
    Unit BYTES
    Storage runtime
    Access Type metric
  • bytes-sent The number of bytes that have been sent out on this listener
    • Attribute Value
    Type LONG
    Nillable false
    Expressions Allowed false
    Unit BYTES
    Storage runtime
    Access Type metric
  • certificate-forwarding If certificate forwarding should be enabled. If this is enabled then the listener will take the certificate from the SSL_CLIENT_CERT attribute. This should only be enabled if behind a proxy, and the proxy is configured to always set these headers.
    • Attribute Value
    Default Value false
    Type BOOLEAN
    Nillable true
    Expressions Allowed true
    Storage configuration
    Access Type read-write
    Restart Required resource-services
  • decode-url If this is true then the parser will decode the URL and query parameters using the selected character encoding (UTF-8 by default). If this is false they will not be decoded. This will allow a later handler to decode them into whatever charset is desired.
    • Attribute Value
    Default Value true
    Type BOOLEAN
    Nillable true
    Expressions Allowed true
    Storage configuration
    Access Type read-write
    Restart Required no-services
  • disallowed-methods A comma separated list of HTTP methods that are not allowed
    • Attribute Value
    Default Value ["TRACE"]
    Type LIST
    Nillable true
    Expressions Allowed true
    Storage configuration
    Access Type read-write
    Restart Required resource-services
  • enable-http2 Enables HTTP2 support for this listener
    • Attribute Value
    Default Value false
    Type BOOLEAN
    Nillable true
    Expressions Allowed true
    Storage configuration
    Access Type read-write
    Restart Required all-services
  • enabled If the listener is enabled
    • Deprecated Since 3.2.0
    Enabled attributes are being deprecated, as they cause problems in enforcement of configuration consistency.
    Attribute Value
    Default Value true
    Type BOOLEAN
    Nillable true
    Expressions Allowed true
    Storage configuration
    Access Type read-write
    Restart Required all-services
  • error-count The number of 500 responses that have been sent by this listener
    • Attribute Value
    Type LONG
    Nillable false
    Expressions Allowed false
    Storage runtime
    Access Type metric
  • http2-enable-push If server push is enabled for this connection
    • Attribute Value
    Default Value true
    Type BOOLEAN
    Nillable true
    Expressions Allowed true
    Storage configuration
    Access Type read-write
    Restart Required all-services
  • http2-header-table-size The size of the header table used for HPACK compression, in bytes. This amount of memory will be allocated per connection for compression. Larger values use more memory but may give better compression.
    • Attribute Value
    Default Value 4096
    Type INT
    Nillable true
    Expressions Allowed true
    Min 1
    Max 2,147,483,647
    Unit BYTES
    Storage configuration
    Access Type read-write
    Restart Required all-services
  • http2-initial-window-size The flow control window size that controls how quickly the client can send data to the server
    • Attribute Value
    Default Value 65535
    Type INT
    Nillable true
    Expressions Allowed true
    Min 1
    Max 2,147,483,647
    Unit BYTES
    Storage configuration
    Access Type read-write
    Restart Required all-services
  • http2-max-concurrent-streams The maximum number of HTTP/2 streams that can be active at any time on a single connection
    • Attribute Value
    Type INT
    Nillable true
    Expressions Allowed true
    Min 1
    Max 2,147,483,647
    Storage configuration
    Access Type read-write
    Restart Required all-services
  • http2-max-frame-size The max HTTP/2 frame size
    • Attribute Value
    Default Value 16384
    Type INT
    Nillable true
    Expressions Allowed true
    Min 1
    Max 2,147,483,647
    Unit BYTES
    Storage configuration
    Access Type read-write
    Restart Required all-services
  • http2-max-header-list-size The maximum size of request headers the server is prepared to accept
    • Attribute Value
    Type INT
    Nillable true
    Expressions Allowed true
    Min 1
    Max 2,147,483,647
    Unit BYTES
    Storage configuration
    Access Type read-write
    Restart Required all-services
  • max-buffered-request-size Maximum size of a buffered request, in bytes. Requests are not usually buffered, the most common case is when performing SSL renegotiation for a POST request, and the post data must be fully buffered in order to perform the renegotiation.
    • Attribute Value
    Default Value 16384
    Type INT
    Nillable true
    Expressions Allowed true
    Min 1
    Max 2,147,483,647
    Unit BYTES
    Storage configuration
    Access Type read-write
    Restart Required no-services
  • max-connections The maximum number of concurrent connections. Only values greater than 0 are allowed. For unlimited connections simply undefine this attribute value.
    • Attribute Value
    Type INT
    Nillable true
    Expressions Allowed true
    Min 1
    Max 2,147,483,647
    Storage configuration
    Access Type read-write
    Restart Required no-services
  • max-cookies The maximum number of cookies that will be parsed. This is used to protect against hash vulnerabilities.
    • Attribute Value
    Default Value 200
    Type INT
    Nillable true
    Expressions Allowed true
    Min 1
    Max 2,147,483,647
    Storage configuration
    Access Type read-write
    Restart Required no-services
  • max-header-size The maximum size of a http request header, in bytes.
    • Attribute Value
    Default Value 1048576
    Type INT
    Nillable true
    Expressions Allowed true
    Min 1
    Max 2,147,483,647
    Unit BYTES
    Storage configuration
    Access Type read-write
    Restart Required no-services
  • max-headers The maximum number of headers that will be parsed. This is used to protect against hash vulnerabilities.
    • Attribute Value
    Default Value 200
    Type INT
    Nillable true
    Expressions Allowed true
    Min 1
    Max 2,147,483,647
    Storage configuration
    Access Type read-write
    Restart Required no-services
  • max-parameters The maximum number of parameters that will be parsed. This is used to protect against hash vulnerabilities. This applies to both query parameters, and to POST data, but is not cumulative (i.e. you can potentially have max parameters * 2 total parameters).
    • Attribute Value
    Default Value 1000
    Type INT
    Nillable true
    Expressions Allowed true
    Min 1
    Max 2,147,483,647
    Storage configuration
    Access Type read-write
    Restart Required no-services
  • max-post-size The maximum size of a post that will be accepted, in bytes.
    • Attribute Value
    Default Value 10485760
    Type LONG
    Nillable true
    Expressions Allowed true
    Min 0
    Max -1
    Unit BYTES
    Storage configuration
    Access Type read-write
    Restart Required no-services
  • max-processing-time The maximum processing time taken by a request on this listener
    • Attribute Value
    Type LONG
    Nillable false
    Expressions Allowed false
    Unit NANOSECONDS
    Storage runtime
    Access Type metric
  • no-request-timeout The length of time in milliseconds that the connection can be idle before it is closed by the container.
    • Attribute Value
    Default Value 60000
    Type INT
    Nillable true
    Expressions Allowed true
    Unit MILLISECONDS
    Storage configuration
    Access Type read-write
    Restart Required no-services
  • processing-time The total processing time of all requests handed by this listener
    • Attribute Value
    Type LONG
    Nillable false
    Expressions Allowed false
    Unit NANOSECONDS
    Storage runtime
    Access Type metric
  • proxy-address-forwarding Enables handling of x-forwarded-host header (and other x-forwarded-* headers) and use this header information to set the remote address. This should only be used behind a trusted proxy that sets these headers otherwise a remote user can spoof their IP address.
    • Attribute Value
    Default Value false
    Type BOOLEAN
    Nillable true
    Expressions Allowed true
    Storage configuration
    Access Type read-write
    Restart Required resource-services
  • proxy-protocol If this is true then the listener will use the proxy protocol v1, as defined by https://www.haproxy.org/download/1.8/doc/proxy-protocol.txt. This option MUST only be enabled for listeners that are behind a load balancer that supports the same protocol.
    • Attribute Value
    Default Value false
    Type BOOLEAN
    Nillable true
    Expressions Allowed true
    Storage configuration
    Access Type read-write
    Restart Required resource-services
  • read-timeout Configure a read timeout for a socket, in milliseconds. If the given amount of time elapses without a successful read taking place, the socket's next read will throw a {@link ReadTimeoutException}.
    • Attribute Value
    Type INT
    Nillable true
    Expressions Allowed true
    Unit MILLISECONDS
    Storage configuration
    Access Type read-write
    Restart Required no-services
  • receive-buffer The receive buffer size, in bytes.
    • Attribute Value
    Type INT
    Nillable true
    Expressions Allowed true
    Min 1
    Max 2,147,483,647
    Storage configuration
    Access Type read-write
    Restart Required no-services
  • record-request-start-time If this is true then Undertow will record the request start time, to allow for request time to be logged. This has a small but measurable performance impact
    • Attribute Value
    Default Value false
    Type BOOLEAN
    Nillable true
    Expressions Allowed true
    Storage configuration
    Access Type read-write
    Restart Required no-services
  • redirect-socket If this listener is supporting non-SSL requests, and a request is received for which a matching requires SSL transport, undertow will automatically redirect the request to the socket binding port specified here.
    • Attribute Value
    Capability reference
    Type STRING
    Nillable true
    Expressions Allowed false
    Storage configuration
    Access Type read-write
    Restart Required resource-services
  • request-count The number of requests this listener has served
    • Attribute Value
    Type LONG
    Nillable false
    Expressions Allowed false
    Storage runtime
    Access Type metric
  • request-parse-timeout The maximum amount of time (in milliseconds) that can be spent parsing the request
    • Attribute Value
    Type INT
    Nillable true
    Expressions Allowed true
    Unit MILLISECONDS
    Storage configuration
    Access Type read-write
    Restart Required no-services
  • require-host-http11 Require that all HTTP/1.1 requests have a 'Host' header, as per the RFC. IF the request does not include this header it will be rejected with a 403.
    • Attribute Value
    Default Value false
    Type BOOLEAN
    Nillable true
    Expressions Allowed true
    Storage configuration
    Access Type read-write
    Restart Required all-services
  • resolve-peer-address Enables host dns lookup
    • Attribute Value
    Default Value false
    Type BOOLEAN
    Nillable true
    Expressions Allowed true
    Storage configuration
    Access Type read-write
    Restart Required resource-services
  • rfc6265-cookie-validation If cookies should be validated to ensure they comply with RFC6265.
  • secure If this is true then requests that originate from this listener are marked as secure, even if the request is not using HTTPS.
    • Attribute Value
    Default Value false
    Type BOOLEAN
    Nillable true
    Expressions Allowed true
    Storage configuration
    Access Type read-write
    Restart Required resource-services
  • send-buffer The send buffer size, in bytes.
    • Attribute Value
    Type INT
    Nillable true
    Expressions Allowed true
    Min 1
    Max 2,147,483,647
    Storage configuration
    Access Type read-write
    Restart Required no-services
  • socket-binding The listener socket binding
    • Attribute Value
    Capability reference
    Type STRING
    Nillable false
    Expressions Allowed false
    Storage configuration
    Access Type read-write
    Restart Required all-services
  • tcp-backlog Configure a server with the specified backlog.
    • Attribute Value
    Default Value 10000
    Type INT
    Nillable true
    Expressions Allowed true
    Min 1
    Max 2,147,483,647
    Storage configuration
    Access Type read-write
    Restart Required no-services
  • tcp-keep-alive Configure a channel to send TCP keep-alive messages in an implementation-dependent manner.
    • Attribute Value
    Type BOOLEAN
    Nillable true
    Expressions Allowed true
    Storage configuration
    Access Type read-write
    Restart Required no-services
  • url-charset URL charset
    • Attribute Value
    Default Value UTF-8
    Type STRING
    Nillable true
    Expressions Allowed true
    Storage configuration
    Access Type read-write
    Restart Required no-services
  • worker The listeners XNIO worker
    • Attribute Value
    Default Value default
    Capability reference
    Type STRING
    Nillable true
    Expressions Allowed false
    Storage configuration
    Access Type read-write
    Restart Required all-services
  • write-timeout Configure a write timeout for a socket, in milliseconds. If the given amount of time elapses without a successful write taking place, the socket's next write will throw a {@link WriteTimeoutException}.
    • Attribute Value
    Type INT
    Nillable true
    Expressions Allowed true
    Unit MILLISECONDS
    Storage configuration
    Access Type read-write
    Restart Required no-services

Operations (3)

  • add Add listener
    Request Parameter Type Required Expressions Allowed Default value Description
    allow-encoded-slash BOOLEAN false true false If a request comes in with encoded / characters (i.e. %2F), will these be decoded.
    allow-equals-in-cookie-value BOOLEAN false true false If this is true then Undertow will allow non-escaped equals characters in unquoted cookie values. Unquoted cookie values may not contain equals characters. If present the value ends before the equals sign. The remainder of the cookie value will be dropped.
    allow-unescaped-characters-in-url BOOLEAN false true false If this is true Undertow will accept non-encoded characters that are disallowed by the URI specification. This defaults to false, and in general should not be needed as most clients correctly encode characters. Note that setting this to true can be considered a security risk, as allowing non-standard characters can allow request smuggling attacks in some circumstances.
    always-set-keep-alive BOOLEAN false true true If this is true then a Connection: keep-alive header will be added to responses, even when it is not strictly required by the specification.
    buffer-pipelined-data BOOLEAN false true false If we should buffer pipelined requests.
    buffer-pool STRING false false default The listeners buffer pool
    certificate-forwarding BOOLEAN false true false If certificate forwarding should be enabled. If this is enabled then the listener will take the certificate from the SSL_CLIENT_CERT attribute. This should only be enabled if behind a proxy, and the proxy is configured to always set these headers.
    decode-url BOOLEAN false true true If this is true then the parser will decode the URL and query parameters using the selected character encoding (UTF-8 by default). If this is false they will not be decoded. This will allow a later handler to decode them into whatever charset is desired.
    disallowed-methods LIST false true ["TRACE"] A comma separated list of HTTP methods that are not allowed
    enable-http2 BOOLEAN false true false Enables HTTP2 support for this listener
    enabled BOOLEAN false true true If the listener is enabled
    http2-enable-push BOOLEAN false true true If server push is enabled for this connection
    http2-header-table-size INT false true 4096 The size of the header table used for HPACK compression, in bytes. This amount of memory will be allocated per connection for compression. Larger values use more memory but may give better compression.
    http2-initial-window-size INT false true 65535 The flow control window size that controls how quickly the client can send data to the server
    http2-max-concurrent-streams INT false true The maximum number of HTTP/2 streams that can be active at any time on a single connection
    http2-max-frame-size INT false true 16384 The max HTTP/2 frame size
    http2-max-header-list-size INT false true The maximum size of request headers the server is prepared to accept
    max-buffered-request-size INT false true 16384 Maximum size of a buffered request, in bytes. Requests are not usually buffered, the most common case is when performing SSL renegotiation for a POST request, and the post data must be fully buffered in order to perform the renegotiation.
    max-connections INT false true The maximum number of concurrent connections. Only values greater than 0 are allowed. For unlimited connections simply undefine this attribute value.
    max-cookies INT false true 200 The maximum number of cookies that will be parsed. This is used to protect against hash vulnerabilities.
    max-header-size INT false true 1048576 The maximum size of a http request header, in bytes.
    max-headers INT false true 200 The maximum number of headers that will be parsed. This is used to protect against hash vulnerabilities.
    max-parameters INT false true 1000 The maximum number of parameters that will be parsed. This is used to protect against hash vulnerabilities. This applies to both query parameters, and to POST data, but is not cumulative (i.e. you can potentially have max parameters * 2 total parameters).
    max-post-size LONG false true 10485760 The maximum size of a post that will be accepted, in bytes.
    no-request-timeout INT false true 60000 The length of time in milliseconds that the connection can be idle before it is closed by the container.
    proxy-address-forwarding BOOLEAN false true false Enables handling of x-forwarded-host header (and other x-forwarded-* headers) and use this header information to set the remote address. This should only be used behind a trusted proxy that sets these headers otherwise a remote user can spoof their IP address.
    proxy-protocol BOOLEAN false true false If this is true then the listener will use the proxy protocol v1, as defined by https://www.haproxy.org/download/1.8/doc/proxy-protocol.txt. This option MUST only be enabled for listeners that are behind a load balancer that supports the same protocol.
    read-timeout INT false true Configure a read timeout for a socket, in milliseconds. If the given amount of time elapses without a successful read taking place, the socket's next read will throw a {@link ReadTimeoutException}.
    receive-buffer INT false true The receive buffer size, in bytes.
    record-request-start-time BOOLEAN false true false If this is true then Undertow will record the request start time, to allow for request time to be logged. This has a small but measurable performance impact
    redirect-socket STRING false false If this listener is supporting non-SSL requests, and a request is received for which a matching requires SSL transport, undertow will automatically redirect the request to the socket binding port specified here.
    request-parse-timeout INT false true The maximum amount of time (in milliseconds) that can be spent parsing the request
    require-host-http11 BOOLEAN false true false Require that all HTTP/1.1 requests have a 'Host' header, as per the RFC. IF the request does not include this header it will be rejected with a 403.
    resolve-peer-address BOOLEAN false true false Enables host dns lookup
    rfc6265-cookie-validation BOOLEAN false true false If cookies should be validated to ensure they comply with RFC6265.
    secure BOOLEAN false true false If this is true then requests that originate from this listener are marked as secure, even if the request is not using HTTPS.
    send-buffer INT false true The send buffer size, in bytes.
    socket-binding STRING true false The listener socket binding
    tcp-backlog INT false true 10000 Configure a server with the specified backlog.
    tcp-keep-alive BOOLEAN false true Configure a channel to send TCP keep-alive messages in an implementation-dependent manner.
    url-charset STRING false true UTF-8 URL charset
    worker STRING false false default The listeners XNIO worker
    write-timeout INT false true Configure a write timeout for a socket, in milliseconds. If the given amount of time elapses without a successful write taking place, the socket's next write will throw a {@link WriteTimeoutException}.
  • remove Listener name
  • reset-statistics Resets all the connector statistics to zero