OpenSearch/docs/en/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.

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].

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.sha1[sha1])
+
--
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.
=============================================================================

. Change the passwords for the built-in users. For more information,
see {xpack-ref}/setting-up-authentication.html[Setting Up User Authentication].
.. If you have not already done so, bootstrap the password for the `elastic`
user by placing a password in the keystore of at least one node.
+
--
[source,shell]
--------------------------------------------------
bin/elasticsearch-keystore create
bin/elasticsearch-keystore add "bootstrap.password"
--------------------------------------------------
After you run the "add" command, you will be prompted to enter a password. This
bootstrap password is only intended to be a transient password that is used to
help you set all the built-in user passwords.
--

.. If you have more than one node or a single node that listens on an external
interface, you must configure SSL/TLS for inter-node communication. Single-node
instances 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 `certgen` command
line tool to generate a certificate authority and signed certificates for your
nodes.
+
--
[source,shell]
----------------------------------------------------------
bin/x-pack/certgen
----------------------------------------------------------
This command generates a zip file with the CA certificate, private key, and
signed certificates and keys in the PEM format for each node that you specify.
If you want to use a commercial or organization-specific CA, you can use the
`-csr` parameter to generate certificate signing requests (CSR) for the nodes
in your cluster.

TIP: For easier setup, use the node name as the instance name when you run
this tool.

--
... Copy the certificate data into a directory within the {es} configuration
directory. For example,
`/home/es/config/certs`.
... Add the following information to the `elasticsearch.yml` on all nodes:
+
--
[source,yaml]
-----------------------------------------------------------
xpack.ssl.key: certs/${node.name}/${node.name}.key <1>
xpack.ssl.certificate: certs/${node.name}/${node.name}.crt <2>
xpack.ssl.certificate_authorities: certs/ca/ca.crt <3>
xpack.security.authc.token.enabled: false <4>
-----------------------------------------------------------
<1> If this path does not exist on every node or the file name does not match
the `node.name` configuration setting, you must specify the full path to the
node key file.
<2> Alternatively, specify the full path to the node certificate.
<3> Alternatively specify the full path to the CA certificate.
<4> Disables the built-in token service.
--

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

.. Set the passwords for all built-in users. You can update passwords from the
**Management > Users** UI in {kib}, use the `setup-passwords` tool, or use the
security user API. For example:
+
--
[source,shell]
--------------------------------------------------
bin/x-pack/setup-passwords interactive
--------------------------------------------------
If you prefer to have randomly generated passwords, specify `auto` instead of
`interactive`. If the node is not listening on "http://localhost:9200", use the
`-u` parameter to specify the appropriate URL.
--

. {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>`.