+doc document how to disable java serialization (#21601)

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 <https://github.com/real-logic/Aeron>`_ instead of TCP
+* Based on `Aeron <https://github.com/real-logic/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 <remote-bytebuffer-serialization-scala>` 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
 --------------------------------

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) <remoting-artery-scala>` 
+
+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 <remote-bytebuffer-serialization-scala>` 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
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 

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.