diff --git a/akka-docs/rst/scala/remoting-artery.rst b/akka-docs/rst/scala/remoting-artery.rst index cca2dbd575..17b259c270 100644 --- a/akka-docs/rst/scala/remoting-artery.rst +++ b/akka-docs/rst/scala/remoting-artery.rst @@ -7,7 +7,7 @@ Remoting (codename Artery) .. note:: This page describes the experimental remoting subsystem, codenamed *Artery* that will eventually replace the - old remoting implementation. For the current stable remoting system please refer to :ref:`_remoting-scala`. + old remoting implementation. For the current stable remoting system please refer to :ref:`remoting-scala`. Remoting enables Actor systems on different hosts or JVMs to communicate with each other. By enabling remoting the system will start listening on a provided network address and also gains the ability to connect to other @@ -28,7 +28,7 @@ Artery is a reimplementation of the old remoting module aimed at improving perfo backwards compatible with the old implementation and it is a drop-in replacement in many cases. Main features of Artery compared to the previous implementation: -* Based on `Aeron `_ instead of TCP +* Based on `Aeron `_ (UDP) instead of TCP * Focused on high-throughput, low-latency communication * Isolation of internal control messages from user messages improving stability and reducing false failure detection in case of heavy traffic by using a dedicated subchannel. @@ -111,7 +111,12 @@ Acquiring references to remote actors In order to communicate with an actor, it is necessary to have its :class:`ActorRef`. In the local case it is usually the creator of the actor (the caller of ``actorOf()``) is who gets the :class:`ActorRef` for an actor that it can -then send to other actors. Alternatively, an actor can look up another located at a known path using +then send to other actors. In other words: + +* An Actor can get a remote Actor's reference simply by receiving a message from it (as it's available as `sender()` then), + or inside of a remote message (e.g. `PleaseReply(message: String, remoteActorRef: ActorRef)`) + +Alternatively, an actor can look up another located at a known path using :class:`ActorSelection`. These methods are available even in remoting enabled systems: * Remote Lookup : used to look up an actor on a remote node with ``actorSelection(path)`` @@ -404,6 +409,8 @@ those actors are serializable. Failing to do so will cause the system to behave For more information please see :ref:`serialization-scala`. +.. _remote-bytebuffer-serialization-scala: + ByteBuffer based serialization ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -412,7 +419,44 @@ TODO Disabling the Java Serializer ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -TODO +With Artery it is possible to completely disable Java Serialization for the entire Actor system. + +Java serialization is known to be slow and prone to attacks of various kinds - it never was designed for high +throughput messaging after all. However it is very convenient to use, thus it remained the default serialization +mechanism that Akka used to serialize user messages as well as some of its internal messages in previous versions. +Since the release of Artery, Akka internals do not rely on Java serialization anymore (exceptions to that being ``java.lang.Throwable`` and "remote deployment"). + +.. note:: + When using Artery, Akka does not use Java Serialization for any of it's internal messages. + It is highly encouraged to disable java serialization, so please plan to do so at the earliest possibility you have in your project. + + One may think that network bandwidth and latency limit the performance of remote messaging, but serialization is a more typical bottleneck. + +For user messages, the default serializer, implemented using Java serialization, remains available and enabled in Artery. +We do however recommend to disable it entirely and utilise a proper serialization library instead in order effectively utilise +the improved performance and ability for rolling deployments using Artery. Libraries that we recommend to use include, +but are not limited to, `Kryo`_ by using the `akka-kryo-serialization`_ library or `Google Protocol Buffers`_ if you want +more control over the schema evolution of your messages. + +In order to completely disable Java Serialization in your Actor system you need to add the following configuration to +your ``application.conf``: + +.. code-block:: ruby + + akka { + actor { + serialization-bindings { + "java.io.Serializable" = none + } + } + } + +Please note that this means that you will have to configure different serializers which will able to handle all of your +remote messages. Please refer to the :ref:`serialization-scala` documentation as well as :ref:`ByteBuffer based serialization ` to learn how to do this. + +.. _Kryo: https://github.com/EsotericSoftware/kryo +.. _akka-kryo-serialization: https://github.com/romix/akka-kryo-serialization +.. _Google Protocol Buffers: https://developers.google.com/protocol-buffers/ Routers with Remote Destinations -------------------------------- diff --git a/akka-docs/rst/scala/remoting.rst b/akka-docs/rst/scala/remoting.rst index 1184d9f07a..14aa975cb7 100644 --- a/akka-docs/rst/scala/remoting.rst +++ b/akka-docs/rst/scala/remoting.rst @@ -1,8 +1,7 @@ .. _remoting-scala: -########## - Remoting -########## +Remoting +######## For an introduction of remoting capabilities of Akka please see :ref:`remoting`. @@ -265,6 +264,69 @@ those actors are serializable. Failing to do so will cause the system to behave For more information please see :ref:`serialization-scala`. +Disabling the Java Serializer +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Since the ``2.4.11`` release of Akka it is possible to entirely disable the default Java Serialization mechanism. +The :ref:`new remoting implementation (codename Artery) ` + +Java serialization is known to be slow and prone to attacks of various kinds - it never was designed for high +throughput messaging after all. However it is very convenient to use, thus it remained the default serialization +mechanism that Akka used to serialize user messages as well as some of its internal messages in previous versions. +Since the release of Artery, Akka internals do not rely on Java serialization anymore (one exception being ``java.lang.Throwable``). + +.. note:: + When using the new remoting implementation (codename Artery), Akka does not use Java Serialization for any of it's internal messages. + It is highly encouraged to disable java serialization, so please plan to do so at the earliest possibility you have in your project. + + One may think that network bandwidth and latency limit the performance of remote messaging, but serialization is a more typical bottleneck. + +For user messages, the default serializer, implemented using Java serialization, remains available and enabled in Artery. +We do however recommend to disable it entirely and utilise a proper serialization library instead in order effectively utilise +the improved performance and ability for rolling deployments using Artery. Libraries that we recommend to use include, +but are not limited to, `Kryo`_ by using the `akka-kryo-serialization`_ library or `Google Protocol Buffers`_ if you want +more control over the schema evolution of your messages. + +In order to completely disable Java Serialization in your Actor system you need to add the following configuration to +your ``application.conf``: + +.. code-block:: ruby + + akka { + actor { + serialization-bindings { + "java.io.Serializable" = none + } + } + } + +Please note that this means that you will have to configure different serializers which will able to handle all of your +remote messages. Please refer to the :ref:`serialization-scala` documentation as well as :ref:`ByteBuffer based serialization ` to learn how to do this. + +.. warning:: + Please note that when enabling the additional-serialization-bindings when using the old remoting, + you must do so on all nodes participating in a cluster, otherwise the mis-aligned serialization + configurations will cause deserialization errors on the receiving nodes. + +You can also easily enable additional serialization bindings that are provided by Akka that are not using Java serialization: + +.. code-block: ruby + akka.actor { + # Set this to on to enable serialization-bindings define in + # additional-serialization-bindings. Those are by default not included + # for backwards compatibility reasons. They are enabled by default if + # akka.remote.artery.enabled=on. + enable-additional-serialization-bindings = on + } + +The reason these are not enabled by default is wire-level compatibility between any 2.4.x Actor Systems. +If you roll out a new cluster, all on the same Akka version that can enable these serializers it is recommended to +enable this setting. When using :ref:`remoting-artery-scala` these serializers are enabled by default. + +.. _Kryo: https://github.com/EsotericSoftware/kryo +.. _akka-kryo-serialization: https://github.com/romix/akka-kryo-serialization +.. _Google Protocol Buffers: https://developers.google.com/protocol-buffers/ + Routers with Remote Destinations ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/akka-docs/rst/scala/serialization.rst b/akka-docs/rst/scala/serialization.rst index 35f203c06f..b9b518008d 100644 --- a/akka-docs/rst/scala/serialization.rst +++ b/akka-docs/rst/scala/serialization.rst @@ -1,9 +1,8 @@ .. _serialization-scala: -###################### - Serialization -###################### +Serialization +############# Akka has a built-in Extension for serialization, and it is both possible to use the built-in serializers and to write your own.