Remoting (Scala)
Loading

Remoting (Scala)

For an introduction of remoting capabilities of Akka please see Location Transparency.

Preparing your ActorSystem for Remoting

The Akka remoting is a separate jar file. Make sure that you have the following dependency in your project:

"com.typesafe.akka" %% "akka-remote" % "2.1.4"

To enable remote capabilities in your Akka project you should, at a minimum, add the following changes to your application.conf file:

akka {
  actor {
    provider = "akka.remote.RemoteActorRefProvider"
  }
  remote {
    transport = "akka.remote.netty.NettyRemoteTransport"
    netty {
      hostname = "127.0.0.1"
      port = 2552
    }
 }
}

As you can see in the example above there are four things you need to add to get started:

  • Change provider from akka.actor.LocalActorRefProvider to akka.remote.RemoteActorRefProvider
  • Add host name - the machine you want to run the actor system on; this host name is exactly what is passed to remote systems in order to identify this system and consequently used for connecting back to this system if need be, hence set it to a reachable IP address or resolvable name in case you want to communicate across the network.
  • Add port number - the port the actor system should listen on, set to 0 to have it chosen automatically

Note

The port number needs to be unique for each actor system on the same machine even if the actor systems have different names. This is because each actor system has its own network subsystem listening for connections and handling messages as not to interfere with other actor systems.

Remote Configuration

The example above only illustrates the bare minimum of properties you have to add to enable remoting. There are lots of more properties that are related to remoting in Akka. We refer to the following reference file for more information:

#####################################
# Akka Remote Reference Config File #
#####################################

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

# comments about akka.actor settings left out where they are already in akka-
# actor.jar, because otherwise they would be repeated in config rendering.

akka {

  actor {

    serializers {
      proto = "akka.remote.serialization.ProtobufSerializer"
      daemon-create = "akka.remote.serialization.DaemonMsgCreateSerializer"
    }


    serialization-bindings {
      # Since com.google.protobuf.Message does not extend Serializable but
      # GeneratedMessage does, need to use the more specific one here in order
      # to avoid ambiguity
      "com.google.protobuf.GeneratedMessage" = proto
      "akka.remote.DaemonMsgCreate" = daemon-create
    }

    deployment {

      default {

        # if this is set to a valid remote address, the named actor will be
        # deployed at that node e.g. "akka://sys@host:port"
        remote = ""

        target {

          # A list of hostnames and ports for instantiating the children of a
          # router
          #   The format should be on "akka://sys@host:port", where:
          #    - sys is the remote actor system name
          #    - hostname can be either hostname or IP address the remote actor
          #      should connect to
          #    - port should be the port for the remote server on the other node
          # The number of actor instances to be spawned is still taken from the
          # nr-of-instances setting as for local routers; the instances will be
          # distributed round-robin among the given nodes.
          nodes = []

        }
      }
    }
  }

  remote {

    # Which implementation of akka.remote.RemoteTransport to use
    # default is a TCP-based remote transport based on Netty
    transport = "akka.remote.netty.NettyRemoteTransport"

    # Enable untrusted mode for full security of server managed actors, prevents
    # system messages to be send by clients, e.g. messages like 'Create',
    # 'Suspend', 'Resume', 'Terminate', 'Supervise', 'Link' etc.
    untrusted-mode = off

    # Timeout for ACK of cluster operations, like checking actor out etc.
    remote-daemon-ack-timeout = 30s

    # If this is "on", Akka will log all inbound messages at DEBUG level,
    # if off then they are not logged
    log-received-messages = off

    # If this is "on", Akka will log all outbound messages at DEBUG level,
    # if off then they are not logged
    log-sent-messages = off

    # If this is "on", Akka will log all RemoteLifeCycleEvents at the level
    # defined for each, if off then they are not logged Failures to deserialize
    # received messages also fall under this flag.
    log-remote-lifecycle-events = on

    # Each property is annotated with (I) or (O) or (I&O), where I stands for
    # “inbound” and O for “outbound” connections. The NettyRemoteTransport always
    # starts the server role to allow inbound connections, and it starts active
    # client connections whenever sending to a destination which is not yet
    # connected; if configured it reuses inbound connections for replies, which
    # is called a passive client connection (i.e. from server to client).
    netty {

      # (O) In case of increased latency / overflow how long should we wait
      # (blocking the sender) until we deem the send to be cancelled?
      # 0 means "never backoff", any positive number will indicate the time to
      # block at most.
      backoff-timeout = 0ms

      # (I&O) Generate your own with the script availbale in
      # '$AKKA_HOME/scripts/generate_config_with_secure_cookie.sh' or using
      # 'akka.util.Crypt.generateSecureCookie'
      secure-cookie = ""

      # (I) Should the remote server require that its peers share the same
      # secure-cookie (defined in the 'remote' section)?
      require-cookie = off

      # (I) Reuse inbound connections for outbound messages
      use-passive-connections = on

      # (I) EXPERIMENTAL If "<id.of.dispatcher>" then the specified dispatcher
      # will be used to accept inbound connections, and perform IO. If "" then
      # dedicated threads will be used.
      #
      # CAUTION: This might lead to the used dispatcher not shutting down properly!
      #          - may prevent the JVM from shutting down normally
      #          - may leak threads when shutting down an ActorSystem
      #
      use-dispatcher-for-io = ""

      # (I) The hostname or ip to bind the remoting to,
      # InetAddress.getLocalHost.getHostAddress is used if empty
      hostname = ""

      # (I) The default remote server port clients should connect to.
      # Default is 2552 (AKKA), use 0 if you want a random available port
      # This port needs to be unique for each actor system on the same machine.
      port = 2552

      # (O) The address of a local network interface (IP Address) to bind to when
      # creating outbound connections. Set to "" or "auto" for automatic selection
      # of local address.
      outbound-local-address = "auto"

      # (I&O) Increase this if you want to be able to send messages with large
      # payloads
      message-frame-size = 1 MiB

      # (O) Sets the connectTimeoutMillis of all outbound connections,
      # i.e. how long a connect may take until it is timed out
      connection-timeout = 120s

      # (I) Sets the size of the connection backlog
      backlog = 4096

      # (I) Sets the SO_REUSE_ADDR flag, valid values are "on", "off" and "off-for-windows"
      # due to the following Windows bug: http://bugs.sun.com/bugdatabase/view_bug.do?bug_id=4476378
      # "off-for-windows" of course means that it's "on" for all other platforms
      reuse-address = off-for-windows

      # (I) Length in akka.time-unit how long core threads will be kept alive if
      # idling
      execution-pool-keepalive = 60s

      # (I) Size in number of threads of the core pool of the remote execution
      # unit.
      # A value of 0 will turn this off, which is can lead to deadlocks under
      # some configurations!
      execution-pool-size = 4

      # (I) Maximum channel size, 0 for off
      max-channel-memory-size = 0b

      # (I) Maximum total size of all channels, 0 for off
      max-total-memory-size = 0b

      # (I&O) Sets the high water mark for the in and outbound sockets,
      # set to 0b for platform default
      write-buffer-high-water-mark = 0b

      # (I&O) Sets the low water mark for the in and outbound sockets,
      # set to 0b for platform default
      write-buffer-low-water-mark = 0b

      # (I&O) Sets the send buffer size of the Sockets,
      # set to 0b for platform default
      send-buffer-size = 0b

      # (I&O) Sets the receive buffer size of the Sockets,
      # set to 0b for platform default
      receive-buffer-size = 0b

      # (O) Time between reconnect attempts for active clients
      reconnect-delay = 5s

      # (O) Read inactivity period (lowest resolution is seconds)
      # after which active client connection is shutdown;
      # will be re-established in case of new communication requests.
      # A value of 0 will turn this feature off
      read-timeout = 0s

      # (O) Write inactivity period (lowest resolution is seconds)
      # after which a heartbeat is sent across the wire.
      # A value of 0 will turn this feature off
      write-timeout = 10s

      # (O) Inactivity period of both reads and writes (lowest resolution is
      # seconds) after which active client connection is shutdown; will be
      # re-established in case of new communication requests.
      # A value of 0 will turn this feature off
      all-timeout = 0s

      # (O) Maximum time window that a client should try to reconnect for
      reconnection-time-window = 600s

      ssl {
        # (I&O) Enable SSL/TLS encryption.
        # This must be enabled on both the client and server to work.
        enable = off

        # (I) This is the Java Key Store used by the server connection
        key-store = "keystore"

        # This password is used for decrypting the key store
        key-store-password = "changeme"

        # (O) This is the Java Key Store used by the client connection
        trust-store = "truststore"

        # This password is used for decrypting the trust store
        trust-store-password = "changeme"

        # (I&O) Protocol to use for SSL encryption, choose from:
        # Java 6 & 7:
        #   'SSLv3', 'TLSv1'
        # Java 7:
        #   'TLSv1.1', 'TLSv1.2'
        protocol = "TLSv1"

        # Example: ["TLS_RSA_WITH_AES_128_CBC_SHA", "TLS_RSA_WITH_AES_256_CBC_SHA"]
        # You need to install the JCE Unlimited Strength Jurisdiction Policy
        # Files to use AES 256.
        # More info here:
        # http://docs.oracle.com/javase/7/docs/technotes/guides/security/SunProviders.html#SunJCEProvider
        enabled-algorithms = ["TLS_RSA_WITH_AES_128_CBC_SHA"]

        # Using /dev/./urandom is only necessary when using SHA1PRNG on Linux to
        # prevent blocking. It is NOT as secure because it reuses the seed.
        # '' => defaults to /dev/random or whatever is set in java.security for
        #    example: securerandom.source=file:/dev/random
        # '/dev/./urandom' => NOT '/dev/urandom' as that doesn't work according
        #    to: http://bugs.sun.com/view_bug.do?bug_id=6202721
        sha1prng-random-source = ""

        # There are three options, in increasing order of security:
        # "" or SecureRandom => (default)
        # "SHA1PRNG" => Can be slow because of blocking issues on Linux
        # "AES128CounterSecureRNG" => fastest startup and based on AES encryption
        # algorithm
        # "AES256CounterSecureRNG"
        # The following use one of 3 possible seed sources, depending on
        # availability: /dev/random, random.org and SecureRandom (provided by Java)
        # "AES128CounterInetRNG"
        # "AES256CounterInetRNG" (Install JCE Unlimited Strength Jurisdiction
        # Policy Files first)
        # Setting a value here may require you to supply the appropriate cipher
        # suite (see enabled-algorithms section above)
        random-number-generator = ""
      }

      # (I&O) Used to configure the number of I/O worker threads on server sockets
      server-socket-worker-pool {
        # Min number of threads to cap factor-based number to
        pool-size-min = 2

        # The pool size factor is used to determine thread pool size
        # using the following formula: ceil(available processors * factor).
        # Resulting size is then bounded by the pool-size-min and
        # pool-size-max values.
        pool-size-factor = 1.0

        # Max number of threads to cap factor-based number to
        pool-size-max = 8
      }

      # (I&O) Used to configure the number of I/O worker threads on client sockets
      client-socket-worker-pool {
        # Min number of threads to cap factor-based number to
        pool-size-min = 2

        # The pool size factor is used to determine thread pool size
        # using the following formula: ceil(available processors * factor).
        # Resulting size is then bounded by the pool-size-min and
        # pool-size-max values.
        pool-size-factor = 1.0

        # Max number of threads to cap factor-based number to
        pool-size-max = 8
      }
    }
  }
}

Note

Setting properties like the listening IP and port number programmatically is best done by using something like the following:

ConfigFactory.parseString("akka.remote.netty.hostname=\"1.2.3.4\"")
    .withFallback(ConfigFactory.load());

Types of Remote Interaction

Akka has two ways of using remoting:

  • Lookup : used to look up an actor on a remote node with actorFor(path)
  • Creation : used to create an actor on a remote node with actorOf(Props(...), actorName)

In the next sections the two alternatives are described in detail.

Looking up Remote Actors

actorFor(path) will obtain an ActorRef to an Actor on a remote node, e.g.:

val actor = context.actorFor("akka://actorSystemName@10.0.0.1:2552/user/actorName")

As you can see from the example above the following pattern is used to find an ActorRef on a remote node:

akka://<actor system>@<hostname>:<port>/<actor path>

Once you obtained a reference to the actor you can interact with it they same way you would with a local actor, e.g.:

actor ! "Pretty awesome feature"

Note

For more details on how actor addresses and paths are formed and used, please refer to Actor References, Paths and Addresses.

Creating Actors Remotely

If you want to use the creation functionality in Akka remoting you have to further amend the application.conf file in the following way (only showing deployment section):

akka {
  actor {
    deployment {
      /sampleActor {
        remote = "akka://sampleActorSystem@127.0.0.1:2553"
      }
    }
  }
}

The configuration above instructs Akka to react when an actor with path /sampleActor is created, i.e. using system.actorOf(Props(...), "sampleActor"). This specific actor will not be directly instantiated, but instead the remote daemon of the remote system will be asked to create the actor, which in this sample corresponds to sampleActorSystem@127.0.0.1:2553.

Once you have configured the properties above you would do the following in code:

val actor = system.actorOf(Props[SampleActor], "sampleActor")
actor ! "Pretty slick"

The actor class SampleActor has to be available to the runtimes using it, i.e. the classloader of the actor systems has to have a JAR containing the class.

Note

In order to ensure serializability of Props when passing constructor arguments to the actor being created, do not make the factory an inner class: this will inherently capture a reference to its enclosing object, which in most cases is not serializable. It is best to create a factory method in the companion object of the actor’s class.

Note

You can use asterisks as wildcard matches for the actor paths, so you could specify: /*/sampleActor and that would match all sampleActor on that level in the hierarchy. You can also use wildcard in the last position to match all actors at a certain level: /someParent/*. Non-wildcard matches always have higher priority to match than wildcards, so: /foo/bar is considered more specific than /foo/* and only the highest priority match is used. Please note that it cannot be used to partially match section, like this: /foo*/bar, /f*o/bar etc.

Warning

Caveat: Remote deployment ties both systems together in a tight fashion, where it may become impossible to shut down one system after the other has become unreachable. This is due to a missing feature—which will be part of the clustering support—that hooks up network failure detection with DeathWatch. If you want to avoid this strong coupling, do not remote-deploy but send Props to a remotely looked-up actor and have that create a child, returning the resulting actor reference.

Warning

Caveat: Akka Remoting does not trigger Death Watch for lost connections.

Programmatic Remote Deployment

To allow dynamically deployed systems, it is also possible to include deployment configuration in the Props which are used to create an actor: this information is the equivalent of a deployment section from the configuration file, and if both are given, the external configuration takes precedence.

With these imports:

import akka.actor.{ Props, Deploy, Address, AddressFromURIString }
import akka.remote.RemoteScope

and a remote address like this:

val one = AddressFromURIString("akka://sys@host:1234")
val two = Address("akka", "sys", "host", 1234) // this gives the same

you can advise the system to create a child on that remote node like so:

val ref = system.actorOf(Props[SampleActor].
  withDeploy(Deploy(scope = RemoteScope(address))))

Serialization

When using remoting for actors you must ensure that the props and messages used for those actors are serializable. Failing to do so will cause the system to behave in an unintended way.

For more information please see Serialization (Scala)

Routers with Remote Destinations

It is absolutely feasible to combine remoting with Routing (Scala). This is also done via configuration:

akka {
  actor {
    deployment {
      /serviceA/aggregation {
        router = "round-robin"
        nr-of-instances = 10
        target {
          nodes = ["akka://app@10.0.0.2:2552", "akka://app@10.0.0.3:2552"]
        }
      }
    }
  }
}

This configuration setting will clone the actor “aggregation” 10 times and deploy it evenly distributed across the two given target nodes.

Description of the Remoting Sample

There is a more extensive remote example that comes with the Akka distribution. Please have a look here for more information: Remote Sample This sample demonstrates both, remote deployment and look-up of remote actors. First, let us have a look at the common setup for both scenarios (this is common.conf):

akka {

  actor {
    provider = "akka.remote.RemoteActorRefProvider"
  }

  remote {
    netty {
      hostname = "127.0.0.1"
    }
  }
}

This enables the remoting by installing the RemoteActorRefProvider and chooses the default remote transport. All other options will be set specifically for each show case.

Note

Be sure to replace the default IP 127.0.0.1 with the real address the system is reachable by if you deploy onto multiple machines!

Remote Lookup

In order to look up a remote actor, that one must be created first. For this purpose, we configure an actor system to listen on port 2552 (this is a snippet from application.conf):

calculator {
  include "common"

  akka {
    remote.netty.port = 2552
  }
}

Then the actor must be created. For all code which follows, assume these imports:

import com.typesafe.config.ConfigFactory
import akka.actor.{ ActorRef, Props, Actor, ActorSystem }

The actor doing the work will be this one:

class SimpleCalculatorActor extends Actor {
  def receive = {
    case Add(n1, n2) 
      println("Calculating %d + %d".format(n1, n2))
      sender ! AddResult(n1, n2, n1 + n2)
    case Subtract(n1, n2) 
      println("Calculating %d - %d".format(n1, n2))
      sender ! SubtractResult(n1, n2, n1 - n2)
  }
}

and we start it within an actor system using the above configuration

val system = ActorSystem("CalculatorApplication",
  ConfigFactory.load.getConfig("calculator"))
val actor = system.actorOf(Props[SimpleCalculatorActor], "simpleCalculator")

With the service actor up and running, we may look it up from another actor system, which will be configured to use port 2553 (this is a snippet from application.conf).

remotelookup {
  include "common"

  akka {
    remote.netty.port = 2553
  }
}

The actor which will query the calculator is a quite simple one for demonstration purposes

class LookupActor extends Actor {
  def receive = {
    case (actor: ActorRef, op: MathOp)  actor ! op
    case result: MathResult  result match {
      case AddResult(n1, n2, r) 
        println("Add result: %d + %d = %d".format(n1, n2, r))
      case SubtractResult(n1, n2, r) 
        println("Sub result: %d - %d = %d".format(n1, n2, r))
    }
  }
}

and it is created from an actor system using the aforementioned client’s config.

val system =
  ActorSystem("LookupApplication", ConfigFactory.load.getConfig("remotelookup"))
val actor = system.actorOf(Props[LookupActor], "lookupActor")
val remoteActor = system.actorFor(
  "akka://CalculatorApplication@127.0.0.1:2552/user/simpleCalculator")

def doSomething(op: MathOp) = {
  actor ! (remoteActor, op)
}

Requests which come in via doSomething will be sent to the client actor along with the reference which was looked up earlier. Observe how the actor system name using in actorFor matches the remote system’s name, as do IP and port number. Top-level actors are always created below the "/user" guardian, which supervises them.

Remote Deployment

Creating remote actors instead of looking them up is not visible in the source code, only in the configuration file. This section is used in this scenario (this is a snippet from application.conf):

remotecreation {
  include "common"

  akka {
    actor {
      deployment {
        /advancedCalculator {
          remote = "akka://CalculatorApplication@127.0.0.1:2552"
        }
      }
    }

    remote.netty.port = 2554
  }
}

For all code which follows, assume these imports:

import com.typesafe.config.ConfigFactory
import akka.actor.{ ActorRef, Props, Actor, ActorSystem }

The client actor looks like in the previous example

class CreationActor extends Actor {
  def receive = {
    case (actor: ActorRef, op: MathOp)  actor ! op
    case result: MathResult  result match {
      case MultiplicationResult(n1, n2, r) 
        println("Mul result: %d * %d = %d".format(n1, n2, r))
      case DivisionResult(n1, n2, r) 
        println("Div result: %.0f / %d = %.2f".format(n1, n2, r))
    }
  }
}

but the setup uses only actorOf:

val system =
  ActorSystem("RemoteCreation", ConfigFactory.load.getConfig("remotecreation"))
val localActor = system.actorOf(Props[CreationActor], "creationActor")
val remoteActor =
  system.actorOf(Props[AdvancedCalculatorActor], "advancedCalculator")

def doSomething(op: MathOp) = {
  localActor ! (remoteActor, op)
}

Observe how the name of the server actor matches the deployment given in the configuration file, which will transparently delegate the actor creation to the remote node.

Remote Events

It is possible to listen to events that occur in Akka Remote, and to subscribe/unsubscribe to there events, you simply register as listener to the below described types in on the ActorSystem.eventStream.

Note

To subscribe to any outbound-related events, subscribe to RemoteClientLifeCycleEvent To subscribe to any inbound-related events, subscribe to RemoteServerLifeCycleEvent To subscribe to any remote events, subscribe to RemoteLifeCycleEvent

By default an event listener is registered which logs all of the events described below. This default was chosen to help setting up a system, but it is quite common to switch this logging off once that phase of the project is finished.

Note

In order to switch off the logging, set akka.remote.log-remote-lifecycle-events = off in your application.conf.

To intercept when an outbound connection is disconnected, you listen to RemoteClientDisconnected which holds the transport used (RemoteTransport) and the outbound address that was disconnected (Address).

To intercept when an outbound connection is connected, you listen to RemoteClientConnected which holds the transport used (RemoteTransport) and the outbound address that was connected to (Address).

To intercept when an outbound client is started you listen to RemoteClientStarted which holds the transport used (RemoteTransport) and the outbound address that it is connected to (Address).

To intercept when an outbound client is shut down you listen to RemoteClientShutdown which holds the transport used (RemoteTransport) and the outbound address that it was connected to (Address).

For general outbound-related errors, that do not classify as any of the others, you can listen to RemoteClientError, which holds the cause (Throwable), the transport used (RemoteTransport) and the outbound address (Address).

To intercept when an inbound server is started (typically only once) you listen to RemoteServerStarted which holds the transport that it will use (RemoteTransport).

To intercept when an inbound server is shut down (typically only once) you listen to RemoteServerShutdown which holds the transport that it used (RemoteTransport).

To intercept when an inbound connection has been established you listen to RemoteServerClientConnected which holds the transport used (RemoteTransport) and optionally the address that connected (Option[Address]).

To intercept when an inbound connection has been disconnected you listen to RemoteServerClientDisconnected which holds the transport used (RemoteTransport) and optionally the address that disconnected (Option[Address]).

To intercept when an inbound remote client has been closed you listen to RemoteServerClientClosed which holds the transport used (RemoteTransport) and optionally the address of the remote client that was closed (Option[Address]).

Remote Security

Akka provides a couple of ways to enhance security between remote nodes (client/server):

  • Untrusted Mode
  • Security Cookie Handshake

Untrusted Mode

As soon as an actor system can connect to another remotely, it may in principle send any possible message to any actor contained within that remote system. One example may be sending a PoisonPill to the system guardian, shutting that system down. This is not always desired, and it can be disabled with the following setting:

akka.remote.untrusted-mode = on

This disallows sending of system messages (actor life-cycle commands, DeathWatch, etc.) and any message extending PossiblyHarmful to the system on which this flag is set. Should a client send them nonetheless they are dropped and logged (at DEBUG level in order to reduce the possibilities for a denial of service attack). PossiblyHarmful covers the predefined messages like PoisonPill and Kill, but it can also be added as a marker trait to user-defined messages.

In summary, the following operations are ignored by a system configured in untrusted mode when incoming via the remoting layer:

  • remote deployment (which also means no remote supervision)
  • remote DeathWatch
  • system.stop(), PoisonPill, Kill
  • sending any message which extends from the PossiblyHarmful marker interface, which includes Terminated

Note

Enabling the untrusted mode does not remove the capability of the client to freely choose the target of its message sends, which means that messages not prohibited by the above rules can be sent to any actor in the remote system. It is good practice for a client-facing system to only contain a well-defined set of entry point actors, which then forward requests (possibly after performing validation) to another actor system containing the actual worker actors. If messaging between these two server-side systems is done using local ActorRef (they can be exchanged safely between actor systems within the same JVM), you can restrict the messages on this interface by marking them PossiblyHarmful so that a client cannot forge them.

SSL

SSL can be used for the remote transport by activating the akka.remote.netty.ssl configuration section. See description of the settings in the Remote Configuration.

The SSL support is implemented with Java Secure Socket Extension, please consult the offical Java Secure Socket Extension documentation and related resources for troubleshooting.

Note

When using SHA1PRNG on Linux it's recommended specify -Djava.security.egd=file:/dev/./urandom as argument to the JVM to prevent blocking. It is NOT as secure because it reuses the seed. Use '/dev/./urandom', not '/dev/urandom' as that doesn't work according to Bug ID: 6202721.

Contents