diff --git a/akka-actor/src/main/resources/reference.conf b/akka-actor/src/main/resources/reference.conf index 0704cccc03..9a56dcbe2d 100644 --- a/akka-actor/src/main/resources/reference.conf +++ b/akka-actor/src/main/resources/reference.conf @@ -586,16 +586,15 @@ akka { "java.io.Serializable" = java } - # 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 = off + # Set this to off to disable serialization-bindings define in + # additional-serialization-bindings. That should only be needed + # for backwards compatibility reasons. + enable-additional-serialization-bindings = on # Additional serialization-bindings that are replacing Java serialization are - # defined in this section and not included by default for backwards compatibility - # reasons. They can be enabled with enable-additional-serialization-bindings=on. - # They are enabled by default if akka.remote.artery.enabled=on. + # defined in this section for backwards compatibility reasons. They are included + # by default but can be excluded for backwards compatibility with Akka 2.4.x. + # They can be disabled with enable-additional-serialization-bindings=off. additional-serialization-bindings { } diff --git a/akka-distributed-data/src/test/scala/akka/cluster/ddata/protobuf/ReplicatedDataSerializerSpec.scala b/akka-distributed-data/src/test/scala/akka/cluster/ddata/protobuf/ReplicatedDataSerializerSpec.scala index e152d2c5b0..8af0e963c2 100644 --- a/akka-distributed-data/src/test/scala/akka/cluster/ddata/protobuf/ReplicatedDataSerializerSpec.scala +++ b/akka-distributed-data/src/test/scala/akka/cluster/ddata/protobuf/ReplicatedDataSerializerSpec.scala @@ -24,7 +24,6 @@ class ReplicatedDataSerializerSpec extends TestKit(ActorSystem( akka.actor.provider=cluster akka.remote.netty.tcp.port=0 akka.remote.artery.canonical.port = 0 - akka.actor.enable-additional-serialization-bindings=on """))) with WordSpecLike with Matchers with BeforeAndAfterAll { val serializer = new ReplicatedDataSerializer(system.asInstanceOf[ExtendedActorSystem]) diff --git a/akka-docs/rst/java/remoting-artery.rst b/akka-docs/rst/java/remoting-artery.rst index 3b206a2b89..2b943b586d 100644 --- a/akka-docs/rst/java/remoting-artery.rst +++ b/akka-docs/rst/java/remoting-artery.rst @@ -444,15 +444,16 @@ Note that the array based methods can be implemented by delegation like this: Disabling the Java Serializer ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -With Artery it is possible to completely disable Java Serialization for the entire Actor system. +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"). + +Akka internals do not rely on Java serialization (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. + 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. diff --git a/akka-docs/rst/java/remoting.rst b/akka-docs/rst/java/remoting.rst index 20c9132ee1..ac41e65cc1 100644 --- a/akka-docs/rst/java/remoting.rst +++ b/akka-docs/rst/java/remoting.rst @@ -281,47 +281,21 @@ For more information please see :ref:`serialization-java`. Disabling the Java Serializer ----------------------------- -Since the ``2.4.11`` release of Akka it is possible to entirely disable the default Java Serialization mechanism. -Please note that :ref:`new remoting implementation (codename Artery) ` does not use Java -serialization for internal messages by default. For compatibility reasons, the current remoting still uses Java -serialization for some classes, however you can disable it in this remoting implementation as well by following -the steps below. - -The first step is to enable some additional serializers that replace previous Java serialization of some internal -messages. This is recommended also when you can't disable Java serialization completely. Those serializers are -enabled with this configuration: - -.. 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-java` these serializers are enabled by default. - -.. 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. +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 (one exception being ``java.lang.Throwable``). + +Akka internals do not rely on Java serialization (exceptions to that being ``java.lang.Throwable`` and "remote deployment"). .. note:: - When using the new remoting implementation (codename Artery), Akka does not use Java Serialization for any of it's internal messages. + 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. + +For user messages, the default serializer, implemented using Java serialization, remains available and enabled by default. 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 diff --git a/akka-docs/rst/project/migration-guide-2.4.x-2.5.x.rst b/akka-docs/rst/project/migration-guide-2.4.x-2.5.x.rst index 24834bae94..60067d89a9 100644 --- a/akka-docs/rst/project/migration-guide-2.4.x-2.5.x.rst +++ b/akka-docs/rst/project/migration-guide-2.4.x-2.5.x.rst @@ -283,6 +283,28 @@ It is still possible to make a rolling upgrade from a version < 2.4.12 by doing For more information see the documentation for the ``akka.remote.netty.ssl.require-mutual-authentication`` configuration setting in :ref:`akka-remote's reference.conf `. +additional-serialization-bindings +--------------------------------- + +From Akka 2.5.0 the ``additional-serialization-bindings`` are enabled by default. That defines +serializers that are replacing some Java serialization that were used in 2.4. This setting was disabled +by default in Akka 2.4.16 but can also be enabled in an Akka 2.4 system. + +To still be able to support rolling upgrade from a system with this setting disabled, e.g. default for 2.4.16, +it is possible to disable the additional serializers and continue using Java serialization for those messages. + +.. code-block:: ruby + + akka.actor { + # Set this to off to disable serialization-bindings define in + # additional-serialization-bindings. That should only be needed + # for backwards compatibility reasons. + enable-additional-serialization-bindings = off + } + +Please note that this setting must be the same on all nodes participating in a cluster, otherwise +the mis-aligned serialization configurations will cause deserialization errors on the receiving nodes. + Cluster ======= diff --git a/akka-docs/rst/scala/remoting-artery.rst b/akka-docs/rst/scala/remoting-artery.rst index eadeb38996..47fe8bcf01 100644 --- a/akka-docs/rst/scala/remoting-artery.rst +++ b/akka-docs/rst/scala/remoting-artery.rst @@ -444,15 +444,16 @@ Note that the array based methods can be implemented by delegation like this: Disabling the Java Serializer ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -With Artery it is possible to completely disable Java Serialization for the entire Actor system. +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"). + +Akka internals do not rely on Java serialization (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. + 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. diff --git a/akka-docs/rst/scala/remoting.rst b/akka-docs/rst/scala/remoting.rst index 1a7a0f92e7..63389b0952 100644 --- a/akka-docs/rst/scala/remoting.rst +++ b/akka-docs/rst/scala/remoting.rst @@ -287,47 +287,21 @@ 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. -Please note that :ref:`new remoting implementation (codename Artery) ` does not use Java -serialization for internal messages by default. For compatibility reasons, the current remoting still uses Java -serialization for some classes, however you can disable it in this remoting implementation as well by following -the steps below. - -The first step is to enable some additional serializers that replace previous Java serialization of some internal -messages. This is recommended also when you can't disable Java serialization completely. Those serializers are -enabled with this configuration: - -.. 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. - -.. 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. +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 (one exception being ``java.lang.Throwable``). + +Akka internals do not rely on Java serialization (exceptions to that being ``java.lang.Throwable`` and "remote deployment"). .. note:: - When using the new remoting implementation (codename Artery), Akka does not use Java Serialization for any of it's internal messages. + 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. + +For user messages, the default serializer, implemented using Java serialization, remains available and enabled by default. 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 diff --git a/akka-remote/src/main/resources/reference.conf b/akka-remote/src/main/resources/reference.conf index 67192f720e..fbbd459a48 100644 --- a/akka-remote/src/main/resources/reference.conf +++ b/akka-remote/src/main/resources/reference.conf @@ -51,9 +51,10 @@ akka { "java.util.Optional" = akka-misc } - # For the purpose of preserving protocol backward compatibility these bindings are not - # included by default. They can be enabled with enable-additional-serialization-bindings=on. - # They are enabled by default if akka.remote.artery.enabled=on. + # Additional serialization-bindings that are replacing Java serialization are + # defined in this section for backwards compatibility reasons. They are included + # by default but can be excluded for backwards compatibility with Akka 2.4.x. + # They can be disabled with enable-additional-serialization-bindings=off. additional-serialization-bindings { "akka.actor.Identify" = akka-misc "akka.actor.ActorIdentity" = akka-misc diff --git a/akka-remote/src/test/scala/akka/remote/serialization/MiscMessageSerializerSpec.scala b/akka-remote/src/test/scala/akka/remote/serialization/MiscMessageSerializerSpec.scala index 2354bd728c..21bd10f43d 100644 --- a/akka-remote/src/test/scala/akka/remote/serialization/MiscMessageSerializerSpec.scala +++ b/akka-remote/src/test/scala/akka/remote/serialization/MiscMessageSerializerSpec.scala @@ -17,10 +17,6 @@ import java.io.NotSerializableException object MiscMessageSerializerSpec { val serializationTestOverrides = """ - akka.actor.enable-additional-serialization-bindings=on - # or they can be enabled with - # akka.remote.artery.enabled=on - akka.actor.serialization-bindings { "akka.remote.serialization.MiscMessageSerializerSpec$TestException" = akka-misc } diff --git a/akka-remote/src/test/scala/akka/remote/serialization/PrimitivesSerializationSpec.scala b/akka-remote/src/test/scala/akka/remote/serialization/PrimitivesSerializationSpec.scala index 6050f0be13..c47d3e8394 100644 --- a/akka-remote/src/test/scala/akka/remote/serialization/PrimitivesSerializationSpec.scala +++ b/akka-remote/src/test/scala/akka/remote/serialization/PrimitivesSerializationSpec.scala @@ -16,9 +16,6 @@ import scala.util.Random object PrimitivesSerializationSpec { val serializationTestOverrides = """ - akka.actor.enable-additional-serialization-bindings=on - # or they can be enabled with - # akka.remote.artery.enabled=on """ val testConfig = ConfigFactory.parseString(serializationTestOverrides).withFallback(AkkaSpec.testConf) @@ -96,8 +93,7 @@ class PrimitivesSerializationSpec extends AkkaSpec(PrimitivesSerializationSpec.t "empty string" → "", "hello" → "hello", "árvíztűrőütvefúrógép" → "árvíztűrőütvefúrógép", - "random" → random - ).foreach { + "random" → random).foreach { case (scenario, item) ⇒ s"resolve serializer for [$scenario]" in { val serializer = SerializationExtension(system) @@ -132,8 +128,7 @@ class PrimitivesSerializationSpec extends AkkaSpec(PrimitivesSerializationSpec.t "empty string" → ByteString.empty, "simple content" → ByteString("hello"), "concatenated content" → (ByteString("hello") ++ ByteString("world")), - "sliced content" → ByteString("helloabc").take(5) - ).foreach { + "sliced content" → ByteString("helloabc").take(5)).foreach { case (scenario, item) ⇒ s"resolve serializer for [$scenario]" in { val serializer = SerializationExtension(system) diff --git a/akka-remote/src/test/scala/akka/remote/serialization/SystemMessageSerializationSpec.scala b/akka-remote/src/test/scala/akka/remote/serialization/SystemMessageSerializationSpec.scala index ad30a23327..c71c844a9a 100644 --- a/akka-remote/src/test/scala/akka/remote/serialization/SystemMessageSerializationSpec.scala +++ b/akka-remote/src/test/scala/akka/remote/serialization/SystemMessageSerializationSpec.scala @@ -10,9 +10,6 @@ import com.typesafe.config.ConfigFactory object SystemMessageSerializationSpec { val serializationTestOverrides = """ - akka.actor.enable-additional-serialization-bindings=on - # or they can be enabled with - # akka.remote.artery.enabled=on """ val testConfig = ConfigFactory.parseString(serializationTestOverrides).withFallback(AkkaSpec.testConf) @@ -43,8 +40,7 @@ class SystemMessageSerializationSpec extends AkkaSpec(PrimitivesSerializationSpe "Unwatch(ref, ref)" → Unwatch(testRef, testRef2), "Failed(ref, ex, uid)" → Failed(testRef, new TestException("test4"), 42), "DeathWatchNotification(ref, confimed, addressTerminated)" → - DeathWatchNotification(testRef, existenceConfirmed = true, addressTerminated = true) - ).foreach { + DeathWatchNotification(testRef, existenceConfirmed = true, addressTerminated = true)).foreach { case (scenario, item) ⇒ s"resolve serializer for [$scenario]" in { val serializer = SerializationExtension(system)