This is an automated email from the ASF dual-hosted git repository.
namelchev pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/ignite.git
The following commit(s) were added to refs/heads/master by this push:
new d25afaeba7f IGNITE-24430 Added documentation about migration of the
control utility to the thin client protocol (#11856)
d25afaeba7f is described below
commit d25afaeba7fa9c9de54e908060b84bc1c0a70552
Author: Nikita Amelchev <[email protected]>
AuthorDate: Thu Feb 13 17:38:37 2025 +0300
IGNITE-24430 Added documentation about migration of the control utility to
the thin client protocol (#11856)
Co-authored-by: SofiaSedova <[email protected]>
---
docs/_docs/tools/control-script.adoc | 108 +++++++++++++++++++++++++++++++++--
1 file changed, 103 insertions(+), 5 deletions(-)
diff --git a/docs/_docs/tools/control-script.adoc
b/docs/_docs/tools/control-script.adoc
index 4da3b9fdb2e..1186f19e5b5 100644
--- a/docs/_docs/tools/control-script.adoc
+++ b/docs/_docs/tools/control-script.adoc
@@ -36,17 +36,16 @@ control.bat <connection parameters> <command> <arguments>
== Connecting to Cluster
-When executed without connection parameters, the control script tries to
connect to a node running on localhost (`localhost:11211`).
+NOTE: Starting from Apache Ignite version 2.17, the utility by default uses a
connection through the thin client protocol (configured on a node via
`org.apache.ignite.configuration.ClientConnectorConfiguration`). See
link:#migration-to-the-thin-client-protocol[Migration Notes] for more
information.
+
+When executed without connection parameters, the control script tries to
connect to a node running on localhost (`localhost:10800`).
If you want to connect to a node that is running on a remove machine, specify
the connection parameters.
[cols="2,3,1",opts="header"]
|===
|Parameter | Description | Default Value
-
| --host HOST_OR_IP | The host name or IP address of the node. | `localhost`
-
-| --port PORT | The port to connect to. | `11211`
-
+| --port PORT | The port to connect to. | `10800`
| --user USER | The user name. |
| --password PASSWORD |The user password. |
| --ssl-protocol PROTOCOL1, PROTOCOL2... | A list of SSL protocols to try when
connecting to the cluster.
link:https://docs.oracle.com/en/java/javase/11/security/java-security-overview1.html#GUID-FCF419A7-B856-46DD-A36F-C6F88F9AF37F[Supported
protocols,window=_blank]. | `TLS`
@@ -61,6 +60,105 @@ If you want to connect to a node that is running on a
remove machine, specify th
| --ssl-factory SSL_FACTORY_PATH | Custom SSL factory Spring xml file path. |
|===
+== Migration to the thin client protocol
+
+With the default configuration of Ignite, no migration actions will be
required. Additional configuration of the connector is no longer necessary.
+
+If you connect to the wrong connector, you will receive an error and may see
the message:
+
+`Make sure you are connecting to the client connector (configured on a node
via 'org.apache.ignite.configuration.ClientConnectorConfiguration'). Connection
to the REST connector was deprecated and will be removed for the control
utility in future releases. Set up the
'IGNITE_CONTROL_UTILITY_USE_CONNECTOR_CONNECTION' system property to 'true' to
forcefully connect to the REST connector (configured on a node via
'org.apache.ignite.configuration.ConnectorConfiguration').`
+
+To ensure backward compatibility, a system property has been added to provide
the old behavior (note: it will be removed in version 2.18):
+
+[tabs]
+--
+tab:Unix[]
+[source, shell]
+----
+export IGNITE_CONTROL_UTILITY_USE_CONNECTOR_CONNECTION=true;
+control.sh --state --host x.x.x.x --port 11212
+----
+tab:Windows[]
+[source, shell]
+----
+SET IGNITE_CONTROL_UTILITY_USE_CONNECTOR_CONNECTION=true
+control.bat --state --host x.x.x.x --port 11212
+----
+--
+
+In some cases, the following actions may be required to migrate user scripts
using the utility:
+
+=== 1. A custom port is specified:
+
+[tabs]
+--
+tab:Unix[]
+[source, shell]
+----
+control.sh --state --host x.x.x.x --port 11212
+----
+tab:Windows[]
+[source, shell]
+----
+control.bat --state --host x.x.x.x --port 11212
+----
+--
+
+To migrate, specify the port for the thin client connector:
+
+[tabs]
+--
+tab:Unix[]
+[source, shell]
+----
+control.sh --state --host x.x.x.x
+control.sh --state --host x.x.x.x --port 10801
+----
+tab:Windows[]
+[source, shell]
+----
+control.bat --state --host x.x.x.x
+control.bat --state --host x.x.x.x --port 10801
+----
+--
+
+=== 2. A custom SSL factory for the binary REST connector is specified,
different from the SSL factory for the thin client connector:
+
+[tabs]
+--
+tab:Unix[]
+[source, shell]
+----
+control.sh --state --ssl-factory connector-ssl-factory.xml
+----
+tab:Windows[]
+[source, shell]
+----
+control.bat --state --ssl-factory connector-ssl-factory.xml
+----
+--
+
+To migrate, specify the SSL factory for the thin client connector:
+
+[tabs]
+--
+tab:Unix[]
+[source, shell]
+----
+control.sh --state --ssl-factory ignite-ssl-factory.xml
+control.sh --state --ssl-factory client-connector-ssl-factory.xml
+----
+tab:Windows[]
+[source, shell]
+----
+control.bat --state --ssl-factory ignite-ssl-factory.xml
+control.bat --state --ssl-factory client-connector-ssl-factory.xml
+----
+--
+
+=== 3. The client connector is disabled.
+
+Enable it in the configuration
(`IgniteConfiguration#setClientConnectorConfiguration`).
== Activation, Deactivation and Topology Management
