Configuration

Just like any other Akka module Akka HTTP is configured via Typesafe Config. Usually this means that you provide an application.conf which contains all the application-specific settings that differ from the default ones provided by the reference configuration files from the individual Akka modules.

These are the relevant default configuration values for the Akka HTTP modules.

akka-http-core

########################################
# akka-http-core Reference Config File #
########################################

# This is the reference config file that contains all the default settings.
# Make your edits/overrides in your application.conf.

# Akka HTTP version, checked against the runtime version of Akka HTTP.
# Loaded from generated conf file.
include "akka-http-version"

akka.http {

  server {
    # The default value of the `Server` header to produce if no
    # explicit `Server`-header was included in a response.
    # If this value is the empty string and no header was included in
    # the request, no `Server` header will be rendered at all.
    server-header = akka-http/${akka.http.version}

    # "PREVIEW" features that are not yet fully production ready.
    # These flags can can change or be removed between patch releases.
    preview {
      # ONLY WORKS WITH `bindAndHandleAsync` (currently)
      # 
      # If this setting is enabled AND the akka-http2-support is found 
      # on the classpath the usual Http().bind... method calls will bind 
      # using HTTP/2. Please note that you must configure HTTPS while doing so.
      enable-http2 = off
    }
    
    # The time after which an idle connection will be automatically closed.
    # Set to `infinite` to completely disable idle connection timeouts.
    idle-timeout = 60 s

    # Defines the default time period within which the application has to
    # produce an HttpResponse for any given HttpRequest it received.
    # The timeout begins to run when the *end* of the request has been
    # received, so even potentially long uploads can have a short timeout.
    # Set to `infinite` to completely disable request timeout checking.
    #
    # If this setting is not `infinite` the HTTP server layer attaches a
    # `Timeout-Access` header to the request, which enables programmatic
    # customization of the timeout period and timeout response for each
    # request individually.
    request-timeout = 20 s

    # The time period within which the TCP binding process must be completed.
    bind-timeout = 1s

    # The time period the HTTP server implementation will keep a connection open after
    # all data has been delivered to the network layer. This setting is similar to the SO_LINGER socket option
    # but does not only include the OS-level socket but also covers the Akka IO / Akka Streams network stack.
    # The setting is an extra precaution that prevents clients from keeping open a connection that is
    # already considered completed from the server side.
    #
    # If the network level buffers (including the Akka Stream / Akka IO networking stack buffers)
    # contains more data than can be transferred to the client in the given time when the server-side considers
    # to be finished with this connection, the client may encounter a connection reset.
    #
    # Set to 'infinite' to disable automatic connection closure (which will risk to leak connections).
    linger-timeout = 1 min

    # The maximum number of concurrently accepted connections when using the
    # `Http().bindAndHandle` methods.
    #
    # This setting doesn't apply to the `Http().bind` method which will still
    # deliver an unlimited backpressured stream of incoming connections.
    #
    # Note, that this setting limits the number of the connections on a best-effort basis.
    # It does *not* strictly guarantee that the number of established TCP connections will never
    # exceed the limit (but it will be approximately correct) because connection termination happens
    # asynchronously. It also does *not* guarantee that the number of concurrently active handler
    # flow materializations will never exceed the limit for the reason that it is impossible to reliably
    # detect when a materialization has ended.
    max-connections = 1024

    # The maximum number of requests that are accepted (and dispatched to
    # the application) on one single connection before the first request
    # has to be completed.
    # Incoming requests that would cause the pipelining limit to be exceeded
    # are not read from the connections socket so as to build up "back-pressure"
    # to the client via TCP flow control.
    # A setting of 1 disables HTTP pipelining, since only one request per
    # connection can be "open" (i.e. being processed by the application) at any
    # time. Set to higher values to enable HTTP pipelining.
    # This value must be > 0 and <= 1024.
    pipelining-limit = 16

    # Enables/disables the addition of a `Remote-Address` header
    # holding the clients (remote) IP address.
    remote-address-header = off

    # Enables/disables the addition of a `Raw-Request-URI` header holding the
    # original raw request URI as the client has sent it.
    raw-request-uri-header = off

    # Enables/disables automatic handling of HEAD requests.
    # If this setting is enabled the server dispatches HEAD requests as GET
    # requests to the application and automatically strips off all message
    # bodies from outgoing responses.
    # Note that, even when this setting is off the server will never send
    # out message bodies on responses to HEAD requests.
    transparent-head-requests = on

    # Enables/disables the returning of more detailed error messages to
    # the client in the error response.
    # Should be disabled for browser-facing APIs due to the risk of XSS attacks
    # and (probably) enabled for internal or non-browser APIs.
    # Note that akka-http will always produce log messages containing the full
    # error details.
    verbose-error-messages = off

    # The initial size of the buffer to render the response headers in.
    # Can be used for fine-tuning response rendering performance but probably
    # doesn't have to be fiddled with in most applications.
    response-header-size-hint = 512

    # The requested maximum length of the queue of incoming connections.
    # If the server is busy and the backlog is full the OS will start dropping
    # SYN-packets and connection attempts may fail. Note, that the backlog
    # size is usually only a maximum size hint for the OS and the OS can
    # restrict the number further based on global limits.
    backlog = 100

    # If this setting is empty the server only accepts requests that carry a
    # non-empty `Host` header. Otherwise it responds with `400 Bad Request`.
    # Set to a non-empty value to be used in lieu of a missing or empty `Host`
    # header to make the server accept such requests.
    # Note that the server will never accept HTTP/1.1 request without a `Host`
    # header, i.e. this setting only affects HTTP/1.1 requests with an empty
    # `Host` header as well as HTTP/1.0 requests.
    # Examples: `www.spray.io` or `example.com:8080`
    default-host-header = ""

    # Socket options to set for the listening socket. If a setting is left
    # undefined, it will use whatever the default on the system is.
    socket-options {
      so-receive-buffer-size = undefined
      so-send-buffer-size = undefined
      so-reuse-address = undefined
      so-traffic-class = undefined
      tcp-keep-alive = undefined
      tcp-oob-inline = undefined
      tcp-no-delay = undefined
    }

    # Modify to tweak parsing settings on the server-side only.
    parsing {
      # no overrides by default, see `akka.http.parsing` for default values
    }

    # Enables/disables the logging of unencrypted HTTP traffic to and from the HTTP
    # server for debugging reasons.
    #
    # Note: Use with care. Logging of unencrypted data traffic may expose secret data.
    #
    # Incoming and outgoing traffic will be logged in hexdump format. To enable logging,
    # specify the number of bytes to log per chunk of data (the actual chunking depends
    # on implementation details and networking conditions and should be treated as
    # arbitrary).
    #
    # For logging on the client side, see akka.http.client.log-unencrypted-network-bytes.
    #
    # `off` : no log messages are produced
    # Int   : determines how many bytes should be logged per data chunk
    log-unencrypted-network-bytes = off
  }

  client {
    # The default value of the `User-Agent` header to produce if no
    # explicit `User-Agent`-header was included in a request.
    # If this value is the empty string and no header was included in
    # the request, no `User-Agent` header will be rendered at all.
    user-agent-header = akka-http/${akka.http.version}

    # The time period within which the TCP connecting process must be completed.
    connecting-timeout = 10s

    # The time after which an idle connection will be automatically closed.
    # Set to `infinite` to completely disable idle timeouts.
    idle-timeout = 60 s

    # The initial size of the buffer to render the request headers in.
    # Can be used for fine-tuning request rendering performance but probably
    # doesn't have to be fiddled with in most applications.
    request-header-size-hint = 512

    # Socket options to set for the listening socket. If a setting is left
    # undefined, it will use whatever the default on the system is.
    socket-options {
      so-receive-buffer-size = undefined
      so-send-buffer-size = undefined
      so-reuse-address = undefined
      so-traffic-class = undefined
      tcp-keep-alive = undefined
      tcp-oob-inline = undefined
      tcp-no-delay = undefined
    }

    # Modify to tweak parsing settings on the client-side only.
    parsing {
      # no overrides by default, see `akka.http.parsing` for default values
    }

    # Enables/disables the logging of unencrypted HTTP traffic to and from the HTTP
    # client for debugging reasons.
    #
    # Note: Use with care. Logging of unencrypted data traffic may expose secret data.
    #
    # Incoming and outgoing traffic will be logged in hexdump format. To enable logging,
    # specify the number of bytes to log per chunk of data (the actual chunking depends
    # on implementation details and networking conditions and should be treated as
    # arbitrary).
    #
    # For logging on the server side, see akka.http.server.log-unencrypted-network-bytes.
    #
    # `off` : no log messages are produced
    # Int   : determines how many bytes should be logged per data chunk
    log-unencrypted-network-bytes = off
  }

  host-connection-pool {
    # The maximum number of parallel connections that a connection pool to a
    # single host endpoint is allowed to establish. Must be greater than zero.
    max-connections = 4

    # The minimum number of parallel connections that a pool should keep alive ("hot").
    # If the number of connections is falling below the given threshold, new ones are being spawned.
    # You can use this setting to build a hot pool of "always on" connections.
    # Default is 0, meaning there might be no active connection at given moment.
    # Keep in mind that `min-connections` should be smaller than `max-connections` or equal
    min-connections = 0

    # The maximum number of times failed requests are attempted again,
    # (if the request can be safely retried) before giving up and returning an error.
    # Set to zero to completely disable request retries.
    max-retries = 5

    # The maximum number of open requests accepted into the pool across all
    # materializations of any of its client flows.
    # Protects against (accidentally) overloading a single pool with too many client flow materializations.
    # Note that with N concurrent materializations the max number of open request in the pool
    # will never exceed N * max-connections * pipelining-limit.
    # Must be a power of 2 and > 0!
    max-open-requests = 32

    # The maximum number of requests that are dispatched to the target host in
    # batch-mode across a single connection (HTTP pipelining).
    # A setting of 1 disables HTTP pipelining, since only one request per
    # connection can be "in flight" at any time.
    # Set to higher values to enable HTTP pipelining.
    # This value must be > 0.
    # (Note that, independently of this setting, pipelining will never be done
    # on a connection that still has a non-idempotent request in flight.
    #
    # Before increasing this value, make sure you understand the effects of head-of-line blocking.
    # Using a connection pool, a request may be issued on a connection where a previous
    # long-running request hasn't finished yet. The response to the pipelined requests may then be stuck
    # behind the response of the long-running previous requests on the server. This may introduce an
    # unwanted "coupling" of run time between otherwise unrelated requests.
    #
    # See http://tools.ietf.org/html/rfc7230#section-6.3.2 for more info.)
    pipelining-limit = 1

    # The time after which an idle connection pool (without pending requests)
    # will automatically terminate itself. Set to `infinite` to completely disable idle timeouts.
    idle-timeout = 30 s

    # Modify to tweak client settings for host connection pools only.
    #
    # IMPORTANT:
    # Please note that this section mirrors `akka.http.client` however is used only for pool-based APIs,
    # such as `Http().superPool` or `Http().singleRequest`.
    client = {
      # The default value of the `User-Agent` header to produce if no
      # explicit `User-Agent`-header was included in a request.
      # If this value is the empty string and no header was included in
      # the request, no `User-Agent` header will be rendered at all.
      user-agent-header = akka-http/${akka.http.version}

      # The time period within which the TCP connecting process must be completed.
      connecting-timeout = 10s

      # The time after which an idle connection will be automatically closed.
      # Set to `infinite` to completely disable idle timeouts.
      idle-timeout = 60 s

      # The initial size of the buffer to render the request headers in.
      # Can be used for fine-tuning request rendering performance but probably
      # doesn't have to be fiddled with in most applications.
      request-header-size-hint = 512

      # The proxy configurations to be used for requests with the specified
      # scheme.
      proxy {
        # Proxy settings for unencrypted HTTP requests
        # Set to 'none' to always connect directly, 'default' to use the system
        # settings as described in http://docs.oracle.com/javase/6/docs/technotes/guides/net/proxies.html
        # or specify the proxy host, port and non proxy hosts as demonstrated
        # in the following example:
        # http {
        #   host = myproxy.com
        #   port = 8080
        #   non-proxy-hosts = ["*.direct-access.net"]
        # }
        http = default

        # Proxy settings for HTTPS requests (currently unsupported)
        https = default
      }

      # Socket options to set for the listening socket. If a setting is left
      # undefined, it will use whatever the default on the system is.
      socket-options {
        so-receive-buffer-size = undefined
        so-send-buffer-size = undefined
        so-reuse-address = undefined
        so-traffic-class = undefined
        tcp-keep-alive = undefined
        tcp-oob-inline = undefined
        tcp-no-delay = undefined
      }


      # IMPORTANT: Please note that this section is replicated in `client` and `server`.
      parsing {
        # no overrides by default, see `akka.http.parsing` for default values
      }
    }
  }

  # Modify to tweak default parsing settings.
  #
  # IMPORTANT:
  # Please note that this sections settings can be overriden by the corresponding settings in:
  # `akka.http.server.parsing`, `akka.http.client.parsing` or `akka.http.host-connection-pool.client.parsing`.
  parsing {
    # The limits for the various parts of the HTTP message parser.
    max-uri-length             = 2k
    max-method-length          = 16
    max-response-reason-length = 64
    max-header-name-length     = 64
    max-header-value-length    = 8k
    max-header-count           = 64
    max-chunk-ext-length       = 256
    max-chunk-size             = 1m

    # Default maximum content length which should not be exceeded by incoming request entities.
    # Can be changed at runtime (to a higher or lower value) via the `HttpEntity::withSizeLimit` method.
    # Note that it is not necessarily a problem to set this to a high value as all stream operations
    # are always properly backpressured.
    # Nevertheless you might want to apply some limit in order to prevent a single client from consuming
    # an excessive amount of server resources.
    #
    # Set to `infinite` to completely disable entity length checks. (Even then you can still apply one
    # programmatically via `withSizeLimit`.)
    max-content-length = 8m

    # Sets the strictness mode for parsing request target URIs.
    # The following values are defined:
    #
    # `strict`: RFC3986-compliant URIs are required,
    #     a 400 response is triggered on violations
    #
    # `relaxed`: all visible 7-Bit ASCII chars are allowed
    #
    uri-parsing-mode = strict

    # Sets the parsing mode for parsing cookies.
    # The following value are defined:
    #
    # `rfc6265`: Only RFC6265-compliant cookies are parsed. Surrounding double-quotes are accepted and
    #   automatically removed. Non-compliant cookies are silently discarded.
    # `raw`: Raw parsing allows any non-control character but ';' to appear in a cookie value. There's no further
    #   post-processing applied, so that the resulting value string may contain any number of whitespace, unicode,
    #   double quotes, or '=' characters at any position.
    #   The rules for parsing the cookie name are the same ones from RFC 6265.
    #
    cookie-parsing-mode = rfc6265

    # Enables/disables the logging of warning messages in case an incoming
    # message (request or response) contains an HTTP header which cannot be
    # parsed into its high-level model class due to incompatible syntax.
    # Note that, independently of this settings, akka-http will accept messages
    # with such headers as long as the message as a whole would still be legal
    # under the HTTP specification even without this header.
    # If a header cannot be parsed into a high-level model instance it will be
    # provided as a `RawHeader`.
    # If logging is enabled it is performed with the configured
    # `error-logging-verbosity`.
    illegal-header-warnings = on

    # Configures the verbosity with which message (request or response) parsing
    # errors are written to the application log.
    #
    # Supported settings:
    # `off`   : no log messages are produced
    # `simple`: a condensed single-line message is logged
    # `full`  : the full error details (potentially spanning several lines) are logged
    error-logging-verbosity = full

    # Configures the processing mode when encountering illegal characters in
    # header value of response.
    #
    # Supported mode:
    # `error`  : default mode, throw an ParsingException and terminate the processing
    # `warn`   : ignore the illegal characters in response header value and log a warning message
    # `ignore` : just ignore the illegal characters in response header value
    illegal-response-header-value-processing-mode = error

    # limits for the number of different values per header type that the
    # header cache will hold
    header-cache {
      default = 12
      Content-MD5 = 0
      Date = 0
      If-Match = 0
      If-Modified-Since = 0
      If-None-Match = 0
      If-Range = 0
      If-Unmodified-Since = 0
      User-Agent = 32
    }

    # Enables/disables inclusion of an Tls-Session-Info header in parsed
    # messages over Tls transports (i.e., HttpRequest on server side and
    # HttpResponse on client side).
    tls-session-info-header = off
  }
}

akka-http

###################################
# akka-http Reference Config File #
###################################

# This is the reference config file that contains all the default settings.
# Make your edits/overrides in your application.conf.

akka.http.routing {
  # Enables/disables the returning of more detailed error messages to the
  # client in the error response
  # Should be disabled for browser-facing APIs due to the risk of XSS attacks
  # and (probably) enabled for internal or non-browser APIs
  # (Note that akka-http will always produce log messages containing the full error details)
  verbose-error-messages = off

  # Enables/disables ETag and `If-Modified-Since` support for FileAndResourceDirectives
  file-get-conditional = on

  # Enables/disables the rendering of the "rendered by" footer in directory listings
  render-vanity-footer = yes

  # The maximum size between two requested ranges. Ranges with less space in between will be coalesced.
  #
  # When multiple ranges are requested, a server may coalesce any of the ranges that overlap or that are separated
  # by a gap that is smaller than the overhead of sending multiple parts, regardless of the order in which the
  # corresponding byte-range-spec appeared in the received Range header field. Since the typical overhead between
  # parts of a multipart/byteranges payload is around 80 bytes, depending on the selected representation's
  # media type and the chosen boundary parameter length, it can be less efficient to transfer many small
  # disjoint parts than it is to transfer the entire selected representation.
  range-coalescing-threshold = 80

  # The maximum number of allowed ranges per request.
  # Requests with more ranges will be rejected due to DOS suspicion.
  range-count-limit = 16

  # The maximum number of bytes per ByteString a decoding directive will produce
  # for an entity data stream.
  decode-max-bytes-per-chunk = 1m

  # Fully qualified config path which holds the dispatcher configuration
  # to be used by FlowMaterialiser when creating Actors for IO operations.
  file-io-dispatcher = ${akka.stream.blocking-io-dispatcher}
}

The other Akka HTTP modules do not offer any configuration via Typesafe Config.