Installing X-Pack in Elasticsearch

After you install Elasticsearch, you can optionally obtain and install X-Pack. For more information about how to obtain X-Pack, see https://www.elastic.co/products/x-pack.

You must run the version of X-Pack that matches the version of Elasticsearch you are running.

Important

If you are installing X-Pack for the first time on an existing cluster, you must perform a full cluster restart. Installing X-Pack 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 rolling upgrade.

To install X-Pack in Elasticsearch:

  1. Optional: If you want to install X-Pack on a machine that doesn’t have internet access:

    1. Manually download the X-Pack zip file: https://artifacts.elastic.co/downloads/packs/x-pack/x-pack-7.0.0-alpha1.zip (sha1)

      Note

      The plugins for Elasticsearch, Kibana, and Logstash are included in the same zip file. If you have already downloaded this file to install X-Pack on one of those other products, you can reuse the same file.

    2. Transfer the zip file to a temporary directory on the offline machine. (Do NOT put the file in the Elasticsearch plugins directory.)
  2. Run bin/elasticsearch-plugin install from ES_HOME on each node in your cluster:

    bin/elasticsearch-plugin install x-pack
    Note

    If you are using a DEB/RPM distribution of Elasticsearch, run the installation with superuser permissions.

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

    bin/elasticsearch-plugin install file:///path/to/file/x-pack-7.0.0-alpha1.zip
    Note

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

  3. Confirm that you want to grant X-Pack additional permissions.

    Tip

    Specify the --batch option when running the install command to automatically grant these permissions and bypass these install prompts.

    1. X-Pack needs these permissions to set the threat context loader during install so Watcher can send email notifications.

      @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
      @     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
    2. X-Pack requires permissions to enable Elasticsearch to launch the machine learning analytical engine. The native controller ensures that the launched process is a valid machine learning component. Once launched, communications between the machine learning processes and Elasticsearch are limited to the operating system user that Elasticsearch runs as.

      @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
      @        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
  4. X-Pack will try to automatically create a number of indices within Elasticsearch. By default, Elasticsearch is configured to allow automatic index creation, and no additional steps are required. However, if you have disabled automatic index creation in Elasticsearch, you must configure action.auto_create_index in elasticsearch.yml to allow X-Pack to create the following indices:

    action.auto_create_index: .security,.monitoring*,.watches,.triggered_watches,.watcher-history*,.ml*
    Important

    If you are using Logstash or 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.

  5. Change the passwords for the built-in users. For more information, see Setting Up User Authentication.

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

      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.

    2. 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 Encrypting Communications.

      1. Generate node certificates. For example, you can use the certgen command line tool to generate a certificate authority and signed certificates for your nodes.

        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.

      2. Copy the certificate data into a directory within the Elasticsearch configuration directory. For example, /home/es/config/certs.
      3. Add the following information to the elasticsearch.yml on all nodes:

        xpack.ssl.key: certs/${node.name}/${node.name}.key 
        xpack.ssl.certificate: certs/${node.name}/${node.name}.crt 
        xpack.ssl.certificate_authorities: certs/ca/ca.crt 
        xpack.security.authc.token.enabled: false 

        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.

        Alternatively, specify the full path to the node certificate.

        Alternatively specify the full path to the CA certificate.

        Disables the built-in token service.

    3. Start Elasticsearch.

      bin/elasticsearch
    4. Set the passwords for all built-in users. You can update passwords from the Management > Users UI in Kibana, use the setup-passwords tool, or use the security user API. For example:

      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.

  6. Install X-Pack on Kibana.
  7. Install X-Pack on Logstash.

Installing X-Pack on a DEB/RPM Package Installation

If you use the DEB/RPM packages to install Elasticsearch, by default Elasticsearch is installed in /usr/share/elasticsearch and the configuration files are stored in /etc/elasticsearch. (For the complete list of default paths, see Debian Directory Layout and RPM Directory Layout in the Elasticsearch Reference.)

To install X-Pack on a DEB/RPM package installation, you need to run bin/plugin install from the /usr/share/elasticsearch directory with superuser permissions:

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