The English version of quarkus.io is the official project site. Translated sites are community supported on a best-effort basis.

HTTP Reference

This document clarifies different HTTP functionalities available in Quarkus.

Eclipse Vert.x supplies the fundamental HTTP layer. For Servlet support, Quarkus employs a customized Undertow version that operates on top of Vert.x, while Jakarta REST support is delivered through RESTEasy.

When Undertow is present, RESTEasy functions as a Servlet filter. In its absence, RESTEasy operates directly on Vert.x without involving Servlets.

1. Serving static resources

If you are looking to use Quarkus for a web application, look at the Quarkus for the Web guide.

1.1. From the application jar

To serve static resources from the application jar, you must place them in the META-INF/resources directory of your application. This location was chosen as it is the standard location for resources in jar files as defined by the Servlet spec. Even though Quarkus can be used without Servlet, following this convention allows existing code that places its resources in this location to function correctly.

1.2. From mvnpm

If you are using mvnpm, as for the following JQuery dependency:

pom.xml
<dependency>
    <groupId>org.mvnpm</groupId>
    <artifactId>bootstrap</artifactId>
    <version>5.3.3</version>
    <scope>runtime</scope>
</dependency>
build.gradle
runtimeOnly("org.mvnpm:bootstrap:5.3.3")

You can import it in your HTML like this:

<script src="_static/bootstrap/5.3.3/dist/css/bootstrap.min.css"></script>

1.3. From WebJars

If you are using webjars, like the following JQuery one:

pom.xml
<dependency>
    <groupId>org.webjars</groupId>
    <artifactId>jquery</artifactId>
    <version>3.1.1</version>
</dependency>
build.gradle
implementation("org.webjars:jquery:3.1.1")

and rather write /webjars/jquery/jquery.min.js instead of /webjars/jquery/3.1.1/jquery.min.js in your HTML files, you can add the quarkus-webjars-locator extension to your project. To use it, add the following to your project’s dependencies:

pom.xml
<dependency>
    <groupId>io.quarkus</groupId>
    <artifactId>quarkus-webjars-locator</artifactId>
</dependency>
build.gradle
implementation("io.quarkus:quarkus-webjars-locator")

1.4. From a local directory

Static resources can be served from a local directory by installing an additional route in the Vert.x router.

For instance, to serve resources from the static/ directory relative to the current path at http://localhost:8080/static/, you can install the following route:

package org.acme;

import io.quarkus.runtime.StartupEvent;
import io.vertx.ext.web.Router;
import io.vertx.ext.web.handler.StaticHandler;
import jakarta.enterprise.event.Observes;


public class StaticResources {

    void installRoute(@Observes StartupEvent startupEvent, Router router) {
        router.route()
                .path("/static/*")
                .handler(StaticHandler.create("static/"));
    }
}

1.5. HTTP Compression

The response body of a static resource is not compressed by default. You can enable the HTTP compression support by means of quarkus.http.enable-compression=true. If compression support is enabled then the response body is compressed if the Content-Type header derived from the file name of a resource is a compressed media type as configured via quarkus.http.compress-media-types.

By default, the following list of media types is compressed: text/html, text/plain, text/xml, text/css, text/javascript and application/javascript.
If the client does not support HTTP compression then the response body is not compressed.

1.6. Other Configurations

Additionally, the index page for static resources can be changed from default index.html, the hidden files (e.g. dot files) can be indicated as not served, the range requests can be disabled, and the caching support (e.g. caching headers and file properties cache) can be configured.

Configuration property fixed at build time - All other configuration properties are overridable at runtime

Configuration property

Tipo

Por defecto

Set the index page when serving static resources.

Environment variable: QUARKUS_HTTP_STATIC_RESOURCES_INDEX_PAGE

Show more

string

index.html

Set whether hidden files should be served.

Environment variable: QUARKUS_HTTP_STATIC_RESOURCES_INCLUDE_HIDDEN

Show more

boolean

true

Set whether range requests (resumable downloads; media streaming) should be enabled.

Environment variable: QUARKUS_HTTP_STATIC_RESOURCES_ENABLE_RANGE_SUPPORT

Show more

boolean

true

Set whether cache handling is enabled.

Environment variable: QUARKUS_HTTP_STATIC_RESOURCES_CACHING_ENABLED

Show more

boolean

true

Set the cache entry timeout. The default is 30 seconds.

Environment variable: QUARKUS_HTTP_STATIC_RESOURCES_CACHE_ENTRY_TIMEOUT

Show more

Duration

30S

Set value for max age in caching headers. The default is 24 hours.

Environment variable: QUARKUS_HTTP_STATIC_RESOURCES_MAX_AGE

Show more

Duration

24H

Set the max cache size.

Environment variable: QUARKUS_HTTP_STATIC_RESOURCES_MAX_CACHE_SIZE

Show more

int

10000

Content encoding for text related files

Environment variable: QUARKUS_HTTP_STATIC_RESOURCES_CONTENT_ENCODING

Show more

Charset

UTF-8

About the Duration format

To write duration values, use the standard java.time.Duration format. See the Duration#parse() Java API documentation for more information.

You can also use a simplified format, starting with a number:

  • If the value is only a number, it represents time in seconds.

  • If the value is a number followed by ms, it represents time in milliseconds.

In other cases, the simplified format is translated to the java.time.Duration format for parsing:

  • If the value is a number followed by h, m, or s, it is prefixed with PT.

  • If the value is a number followed by d, it is prefixed with P.

2. Configuring the Context path

By default, Quarkus will serve content from under the root context. If you want to change this you can use the quarkus.http.root-path config key to set the context path.

If you are using Servlet you can control the Servlet context path via quarkus.servlet.context-path. This item is relative to the http root above, and will only affect Servlet and things that run on top of Servlet. Most applications will want to use the HTTP root as this affects everything that Quarkus serves.

If both are specified then all non-Servlet web endpoints will be relative to quarkus.http.root-path, while Servlet’s will be served relative to {quarkus.http.root-path}/{quarkus.servlet.context-path}.

If REST Assured is used for testing and quarkus.http.root-path is set then Quarkus will automatically configure the base URL for use in Quarkus tests, so test URL’s should not include the root path.

In general, path configurations for web content are interpreted relative to quarkus.http.root-path (which is / by default).

  • To specify paths within this context root, use a relative path that does not begin with a forward slash.

  • If you want to specify the URI explicitly, so it is always the same regardless of the value of quarkus.http.root-path, use an absolute path that begins with a forward slash.

As an example, if an extension configures a service path, that endpoint will be served from ${quarkus.http.root-path}/service. If you change the configuration of that path to /service, that endpoint will be served from /service.

The Path Resolution in Quarkus blog post further explains how path resolution works for both user and extension defined paths.

Management Interface

quarkus.http.root-path is only used for the main HTTP server. If you enabled the management interface (using the quarkus.management.enabled=true property), you can configure the root path of the management interface using: quarkus.management.root-path.

Refer to the management interface reference for more information.

3. Supporting secure connections with TLS/SSL

To have Quarkus support secure connections, you must either provide a certificate and associated key file, or supply a keystore.

In both cases, a password must be provided. See the designated paragraph for a detailed description of how to provide it.

To enable TLS/SSL support with native executables, please refer to our Using SSL With Native Executables guide.

3.1. Providing a certificate and key file

If the certificate has not been loaded into a keystore, it can be provided directly using the properties listed below. Quarkus will first try to load the given files as resources, and uses the filesystem as a fallback. The certificate / key pair will be loaded into a newly created keystore on startup.

Your application.properties would then look like this:

quarkus.http.ssl.certificate.files=/path/to/certificate
quarkus.http.ssl.certificate.key-files=/path/to/key

3.2. Providing a keystore

An alternate solution is to directly provide a keystore which already contains a default entry with a certificate. You will need to at least provide the file and a password.

As with the certificate/key file combination, Quarkus will first try to resolve the given path as a resource, before attempting to read it from the filesystem.

Add the following property to your application.properties:

quarkus.http.ssl.certificate.key-store-file=/path/to/keystore

As an optional hint, the type of keystore can be provided as one of the options listed. If the type is not provided, Quarkus will try to deduce it from the file extensions.

quarkus.http.ssl.certificate.key-store-file-type=[one of JKS, JCEKS, P12, PKCS12, PFX]

3.3. Setting the password

In both aforementioned scenarios, a password needs to be provided to create/load the keystore with. The password can be set in your application.properties (in plain-text) using the following property:

quarkus.http.ssl.certificate.key-store-password=your-password

However, instead of providing the password as plain-text in the configuration file (which is considered bad practice), it can instead be supplied (using MicroProfile Config) as the environment variable QUARKUS_HTTP_SSL_CERTIFICATE_KEY_STORE_PASSWORD. This will also work in tandem with Kubernetes secrets.

Note: To remain compatible with earlier versions of Quarkus (before 0.16) the default password is set to "password". It is therefore not a mandatory parameter!

3.4. Configure the HTTPS port

By default, Quarkus listens to port 8443 for SSL secured connections and 8444 when running tests.

These ports can be configured in your application.properties with the properties quarkus.http.ssl-port and quarkus.http.test-ssl-port.

3.5. Disable the HTTP port

It is possible to disable the HTTP port and only support secure requests. This is done via the quarkus.http.insecure-requests property in application.properties. There are three possible values:

enabled

The default, HTTP works as normal

redirect

HTTP requests will be redirected to the HTTPS port

disabled

The HTTP port will not be opened.

if you use redirect or disabled and have not added an SSL certificate or keystore, your server will not start!

3.6. Reloading the certificates

Key store, trust store and certificate files can be reloaded periodically. Configure the quarkus.http.ssl.certificate.reload-period property to specify the interval at which the certificates should be reloaded:

quarkus.http.ssl.certificate.files=/mount/certs/tls.crt
quarkus.http.ssl.certificate.key-files=/mount/certs/tls.key
quarkus.http.ssl.certificate.reload-period=1h

The files are reloaded from the same location as they were initially loaded from. If there is no content change, the reloading is a no-op. It the reloading fails, the server will continue to use the previous certificates.

4. Additional HTTP Headers

To enable HTTP headers to be sent on every response, add the following properties:

quarkus.http.header."X-Content-Type-Options".value=nosniff

This will include the X-Content-Type-Options: nosniff HTTP Header on responses for requests performed on any resource in the application.

You can also specify a path pattern and the HTTP methods the header needs to be applied:

quarkus.http.header.Pragma.value=no-cache
quarkus.http.header.Pragma.path=/headers/pragma
quarkus.http.header.Pragma.methods=GET,HEAD

This will apply the Pragma header only when the /headers/pragma resource is called with a GET or a HEAD method

Configuration property fixed at build time - All other configuration properties are overridable at runtime

Configuration property

Tipo

Por defecto

The path this header should be applied

Environment variable: QUARKUS_HTTP_HEADER__HEADER__PATH

Show more

string

/*

The value for this header configuration

Environment variable: QUARKUS_HTTP_HEADER__HEADER__VALUE

Show more

string

required

The HTTP methods for this header configuration

Environment variable: QUARKUS_HTTP_HEADER__HEADER__METHODS

Show more

list of string

The path this header should be applied

Environment variable: QUARKUS_MANAGEMENT_HEADER__HEADER__PATH

Show more

string

/*

The value for this header configuration

Environment variable: QUARKUS_MANAGEMENT_HEADER__HEADER__VALUE

Show more

string

required

The HTTP methods for this header configuration

Environment variable: QUARKUS_MANAGEMENT_HEADER__HEADER__METHODS

Show more

list of string

4.1. Additional HTTP Headers per path

If you need different header values depending on the path, you can use the following configuration:

quarkus.http.filter.index.header."Cache-Control"=none
quarkus.http.filter.index.matches=/index.html

This will set the Cache-Control header to none when /index.html is called.

The index after quarkus.http.filter in the key is used for grouping and (as an example) can be named as you like.

You can use a regular expression in the path and also specify the HTTP methods where the HTTP header will be set:

quarkus.http.filter.static.header."Cache-Control"=max-age=31536000
quarkus.http.filter.static.methods=GET,HEAD
quarkus.http.filter.static.matches=/static/.*

In case of overlapping paths in the configuration, you can specify an order (higher values take precedence). For example, having the following configuration:

quarkus.http.filter.just-order.order=10
quarkus.http.filter.just-order.header."Cache-Control"=max-age=5000
quarkus.http.filter.just-order.matches=/paths/order

quarkus.http.filter.any-order.order=11
quarkus.http.filter.any-order.header."Cache-Control"=max-age=1
quarkus.http.filter.any-order.matches=/paths/order.*

Will include the Cache-Control: max-age=1 header when /paths/order is requested.

Configuration property fixed at build time - All other configuration properties are overridable at runtime

Configuration property

Tipo

Por defecto

A regular expression for the paths matching this configuration

Environment variable: QUARKUS_HTTP_FILTER__FILTER__MATCHES

Show more

string

required

Additional HTTP Headers always sent in the response

Environment variable: QUARKUS_HTTP_FILTER__FILTER__HEADER

Show more

Map<String,String>

The HTTP methods for this path configuration

Environment variable: QUARKUS_HTTP_FILTER__FILTER__METHODS

Show more

list of string

Environment variable: QUARKUS_HTTP_FILTER__FILTER__ORDER

int

A regular expression for the paths matching this configuration

Environment variable: QUARKUS_MANAGEMENT_FILTER__FILTER__MATCHES

Show more

string

required

Additional HTTP Headers always sent in the response

Environment variable: QUARKUS_MANAGEMENT_FILTER__FILTER__HEADER

Show more

Map<String,String>

The HTTP methods for this path configuration

Environment variable: QUARKUS_MANAGEMENT_FILTER__FILTER__METHODS

Show more

list of string

Environment variable: QUARKUS_MANAGEMENT_FILTER__FILTER__ORDER

int

5. Support 100-Continue in vert.x

To support 100-continue, the quarkus.http.handle-100-continue-automatically option needs to be enabled explicitly For additional information check 100-continue and the related Vert.x documentation.

quarkus.http.handle-100-continue-automatically=true

6. HTTP/2 Support

HTTP/2 is enabled by default, and will be used by browsers if SSL is in use. Even if SSL is not in use HTTP/2 via cleartext upgrade is supported, and may be used by non-browser clients.

If you want to disable HTTP/2 you can set:

quarkus.http.http2=false

Note that some configuration attributes are specific to HTTP/2. For example, to configure the max header list size (~ header), you need to configure the quarkus.http.limits.max-header-list-size attribute. You can also enable or disable HTTP/2 push using quarkus.http.http2-push-enabled.

7. Listening on a Random Port

If you don’t want to specify a port you can set quarkus.http.port=0 or quarkus.http.test-port=0. A random open port will be picked by the OS, and a log message printed in the console. When the port is bound the quarkus.http.port system property will be set to the actual port that was selected, so you can use this to get the actual port number from inside the application. If you are in a test you can inject the URL normally and this will be configured with the actual port, and REST Assured will also be configured appropriately.

As this sets a system property you can access quarkus.http.port via MicroProfile Config, however if you use injection the injected value may not always be correct. This port allocation is one of the last things to happen in Quarkus startup, so if your object that is being injected is created eagerly before the port has opened the injected value will not be correct.

8. CORS filter

To make your Quarkus application accessible to another application running on a different domain, you need to configure cross-origin resource sharing (CORS). For more information about the CORS filter that Quarkus provides, see the Quarkus CORS filter section of the "Cross-origin resource sharing" guide.

9. HTTP Limits Configuration

Configuration property fixed at build time - All other configuration properties are overridable at runtime

Configuration property

Tipo

Por defecto

The maximum length of all headers.

Environment variable: QUARKUS_HTTP_LIMITS_MAX_HEADER_SIZE

Show more

MemorySize

20K

The maximum size of a request body.

Environment variable: QUARKUS_HTTP_LIMITS_MAX_BODY_SIZE

Show more

MemorySize

10240K

The max HTTP chunk size

Environment variable: QUARKUS_HTTP_LIMITS_MAX_CHUNK_SIZE

Show more

MemorySize

8192

The maximum length of the initial line (e.g. "GET / HTTP/1.0").

Environment variable: QUARKUS_HTTP_LIMITS_MAX_INITIAL_LINE_LENGTH

Show more

int

4096

The maximum length of a form attribute.

Environment variable: QUARKUS_HTTP_LIMITS_MAX_FORM_ATTRIBUTE_SIZE

Show more

MemorySize

2048

Set the maximum number of fields of a form. Set to -1 to allow unlimited number of attributes.

Environment variable: QUARKUS_HTTP_LIMITS_MAX_FORM_FIELDS

Show more

int

256

Set the maximum number of bytes a server can buffer when decoding a form. Set to -1 to allow unlimited length

Environment variable: QUARKUS_HTTP_LIMITS_MAX_FORM_BUFFERED_BYTES

Show more

MemorySize

1K

The maximum number of HTTP request parameters permitted for incoming requests.

If a client sends more than this number of parameters in a request, the connection is closed.

Environment variable: QUARKUS_HTTP_LIMITS_MAX_PARAMETERS

Show more

int

1000

The maximum number of connections that are allowed at any one time. If this is set it is recommended to set a short idle timeout.

Environment variable: QUARKUS_HTTP_LIMITS_MAX_CONNECTIONS

Show more

int

Set the SETTINGS_HEADER_TABLE_SIZE HTTP/2 setting.

Allows the sender to inform the remote endpoint of the maximum size of the header compression table used to decode header blocks, in octets. The encoder can select any size equal to or less than this value by using signaling specific to the header compression format inside a header block. The initial value is 4,096 octets.

Environment variable: QUARKUS_HTTP_LIMITS_HEADER_TABLE_SIZE

Show more

long

Set SETTINGS_MAX_CONCURRENT_STREAMS HTTP/2 setting.

Indicates the maximum number of concurrent streams that the sender will allow. This limit is directional: it applies to the number of streams that the sender permits the receiver to create. Initially, there is no limit to this value. It is recommended that this value be no smaller than 100, to not unnecessarily limit parallelism.

Environment variable: QUARKUS_HTTP_LIMITS_MAX_CONCURRENT_STREAMS

Show more

long

Set the SETTINGS_MAX_FRAME_SIZE HTTP/2 setting. Indicates the size of the largest frame payload that the sender is willing to receive, in octets. The initial value is 2^14 (16,384) octets.

Environment variable: QUARKUS_HTTP_LIMITS_MAX_FRAME_SIZE

Show more

int

Set the SETTINGS_MAX_HEADER_LIST_SIZE HTTP/2 setting. This advisory setting informs a peer of the maximum size of header list that the sender is prepared to accept, in octets. The value is based on the uncompressed size of header fields, including the length of the name and value in octets plus an overhead of 32 octets for each header field. The default value is 8192

Environment variable: QUARKUS_HTTP_LIMITS_MAX_HEADER_LIST_SIZE

Show more

long

Set the max number of RST frame allowed per time window, this is used to prevent HTTP/2 RST frame flood DDOS attacks. The default value is 200, setting zero or a negative value, disables flood protection.

Environment variable: QUARKUS_HTTP_LIMITS_RST_FLOOD_MAX_RST_FRAME_PER_WINDOW

Show more

int

Set the duration of the time window when checking the max number of RST frames, this is used to prevent HTTP/2 RST frame flood DDOS attacks.. The default value is 30 s, setting zero or a negative value, disables flood protection.

Environment variable: QUARKUS_HTTP_LIMITS_RST_FLOOD_WINDOW_DURATION

Show more

Duration

The maximum length of all headers.

Environment variable: QUARKUS_MANAGEMENT_LIMITS_MAX_HEADER_SIZE

Show more

MemorySize

20K

The maximum size of a request body.

Environment variable: QUARKUS_MANAGEMENT_LIMITS_MAX_BODY_SIZE

Show more

MemorySize

10240K

The max HTTP chunk size

Environment variable: QUARKUS_MANAGEMENT_LIMITS_MAX_CHUNK_SIZE

Show more

MemorySize

8192

The maximum length of the initial line (e.g. "GET / HTTP/1.0").

Environment variable: QUARKUS_MANAGEMENT_LIMITS_MAX_INITIAL_LINE_LENGTH

Show more

int

4096

The maximum length of a form attribute.

Environment variable: QUARKUS_MANAGEMENT_LIMITS_MAX_FORM_ATTRIBUTE_SIZE

Show more

MemorySize

2048

Set the maximum number of fields of a form. Set to -1 to allow unlimited number of attributes.

Environment variable: QUARKUS_MANAGEMENT_LIMITS_MAX_FORM_FIELDS

Show more

int

256

Set the maximum number of bytes a server can buffer when decoding a form. Set to -1 to allow unlimited length

Environment variable: QUARKUS_MANAGEMENT_LIMITS_MAX_FORM_BUFFERED_BYTES

Show more

MemorySize

1K

The maximum number of HTTP request parameters permitted for incoming requests.

If a client sends more than this number of parameters in a request, the connection is closed.

Environment variable: QUARKUS_MANAGEMENT_LIMITS_MAX_PARAMETERS

Show more

int

1000

The maximum number of connections that are allowed at any one time. If this is set it is recommended to set a short idle timeout.

Environment variable: QUARKUS_MANAGEMENT_LIMITS_MAX_CONNECTIONS

Show more

int

Set the SETTINGS_HEADER_TABLE_SIZE HTTP/2 setting.

Allows the sender to inform the remote endpoint of the maximum size of the header compression table used to decode header blocks, in octets. The encoder can select any size equal to or less than this value by using signaling specific to the header compression format inside a header block. The initial value is 4,096 octets.

Environment variable: QUARKUS_MANAGEMENT_LIMITS_HEADER_TABLE_SIZE

Show more

long

Set SETTINGS_MAX_CONCURRENT_STREAMS HTTP/2 setting.

Indicates the maximum number of concurrent streams that the sender will allow. This limit is directional: it applies to the number of streams that the sender permits the receiver to create. Initially, there is no limit to this value. It is recommended that this value be no smaller than 100, to not unnecessarily limit parallelism.

Environment variable: QUARKUS_MANAGEMENT_LIMITS_MAX_CONCURRENT_STREAMS

Show more

long

Set the SETTINGS_MAX_FRAME_SIZE HTTP/2 setting. Indicates the size of the largest frame payload that the sender is willing to receive, in octets. The initial value is 2^14 (16,384) octets.

Environment variable: QUARKUS_MANAGEMENT_LIMITS_MAX_FRAME_SIZE

Show more

int

Set the SETTINGS_MAX_HEADER_LIST_SIZE HTTP/2 setting. This advisory setting informs a peer of the maximum size of header list that the sender is prepared to accept, in octets. The value is based on the uncompressed size of header fields, including the length of the name and value in octets plus an overhead of 32 octets for each header field. The default value is 8192

Environment variable: QUARKUS_MANAGEMENT_LIMITS_MAX_HEADER_LIST_SIZE

Show more

long

Set the max number of RST frame allowed per time window, this is used to prevent HTTP/2 RST frame flood DDOS attacks. The default value is 200, setting zero or a negative value, disables flood protection.

Environment variable: QUARKUS_MANAGEMENT_LIMITS_RST_FLOOD_MAX_RST_FRAME_PER_WINDOW

Show more

int

Set the duration of the time window when checking the max number of RST frames, this is used to prevent HTTP/2 RST frame flood DDOS attacks.. The default value is 30 s, setting zero or a negative value, disables flood protection.

Environment variable: QUARKUS_MANAGEMENT_LIMITS_RST_FLOOD_WINDOW_DURATION

Show more

Duration

About the Duration format

To write duration values, use the standard java.time.Duration format. See the Duration#parse() Java API documentation for more information.

You can also use a simplified format, starting with a number:

  • If the value is only a number, it represents time in seconds.

  • If the value is a number followed by ms, it represents time in milliseconds.

In other cases, the simplified format is translated to the java.time.Duration format for parsing:

  • If the value is a number followed by h, m, or s, it is prefixed with PT.

  • If the value is a number followed by d, it is prefixed with P.

About the MemorySize format

A size configuration option recognises string in this format (shown as a regular expression): [0-9]+[KkMmGgTtPpEeZzYy]?. If no suffix is given, assume bytes.

10. Configure traffic shaping

Traffic shaping allows you to limit the bandwidth across all channels (i.e. connections), regardless of the number of open channels. This can be useful when you want to control the overall network traffic to prevent congestion or prioritize certain types of traffic.

To enable traffic shaping, add the following property in your application configuration:

quarkus.http.traffic-shaping.enabled=true # Required to enable traffic shaping

The traffic shaping allows you to configure various parameters, such as write and read limitations (in bytes per second), check interval (the delay between two computations of the bandwidth), and maximum time to wait:

quarkus.http.traffic-shaping.enabled=true # Required to enable traffic shaping
quarkus.http.traffic-shaping.check-interval=30s
quarkus.http.traffic-shaping.outbound-global-bandwidth=1M
quarkus.http.traffic-shaping.inbound-global-bandwidth=1M
quarkus.http.traffic-shaping.max-delay=10s

The check interval represents the period at which the traffic is computed, and a higher interval may result in less precise traffic shaping. Despite 0 being accepted (no accounting), it is recommended to set a positive value for the check interval, even if it is high since the precision of the traffic shaping depends on the period where the traffic is computed. In this case, a suggested value is something close to 5 or 10 minutes.

The outbound-global-bandwidth and inbound-global-bandwidth parameters represent the maximum number of bytes per second for write and read operations, respectively. You shall also consider to have object size in read or write operations relatively adapted to the bandwidth you required. For instance having 10 MB objects for 10KB/s will lead to burst effect, while having 100 KB objects for 1 MB/s should be smoothly handle by the traffic shaping.

Additionally, you can set the maximum time to wait (max-delay), which specifies an upper bound for time shaping. By default, it is set to 15 seconds. It must be less than the HTTP timeout. When one of the threshold is reached, no write happens for that period of time.

11. Configuring HTTP Access Logs

You can add HTTP request logging by configuring it in application.properties. There are two options for logging, either logging to the standard JBoss logging output, or logging to a dedicated file.

Configuration property fixed at build time - All other configuration properties are overridable at runtime

Configuration property

Tipo

Por defecto

If access logging is enabled. By default this will log via the standard logging facility

Environment variable: QUARKUS_HTTP_ACCESS_LOG_ENABLED

Show more

boolean

false

A regular expression that can be used to exclude some paths from logging.

Environment variable: QUARKUS_HTTP_ACCESS_LOG_EXCLUDE_PATTERN

Show more

string

The access log pattern.

If this is the string common, combined or long then this will use one of the specified named formats:

  • common: %h %l %u %t "%r" %s %b

  • combined: %h %l %u %t "%r" %s %b "%{i,Referer}" "%{i,User-Agent}"

  • long: %r\n%{ALL_REQUEST_HEADERS}

Otherwise, consult the Quarkus documentation for the full list of variables that can be used.

Environment variable: QUARKUS_HTTP_ACCESS_LOG_PATTERN

Show more

string

common

If logging should be done to a separate file.

Environment variable: QUARKUS_HTTP_ACCESS_LOG_LOG_TO_FILE

Show more

boolean

false

The access log file base name, defaults to 'quarkus' which will give a log file name of 'quarkus.log'.

Environment variable: QUARKUS_HTTP_ACCESS_LOG_BASE_FILE_NAME

Show more

string

quarkus

The log directory to use when logging access to a file If this is not set then the current working directory is used.

Environment variable: QUARKUS_HTTP_ACCESS_LOG_LOG_DIRECTORY

Show more

string

The log file suffix

Environment variable: QUARKUS_HTTP_ACCESS_LOG_LOG_SUFFIX

Show more

string

.log

The log category to use if logging is being done via the standard log mechanism (i.e. if base-file-name is empty).

Environment variable: QUARKUS_HTTP_ACCESS_LOG_CATEGORY

Show more

string

io.quarkus.http.access-log

If the log should be rotated daily

Environment variable: QUARKUS_HTTP_ACCESS_LOG_ROTATE

Show more

boolean

true

If rerouted requests should be consolidated into one log entry

Environment variable: QUARKUS_HTTP_ACCESS_LOG_CONSOLIDATE_REROUTED_REQUESTS

Show more

boolean

false

Attribute Short Form Long Form

Remote IP address

%a

%{REMOTE_IP}

Local IP address

%A

%{LOCAL_IP}

Bytes sent, excluding HTTP headers, or '-' if no bytes were sent

%b

Bytes sent, excluding HTTP headers

%B

%{BYTES_SENT}

Remote host name

%h

%{REMOTE_HOST}

Request protocol

%H

%{PROTOCOL}

Request method

%m

%{METHOD}

Local port

%p

%{LOCAL_PORT}

Query string (prepended with a '?' if it exists, otherwise an empty string)

%q

%{QUERY_STRING}

First line of the request

%r

%{REQUEST_LINE}

HTTP status code of the response

%s

%{RESPONSE_CODE}

Date and time, in Common Log Format format

%t

%{DATE_TIME}

Remote user that was authenticated

%u

%{REMOTE_USER}

Requested URL path

%U

%{REQUEST_URL}

Request relative path

%R

%{REQUEST_PATH}

Local server name

%v

%{LOCAL_SERVER_NAME}

Time taken to process the request, in millis

%D

%{RESPONSE_TIME}

Time taken to process the request, in seconds

%T

Time taken to process the request, in micros

%{RESPONSE_TIME_MICROS}

Time taken to process the request, in nanos

%{RESPONSE_TIME_NANOS}

Current request thread name

%I

%{THREAD_NAME}

SSL cypher

%{SSL_CIPHER}

SSL client certificate

%{SSL_CLIENT_CERT}

SSL session id

%{SSL_SESSION_ID}

All request headers

%{ALL_REQUEST_HEADERS}

Cookie value

%{c,cookie_name}

Query parameter

%{q,query_param_name}

Request header

%{i,request_header_name}

Response header

%{o,response_header_name}

Vert.x Routing Context Internal Data

%{d,map_key}

Vert.x MDC data (e.g. 'traceId' for OpenTelemetry)

%{X,mdc-key}

Set quarkus.http.access-log.consolidate-rerouted-requests=true to enable support for the modifier <. This modifier can be used for requests that have been internally redirected to consult the original request. The following attributes support this modifier:

Attribute Short Form Long Form

First line of the request

%<r

%{<REQUEST_LINE}

Request method

%<m

%{<METHOD}

Request relative path

%<R

%{<REQUEST_PATH}

Requested URL path

%<U

%{<REQUEST_URL}

Query string (prepended with a '?' if it exists, otherwise an empty string)

%<q

%{<QUERY_STRING}

Query parameter

%{<q,query_param_name}

Set quarkus.http.record-request-start-time=true to enable recording request start times when using any of the attributes related to logging request processing times.

Assuming security has been set up for the application (see our guide for more details), logging attribute Remote user that was authenticated is set to the value of the io.quarkus.security.identity.SecurityIdentity principal. If your application use custom Jakarta REST SecurityContext, the context principal is used instead. Please refer to the Logging guide for options how to add contextual log information yourself.

Use quarkus.http.access-log.exclude-pattern=/some/path/.* to exclude all entries concerning the path /some/path/…​ (including subsequent paths) from the log.

12. Arbitrary customizations

Quarkus allows users to arbitrarily customize the options of HTTP servers started by Quarkus via the use of io.quarkus.vertx.http.HttpServerOptionsCustomizer. For example, if the HTTP port needs to be set programmatically, then the following code could be used:

import jakarta.inject.Singleton;
import io.quarkus.vertx.http.HttpServerOptionsCustomizer;

@Singleton (1)
public static class MyCustomizer implements HttpServerOptionsCustomizer {

    @Override
    public void customizeHttpServer(HttpServerOptions options) { (2)
        options.setPort(9998);
    }
}
1 By making the class a managed bean, Quarkus will take the customizer into account when it starts the Vert.x servers
2 In this case, we only care about customizing the HTTP server, so we just override the customizeHttpServer method, but users should be aware that HttpServerOptionsCustomizer allows configuring the HTTPS and Domain Socket servers as well

13. Running behind a reverse proxy

Quarkus could be accessed through proxies that additionally generate headers (e.g. X-Forwarded-Host) to keep information from the client-facing side of the proxy servers that is altered or lost when they are involved. In those scenarios, Quarkus can be configured to automatically update information like protocol, host, port and URI reflecting the values in these headers.

Activating this feature leaves the server exposed to several security issues (i.e. information spoofing). Consider activate it only when running behind a reverse proxy.

To set up this feature, please include the following lines in src/main/resources/application.properties:

quarkus.http.proxy.proxy-address-forwarding=true

To consider only de-facto standard header (Forwarded header), please include the following lines in src/main/resources/application.properties:

quarkus.http.proxy.allow-forwarded=true

To consider only non-standard headers, please include the following lines instead in src/main/resources/application.properties:

quarkus.http.proxy.proxy-address-forwarding=true
quarkus.http.proxy.allow-x-forwarded=true
quarkus.http.proxy.enable-forwarded-host=true
quarkus.http.proxy.enable-forwarded-prefix=true
quarkus.http.proxy.trusted-proxies=127.0.0.1 (1)
1 Configure trusted proxy with the IP address 127.0.0.1. Request headers from any other address are going to be ignored.

Both configurations related to standard and non-standard headers can be combined, although the standard headers configuration will have precedence. However, combining them has security implications as clients can forge requests with a forwarded header that is not overwritten by the proxy. Therefore, proxies should strip unexpected X-Forwarded or X-Forwarded-* headers from the client.

Supported forwarding address headers are:

  • Forwarded

  • X-Forwarded-Proto

  • X-Forwarded-Host

  • X-Forwarded-Port

  • X-Forwarded-Ssl

  • X-Forwarded-Prefix

One can easily add a SameSite cookie property to any of the cookies set by a Quarkus endpoint by listing a cookie name and a SameSite attribute, for example:

quarkus.http.same-site-cookie.jwt.value=Lax
quarkus.http.same-site-cookie.session.value=Strict

Given this configuration, the jwt cookie will have a SameSite=Lax attribute and the session cookie will have a SameSite=Strict attribute.

15. Servlet Config

To use Servlet you need to explicitly include quarkus-undertow:

pom.xml
<dependency>
    <groupId>io.quarkus</groupId>
    <artifactId>quarkus-undertow</artifactId>
</dependency>
build.gradle
implementation("io.quarkus:quarkus-undertow")

15.1. undertow-handlers.conf

You can make use of the Undertow predicate language using an undertow-handlers.conf file. This file should be placed in the META-INF directory of your application jar. This file contains handlers defined using the Undertow predicate language.

15.2. web.xml

If you are using a web.xml file as your configuration file, you can place it in the src/main/resources/META-INF directory.

15.3. Built-in route order values

Route order values are the values that are specified via Vert.x route io.vertx.ext.web.Route.order(int) function.

Quarkus registers a couple of routes with specific order values. The constants are defined in the io.quarkus.vertx.http.runtime.RouteConstants class and listed in the table below. A custom route should define the order of value 20000 or higher so that it does not interfere with the functionality provided by Quarkus and extensions.

Route order constants defined in io.quarkus.vertx.http.runtime.RouteConstants and known extensions:

Route order value

Constant name

Origin

Integer.MIN_VALUE

ROUTE_ORDER_ACCESS_LOG_HANDLER

Access-log handler, if enabled in the configuration.

Integer.MIN_VALUE

ROUTE_ORDER_RECORD_START_TIME

Handler adding the start-time, if enabled in the configuration.

Integer.MIN_VALUE

ROUTE_ORDER_HOT_REPLACEMENT

-replacement body handler.

Integer.MIN_VALUE

ROUTE_ORDER_BODY_HANDLER_MANAGEMENT

Body handler for the management router.

Integer.MIN_VALUE

ROUTE_ORDER_HEADERS

Handlers that add headers specified in the configuration.

Integer.MIN_VALUE

ROUTE_ORDER_CORS_MANAGEMENT

CORS-Origin handler of the management router.

Integer.MIN_VALUE + 1

ROUTE_ORDER_BODY_HANDLER

Body handler.

-2

ROUTE_ORDER_UPLOAD_LIMIT

Route that enforces the upload body size limit.

0

ROUTE_ORDER_COMPRESSION

Compression handler.

1000

ROUTE_ORDER_BEFORE_DEFAULT

Route with priority over the default route (add an offset from this value).

10000

ROUTE_ORDER_DEFAULT

Default route order (i.e. Static Resources, Servlet).

20000

ROUTE_ORDER_AFTER_DEFAULT

Route without priority over the default route (add an offset from this value)