[role="xpack"] [[installing-xpack-es]] == Installing X-Pack in Elasticsearch ++++ Installing {xpack} ++++ 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 <> 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 <>. ... 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 <>. .. 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 <>. 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: <>. . {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=`.