OpenSearch/docs/en/setup/installing-xes.asciidoc

[role="xpack"]
[[installing-xpack-es]]
== Installing X-Pack in Elasticsearch
++++
<titleabbrev>Installing {xpack}</titleabbrev>
++++

After you install {es}, you can optionally obtain and install {xpack}.
For more information about how to obtain {xpack},
see https://www.elastic.co/products/x-pack.

You must run the version of {xpack} that matches the version of {es} you are
running. See the
https://www.elastic.co/support/matrix#matrix_compatibility[Elastic Support Matrix]
for more information about product compatibility.

IMPORTANT: If you are installing {xpack} for the first time on an existing
cluster, you must perform a full cluster restart. Installing {xpack} enables
security and security must be enabled on ALL nodes in a cluster for the cluster
to operate correctly. When upgrading you can usually perform
a {ref}/rolling-upgrades.html[rolling upgrade].

The following diagram provides an overview of the steps that are required to
set up {xpack} on {es}:

image::setup/images/ElasticsearchFlow.jpg[Installation overview on {es}]

To install {xpack} in {es}:

. Optional: If you want to install {xpack} on a machine that doesn't have
internet access:

.. Manually download the {xpack} zip file:
https://artifacts.elastic.co/downloads/packs/x-pack/x-pack-{version}.zip[
+https://artifacts.elastic.co/downloads/packs/x-pack/x-pack-{version}.zip+]
(https://artifacts.elastic.co/downloads/packs/x-pack/x-pack-{version}.zip.sha512[sha512])
+
--
NOTE: The plugins for {es}, {kib}, and Logstash are included in the same zip
file. If you have already downloaded this file to install {xpack} on one of
those other products, you can reuse the same file.

--

.. Transfer the zip file to a temporary directory on the offline machine. (Do
NOT put the file in the {es} plugins directory.)

. Run `bin/elasticsearch-plugin install` from `ES_HOME` on each node in your
cluster:
+
--
[source,shell]
----------------------------------------------------------
bin/elasticsearch-plugin install x-pack
----------------------------------------------------------

NOTE: If you are using a <<xpack-package-installation, DEB/RPM distribution>>
      of {es}, run the installation with superuser permissions.

The plugin install scripts require direct internet access to download and
install {xpack}. If your server doesn’t have internet access, specify the
location of the {xpack} zip file that you downloaded to a temporary directory.

["source","sh",subs="attributes"]
----------------------------------------------------------
bin/elasticsearch-plugin install file:///path/to/file/x-pack-{version}.zip
----------------------------------------------------------

NOTE:  You must specify an absolute path to the zip file after the `file://` protocol.

--

. Confirm that you want to grant {xpack} additional permissions.
+
--
TIP:  Specify the `--batch` option when running the install command to
      automatically grant these permissions and bypass these install prompts.

--
+
  .. {xpack} needs these permissions to set the threat context loader during
  install so {watcher} can send email notifications.
+
--
[source,shell]
----------------------------------------------------------
@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
@     WARNING: plugin requires additional permissions     @
@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
* java.lang.RuntimePermission accessClassInPackage.com.sun.activation.registries
* java.lang.RuntimePermission getClassLoader
* java.lang.RuntimePermission setContextClassLoader
* java.lang.RuntimePermission setFactory
* java.security.SecurityPermission createPolicy.JavaPolicy
* java.security.SecurityPermission getPolicy
* java.security.SecurityPermission putProviderProperty.BC
* java.security.SecurityPermission setPolicy
* java.util.PropertyPermission * read,write
* java.util.PropertyPermission sun.nio.ch.bugLevel write
* javax.net.ssl.SSLPermission setHostnameVerifier
See http://docs.oracle.com/javase/8/docs/technotes/guides/security/permissions.html
for descriptions of what these permissions allow and the associated risks.

Continue with installation? [y/N]y
----------------------------------------------------------
--
  .. {xpack} requires permissions to enable {es} to launch the {ml} analytical
  engine. The native controller ensures that the launched process is a valid
  {ml} component. Once launched, communications between the {ml} processes and
  {es} are limited to the operating system user that {es} runs as.
+
--
[source,shell]
----------------------------------------------------------
@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
@        WARNING: plugin forks a native controller        @
@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
This plugin launches a native controller that is not subject to
the Java security manager nor to system call filters.

Continue with installation? [y/N]y
----------------------------------------------------------
--

. {xpack} will try to automatically create a number of indices within {es}.
By default, {es} is configured to allow automatic index creation, and no
additional steps are required. However, if you have disabled automatic index
creation in {es}, you must configure
{ref}/docs-index_.html#index-creation[`action.auto_create_index`] in
`elasticsearch.yml` to allow {xpack} to create the following indices:
+
--
[source,yaml]
-----------------------------------------------------------
action.auto_create_index: .security,.monitoring*,.watches,.triggered_watches,.watcher-history*,.ml*
-----------------------------------------------------------
--
+
[IMPORTANT]
=============================================================================
If you are using https://www.elastic.co/products/logstash[Logstash]
or https://www.elastic.co/products/beats[Beats] then you will most likely
require additional index names in your `action.auto_create_index` setting, and
the exact value will depend on your local configuration. If you are unsure of
the correct value for your environment, you may consider setting the value to
 `*` which will allow automatic creation of all indices.
=============================================================================

. Configure Transport Layer Security (TLS/SSL).
+
--
If you have a non-trial license and you want to use {security}, you must
configure TLS for internode-communication.

NOTE: This requirement applies to clusters with more than one node and to
clusters with a single node that listens on an external interface. Single-node
clusters that use a loopback interface do not have this requirement.  For more
information, see
{xpack-ref}/encrypting-communications.html[Encrypting Communications].

--
.. Generate node certificates. For example, you can use the `certutil` command
line tool to generate a certificate authority (CA) and signed certificates for
your nodes. For more information, see <<certutil>>.

... Generate a new Certificate Authority (CA) for your {es} cluster:
+
--
[source,shell]
----------------------------------------------------------
bin/x-pack/certutil ca
----------------------------------------------------------

You can configure the cluster to trust all nodes that have a certificate that
has been signed by this CA.

The command outputs a single file, with a default name of `elastic-stack-ca.p12`.
This file is a PKCS#12 keystore that contains the public certificate for your CA
and the private key that is used to sign the certificates for each node.

The `certutil` command also prompts you for a password to protect the file and
key. If you plan to add more nodes to your cluster in the future, retain a copy
of the file and remember its password.
--

... Generate a certificate and private key for each node in your cluster:
+
--
[source,shell]
----------------------------------------------------------
bin/x-pack/certutil cert --ca elastic-stack-ca.p12
----------------------------------------------------------
The output is a single PKCS#12 keystore that includes the node certificate, node
key, and CA certificate.

You are also prompted for a password. You can enter a password for your
certificate and key, or you can leave the password blank by pressing Enter.

By default `certutil` generates certificates that have no hostname information
in them (that is, they do not have any Subject Alternative Name fields).
This means that you can use the certificate for every node in your cluster, but
you must turn off hostname verification as shown in the configuration below.

If you want to use hostname verification within your cluster, run the
`certutil cert` command once for each of your nodes and provide the `--name`,
`--dns` and `--ip` options.
--
... Alternatively, if you want to use a commercial or organization-specific CA,
you can use the `certutil csr` command to generate certificate signing requests
(CSR) for the nodes in your cluster. For more information, see <<certutil>>.

.. Copy the applicable `.p12` file into a directory within the {es} configuration
directory on each node. For example, `/home/es/config/certs`. There is no need
to copy the CA file to this directory.

.. Add the following information to the `elasticsearch.yml` file on each node:
+
--
[source,yaml]
-----------------------------------------------------------
xpack.ssl.keystore.path: certs/elastic-certificates.p12 <1>
xpack.ssl.truststore.path: certs/elastic-certificates.p12 <2>
xpack.security.transport.ssl.verification_mode: certificate <3>
xpack.security.transport.ssl.enabled: true
-----------------------------------------------------------
<1> If you created a separate certificate for each node, then you might need to
customize this path on each node. If the filename matches the node name, you can
use the `certs/${node.name}.p12` format, for example.
<2> The `certutil` output includes the CA certificate inside the PKCS#12
keystore, therefore the keystore can also be used as the truststore. This name
should match the `keystore.path` value.
<3> If you used the `--dns` or `--ip` options with the `certutil cert` command
and you want to enable strict hostname checking, set the verification mode to
`full`.

For more information about these settings, see
{ref}/security-settings.html[Security Settings in {es}].
--

.. If you secured the node's PKCS#12 file with a password, then you must add
the password to your {es} keystore. Run the following commands:
+
--
[source,shell]
-----------------------------------------------------------
bin/elasticsearch-keystore add xpack.ssl.keystore.secure_password

bin/elasticsearch-keystore add xpack.ssl.truststore.secure_password
-----------------------------------------------------------
--

. Start {es}.
+
--
[source,shell]
----------------------------------------------------------
bin/elasticsearch
----------------------------------------------------------
--

. Set the passwords for all built-in users. The +setup-passwords+ command is
the simplest method to set the built-in users' passwords for the first time.
+
--
For example, you can run the command in an "interactive" mode, which prompts you
to enter new passwords for the `elastic`, `kibana`, and `logstash_system` users:

[source,shell]
--------------------------------------------------
bin/x-pack/setup-passwords interactive
--------------------------------------------------

For more information about the command options, see <<setup-passwords>>.

IMPORTANT: The `setup-passwords` command uses a transient bootstrap password
that is no longer valid after the command runs successfully. You cannot run the
`setup-passwords` command a second time. Instead, you can update passwords from
the **Management > Users** UI in {kib} or use the security user API.

For more information, see
{xpack-ref}/setting-up-authentication.html#set-built-in-user-passwords[Setting Built-in User Passwords].
--

. Optional: <<setup-xpack-client, Configure the Java Client>>.

. {kibana-ref}/installing-xpack-kb.html[Install {xpack} on {kib}].

. {logstash-ref}/installing-xpack-log.html[Install {xpack} on Logstash].


[float]
[[xpack-package-installation]]
=== Installing {xpack} on a DEB/RPM Package Installation

If you use the DEB/RPM packages to install {es}, by default {es} is installed
in `/usr/share/elasticsearch` and the configuration files are stored
in `/etc/elasticsearch`. (For the complete list of default paths, see
{ref}/deb.html#deb-layout[Debian Directory Layout] and
{ref}/rpm.html#rpm-layout[RPM Directory Layout] in the {es} Reference.)

To install {xpack} on a DEB/RPM package installation, you need to run
`bin/plugin install` from the `/usr/share/elasticsearch` directory with superuser
permissions:

[source,shell]
----------------------------------------------------------
cd /usr/share/elasticsearch
sudo bin/elasticsearch-plugin install x-pack
----------------------------------------------------------

NOTE: If the configuration files are not in `/etc/elasticsearch` you need to
      specify the location of the configuration files by setting the environment
      variable `ES_PATH_CONF` via `ES_PATH_CONF=<path>`.