From 9cb7839829ff3d0cfab500992b45ae6afeb77e12 Mon Sep 17 00:00:00 2001 From: Patrik Nordwall Date: Tue, 1 Nov 2016 18:00:29 +0100 Subject: [PATCH] fix enable-additional-serialization-bindings docs (#21769) * the config block was not shown * also fixed several other mistakes --- akka-docs/rst/java/distributed-pub-sub.rst | 2 +- akka-docs/rst/java/remoting.rst | 49 +++++++++++---------- akka-docs/rst/scala/distributed-pub-sub.rst | 2 +- akka-docs/rst/scala/remoting.rst | 49 +++++++++++---------- 4 files changed, 54 insertions(+), 48 deletions(-) diff --git a/akka-docs/rst/java/distributed-pub-sub.rst b/akka-docs/rst/java/distributed-pub-sub.rst index 020f634b55..e73e8bd225 100644 --- a/akka-docs/rst/java/distributed-pub-sub.rst +++ b/akka-docs/rst/java/distributed-pub-sub.rst @@ -182,7 +182,7 @@ and then it takes a while for it to be populated. Delivery Guarantee ------------------ -As in :ref:`message-general-rules` of Akka, message delivery guarantee in distributed pub sub modes is **at-most-once delivery**. +As in :ref:`message-delivery-reliability` of Akka, message delivery guarantee in distributed pub sub modes is **at-most-once delivery**. In other words, messages can be lost over the wire. If you are looking for at-least-once delivery guarantee, we recommend `Kafka Akka Streams integration `_. diff --git a/akka-docs/rst/java/remoting.rst b/akka-docs/rst/java/remoting.rst index 17eceff832..9ea89144ff 100644 --- a/akka-docs/rst/java/remoting.rst +++ b/akka-docs/rst/java/remoting.rst @@ -169,6 +169,7 @@ you can advise the system to create a child on that remote node like so: .. includecode:: code/docs/remoting/RemoteDeploymentDocTest.java#deploy .. _remote-deployment-whitelist-java: + Remote deployment whitelist --------------------------- @@ -286,6 +287,29 @@ serialization for internal messages by default. For compatibility reasons, the c 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. + 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. @@ -319,26 +343,6 @@ your ``application.conf``: 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/ @@ -479,8 +483,7 @@ untrusted mode when incoming via the remoting layer: Configuring SSL/TLS for Akka Remoting ------------------------------------- -SSL can be used as the remote transport by adding ``akka.remote.netty.ssl`` to the ``enabled-transport`` configuration section:: - +SSL can be used as the remote transport by adding ``akka.remote.netty.ssl`` to the ``enabled-transport`` configuration section. An example of setting up the default Netty based SSL driver as default:: akka { @@ -525,7 +528,7 @@ Since an Akka remoting is inherently :ref:`peer-to-peer `_ -as well as the :ref:`Oracle documentation on creating KeyStore and TrustStores ` +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. diff --git a/akka-docs/rst/scala/distributed-pub-sub.rst b/akka-docs/rst/scala/distributed-pub-sub.rst index 1df22e831e..d4723d0a67 100644 --- a/akka-docs/rst/scala/distributed-pub-sub.rst +++ b/akka-docs/rst/scala/distributed-pub-sub.rst @@ -186,7 +186,7 @@ and then it takes a while for it to be populated. Delivery Guarantee ------------------ -As in :ref:`message-general-rules` of Akka, message delivery guarantee in distributed pub sub modes is **at-most-once delivery**. +As in :ref:`message-delivery-reliability` of Akka, message delivery guarantee in distributed pub sub modes is **at-most-once delivery**. In other words, messages can be lost over the wire. If you are looking for at-least-once delivery guarantee, we recommend `Kafka Akka Streams integration `_. diff --git a/akka-docs/rst/scala/remoting.rst b/akka-docs/rst/scala/remoting.rst index 6849c6aac6..1a7a0f92e7 100644 --- a/akka-docs/rst/scala/remoting.rst +++ b/akka-docs/rst/scala/remoting.rst @@ -175,6 +175,7 @@ you can advise the system to create a child on that remote node like so: .. includecode:: code/docs/remoting/RemoteDeploymentDocSpec.scala#deploy .. _remote-deployment-whitelist-scala: + Remote deployment whitelist --------------------------- @@ -292,6 +293,29 @@ serialization for internal messages by default. For compatibility reasons, the c 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. + 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. @@ -325,26 +349,6 @@ your ``application.conf``: 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/ @@ -485,8 +489,7 @@ untrusted mode when incoming via the remoting layer: Configuring SSL/TLS for Akka Remoting ------------------------------------- -SSL can be used as the remote transport by adding ``akka.remote.netty.ssl`` to the ``enabled-transport`` configuration section:: - +SSL can be used as the remote transport by adding ``akka.remote.netty.ssl`` to the ``enabled-transport`` configuration section. An example of setting up the default Netty based SSL driver as default:: akka { @@ -533,7 +536,7 @@ Since an Akka remoting is inherently :ref:`peer-to-peer `_ -as well as the :ref:`Oracle documentation on creating KeyStore and TrustStores ` +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.