Add MSI installation to documentation (#25213)
* Add MSI installation to documentation Move installation documentation for Windows with the .zip archive into the zip and tar installation documentation, and clearly indicate any differences for installing on macOS/Linux and Windows. * Separate out installation with .zip on Windows
This commit is contained in:
Russ Cam
GitHub
parent
7291aba8ae
commit
9eca380a76
|
|
@ -111,9 +111,14 @@ java -version
|
|||
echo $JAVA_HOME
|
||||
--------------------------------------------------
|
||||
|
||||
Once we have Java set up, we can then download and run Elasticsearch. The binaries are available from http://www.elastic.co/downloads[`www.elastic.co/downloads`] along with all the releases that have been made in the past. For each release, you have a choice among a `zip` or `tar` archive, or a `DEB` or `RPM` package. For simplicity, let's use the tar file.
|
||||
Once we have Java set up, we can then download and run Elasticsearch. The binaries are available from http://www.elastic.co/downloads[`www.elastic.co/downloads`] along with all the releases that have been made in the past. For each release, you have a choice among a `zip` or `tar` archive, a `DEB` or `RPM` package, or a Windows `MSI` installation package.
|
||||
|
||||
Let's download the Elasticsearch {version} tar as follows (Windows users should download the zip package):
|
||||
[float]
|
||||
=== Installation example with tar
|
||||
|
||||
For simplicity, let's use the <<zip-targz, tar>> file.
|
||||
|
||||
Let's download the Elasticsearch {version} tar as follows:
|
||||
|
||||
["source","sh",subs="attributes,callouts"]
|
||||
--------------------------------------------------
|
||||
|
|
@ -121,7 +126,7 @@ curl -L -O https://artifacts.elastic.co/downloads/elasticsearch/elasticsearch-{v
|
|||
--------------------------------------------------
|
||||
// NOTCONSOLE
|
||||
|
||||
Then extract it as follows (Windows users should unzip the zip package):
|
||||
Then extract it as follows:
|
||||
|
||||
["source","sh",subs="attributes,callouts"]
|
||||
--------------------------------------------------
|
||||
|
|
@ -135,14 +140,74 @@ It will then create a bunch of files and folders in your current directory. We t
|
|||
cd elasticsearch-{version}/bin
|
||||
--------------------------------------------------
|
||||
|
||||
And now we are ready to start our node and single cluster (Windows users should run the elasticsearch.bat file):
|
||||
And now we are ready to start our node and single cluster:
|
||||
|
||||
[source,sh]
|
||||
--------------------------------------------------
|
||||
./elasticsearch
|
||||
--------------------------------------------------
|
||||
|
||||
If everything goes well, you should see a bunch of messages that look like below:
|
||||
[float]
|
||||
=== Installation example with MSI Windows Installer
|
||||
|
||||
For Windows users, we recommend using the <<windows, MSI Installer package>>. The package contains a graphical user interface (GUI) that guides you through the installation process.
|
||||
|
||||
First, download the Elasticsearch {version} MSI from
|
||||
https://artifacts.elastic.co/downloads/elasticsearch/elasticsearch-{version}.msi.
|
||||
|
||||
Then double-click the downloaded file to launch the GUI. Within the first screen, select the deployment directories:
|
||||
|
||||
[[getting-started-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.
|
||||
To align with the tar example, choose not to install as a service:
|
||||
|
||||
[[getting-started-msi-installer-service]]
|
||||
image::images/msi_installer/msi_installer_no_service.png[]
|
||||
|
||||
For configuration, simply leave the default values:
|
||||
|
||||
[[getting-started-msi-installer-configuration]]
|
||||
image::images/msi_installer/msi_installer_configuration.png[]
|
||||
|
||||
Again, to align with the tar example, uncheck all plugins to not install any plugins:
|
||||
|
||||
[[getting-started-msi-installer-plugins]]
|
||||
image::images/msi_installer/msi_installer_plugins.png[]
|
||||
|
||||
After clicking the install button, Elasticsearch will be installed:
|
||||
|
||||
[[getting-started-msi-installer-success]]
|
||||
image::images/msi_installer/msi_installer_success.png[]
|
||||
|
||||
By default, Elasticsearch will be installed at `%PROGRAMFILES%\Elastic\Elasticsearch`. Navigate here and go into the bin directory as follows:
|
||||
|
||||
**with Command Prompt:**
|
||||
|
||||
[source,sh]
|
||||
--------------------------------------------------
|
||||
cd %PROGRAMFILES%\Elastic\Elasticsearch\bin
|
||||
--------------------------------------------------
|
||||
|
||||
**with PowerShell:**
|
||||
|
||||
[source,powershell]
|
||||
--------------------------------------------------
|
||||
cd $env:PROGRAMFILES\Elastic\Elasticsearch\bin
|
||||
--------------------------------------------------
|
||||
|
||||
And now we are ready to start our node and single cluster:
|
||||
|
||||
[source,sh]
|
||||
--------------------------------------------------
|
||||
.\elasticsearch.exe
|
||||
--------------------------------------------------
|
||||
|
||||
[float]
|
||||
=== Successfully running node
|
||||
|
||||
If everything goes well with installation, you should see a bunch of messages that look like below:
|
||||
|
||||
["source","sh",subs="attributes,callouts"]
|
||||
--------------------------------------------------
|
||||
|
|
|
|||
Binary file not shown.
|
After Width: | Height: | Size: 59 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 69 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 47 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 51 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 36 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 79 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 86 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 51 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 49 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 34 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 57 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 57 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 78 KiB |
|
|
@ -7,9 +7,9 @@ Elasticsearch is provided in the following package formats:
|
|||
`zip`/`tar.gz`::
|
||||
|
||||
The `zip` and `tar.gz` packages are suitable for installation on any system
|
||||
and are the easiest choice for getting started with Elasticsearch.
|
||||
and are the easiest choice for getting started with Elasticsearch on most systems.
|
||||
+
|
||||
<<zip-targz>> or <<windows>>
|
||||
<<zip-targz>> or <<zip-windows>>
|
||||
|
||||
`deb`::
|
||||
|
||||
|
|
@ -27,6 +27,14 @@ Elasticsearch website or from our RPM repository.
|
|||
+
|
||||
<<rpm>>
|
||||
|
||||
`msi`::
|
||||
|
||||
The `msi` package is suitable for installation on Windows 64-bit systems with at least
|
||||
.NET 4.5 framework installed, and is the easiest choice for getting started with
|
||||
Elasticsearch on Windows. MSIs may be downloaded from the Elasticsearch website.
|
||||
+
|
||||
<<windows>>
|
||||
|
||||
`docker`::
|
||||
|
||||
An image is available for running Elasticsearch as a Docker container. It ships with {xpack-ref}/index.html[X-Pack] pre-installed and may be downloaded from the Elastic Docker Registry.
|
||||
|
|
@ -48,6 +56,8 @@ Ansible:: https://github.com/elastic/ansible-elasticsearch[ansible-elasticsearch
|
|||
|
||||
include::install/zip-targz.asciidoc[]
|
||||
|
||||
include::install/zip-windows.asciidoc[]
|
||||
|
||||
include::install/deb.asciidoc[]
|
||||
|
||||
include::install/rpm.asciidoc[]
|
||||
|
|
|
|||
|
|
@ -1,9 +1,12 @@
|
|||
[[windows]]
|
||||
=== Install Elasticsearch on Windows
|
||||
=== Install Elasticsearch with MSI Windows Installer
|
||||
|
||||
Elasticsearch can be installed on Windows using the `.zip` package. This
|
||||
comes with a `elasticsearch-service.bat` command which will setup Elasticsearch to run as a
|
||||
service.
|
||||
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.
|
||||
|
|
@ -14,8 +17,8 @@ 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].
|
||||
|
||||
[[install-windows]]
|
||||
==== Download and install the `.zip` package
|
||||
[[download-msi]]
|
||||
==== Download the `.msi` package
|
||||
|
||||
ifeval::["{release-state}"=="unreleased"]
|
||||
|
||||
|
|
@ -25,33 +28,252 @@ endif::[]
|
|||
|
||||
ifeval::["{release-state}"!="unreleased"]
|
||||
|
||||
Download the `.zip` archive for Elasticsearch v{version} from: https://artifacts.elastic.co/downloads/elasticsearch/elasticsearch-{version}.zip
|
||||
|
||||
Unzip it with your favourite unzip tool. This will create a folder called
|
||||
+elasticsearch-{version}+, which we will refer to as `%ES_HOME%`. In a terminal
|
||||
window, `cd` to the `%ES_HOME%` directory, for instance:
|
||||
|
||||
["source","sh",subs="attributes"]
|
||||
----------------------------
|
||||
cd c:\elasticsearch-{version}
|
||||
----------------------------
|
||||
Download the `.msi` package for Elasticsearch v{version} from https://artifacts.elastic.co/downloads/elasticsearch/elasticsearch-{version}.msi
|
||||
|
||||
endif::[]
|
||||
|
||||
[[windows-running]]
|
||||
[[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 {xpack-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
|
||||
|
||||
Elasticsearch can be started from the command line as follows:
|
||||
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]
|
||||
["source","sh",subs="attributes,callouts"]
|
||||
--------------------------------------------
|
||||
.\bin\elasticsearch.bat
|
||||
.\bin\elasticsearch.exe
|
||||
--------------------------------------------
|
||||
|
||||
By default, Elasticsearch runs in the foreground, prints its logs to `STDOUT`,
|
||||
and can be stopped by pressing `Ctrl-C`.
|
||||
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`.
|
||||
|
||||
[[windows-configuring]]
|
||||
[[msi-installer-command-line-configuration]]
|
||||
==== Configuring Elasticsearch on the command line
|
||||
|
||||
Elasticsearch loads its configuration from the `%ES_HOME%\config\elasticsearch.yml`
|
||||
|
|
@ -61,12 +283,12 @@ file by default. The format of this config file is explained in
|
|||
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]
|
||||
["source","sh",subs="attributes,callouts"]
|
||||
--------------------------------------------
|
||||
.\bin\elasticsearch.bat -Ecluster.name=my_cluster -Enode.name=node_1
|
||||
.\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 `-Epath.logs="C:\My Logs\logs"`.
|
||||
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
|
||||
|
|
@ -74,187 +296,124 @@ such as `node.name` could be specified on the command line.
|
|||
|
||||
include::check-running.asciidoc[]
|
||||
|
||||
[[windows-service]]
|
||||
[[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
|
||||
through the `elasticsearch-service.bat` script in the `bin\` folder which allows one to
|
||||
install, remove, manage or configure the service and potentially start and
|
||||
stop the service, all from the command-line.
|
||||
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"]
|
||||
--------------------------------------------------
|
||||
c:\elasticsearch-{version}{backslash}bin>elasticsearch-service
|
||||
--------------------------------------------
|
||||
start /wait msiexec.exe /i elasticsearch-{version}.msi /qn
|
||||
--------------------------------------------
|
||||
|
||||
Usage: elasticsearch-service.bat install|remove|start|stop|manager [SERVICE_ID]
|
||||
--------------------------------------------------
|
||||
Similar to the install process, a path to a log file for the upgrade process can
|
||||
be passed using the `/l` command line argument
|
||||
|
||||
The script requires one parameter (the command to execute) followed by an
|
||||
optional one indicating the service id (useful when installing multiple
|
||||
Elasticsearch services).
|
||||
["source","sh",subs="attributes,callouts"]
|
||||
--------------------------------------------
|
||||
start /wait msiexec.exe /i elasticsearch-{version}.msi /qn /l upgrade.log
|
||||
--------------------------------------------
|
||||
|
||||
The commands available are:
|
||||
[[uninstall-msi-gui]]
|
||||
==== Uninstall using Add/Remove Programs
|
||||
|
||||
[horizontal]
|
||||
`install`:: Install Elasticsearch as a service
|
||||
The `.msi` package handles uninstallation of all directories and files added as part of installation.
|
||||
|
||||
`remove`:: Remove the installed Elasticsearch service (and stop the service if started)
|
||||
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.
|
||||
|
||||
`start`:: Start the Elasticsearch service (if installed)
|
||||
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.
|
||||
|
||||
`stop`:: Stop the Elasticsearch service (if started)
|
||||
Once opened, find the Elasticsearch installation within the list of installed applications, click
|
||||
and choose `Uninstall`:
|
||||
|
||||
`manager`:: Start a GUI for managing the installed service
|
||||
[[msi-installer-uninstall]]
|
||||
image::images/msi_installer/msi_installer_uninstall.png[]
|
||||
|
||||
Based on the architecture of the available JDK/JRE (set through `JAVA_HOME`),
|
||||
the appropriate 64-bit(x64) or 32-bit(x86) service will be installed. This
|
||||
information is made available during install:
|
||||
This will launch the uninstallation process.
|
||||
|
||||
["source","sh",subs="attributes"]
|
||||
--------------------------------------------------
|
||||
c:\elasticsearch-{version}{backslash}bin>elasticsearch-service install
|
||||
Installing service : "elasticsearch-service-x64"
|
||||
Using JAVA_HOME (64-bit): "c:\jvm\jdk1.8"
|
||||
The service 'elasticsearch-service-x64' has been installed.
|
||||
--------------------------------------------------
|
||||
[[uninstall-msi-command-line]]
|
||||
==== Uninstall using the command line
|
||||
|
||||
NOTE: While a JRE can be used for the Elasticsearch service, due to its use of a client VM (as opposed to a server JVM which offers better performance for long-running applications) its usage is discouraged and a warning will be issued.
|
||||
Uninstallation can also be performed from the command line by navigating to the directory
|
||||
containing the `.msi` package and running:
|
||||
|
||||
NOTE: The system environment variable `JAVA_HOME` should be set to the path to
|
||||
the JDK installation that you want the service to use. If you upgrade the JDK,
|
||||
you are not required to the reinstall the service but you must set the value of
|
||||
the system environment variable `JAVA_HOME` to the path to the new JDK
|
||||
installation. However, upgrading across JVM types (e.g. JRE versus SE) is not
|
||||
supported, and does require the service to be reinstalled.
|
||||
["source","sh",subs="attributes,callouts"]
|
||||
--------------------------------------------
|
||||
start /wait msiexec.exe /x elasticsearch-{version}.msi /qn
|
||||
--------------------------------------------
|
||||
|
||||
[[windows-service-settings]]
|
||||
[float]
|
||||
=== Customizing service settings
|
||||
Similar to the install process, a path to a log file for the uninstallation process can
|
||||
be passed using the `/l` command line argument
|
||||
|
||||
The Elasticsearch service can be configured prior to installation by setting the following environment variables (either using the https://technet.microsoft.com/en-us/library/cc754250(v=ws.10).aspx[set command] from the command line, or through the `System Properties->Environment Variables` GUI).
|
||||
["source","sh",subs="attributes,callouts"]
|
||||
--------------------------------------------
|
||||
start /wait msiexec.exe /x elasticsearch-{version}.msi /qn /l uninstall.log
|
||||
--------------------------------------------
|
||||
|
||||
[horizontal]
|
||||
`SERVICE_ID`::
|
||||
|
||||
A unique identifier for the service. Useful if installing multiple instances on the same machine. Defaults to `elasticsearch-service-x86` (on 32-bit Windows) or `elasticsearch-service-x64` (on 64-bit Windows).
|
||||
|
||||
`SERVICE_USERNAME`::
|
||||
|
||||
The user to run as, defaults to the local system account.
|
||||
|
||||
`SERVICE_PASSWORD`::
|
||||
|
||||
The password for the user specified in `%SERVICE_USERNAME%`.
|
||||
|
||||
`SERVICE_DISPLAY_NAME`::
|
||||
|
||||
The name of the service. Defaults to `Elasticsearch <version> %SERVICE_ID%`.
|
||||
|
||||
`SERVICE_DESCRIPTION`::
|
||||
|
||||
The description of the service. Defaults to `Elasticsearch <version> Windows Service - https://elastic.co`.
|
||||
|
||||
`JAVA_HOME`::
|
||||
|
||||
The installation directory of the desired JVM to run the service under.
|
||||
|
||||
`LOG_DIR`::
|
||||
|
||||
Log directory, defaults to `%ES_HOME%\logs`.
|
||||
|
||||
`DATA_DIR`::
|
||||
|
||||
Data directory, defaults to `%ES_HOME%\data`.
|
||||
|
||||
`CONF_DIR`::
|
||||
|
||||
Configuration file directory (which needs to include `elasticsearch.yml`
|
||||
and `log4j2.properties` files), defaults to `%ES_HOME%\conf`.
|
||||
|
||||
`ES_JAVA_OPTS`::
|
||||
|
||||
Any additional JVM system properties you may want to apply.
|
||||
|
||||
`ES_START_TYPE`::
|
||||
|
||||
Startup mode for the service. Can be either `auto` or `manual` (default).
|
||||
|
||||
`ES_STOP_TIMEOUT` ::
|
||||
|
||||
The timeout in seconds that procrun waits for service to exit gracefully. Defaults to `0`.
|
||||
|
||||
NOTE: At its core, `elasticsearch-service.bat` relies on http://commons.apache.org/proper/commons-daemon/[Apache Commons Daemon] project
|
||||
to install the service. Environment variables set prior to the service installation are copied and will be used during the service lifecycle. This means any changes made to them after the installation will not be picked up unless the service is reinstalled.
|
||||
|
||||
NOTE: On Windows, the <<heap-size,heap size>> can be configured as for
|
||||
any other Elasticsearch installation when running Elasticsearch from the
|
||||
command line, or when installing Elasticsearch as a service for the
|
||||
first time. To adjust the heap size for an already installed service,
|
||||
use the service manager: `bin\elasticsearch-service.bat manager`.
|
||||
|
||||
Using the Manager GUI::
|
||||
|
||||
It is also possible to configure the service after it's been installed using the manager GUI (`elasticsearch-service-mgr.exe`), which offers insight into the installed service, including its status, startup type, JVM, start and stop settings amongst other things. Simply invoking `elasticsearch-service.bat manager` from the command-line will open up the manager window:
|
||||
|
||||
image::images/service-manager-win.png["Windows Service Manager GUI",align="center"]
|
||||
|
||||
Most changes (like JVM settings) made through the manager GUI will require a restart of the service in order to take affect.
|
||||
|
||||
[[windows-layout]]
|
||||
==== Directory layout of `.zip` archive
|
||||
|
||||
The `.zip` package is entirely self-contained. All files and directories are,
|
||||
by default, contained within `%ES_HOME%` -- the directory created when
|
||||
unpacking the archive.
|
||||
|
||||
This is very convenient because you don't have to create any directories to
|
||||
start using Elasticsearch, and uninstalling Elasticsearch is as easy as
|
||||
removing the `%ES_HOME%` directory. However, it is advisable to change the
|
||||
default locations of the config directory, the data directory, and the logs
|
||||
directory so that you do not delete important data later on.
|
||||
|
||||
|
||||
[cols="<h,<,<m,<m",options="header",]
|
||||
|=======================================================================
|
||||
| Type | Description | Default Location | Setting
|
||||
| home
|
||||
| Elasticsearch home directory or `%ES_HOME%`
|
||||
d| Directory created by unpacking the archive
|
||||
|
|
||||
|
||||
| bin
|
||||
| Binary scripts including `elasticsearch` to start a node
|
||||
and `elasticsearch-plugin` to install plugins
|
||||
| %ES_HOME%\bin
|
||||
d|
|
||||
|
||||
| conf
|
||||
| Configuration files including `elasticsearch.yml`
|
||||
| %ES_HOME%\config
|
||||
| path.conf
|
||||
|
||||
| data
|
||||
| The location of the data files of each index / shard allocated
|
||||
on the node. Can hold multiple locations.
|
||||
| %ES_HOME%\data
|
||||
| path.data
|
||||
|
||||
| logs
|
||||
| Log files location.
|
||||
| %ES_HOME%\logs
|
||||
| path.logs
|
||||
|
||||
| plugins
|
||||
| Plugin files location. Each plugin will be contained in a subdirectory.
|
||||
| %ES_HOME%\plugins
|
||||
|
|
||||
|
||||
| repo
|
||||
| Shared file system repository locations. Can hold multiple locations. A file system repository can be placed in to any subdirectory of any directory specified here.
|
||||
d| Not configured
|
||||
| path.repo
|
||||
|
||||
|=======================================================================
|
||||
|
||||
include::next-steps.asciidoc[]
|
||||
include::next-steps.asciidoc[]
|
||||
|
|
@ -187,7 +187,12 @@ directory so that you do not delete important data later on.
|
|||
d| Not configured
|
||||
| path.repo
|
||||
|
||||
| script
|
||||
| Location of script files.
|
||||
| $ES_HOME/scripts
|
||||
| path.scripts
|
||||
|
||||
|=======================================================================
|
||||
|
||||
|
||||
include::next-steps.asciidoc[]
|
||||
include::next-steps.asciidoc[]
|
||||
|
|
@ -0,0 +1,269 @@
|
|||
[[zip-windows]]
|
||||
=== Install Elasticsearch with `.zip` on Windows
|
||||
|
||||
Elasticsearch can be installed on Windows using the `.zip` package. This
|
||||
comes with a `elasticsearch-service.bat` command which will setup Elasticsearch to run as a
|
||||
service.
|
||||
|
||||
TIP: Elasticsearch has historically been installed on Windows using the `.zip` archive.
|
||||
An <<windows, MSI installer package>> is available that provides the easiest getting started
|
||||
experience for Windows. 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].
|
||||
|
||||
[[install-windows]]
|
||||
==== Download and install the `.zip` package
|
||||
|
||||
ifeval::["{release-state}"=="unreleased"]
|
||||
|
||||
Version {version} of Elasticsearch has not yet been released.
|
||||
|
||||
endif::[]
|
||||
|
||||
ifeval::["{release-state}"!="unreleased"]
|
||||
|
||||
Download the `.zip` archive for Elasticsearch v{version} from: https://artifacts.elastic.co/downloads/elasticsearch/elasticsearch-{version}.zip
|
||||
|
||||
Unzip it with your favourite unzip tool. This will create a folder called
|
||||
+elasticsearch-{version}+, which we will refer to as `%ES_HOME%`. In a terminal
|
||||
window, `cd` to the `%ES_HOME%` directory, for instance:
|
||||
|
||||
["source","sh",subs="attributes"]
|
||||
----------------------------
|
||||
cd c:\elasticsearch-{version}
|
||||
----------------------------
|
||||
|
||||
endif::[]
|
||||
|
||||
[[windows-running]]
|
||||
==== Running Elasticsearch from the command line
|
||||
|
||||
Elasticsearch can be started from the command line as follows:
|
||||
|
||||
[source,sh]
|
||||
--------------------------------------------
|
||||
.\bin\elasticsearch.bat
|
||||
--------------------------------------------
|
||||
|
||||
By default, Elasticsearch runs in the foreground, prints its logs to `STDOUT`,
|
||||
and can be stopped by pressing `Ctrl-C`.
|
||||
|
||||
[[windows-configuring]]
|
||||
==== 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]
|
||||
--------------------------------------------
|
||||
.\bin\elasticsearch.bat -Ecluster.name=my_cluster -Enode.name=node_1
|
||||
--------------------------------------------
|
||||
|
||||
NOTE: Values that contain spaces must be surrounded with quotes. For instance `-Epath.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[]
|
||||
|
||||
[[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
|
||||
through the `elasticsearch-service.bat` script in the `bin\` folder which allows one to
|
||||
install, remove, manage or configure the service and potentially start and
|
||||
stop the service, all from the command-line.
|
||||
|
||||
["source","sh",subs="attributes,callouts"]
|
||||
--------------------------------------------------
|
||||
c:\elasticsearch-{version}{backslash}bin>elasticsearch-service.bat
|
||||
|
||||
Usage: elasticsearch-service.bat install|remove|start|stop|manager [SERVICE_ID]
|
||||
--------------------------------------------------
|
||||
|
||||
The script requires one parameter (the command to execute) followed by an
|
||||
optional one indicating the service id (useful when installing multiple
|
||||
Elasticsearch services).
|
||||
|
||||
The commands available are:
|
||||
|
||||
[horizontal]
|
||||
`install`:: Install Elasticsearch as a service
|
||||
|
||||
`remove`:: Remove the installed Elasticsearch service (and stop the service if started)
|
||||
|
||||
`start`:: Start the Elasticsearch service (if installed)
|
||||
|
||||
`stop`:: Stop the Elasticsearch service (if started)
|
||||
|
||||
`manager`:: Start a GUI for managing the installed service
|
||||
|
||||
Based on the architecture of the available JDK/JRE (set through `JAVA_HOME`),
|
||||
the appropriate 64-bit(x64) or 32-bit(x86) service will be installed. This
|
||||
information is made available during install:
|
||||
|
||||
["source","sh",subs="attributes"]
|
||||
--------------------------------------------------
|
||||
c:\elasticsearch-{version}{backslash}bin>elasticsearch-service.bat install
|
||||
Installing service : "elasticsearch-service-x64"
|
||||
Using JAVA_HOME (64-bit): "c:\jvm\jdk1.8"
|
||||
The service 'elasticsearch-service-x64' has been installed.
|
||||
--------------------------------------------------
|
||||
|
||||
NOTE: While a JRE can be used for the Elasticsearch service, due to its use of a client VM (as opposed to a server JVM which offers better performance for long-running applications) its usage is discouraged and a warning will be issued.
|
||||
|
||||
NOTE: The system environment variable `JAVA_HOME` should be set to the path to
|
||||
the JDK installation that you want the service to use. If you upgrade the JDK,
|
||||
you are not required to the reinstall the service but you must set the value of
|
||||
the system environment variable `JAVA_HOME` to the path to the new JDK
|
||||
installation. However, upgrading across JVM types (e.g. JRE versus SE) is not
|
||||
supported, and does require the service to be reinstalled.
|
||||
|
||||
[[windows-service-settings]]
|
||||
[float]
|
||||
=== Customizing service settings
|
||||
|
||||
The Elasticsearch service can be configured prior to installation by setting the following environment variables (either using the https://technet.microsoft.com/en-us/library/cc754250(v=ws.10).aspx[set command] from the command line, or through the `System Properties->Environment Variables` GUI).
|
||||
|
||||
[horizontal]
|
||||
`SERVICE_ID`::
|
||||
|
||||
A unique identifier for the service. Useful if installing multiple instances on the same machine. Defaults to `elasticsearch-service-x86` (on 32-bit Windows) or `elasticsearch-service-x64` (on 64-bit Windows).
|
||||
|
||||
`SERVICE_USERNAME`::
|
||||
|
||||
The user to run as, defaults to the local system account.
|
||||
|
||||
`SERVICE_PASSWORD`::
|
||||
|
||||
The password for the user specified in `%SERVICE_USERNAME%`.
|
||||
|
||||
`SERVICE_DISPLAY_NAME`::
|
||||
|
||||
The name of the service. Defaults to `Elasticsearch <version> %SERVICE_ID%`.
|
||||
|
||||
`SERVICE_DESCRIPTION`::
|
||||
|
||||
The description of the service. Defaults to `Elasticsearch <version> Windows Service - https://elastic.co`.
|
||||
|
||||
`JAVA_HOME`::
|
||||
|
||||
The installation directory of the desired JVM to run the service under.
|
||||
|
||||
`LOG_DIR`::
|
||||
|
||||
Log directory, defaults to `%ES_HOME%\logs`.
|
||||
|
||||
`DATA_DIR`::
|
||||
|
||||
Data directory, defaults to `%ES_HOME%\data`.
|
||||
|
||||
`CONF_DIR`::
|
||||
|
||||
Configuration file directory (which needs to include `elasticsearch.yml`
|
||||
and `log4j2.properties` files), defaults to `%ES_HOME%\conf`.
|
||||
|
||||
`ES_JAVA_OPTS`::
|
||||
|
||||
Any additional JVM system properties you may want to apply.
|
||||
|
||||
`ES_START_TYPE`::
|
||||
|
||||
Startup mode for the service. Can be either `auto` or `manual` (default).
|
||||
|
||||
`ES_STOP_TIMEOUT` ::
|
||||
|
||||
The timeout in seconds that procrun waits for service to exit gracefully. Defaults to `0`.
|
||||
|
||||
NOTE: At its core, `elasticsearch-service.bat` relies on http://commons.apache.org/proper/commons-daemon/[Apache Commons Daemon] project
|
||||
to install the service. Environment variables set prior to the service installation are copied and will be used during the service lifecycle. This means any changes made to them after the installation will not be picked up unless the service is reinstalled.
|
||||
|
||||
NOTE: On Windows, the <<heap-size,heap size>> can be configured as for
|
||||
any other Elasticsearch installation when running Elasticsearch from the
|
||||
command line, or when installing Elasticsearch as a service for the
|
||||
first time. To adjust the heap size for an already installed service,
|
||||
use the service manager: `bin\elasticsearch-service.bat manager`.
|
||||
|
||||
Using the Manager GUI::
|
||||
|
||||
It is also possible to configure the service after it's been installed using the manager GUI (`elasticsearch-service-mgr.exe`), which offers insight into the installed service, including its status, startup type, JVM, start and stop settings amongst other things. Simply invoking `elasticsearch-service.bat manager` from the command-line will open up the manager window:
|
||||
|
||||
image::images/service-manager-win.png["Windows Service Manager GUI",align="center"]
|
||||
|
||||
Most changes (like JVM settings) made through the manager GUI will require a restart of the service in order to take affect.
|
||||
|
||||
[[windows-layout]]
|
||||
==== Directory layout of `.zip` archive
|
||||
|
||||
The `.zip` package is entirely self-contained. All files and directories are,
|
||||
by default, contained within `%ES_HOME%` -- the directory created when
|
||||
unpacking the archive.
|
||||
|
||||
This is very convenient because you don't have to create any directories to
|
||||
start using Elasticsearch, and uninstalling Elasticsearch is as easy as
|
||||
removing the `%ES_HOME%` directory. However, it is advisable to change the
|
||||
default locations of the config directory, the data directory, and the logs
|
||||
directory so that you do not delete important data later on.
|
||||
|
||||
|
||||
[cols="<h,<,<m,<m",options="header",]
|
||||
|=======================================================================
|
||||
| Type | Description | Default Location | Setting
|
||||
| home
|
||||
| Elasticsearch home directory or `%ES_HOME%`
|
||||
d| Directory created by unpacking the archive
|
||||
|
|
||||
|
||||
| bin
|
||||
| Binary scripts including `elasticsearch` to start a node
|
||||
and `elasticsearch-plugin` to install plugins
|
||||
| %ES_HOME%\bin
|
||||
d|
|
||||
|
||||
| conf
|
||||
| Configuration files including `elasticsearch.yml`
|
||||
| %ES_HOME%\config
|
||||
| path.conf
|
||||
|
||||
| data
|
||||
| The location of the data files of each index / shard allocated
|
||||
on the node. Can hold multiple locations.
|
||||
| %ES_HOME%\data
|
||||
| path.data
|
||||
|
||||
| logs
|
||||
| Log files location.
|
||||
| %ES_HOME%\logs
|
||||
| path.logs
|
||||
|
||||
| plugins
|
||||
| Plugin files location. Each plugin will be contained in a subdirectory.
|
||||
| %ES_HOME%\plugins
|
||||
|
|
||||
|
||||
| repo
|
||||
| Shared file system repository locations. Can hold multiple locations. A file system repository can be placed in to any subdirectory of any directory specified here.
|
||||
d| Not configured
|
||||
| path.repo
|
||||
|
||||
| script
|
||||
| Location of script files.
|
||||
| %ES_HOME%\scripts
|
||||
| path.scripts
|
||||
|
||||
|=======================================================================
|
||||
|
||||
include::next-steps.asciidoc[]
|
||||
Loading…
Reference in New Issue