314 lines
13 KiB
Plaintext
314 lines
13 KiB
Plaintext
[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>`.
|