Configuration
Loading

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 {

  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.version}

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

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

    # 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.
    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
    }
  }

  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.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
    }

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

  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 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.
    # 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.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.http-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

    # Maximum content length which should not be exceeded by incoming HttpRequests.
    # For file uploads which use the entityBytes Source of an incoming HttpRequest it is safe to
    # set this to a very high value (or to `infinite` if feeling very adventurous) as the streaming
    # upload will be back-pressured properly by Akka Streams.
    # Please note however that this setting is a global property, and is applied to all incoming requests,
    # not only file uploads consumed in a streaming fashion, so pick this limit wisely.
    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

    # 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
    }
  }
}

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.

Contents