[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. 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 <> 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 passwords and SSL/TLS. .. If you have a non-trial license and you want to use {security}, you must configure SSL/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 `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. For more information, see <>. 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.transport.ssl.enabled: true xpack.security.http.ssl.enabled: true <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> This setting is optional. It enables SSL on the HTTP layer to ensure that communication between HTTP clients and the cluster is encrypted. -- .. 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=`.