Configuration

Configuration

Specifying the configuration file

If you don’t specify a configuration file then Akka uses default values, corresponding to the akka-reference.conf that you see below. You can specify your own configuration file to override any property in the reference config. You only have to define the properties that differ from the default configuration.

The location of the config file to use can be specified in various ways:

  • Define the -Dakka.config=... system property parameter with a file path to configuration file.
  • Put an akka.conf file in the root of the classpath.
  • Define the AKKA_HOME environment variable pointing to the root of the Akka distribution. The config is taken from the AKKA_HOME/config/akka.conf. You can also point to the AKKA_HOME by specifying the -Dakka.home=... system property parameter.

If several of these ways to specify the config file are used at the same time the precedence is the order as given above, i.e. you can always redefine the location with the -Dakka.config=... system property.

Defining the configuration file

Here is the reference configuration file:

####################
# Akka Config File #
####################

# This file has all the default settings, so all these could be removed with no visible effect.
# Modify as needed.

akka {
  version = "1.3.1"   # Akka version, checked against the runtime version of Akka.

  enabled-modules = []       # Comma separated list of the enabled modules. Options: ["remote", "camel", "http"]

  time-unit = "seconds"      # Time unit for all timeout properties throughout the config

  event-handlers = ["akka.event.EventHandler$DefaultListener"] # event handlers to register at boot time (EventHandler$DefaultListener logs to STDOUT)
  event-handler-level = "INFO" # Options: ERROR, WARNING, INFO, DEBUG

  # These boot classes are loaded (and created) automatically when the Akka Microkernel boots up
  #     Can be used to bootstrap your application(s)
  #     Should be the FQN (Fully Qualified Name) of the boot class which needs to have a default constructor
  # boot = ["sample.camel.Boot",
  #         "sample.rest.java.Boot",
  #         "sample.rest.scala.Boot",
  #         "sample.security.Boot"]
  boot = []

  actor {
    timeout = 5                        # Default timeout for Future based invocations
                                       #    - Actor:        ? and ask
                                       #    - UntypedActor: ask
                                       #    - TypedActor:   methods with non-void return type
    serialize-messages = off           # Does a deep clone of (non-primitive) messages to ensure immutability
    throughput = 5                     # Default throughput for all ExecutorBasedEventDrivenDispatcher, set to 1 for complete fairness
    throughput-deadline-time = -1      # Default throughput deadline for all ExecutorBasedEventDrivenDispatcher, set to 0 or negative for no deadline
    dispatcher-shutdown-timeout = 1    # Using the akka.time-unit, how long dispatchers by default will wait for new actors until they shut down

    default-dispatcher {
      type = "GlobalExecutorBasedEventDriven" # Must be one of the following, all "Global*" are non-configurable
                                              #   - ExecutorBasedEventDriven
                                              #   - ExecutorBasedEventDrivenWorkStealing
                                              #   - GlobalExecutorBasedEventDriven
      daemonic = off                   # If the Threads created for this dispatcher should be daemons or not
      keep-alive-time = 60             # Keep alive time for threads
      core-pool-size-factor = 1.0      # No of core threads ... ceil(available processors * factor)
      max-pool-size-factor  = 4.0      # Max no of threads ... ceil(available processors * factor)
      executor-bounds = -1             # Makes the Executor bounded, -1 is unbounded
      task-queue-size = -1             # Specifies the bounded capacity of the task queue (< 1 == unbounded)
      task-queue-type = "linked"       # Specifies which type of task queue will be used, can be "array" or "linked" (default)
      allow-core-timeout = on          # Allow core threads to time out
      rejection-policy = "sane"        # sane, abort, caller-runs, discard-oldest, discard
      throughput = 5                   # Throughput for ExecutorBasedEventDrivenDispatcher, set to 1 for complete fairness
      throughput-deadline-time = -1    # Throughput deadline for ExecutorBasedEventDrivenDispatcher, set to 0 or negative for no deadline
      mailbox-capacity = -1            # If negative (or zero) then an unbounded mailbox is used (default)
                                       # If positive then a bounded mailbox is used and the capacity is set using the property
                                       # NOTE: setting a mailbox to 'blocking' can be a bit dangerous,
                                       #       could lead to deadlock, use with care
                                       #
                                       # The following are only used for ExecutorBasedEventDriven
                                       # and only if mailbox-capacity > 0
      mailbox-push-timeout-time = 10   # Specifies the timeout to add a new message to a mailbox that is full - negative number means infinite timeout
                                       #       (in unit defined by the time-unit property)
    }

    debug {
      receive = "false"       # enable function of Actor.loggable(), which is
                              # to log any received message at DEBUG level
      autoreceive = "false"   # enable DEBUG logging of all AutoReceiveMessages
                              # (Kill, PoisonPill and the like)
      lifecycle = "false"     # enable DEBUG logging of actor lifecycle changes
    }

    mailbox {
        mongodb {
            # Any specified collection name will be used as a prefix for collections that use durable mongo mailboxes
            uri = "mongodb://localhost/akka.mailbox"   # Follow Mongo URI Spec - http://www.mongodb.org/display/DOCS/Connections
            # Configurable timeouts for certain ops
            timeout {
                read = 3000 # number of milliseconds to wait for a read to succeed before timing out the future
                write = 3000 # number of milliseconds to wait for a write to succeed before timing out the future
            }
        }
      }
    }

  stm {
    fair             = on     # Should global transactions be fair or non-fair (non fair yield better performance)
    max-retries      = 1000
    timeout          = 5      # Default timeout for blocking transactions and transaction set (in unit defined by
                              #     the time-unit property)
    write-skew       = true
    blocking-allowed = false
    interruptible    = false
    speculative      = true
    quick-release    = true
    propagation      = "requires"
    trace-level      = "none"
  }

  http {
    hostname = "localhost"
    port = 9998

    #If you are using akka.http.AkkaRestServlet
    filters = ["akka.security.AkkaSecurityFilterFactory"] # List with all jersey filters to use
    # resource-packages = ["sample.rest.scala",
    #                      "sample.rest.java",
    #                      "sample.security"] # List with all resource packages for your Jersey services
    resource-packages = []

    # The authentication service to use. Need to be overridden (sample now)
    # authenticator = "sample.security.BasicAuthenticationService"
    authenticator = "N/A"

    # Uncomment if you are using the KerberosAuthenticationActor
    # kerberos {
    #   servicePrincipal = "HTTP/localhost@EXAMPLE.COM"
    #   keyTabLocation   = "URL to keytab"
    #   kerberosDebug    = "true"
    #   realm            = "EXAMPLE.COM"
    # }
    kerberos {
      servicePrincipal = "N/A"
      keyTabLocation   = "N/A"
      kerberosDebug    = "N/A"
      realm            = ""
    }

    #If you are using akka.http.AkkaMistServlet
    mist-dispatcher {
      #type = "GlobalExecutorBasedEventDriven" # Uncomment if you want to use a different dispatcher than the default one for Comet
    }
    connection-close = true                 # toggles the addition of the "Connection" response header with a "close" value
    root-actor-id = "_httproot"             # the id of the actor to use as the root endpoint
    root-actor-builtin = true               # toggles the use of the built-in root endpoint base class
    timeout = 1000                          # the default timeout for all async requests (in ms)
    expired-header-name = "Async-Timeout"   # the name of the response header to use when an async request expires
    expired-header-value = "expired"        # the value of the response header to use when an async request expires
  }

  remote {

    # secure-cookie = "050E0A0D0D06010A00000900040D060F0C09060B" # generate your own with '$AKKA_HOME/scripts/generate_config_with_secure_cookie.sh' or using 'Crypt.generateSecureCookie'
    secure-cookie = ""

    layer = "akka.remote.netty.NettyRemoteSupport"

    server {
      hostname = "localhost"       # The hostname or IP that clients should connect to
      port = 2552                  # The port clients should connect to. Default is 2552 (AKKA)
      message-frame-size = 1048576 # Increase this if you want to be able to send messages with large payloads
      require-cookie = off         # Should the remote server require that it peers share the same secure-cookie (defined in the 'remote' section)?
      untrusted-mode = off         # Enable untrusted mode for full security of server managed actors, allows untrusted clients to connect.
      backlog = 4096               # Sets the size of the connection backlog
      execution-pool-keepalive = 60# Length in akka.time-unit how long core threads will be kept alive if idling
      execution-pool-size      = 16# Size of the core pool of the remote execution unit
      max-channel-memory-size  = 0 # Maximum channel size, 0 for off
      max-total-memory-size    = 0 # Maximum total size of all channels, 0 for off
    }

    client {
      buffering {
        retry-message-send-on-failure = off # Buffer outbound messages when send failed, if off you'll get an exception instead
        capacity = -1                      # If negative (or zero) then an unbounded mailbox is used (default)
                                           # If positive then a bounded mailbox is used and the capacity is set using the property
      }
      connection-timeout = 10              # Number in time-unit, timeout for establishing outbound connections
      reconnect-delay = 5                  # Number in time-unit, the interval at which to try to reestablish outbound connections
      read-timeout = 120                   # Number in time-unit, period of inactivity after which a connection should be closed
      message-frame-size = 1048576         # Size in bytes
      reap-futures-delay = 5               # Number in time-unit, the interval of garbage-collecting Future calls
      reconnection-time-window = 600 # Maximum time window that a client should try to reconnect for
    }
  }

  test {
    timefactor = "1.0"    # factor by which to scale timeouts during tests, e.g. to account for shared build system load
  }
}

A custom akka.conf might look like this:

# In this file you can override any option defined in the 'akka-reference.conf' file.
# Copy in all or parts of the 'akka-reference.conf' file and modify as you please.

akka {
  event-handlers = ["akka.event.slf4j.Slf4jEventHandler"]

  # Comma separated list of the enabled modules.
  enabled-modules = ["camel", "remote"]

  # These boot classes are loaded (and created) automatically when the Akka Microkernel boots up
  #     Can be used to bootstrap your application(s)
  #     Should be the FQN (Fully Qualified Name) of the boot class which needs to have a default constructor
  boot = ["sample.camel.Boot",
          "sample.myservice.Boot"]

  actor {
    throughput = 10  # Throughput for ExecutorBasedEventDrivenDispatcher, set to 1 for complete fairness
  }

  remote {
    server {
      port = 2562    # The port clients should connect to. Default is 2552 (AKKA)
    }
  }
}

Specifying files for different modes

You can use different configuration files for different purposes by specifying a mode option, either as -Dakka.mode=... system property or as AKKA_MODE=... environment variable. For example using DEBUG log level when in development mode. Run with -Dakka.mode=dev and place the following akka.dev.conf in the root of the classpath.

akka.dev.conf:

akka {
  event-handler-level = "DEBUG"
}

The mode option works in the same way when using configuration files in AKKA_HOME/config/ directory.

The mode option is not used when specifying the configuration file with -Dakka.config=... system property.

Including files

Sometimes it can be useful to include another configuration file, for example if you have one akka.conf with all environment independent settings and then override some settings for specific modes.

akka.dev.conf:

include "akka.conf"

akka {
  event-handler-level = "DEBUG"
}

Showing Configuration Source

If the system property akka.output.config.source is set to anything but null, then the source from which Akka reads its configuration is printed to the console during application startup.

Summary of System Properties

Contents