419 lines
16 KiB
Plaintext
419 lines
16 KiB
Plaintext
[[windows]]
|
|
=== Install Elasticsearch with MSI Windows Installer
|
|
|
|
Elasticsearch can be installed on Windows using the `.msi` package. This can
|
|
install Elasticsearch as a Windows service or allow it to be run manually using
|
|
the included `elasticsearch.exe` executable.
|
|
|
|
TIP: Elasticsearch has historically been installed on Windows using the <<zip-windows, .zip>> archive.
|
|
You can continue using the `.zip` approach if you prefer.
|
|
|
|
The latest stable version of Elasticsearch can be found on the
|
|
link:/downloads/elasticsearch[Download Elasticsearch] page.
|
|
Other versions can be found on the
|
|
link:/downloads/past-releases[Past Releases page].
|
|
|
|
NOTE: Elasticsearch requires Java 8 or later. Use the
|
|
http://www.oracle.com/technetwork/java/javase/downloads/index.html[official Oracle distribution]
|
|
or an open-source distribution such as http://openjdk.java.net[OpenJDK].
|
|
|
|
[[download-msi]]
|
|
==== Download the `.msi` package
|
|
|
|
ifeval::["{release-state}"=="unreleased"]
|
|
|
|
Version {version} of Elasticsearch has not yet been released.
|
|
|
|
endif::[]
|
|
|
|
ifeval::["{release-state}"!="unreleased"]
|
|
|
|
Download the `.msi` package for Elasticsearch v{version} from https://artifacts.elastic.co/downloads/elasticsearch/elasticsearch-{version}.msi
|
|
|
|
endif::[]
|
|
|
|
[[install-msi-gui]]
|
|
==== Install using the graphical user interface (GUI)
|
|
|
|
Double-click the downloaded `.msi` package to launch a GUI wizard that will guide you through the
|
|
installation process. You can view help on any step by clicking the `?` button, which reveals an
|
|
aside panel with additional information for each input:
|
|
|
|
[[msi-installer-help]]
|
|
image::images/msi_installer/msi_installer_help.png[]
|
|
|
|
Within the first screen, select the directory for the installation. In addition, select directories for where
|
|
data, logs and configuration will reside or <<msi-command-line-options,roll with the default locations>>:
|
|
|
|
[[msi-installer-locations]]
|
|
image::images/msi_installer/msi_installer_locations.png[]
|
|
|
|
Then select whether to install as a service or start Elasticsearch manually as needed. When
|
|
installing as a service, you can also decide which account to run the service under as well
|
|
as whether the service should be started after installation and when Windows is started or
|
|
restarted:
|
|
|
|
[[msi-installer-service]]
|
|
image::images/msi_installer/msi_installer_service.png[]
|
|
|
|
IMPORTANT: When selecting an account to run the service with, be sure that the chosen account
|
|
has sufficient privileges to access the installation and other deployment directories chosen.
|
|
|
|
Common configuration settings are exposed within the Configuration section, allowing the cluster
|
|
name, node name and roles to be set, in addition to memory and network settings:
|
|
|
|
[[msi-installer-configuration]]
|
|
image::images/msi_installer/msi_installer_configuration.png[]
|
|
|
|
Finally, the installer provides a list of common plugins that can be downloaded and installed as
|
|
part of the installation:
|
|
|
|
[[msi-installer-selected-plugins]]
|
|
image::images/msi_installer/msi_installer_selected_plugins.png[]
|
|
|
|
By default, the {xpack-ref}/index.html[X-Pack] plugin will be selected to be installed, and if
|
|
installing with the <<ingest, ingest>> node role, the {plugins}/ingest-attachment.html[Ingest Attachment Processor] and {plugins}/ingest-geoip.html[Ingest GeoIP Processor] plugins will also be selected for installation.
|
|
|
|
NOTE: X-Pack includes a trial license for 30 days. After that, you can obtain one of the https://www.elastic.co/subscriptions[available subscriptions] or {ref}/security-settings.html[disable Security]. The Basic license is free and includes the https://www.elastic.co/products/x-pack/monitoring[Monitoring] extension.
|
|
|
|
After clicking the install button, Elasticsearch will be installed:
|
|
|
|
[[msi-installer-success]]
|
|
image::images/msi_installer/msi_installer_success.png[]
|
|
|
|
[[install-msi-command-line]]
|
|
==== Install using the command line
|
|
|
|
The `.msi` can also install Elasticsearch using the command line. The simplest installation
|
|
using the same defaults as the GUI is achieved by first navigating to the download directory,
|
|
then running:
|
|
|
|
["source","sh",subs="attributes,callouts"]
|
|
--------------------------------------------
|
|
msiexec.exe /i elasticsearch-{version}.msi /qn
|
|
--------------------------------------------
|
|
|
|
By default, msiexec does not wait for the installation process to complete, since it runs in the
|
|
Windows subsystem. To wait on the process to finish and ensure that `%ERRORLEVEL%` is set
|
|
accordingly, it is recommended to use `start /wait` to create a process and wait for it to exit
|
|
|
|
["source","sh",subs="attributes,callouts"]
|
|
--------------------------------------------
|
|
start /wait msiexec.exe /i elasticsearch-{version}.msi /qn
|
|
--------------------------------------------
|
|
|
|
As with any MSI installation package, a log file for the installation process can be found
|
|
within the `%TEMP%` directory, with a randomly generated name adhering to the format
|
|
`MSI*.LOG`. The path to a log file can be supplied using the `/l` command line argument
|
|
|
|
["source","sh",subs="attributes,callouts"]
|
|
--------------------------------------------
|
|
start /wait msiexec.exe /i elasticsearch-{version}.msi /qn /l install.log
|
|
--------------------------------------------
|
|
|
|
Supported Windows Installer command line arguments can be viewed using
|
|
|
|
["source","sh",subs="attributes,callouts"]
|
|
--------------------------------------------
|
|
msiexec.exe /help
|
|
--------------------------------------------
|
|
|
|
or by consulting the https://msdn.microsoft.com/en-us/library/windows/desktop/aa367988(v=vs.85).aspx[Windows Installer SDK Command-Line Options].
|
|
|
|
[[msi-command-line-options]]
|
|
==== Command line options
|
|
|
|
All settings exposed within the GUI are also available as command line arguments (referred to
|
|
as _properties_ within Windows Installer documentation) that can be passed to msiexec:
|
|
|
|
[horizontal]
|
|
`INSTALLDIR`::
|
|
|
|
The installation directory. Defaults to `%PROGRAMFILES%\Elastic\Elasticsearch`
|
|
|
|
`DATADIRECTORY`::
|
|
|
|
The directory in which to store your data.
|
|
Defaults to `%ALLUSERSPROFILE%\Elastic\Elasticsearch\data`
|
|
|
|
`CONFIGDIRECTORY`::
|
|
|
|
The directory in which to store your configuration.
|
|
Defaults to `%ALLUSERSPROFILE%\Elastic\Elasticsearch\config`
|
|
|
|
`LOGSDIRECTORY`::
|
|
|
|
The directory in which to store your logs.
|
|
Defaults to `%ALLUSERSPROFILE%\Elastic\Elasticsearch\logs`
|
|
|
|
`PLACEWRITABLELOCATIONSINSAMEPATH`::
|
|
|
|
Whether the data, configuration and logs directories
|
|
should be created under the installation directory. Defaults to `false`
|
|
|
|
`INSTALLASSERVICE`::
|
|
|
|
Whether Elasticsearch is installed and configured as a Windows Service.
|
|
Defaults to `true`
|
|
|
|
`STARTAFTERINSTALL`::
|
|
|
|
Whether the Windows Service is started after installation finishes.
|
|
Defaults to `true`
|
|
|
|
`STARTWHENWINDOWSSTARTS`::
|
|
|
|
Whether the Windows Service is started when Windows is started.
|
|
Defaults to `true`
|
|
|
|
`USELOCALSYSTEM`::
|
|
|
|
Whether the Windows service runs under the LocalSystem Account.
|
|
Defaults to `true`
|
|
|
|
`USENETWORKSERVICE`::
|
|
|
|
Whether the Windows service runs under the NetworkService Account. Defaults
|
|
to `false`
|
|
|
|
`USEEXISTINGUSER`::
|
|
|
|
Whether the Windows service runs under a specified existing account. Defaults
|
|
to `false`
|
|
|
|
`USER`::
|
|
|
|
The username for the account under which the Windows service runs. Defaults to `""`
|
|
|
|
`PASSWORD`::
|
|
|
|
The password for the account under which the Windows service runs. Defaults to `""`
|
|
|
|
`CLUSTERNAME`::
|
|
|
|
The name of the cluster. Defaults to `elasticsearch`
|
|
|
|
`NODENAME`::
|
|
|
|
The name of the node. Defaults to `%COMPUTERNAME%`
|
|
|
|
`MASTERNODE`::
|
|
|
|
Whether Elasticsearch is configured as a master node. Defaults to `true`
|
|
|
|
`DATANODE`::
|
|
|
|
Whether Elasticsearch is configured as a data node. Defaults to `true`
|
|
|
|
`INGESTNODE`::
|
|
|
|
Whether Elasticsearch is configured as an ingest node. Defaults to `true`
|
|
|
|
`SELECTEDMEMORY`::
|
|
|
|
The amount of memory to allocate to the JVM heap for Elasticsearch.
|
|
Defaults to half of the available memory on the target machine, up to a maximum of 30.5GB
|
|
|
|
`LOCKMEMORY`::
|
|
|
|
Whether `bootstrap.memory_lock` should be used to try to lock the process
|
|
address space into RAM. Defaults to `true`
|
|
|
|
`UNICASTNODES`::
|
|
|
|
A comma separated list of hosts in the form `host:port` or `host` to be used for
|
|
unicast discovery. Defaults to `""`
|
|
|
|
`MINIMUMMASTERNODES`::
|
|
|
|
The minimum number of master-eligible nodes that must be visible
|
|
in order to form a cluster. Defaults to `""`
|
|
|
|
`NETWORKHOST`::
|
|
|
|
The hostname or IP address to bind the node to and _publish_ (advertise) this
|
|
host to other nodes in the cluster. Defaults to `""`
|
|
|
|
`HTTPPORT`::
|
|
|
|
The port to use for exposing Elasticsearch APIs over HTTP. Defaults to `9200`
|
|
|
|
`TRANSPORTPORT`::
|
|
|
|
The port to use for internal communication between nodes within the cluster.
|
|
Defaults to `9300`
|
|
|
|
`PLUGINS`::
|
|
|
|
A comma separated list of the plugins to download and install as part of the installation. Defaults to
|
|
`x-pack, ingest-attachment, ingest-geoip`
|
|
|
|
To pass a value, simply append the property name and value using the format `<PROPERTYNAME>="<VALUE>"` to
|
|
the installation command. For example, to use a different installation directory to the default one:
|
|
|
|
["source","sh",subs="attributes,callouts"]
|
|
--------------------------------------------
|
|
start /wait msiexec.exe /i elasticsearch-{version}.msi /qn INSTALLDIR="C:\Custom Install Directory"
|
|
--------------------------------------------
|
|
|
|
Consult the https://msdn.microsoft.com/en-us/library/windows/desktop/aa367988(v=vs.85).aspx[Windows Installer SDK Command-Line Options]
|
|
for additional rules related to values containing quotation marks.
|
|
|
|
[[msi-installer-command-line-running]]
|
|
==== Running Elasticsearch from the command line
|
|
|
|
Once installed, Elasticsearch can be started from the command line, if not installed as a service
|
|
and configured to start when installation completes, as follows:
|
|
|
|
["source","sh",subs="attributes,callouts"]
|
|
--------------------------------------------
|
|
.\bin\elasticsearch.exe
|
|
--------------------------------------------
|
|
|
|
By default, Elasticsearch runs in the foreground, prints its logs to `STDOUT` in addition
|
|
to the `<cluster name>.log` file within `LOGSDIRECTORY`, and can be stopped by pressing `Ctrl-C`.
|
|
|
|
[[msi-installer-command-line-configuration]]
|
|
==== Configuring Elasticsearch on the command line
|
|
|
|
Elasticsearch loads its configuration from the `%ES_HOME%\config\elasticsearch.yml`
|
|
file by default. The format of this config file is explained in
|
|
<<settings>>.
|
|
|
|
Any settings that can be specified in the config file can also be specified on
|
|
the command line, using the `-E` syntax as follows:
|
|
|
|
["source","sh",subs="attributes,callouts"]
|
|
--------------------------------------------
|
|
.\bin\elasticsearch.exe -E cluster.name=my_cluster -E node.name=node_1
|
|
--------------------------------------------
|
|
|
|
NOTE: Values that contain spaces must be surrounded with quotes. For instance `-E path.logs="C:\My Logs\logs"`.
|
|
|
|
TIP: Typically, any cluster-wide settings (like `cluster.name`) should be
|
|
added to the `elasticsearch.yml` config file, while any node-specific settings
|
|
such as `node.name` could be specified on the command line.
|
|
|
|
include::check-running.asciidoc[]
|
|
|
|
[[msi-installer-windows-service]]
|
|
==== Installing Elasticsearch as a Service on Windows
|
|
|
|
Elasticsearch can be installed as a service to run in the background or start
|
|
automatically at boot time without any user interaction. This can be achieved upon installation
|
|
using the following command line options
|
|
|
|
* `INSTALLASSERVICE=true`
|
|
* `STARTAFTERINSTALL=true`
|
|
* `STARTWHENWINDOWSSTARTS=true`
|
|
|
|
Once installed, Elasticsearch will appear within the Services control panel:
|
|
|
|
[[msi-installer-installed-service]]
|
|
image::images/msi_installer/msi_installer_installed_service.png[]
|
|
|
|
and can be stopped and restarted from within the control panel, or from the command line using:
|
|
|
|
with Command Prompt:
|
|
|
|
[source,sh]
|
|
--------------------------------------------
|
|
sc.exe stop Elasticsearch
|
|
sc.exe start Elasticsearch
|
|
--------------------------------------------
|
|
|
|
with PowerShell:
|
|
|
|
[source,powershell]
|
|
--------------------------------------------
|
|
Get-Service Elasticsearch | Stop-Service | Start-Service
|
|
--------------------------------------------
|
|
|
|
Changes can be made to jvm.options and elasticsearch.yml configuration files to configure the
|
|
service after installation. Most changes (like JVM settings) will require a restart of the
|
|
service in order to take affect.
|
|
|
|
[[upgrade-msi-gui]]
|
|
==== Upgrade using the graphical user interface (GUI)
|
|
|
|
The `.msi` package supports upgrading an installed version of Elasticsearch to a newer
|
|
version of Elasticsearch. The upgrade process handles upgrading all installed plugins as
|
|
well as retaining both your data and configuration.
|
|
|
|
Downloading and clicking on a newer version of the `.msi` package will launch the GUI wizard.
|
|
The first step will list the read only properties from the previous installation:
|
|
|
|
[[msi-installer-upgrade-notice]]
|
|
image::images/msi_installer/msi_installer_upgrade_notice.png[]
|
|
|
|
The following configuration step allows certain configuration options to be changed:
|
|
|
|
[[msi-installer-upgrade-configuration]]
|
|
image::images/msi_installer/msi_installer_upgrade_configuration.png[]
|
|
|
|
Finally, the plugins step allows currently installed plugins to be upgraded or removed, and
|
|
for plugins not currently installed, to be downloaded and installed:
|
|
|
|
[[msi-installer-upgrade-plugins]]
|
|
image::images/msi_installer/msi_installer_upgrade_plugins.png[]
|
|
|
|
[[upgrade-msi-command-line]]
|
|
==== Upgrade using the command line
|
|
|
|
The `.msi` can also upgrade Elasticsearch using the command line. The simplest upgrade
|
|
using the same defaults as the currently installed version is achieved by first
|
|
navigating to the download directory, then running:
|
|
|
|
["source","sh",subs="attributes,callouts"]
|
|
--------------------------------------------
|
|
start /wait msiexec.exe /i elasticsearch-{version}.msi /qn
|
|
--------------------------------------------
|
|
|
|
Similar to the install process, a path to a log file for the upgrade process can
|
|
be passed using the `/l` command line argument
|
|
|
|
["source","sh",subs="attributes,callouts"]
|
|
--------------------------------------------
|
|
start /wait msiexec.exe /i elasticsearch-{version}.msi /qn /l upgrade.log
|
|
--------------------------------------------
|
|
|
|
[[uninstall-msi-gui]]
|
|
==== Uninstall using Add/Remove Programs
|
|
|
|
The `.msi` package handles uninstallation of all directories and files added as part of installation.
|
|
|
|
WARNING: Uninstallation will remove all directories and their contents created as part of
|
|
installation, including data within the data directory. If you wish to retain your data upon
|
|
uninstallation, it is recommended that you make a copy of the data directory before uninstallation.
|
|
|
|
MSI installer packages do not provide a GUI for uninstallation. An installed program can be uninstalled
|
|
by pressing the Windows key and typing `add or remove programs` to open the system settings.
|
|
|
|
Once opened, find the Elasticsearch installation within the list of installed applications, click
|
|
and choose `Uninstall`:
|
|
|
|
[[msi-installer-uninstall]]
|
|
image::images/msi_installer/msi_installer_uninstall.png[]
|
|
|
|
This will launch the uninstallation process.
|
|
|
|
[[uninstall-msi-command-line]]
|
|
==== Uninstall using the command line
|
|
|
|
Uninstallation can also be performed from the command line by navigating to the directory
|
|
containing the `.msi` package and running:
|
|
|
|
["source","sh",subs="attributes,callouts"]
|
|
--------------------------------------------
|
|
start /wait msiexec.exe /x elasticsearch-{version}.msi /qn
|
|
--------------------------------------------
|
|
|
|
Similar to the install process, a path to a log file for the uninstallation process can
|
|
be passed using the `/l` command line argument
|
|
|
|
["source","sh",subs="attributes,callouts"]
|
|
--------------------------------------------
|
|
start /wait msiexec.exe /x elasticsearch-{version}.msi /qn /l uninstall.log
|
|
--------------------------------------------
|
|
|
|
include::next-steps.asciidoc[] |