Classic Remoting (Deprecated)

Module info

To use Pekko Remoting, you must add the following dependency in your project:

sbt

val PekkoVersion = "1.0.0"
libraryDependencies += "org.apache.pekko" %% "pekko-remote" % PekkoVersion

Maven

<properties>
  <scala.binary.version>2.13</scala.binary.version>
</properties>
<dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>org.apache.pekko</groupId>
      <artifactId>pekko-bom_${scala.binary.version}</artifactId>
      <version>1.0.0</version>
      <type>pom</type>
      <scope>import</scope>
    </dependency>
  </dependencies>
</dependencyManagement>
<dependencies>
  <dependency>
    <groupId>org.apache.pekko</groupId>
    <artifactId>pekko-remote_${scala.binary.version}</artifactId>
  </dependency>
</dependencies>

Gradle

def versions = [
  ScalaBinary: "2.13"
]
dependencies {
  implementation platform("org.apache.pekko:pekko-bom_${versions.ScalaBinary}:1.0.0")

  implementation "org.apache.pekko:pekko-remote_${versions.ScalaBinary}"
}

Classic remoting depends on Netty. This needs to be explicitly added as a dependency so that users not using classic remoting do not have to have Netty on the classpath:

sbt

libraryDependencies += "io.netty" % "netty" % "3.10.6.Final"

Maven

<dependencies>
  <dependency>
    <groupId>io.netty</groupId>
    <artifactId>netty</artifactId>
    <version>3.10.6.Final</version>
  </dependency>
</dependencies>

Gradle

dependencies {
  implementation "io.netty:netty:3.10.6.Final"
}

Configuration

To enable classic remoting in your Pekko project you should, at a minimum, add the following changes to your application.conf file:

pekko {
  actor {
    # provider=remote is possible, but prefer cluster
    provider = cluster
  }
  remote.artery.enabled = false
  remote.classic {
    enabled-transports = ["pekko.remote.classic.netty.tcp"]
    netty.tcp {
      hostname = "127.0.0.1"
      port = 7355
    }
 }
}

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

• Change provider from local. We recommend using Pekko Cluster over using remoting directly.
• Disable artery remoting. Artery is the default remoting implementation in Apache Pekko.
• 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

The example above only illustrates the bare minimum of properties you have to add to enable remoting. All settings are described in Remote Configuration.

Introduction

We recommend Pekko Cluster over using remoting directly. As remoting is the underlying module that allows for Cluster, it is still useful to understand details about it though.

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

You need to enable serialization for your actor messages. Serialization with Jackson is a good choice in many cases and our recommendation if you don’t have other preference.

Types of Remote Interaction

Pekko has two ways of using remoting:

• Lookup : used to look up an actor on a remote node with actorSelection(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

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

Scala

val selection =
  context.actorSelection("pekko.tcp://actorSystemName@10.0.0.1:7355/user/actorName")

Java

ActorSelection selection =
  context.actorSelection("pekko.tcp://app@10.0.0.1:7355/user/serviceA/worker");

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

pekko.<protocol>://<actor system name>@<hostname>:<port>/<actor path>

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

Scala

selection ! "Pretty awesome feature"

Java

selection.tell("Pretty awesome feature", getSelf());

To acquire an ActorRef for an ActorSelection you need to send a message to the selection and use the sender reference of the reply from the actor. There is a built-in Identify message that all Actors will understand and automatically reply to with a ActorIdentity message containing the ActorRef. This can also be done with the resolveOne method of the ActorSelection, which returns a FutureCompletionStage of the matching ActorRef.

Creating Actors Remotely

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

pekko {
  actor {
    deployment {
      /sampleActor {
        remote = "pekko.tcp://sampleActorSystem@127.0.0.1:7356"
      }
    }
  }
}

The configuration above instructs Pekko to react when an actor with path /sampleActor is created, i.e. using system.actorOf(Props(...), "sampleActor")system.actorOf(new 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:7356.

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

Scala

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

Java

copysource
ActorRef actor = system.actorOf(Props.create(SampleActor.class), "sampleActor");
actor.tell("Pretty slick", ActorRef.noSender());

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.

When using remote deployment of actors you must ensure that all parameters of the Props can be serialized.

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:

Scala

copysourceimport org.apache.pekko
import pekko.actor.{ Address, AddressFromURIString, Deploy, Props }
import pekko.remote.RemoteScope

Java

copysourceimport org.apache.pekko.actor.ActorRef;
import org.apache.pekko.actor.Address;
import org.apache.pekko.actor.AddressFromURIString;
import org.apache.pekko.actor.Deploy;
import org.apache.pekko.actor.Props;
import org.apache.pekko.actor.ActorSystem;
import org.apache.pekko.remote.RemoteScope;

and a remote address like this:

Scala

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

Java

copysourceAddress addr = new Address("pekko", "sys", "host", 1234);
addr = AddressFromURIString.parse("pekko://sys@host:1234"); // the same

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

Scala

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

Java

copysourceProps props = Props.create(SampleActor.class).withDeploy(new Deploy(new RemoteScope(addr)));
ActorRef ref = system.actorOf(props);

Remote deployment allow list

As remote deployment can potentially be abused by both users and even attackers an allow list feature is available to guard the ActorSystem from deploying unexpected actors. Please note that remote deployment is not remote code loading, the Actors class to be deployed onto a remote system needs to be present on that remote system. This still however may pose a security risk, and one may want to restrict remote deployment to only a specific set of known actors by enabling the allow list feature.

To enable remote deployment allow list set the pekko.remote.deployment.enable-allow-list value to on. The list of allowed classes has to be configured on the “remote” system, in other words on the system onto which others will be attempting to remote deploy Actors. That system, locally, knows best which Actors it should or should not allow others to remote deploy onto it. The full settings section may for example look like this:

copysourcepekko.remote.deployment {
  enable-allow-list = on
  
  allowed-actor-classes = [
    "NOT_ON_CLASSPATH", # verify we don't throw if a class not on classpath is listed here
    "org.apache.pekko.remote.classic.RemoteDeploymentAllowListSpec.EchoAllowed"
  ]
}

Actor classes not included in the allow list will not be allowed to be remote deployed onto this system.

Lifecycle and Failure Recovery Model

Each link with a remote system can be in one of the four states as illustrated above. Before any communication happens with a remote system at a given Address the state of the association is Idle. The first time a message is attempted to be sent to the remote system or an inbound connection is accepted the state of the link transitions to Active denoting that the two systems has messages to send or receive and no failures were encountered so far. When a communication failure happens and the connection is lost between the two systems the link becomes Gated.

In this state the system will not attempt to connect to the remote host and all outbound messages will be dropped. The time while the link is in the Gated state is controlled by the setting pekko.remote.retry-gate-closed-for: after this time elapses the link state transitions to Idle again. Gate is one-sided in the sense that whenever a successful inbound connection is accepted from a remote system during Gate it automatically transitions to Active and communication resumes immediately.

In the face of communication failures that are unrecoverable because the state of the participating systems are inconsistent, the remote system becomes Quarantined. Unlike Gate, quarantining is permanent and lasts until one of the systems is restarted. After a restart communication can be resumed again and the link can become Active again.

Watching Remote Actors

Watching a remote actor is not different than watching a local actor, as described in Lifecycle Monitoring aka DeathWatch.

Failure Detector

Please see:

• Phi Accrual Failure Detector implementation for details
• Using the Failure Detector below for usage

Using the Failure Detector

Remoting uses the org.apache.pekko.remote.PhiAccrualFailureDetector failure detector by default, or you can provide your by implementing the org.apache.pekko.remote.FailureDetector and configuring it:

pekko.remote.watch-failure-detector.implementation-class = "com.example.CustomFailureDetector"

In the Remote Configuration you may want to adjust these depending on you environment:

• When a phi value is considered to be a failure pekko.remote.watch-failure-detector.threshold
• Margin of error for sudden abnormalities pekko.remote.watch-failure-detector.acceptable-heartbeat-pause

Serialization

You need to enable serialization for your actor messages. Serialization with Jackson is a good choice in many cases and our recommendation if you don’t have other preference.

Routers with Remote Destinations

It is absolutely feasible to combine remoting with Routing.

A pool of remote deployed routees can be configured as:

copysourcepekko.actor.deployment {
  /parent/remotePool {
    router = round-robin-pool
    nr-of-instances = 10
    target.nodes = ["pekko://app@10.0.0.2:7355", "pekko://app@10.0.0.3:7355"]
  }
}

This configuration setting will clone the actor defined in the Props of the remotePool 10 times and deploy it evenly distributed across the two given target nodes.

When using a pool of remote deployed routees you must ensure that all parameters of the Props can be serialized.

A group of remote actors can be configured as:

copysourcepekko.actor.deployment {
  /parent/remoteGroup {
    router = round-robin-group
    routees.paths = [
      "pekko://app@10.0.0.1:7355/user/workers/w1",
      "pekko://app@10.0.0.2:7355/user/workers/w1",
      "pekko://app@10.0.0.3:7355/user/workers/w1"]
  }
}

This configuration setting will send messages to the defined remote actor paths. It requires that you create the destination actors on the remote nodes with matching paths. That is not done by the router.

Remote Events

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

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.

To be notified when an association is over (“disconnected”) listen to DisassociatedEvent which holds the direction of the association (inbound or outbound) and the addresses of the involved parties.

To be notified when an association is successfully established (“connected”) listen to AssociatedEvent which holds the direction of the association (inbound or outbound) and the addresses of the involved parties.

To intercept errors directly related to associations, listen to AssociationErrorEvent which holds the direction of the association (inbound or outbound), the addresses of the involved parties and the Throwable cause.

To be notified when the remoting subsystem is ready to accept associations, listen to RemotingListenEvent which contains the addresses the remoting listens on.

To be notified when the current system is quarantined by the remote system, listen to ThisActorSystemQuarantinedEvent, which includes the addresses of local and remote ActorSystems.

To be notified when the remoting subsystem has been shut down, listen to RemotingShutdownEvent.

To intercept generic remoting related errors, listen to RemotingErrorEvent which holds the Throwable cause.

Remote Security

An ActorSystem should not be exposed via Pekko Remote over plain TCP to an untrusted network (e.g. Internet). It should be protected by network security, such as a firewall. If that is not considered as enough protection TLS with mutual authentication should be enabled.

Best practice is that Pekko remoting nodes should only be accessible from the adjacent network. Note that if TLS is enabled with mutual authentication there is still a risk that an attacker can gain access to a valid certificate by compromising any node with certificates issued by the same internal PKI tree.

By default, Java serialization is disabled in Pekko. That is also security best-practice because of its multiple known attack surfaces.

Configuring SSL/TLS for Pekko Remoting

SSL can be used as the remote transport by adding pekko.remote.classic.netty.ssl to the enabled-transport configuration section. An example of setting up the default Netty based SSL driver as default:

pekko {
  remote.classic {
    enabled-transports = [pekko.remote.classic.netty.ssl]
  }
}

Next the actual SSL/TLS parameters have to be configured:

pekko {
  remote.classic {
    netty.ssl {
      hostname = "127.0.0.1"
      port = "3553"

      security {
        key-store = "/example/path/to/mykeystore.jks"
        trust-store = "/example/path/to/mytruststore.jks"

        key-store-password = ${SSL_KEY_STORE_PASSWORD}
        key-password = ${SSL_KEY_PASSWORD}
        trust-store-password = ${SSL_TRUST_STORE_PASSWORD}

        protocol = "TLSv1.2"

        enabled-algorithms = [TLS_DHE_RSA_WITH_AES_128_GCM_SHA256]
      }
    }
  }
}

Always use substitution from environment variables for passwords. Don’t define real passwords in config files.

According to RFC 7525 the recommended algorithms to use with TLS 1.2 (as of writing this document) are:

• TLS_DHE_RSA_WITH_AES_128_GCM_SHA256
• TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
• TLS_DHE_RSA_WITH_AES_256_GCM_SHA384
• TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384

You should always check the latest information about security and algorithm recommendations though before you configure your system.

Since a Pekko remoting is inherently peer-to-peer both the key-store as well as trust-store need to be configured on each remoting node participating in the cluster.

The official Java Secure Socket Extension documentation as well as the Oracle documentation on creating KeyStore and TrustStores are both great resources to research when setting up security on the JVM. Please consult those resources when troubleshooting and configuring SSL.

Mutual authentication between TLS peers is enabled by default.

Mutual authentication means that the passive side (the TLS server side) of a connection will also request and verify a certificate from the connecting peer. Without this mode only the client side is requesting and verifying certificates. While Pekko is a peer-to-peer technology, each connection between nodes starts out from one side (the “client”) towards the other (the “server”).

Note that if TLS is enabled with mutual authentication there is still a risk that an attacker can gain access to a valid certificate by compromising any node with certificates issued by the same internal PKI tree.

See also a description of the settings in the Remote Configuration section.

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:

pekko.remote.classic.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.

Messages sent with actor selection are by default discarded in untrusted mode, but permission to receive actor selection messages can be granted to specific actors defined in configuration:

pekko.remote.classic.trusted-selection-paths = ["/user/receptionist", "/user/namingService"]

The actual message must still not be of type PossiblyHarmful.

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
• messages sent with actor selection, unless destination defined in trusted-selection-paths.

Remote Configuration

There are lots of configuration properties that are related to remoting in Pekko. We refer to the reference configuration for more information.

copysourceConfigFactory.parseString("pekko.remote.classic.netty.tcp.hostname=\"1.2.3.4\"")
    .withFallback(ConfigFactory.load());

Pekko behind NAT or in a Docker container

In setups involving Network Address Translation (NAT), Load Balancers or Docker containers the hostname and port pair that Pekko binds to will be different than the “logical” host name and port pair that is used to connect to the system from the outside. This requires special configuration that sets both the logical and the bind pairs for remoting.

pekko.remote.classic.netty.tcp {
      hostname = my.domain.com      # external (logical) hostname
      port = 8000                   # external (logical) port

      bind-hostname = local.address # internal (bind) hostname
      bind-port = 7355              # internal (bind) port
}

Keep in mind that local.address will most likely be in one of private network ranges:

• 10.0.0.0 - 10.255.255.255 (network class A)
• 172.16.0.0 - 172.31.255.255 (network class B)
• 192.168.0.0 - 192.168.255.255 (network class C)

For further details see RFC 1597 and RFC 1918.