diff --git a/docs/en/installing-xes.asciidoc b/docs/en/installing-xes.asciidoc index 5d4b6953712..5436ac01b87 100644 --- a/docs/en/installing-xes.asciidoc +++ b/docs/en/installing-xes.asciidoc @@ -220,6 +220,8 @@ For more information, see {xpack-ref}/setting-up-authentication.html#set-built-in-user-passwords[Setting Built-in User Passwords]. -- +. Optional: <>. + . {kibana-ref}/installing-xpack-kb.html[Install {xpack} on {kib}]. . {logstash-ref}/installing-xpack-log.html[Install {xpack} on Logstash]. diff --git a/docs/en/security/tribe-clients-integrations/java.asciidoc b/docs/en/security/tribe-clients-integrations/java.asciidoc index 93d911a21fe..e5c622aef91 100644 --- a/docs/en/security/tribe-clients-integrations/java.asciidoc +++ b/docs/en/security/tribe-clients-integrations/java.asciidoc @@ -16,120 +16,21 @@ NOTE: Using the Java Node Client with secured clusters is not recommended or To use the transport client with a secured cluster, you need to: [[java-transport-client-role]] +. <>. + . Configure a user with the privileges required to start the transport client. A default `transport_client` role is built-in to {xpack} that grants the appropriate cluster permissions for the transport client to work with the secured cluster. The transport client uses the _Nodes Info API_ to fetch information about the nodes in the cluster. -. Add the {xpack} transport JAR file to your CLASSPATH. You can download the {xpack} -distribution and extract the JAR file manually or you can get it from the -https://artifacts.elastic.co/maven/org/elasticsearch/client/x-pack-transport/{version}/x-pack-transport-{version}.jar[Elasticsearch Maven repository]. -+ -As with any dependency, you will also need its transitive dependencies. Refer to the -https://artifacts.elastic.co/maven/org/elasticsearch/client/x-pack-transport/{version}/x-pack-transport-{version}.pom[X-Pack POM file -for your version] when downloading for offline usage. --- - -If you are using Maven, you need to add the {xpack} JAR file as a dependency in -your project's `pom.xml` file: - -[source,xml] --------------------------------------------------------------- - - - - - - elasticsearch-releases - https://artifacts.elastic.co/maven - - true - - - false - - - ... - - ... - - - - - org.elasticsearch.client - x-pack-transport - {version} - - ... - - ... - - --------------------------------------------------------------- - -If you are using Gradle, you need to add the {xpack} JAR file as a dependency in -your `build.gradle` file: - -[source,groovy] --------------------------------------------------------------- -repositories { - /* ... Any other repositories ... */ - - // Add the Elasticsearch Maven Repository - maven { - url "https://artifacts.elastic.co/maven" - } -} - -dependencies { - compile "org.elasticsearch.client:x-pack-transport:{version}" - - /* ... */ -} --------------------------------------------------------------- --- - -If you are using a repository manager such as https://www.sonatype.com/nexus-repository-oss[Nexus OSS] within your -company, you need to add the repository as per the following screenshot: - - -image::images/nexus.png["Adding the Elastic repo in Nexus",link="images/nexus.png"] - - -Then in your project's `pom.xml` if using maven, add the following repositories and dependencies definitions: - -[source,xml] --------------------------------------------------------------- - - - org.elasticsearch.client - x-pack-transport - {version} - - - - - - local-nexus - Elastic Local Nexus - http://0.0.0.0:8081/repository/elasticsearch/ - - true - - - false - - - --------------------------------------------------------------- - . Set up the transport client. At a minimum, you must configure `xpack.security.user` to include the name and password of your transport client user in your requests. The following snippet configures the user credentials globally--every request submitted with this client includes the `transport_client_user` credentials in its headers. + +-- [source,java] ------------------------------------------------------------------------------------------------- import org.elasticsearch.xpack.client.PreBuiltXPackTransportClient; @@ -143,20 +44,20 @@ TransportClient client = new PreBuiltXPackTransportClient(Settings.builder() .addTransportAddress(new InetSocketTransportAddress("localhost", 9300)) .addTransportAddress(new InetSocketTransportAddress("localhost", 9301)); ------------------------------------------------------------------------------------------------- -+ + WARNING: If you configure a transport client without SSL, passwords are sent in clear text. -+ + You can also add an `Authorization` header to each request. If you've configured global authorization credentials, the `Authorization` header overrides the global authentication credentials. This is useful when an application has multiple users who access Elasticsearch using the same client. You can set the global token to a user that only has the `transport_client` role, and add the `transport_client` role to the individual users. -+ + For example, the following snippet adds the `Authorization` header to a search request: -+ + [source,java] -------------------------------------------------------------------------------------------------- import org.elasticsearch.common.settings.SecureString; @@ -181,6 +82,7 @@ String token = basicAuthHeaderValue("test_user", new SecureString("x-pack-test-p client.filterWithHeader(Collections.singletonMap("Authorization", token)) .prepareSearch().get(); -------------------------------------------------------------------------------------------------- +-- . Enable SSL to authenticate clients and encrypt communications. To enable SSL, you need to: @@ -188,9 +90,10 @@ you need to: .. Configure the paths to the client's key and certificate in addition to the certificate authorities. Client authentication requires every client to have a certification signed by a trusted CA. + +-- NOTE: Client authentication is enabled by default. For information about disabling client authentication, see <>. -+ + [source,java] -------------------------------------------------------------------------------------------------- import org.elasticsearch.xpack.client.PreBuiltXPackTransportClient; @@ -205,11 +108,12 @@ TransportClient client = new PreBuiltXPackTransportClient(Settings.builder() ... .build()); -------------------------------------------------------------------------------------------------- +-- -+ .. Enable the SSL transport by setting `xpack.security.transport.ssl.enabled` to `true` in the client configuration. + +-- [source,java] -------------------------------------------------------------------------------------------------- import org.elasticsearch.xpack.client.PreBuiltXPackTransportClient; @@ -227,6 +131,7 @@ TransportClient client = new PreBuiltXPackTransportClient(Settings.builder() .addTransportAddress(new InetSocketTransportAddress(InetAddress.getByName("localhost"), 9300)) .addTransportAddress(new InetSocketTransportAddress(InetAddress.getByName("localhost"), 9301)) -------------------------------------------------------------------------------------------------- +-- [float] [[disabling-client-auth]] diff --git a/docs/en/setup-xclient.asciidoc b/docs/en/setup-xclient.asciidoc new file mode 100644 index 00000000000..c1243e84275 --- /dev/null +++ b/docs/en/setup-xclient.asciidoc @@ -0,0 +1,116 @@ +[role="xpack"] +[[setup-xpack-client]] +== Configuring {xpack} Java Clients + +If you want to use a Java {ref}/transport-client.html[transport client] with a +cluster where {xpack} is installed, then you must download and configure the +{xpack} transport client. + +WARNING: The `TransportClient` is aimed to be replaced by the Java High Level REST +Client, which executes HTTP requests instead of serialized Java requests. The +`TransportClient` will be deprecated in upcoming versions of {es}. + +. Add the {xpack} transport JAR file to your *CLASSPATH*. You can download the {xpack} +distribution and extract the JAR file manually or you can get it from the +https://artifacts.elastic.co/maven/org/elasticsearch/client/x-pack-transport/{version}/x-pack-transport-{version}.jar[Elasticsearc Maven repository]. +As with any dependency, you will also need its transitive dependencies. Refer to the +https://artifacts.elastic.co/maven/org/elasticsearch/client/x-pack-transport/{version}/x-pack-transport-{version}.pom[X-Pack POM file +for your version] when downloading for offline usage. + +. If you are using Maven, you need to add the {xpack} JAR file as a dependency in +your project's `pom.xml` file: ++ +-- +[source,xml] +-------------------------------------------------------------- + + + + + elasticsearch-releases + https://artifacts.elastic.co/maven + + true + + + false + + + ... + + ... + + + + + org.elasticsearch.client + x-pack-transport + {version} + + ... + + ... + + +-------------------------------------------------------------- +-- + +. If you are using Gradle, you need to add the {xpack} JAR file as a dependency in +your `build.gradle` file: ++ +-- +[source,groovy] +-------------------------------------------------------------- +repositories { + /* ... Any other repositories ... */ + + // Add the Elasticsearch Maven Repository + maven { + url "https://artifacts.elastic.co/maven" + } +} + +dependencies { + compile "org.elasticsearch.client:x-pack-transport:{version}" + + /* ... */ +} +-------------------------------------------------------------- +-- + +. If you are using a repository manager such as https://www.sonatype.com/nexus-repository-oss[Nexus OSS] within your +company, you need to add the repository as per the following screenshot: ++ +-- +image::security/images/nexus.png["Adding the Elastic repo in Nexus",link="images/nexus.png"] + +Then in your project's `pom.xml` if using maven, add the following repositories and dependencies definitions: + +[source,xml] +-------------------------------------------------------------- + + + org.elasticsearch.client + x-pack-transport + {version} + + + + + + local-nexus + Elastic Local Nexus + http://0.0.0.0:8081/repository/elasticsearch/ + + true + + + false + + + +-------------------------------------------------------------- +-- + +. If you are using {security}, there are more configuration steps. See +{xpack-ref}/java-clients.html[Java Client and Security]. diff --git a/docs/en/setup-xes.asciidoc b/docs/en/setup-xes.asciidoc index a6c9090d118..0fdbf15d0e7 100644 --- a/docs/en/setup-xes.asciidoc +++ b/docs/en/setup-xes.asciidoc @@ -12,3 +12,4 @@ easy-to-install package. To access this functionality, you must include::installing-xes.asciidoc[] include::settings/configuring-xes.asciidoc[] +include::setup-xclient.asciidoc[]