Documentation

You are viewing the documentation for the 2.6.12 release in the 2.6.x series of releases. The latest stable release series is 3.0.x.

§Configuring the Akka HTTP server backend

By default, Play uses the Akka HTTP server backend.

Like the rest of Play, the Akka HTTP server backend is configured with Typesafe Config.

#
# Copyright (C) 2009-2017 Lightbend Inc. <https://www.lightbend.com>
#

# Configuration for Play's AkkaHttpServer
play {

  server {
    # The server provider class name
    provider = "play.core.server.AkkaHttpServerProvider"

    akka {
      # How long to wait when binding to the listening socket
      bindTimeout = 5 seconds

      # How long a request takes until it times out. Set to null or "infinite" to disable the timeout.
      requestTimeout = infinite

      # 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 = off

      # 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 = ""

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

      # 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 = warn

      # This setting is set in `akka.http.server.parsing.max-content-length`
      # Play uses the concept of a `BodyParser` to enforce this limit, so we override it to infinite.
      max-content-length = infinite

      # 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).
      #
      # See Akka HTTP `akka.http.server.parsing.tls-session-info-header` for
      # more information about how this works.
      tls-session-info-header = on

    }
  }

}

The configurations above are specific to Akka HTTP server backend, but other more generic configurations are also available:

play {

  server {

    # The root directory for the Play server instance. This value can
    # be set by providing a path as the first argument to the Play server
    # launcher script. See `ServerConfig.loadConfiguration`.
    dir = ${?user.dir}

    # HTTP configuration
    http {
      # The HTTP port of the server. Use a value of "disabled" if the server
      # shouldn't bind an HTTP port.
      port = 9000
      port = ${?http.port}

      # The interface address to bind to.
      address = "0.0.0.0"
      address = ${?http.address}

      # The idle timeout for an open connection after which it will be closed
      # Set to null or "infinite" to disable the timeout, but notice that this
      # is not encouraged since timeout are important mechanisms to protect your
      # servers from malicious attacks or programming mistakes.
      idleTimeout = 75 seconds
    }

    # HTTPS configuration
    https {

      # The HTTPS port of the server.
      port = ${?https.port}

      # The interface address to bind to
      address = "0.0.0.0"
      address = ${?https.address}

      # The idle timeout for an open connection after which it will be closed
      # Set to null or "infinite" to disable the timeout, but notice that this
      # is not encouraged since timeout are important mechanisms to protect your
      # servers from malicious attacks or programming mistakes.
      idleTimeout = ${play.server.http.idleTimeout}

      # The SSL engine provider
      engineProvider = "play.core.server.ssl.DefaultSSLEngineProvider"
      engineProvider = ${?play.http.sslengineprovider}

      # HTTPS keystore configuration, used by the default SSL engine provider
      keyStore {
        # The path to the keystore
        path = ${?https.keyStore}

        # The type of the keystore
        type = "JKS"
        type = ${?https.keyStoreType}

        # The password for the keystore
        password = ""
        password = ${?https.keyStorePassword}

        # The algorithm to use. If not set, uses the platform default algorithm.
        algorithm = ${?https.keyStoreAlgorithm}
      }

      # HTTPS truststore configuration
      trustStore {

        # If true, does not do CA verification on client side certificates
        noCaVerification = false
      }

      # Whether JSSE want client auth mode should be used. This means, the server
      # will request a client certificate, but won't fail if one isn't provided.
      wantClientAuth = false

      # Whether JSSE need client auth mode should be used. This means, the server
      # will request a client certificate, and will fail and terminate the session
      # if one isn't provided.
      needClientAuth = false
    }

    # The path to the process id file created by the server when it runs.
    # If set to "/dev/null" then no pid file will be created.
    pidfile.path = ${play.server.dir}/RUNNING_PID
    pidfile.path = ${?pidfile.path}

    websocket {
      # Maximum allowable frame payload length. Setting this value to your application's
      # requirement may reduce denial of service attacks using long data frames.
      frame.maxLength = 64k
      frame.maxLength = ${?websocket.frame.maxLength}
    }
  }

  editor = ${?PLAY_EDITOR}

}

You can read more about the configuration settings in the Akka HTTP documentation.

Note: Akka HTTP has a number of timeouts configurations that you can use to protect your application from attacks or programming mistakes. The Akka HTTP Server in Play will automatically recognize all these Akka configurations. For example, if you have idle-timeout and request-timeout configurations like below:

akka.http.server.idle-timeout = 20s
akka.http.server.request-timeout = 30s

They will be automatically recognized. Keep in mind that Play configurations listed above will override the Akka ones.

There is also a separate configuration file for the HTTP/2 support in Akka HTTP, if you have enabled the AkkaHttp2Support plugin:

#
# Copyright (C) 2009-2017 Lightbend Inc. <https://www.lightbend.com>
#

# Determines whether HTTP2 is enabled.
play.server.akka.http2 {
  enabled = true
  enabled = ${?http2.enabled}
}

Note: In dev mode, when you use the run command, your application.conf settings will not be picked up by the server. This is because in dev mode the server starts before the application classpath is available. There are several other options you’ll need to use instead.

Next: Configuring Netty Server Backend