elasticsearch/docs/reference/setup/install/deb.asciidoc

[[deb]]
=== Install Elasticsearch with Debian Package

The Debian package for Elasticsearch can be <<install-deb,downloaded from our website>>
or from our <<deb-repo,APT repository>>. It can be used to install
Elasticsearch on any Debian-based system such as Debian and Ubuntu.

include::license.asciidoc[]

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 includes a bundled version of https://openjdk.java.net[OpenJDK]
from the JDK maintainers (GPLv2+CE). To use your own version of Java,
see the <<jvm-version, JVM version requirements>>

[[deb-key]]
==== Import the Elasticsearch PGP Key

include::key.asciidoc[]

[source,sh]
-------------------------
wget -qO - https://artifacts.elastic.co/GPG-KEY-elasticsearch | sudo gpg --dearmor -o /usr/share/keyrings/elasticsearch-keyring.gpg
-------------------------

[[deb-repo]]
==== Installing from the APT repository

ifeval::["{release-state}"=="unreleased"]

WARNING: Version {version} of Elasticsearch has not yet been released.

endif::[]

You may need to install the `apt-transport-https` package on Debian before proceeding:

[source,sh]
--------------------------------------------------
sudo apt-get install apt-transport-https
--------------------------------------------------

Save the repository definition to  +/etc/apt/sources.list.d/elastic-{major-version}.list+:

ifeval::["{release-state}"=="released"]

["source","sh",subs="attributes,callouts"]
--------------------------------------------------
echo "deb [signed-by=/usr/share/keyrings/elasticsearch-keyring.gpg] https://artifacts.elastic.co/packages/{major-version}/apt stable main" | sudo tee /etc/apt/sources.list.d/elastic-{major-version}.list
--------------------------------------------------

ifeval::["{release-state}"=="prerelease"]

["source","sh",subs="attributes,callouts"]
--------------------------------------------------
echo "deb [signed-by=/usr/share/keyrings/elasticsearch-keyring.gpg] https://artifacts.elastic.co/packages/{major-version}-prerelease/apt stable main" | sudo tee /etc/apt/sources.list.d/elastic-{major-version}.list
--------------------------------------------------

endif::[]


[NOTE]
==================================================

These instructions do not use `add-apt-repository` for several reasons:

. `add-apt-repository` adds entries to the system `/etc/apt/sources.list` file
  rather than a clean per-repository file in `/etc/apt/sources.list.d`
. `add-apt-repository` is not part of the default install on many distributions
  and requires a number of non-default dependencies.
. Older versions of `add-apt-repository` always add a `deb-src` entry which
  will cause errors because we do not provide a source package. If you have added
  the `deb-src` entry, you will see an error like the following until you delete
  the `deb-src` line:

    Unable to find expected entry 'main/source/Sources' in Release file
    (Wrong sources.list entry or malformed file)

==================================================

You can install the Elasticsearch Debian package with:

[source,sh]
--------------------------------------------------
sudo apt-get update && sudo apt-get install elasticsearch
--------------------------------------------------

[WARNING]
==================================================
If two entries exist for the same Elasticsearch repository, you will see an error like this during `apt-get update`:

["literal",subs="attributes,callouts"]

Duplicate sources.list entry https://artifacts.elastic.co/packages/{major-version}/apt/ ...`

Examine +/etc/apt/sources.list.d/elasticsearch-{major-version}.list+ for the duplicate entry or locate the duplicate entry amongst the files in `/etc/apt/sources.list.d/` and the `/etc/apt/sources.list` file.
==================================================

endif::[]

include::skip-set-kernel-parameters.asciidoc[]

[[install-deb]]
==== Download and install the Debian package manually

ifeval::["{release-state}"=="unreleased"]

WARNING: Version {version} of Elasticsearch has not yet been released.

endif::[]

The Debian package for Elasticsearch v{version} can be downloaded from the website and installed as follows:

["source","sh",subs="attributes"]
--------------------------------------------
wget https://artifacts.elastic.co/downloads/elasticsearch/elasticsearch-{version}-amd64.deb
wget https://artifacts.elastic.co/downloads/elasticsearch/elasticsearch-{version}-amd64.deb.sha512
shasum -a 512 -c elasticsearch-{version}-amd64.deb.sha512 <1>
sudo dpkg -i elasticsearch-{version}-amd64.deb
--------------------------------------------
<1> Compares the SHA of the downloaded Debian package and the published checksum, which should output
    `elasticsearch-{version}-amd64.deb: OK`.

// Set a `distro` attribute so we can reuse files containing anchors
:distro: deb
[id="deb-security-configuration"]
include::package-security.asciidoc[]

ifdef::include-xpack[]
[role="xpack"]
[[deb-enable-indices]]
==== Enable automatic creation of system indices

include::xpack-indices.asciidoc[]

endif::include-xpack[]

[id="{distro}-running-systemd"]
include::systemd.asciidoc[]

[[deb-check-running]]

:es-conf:       /etc/elasticsearch
:slash:        /

include::check-running.asciidoc[]

[[deb-configuring]]
==== Configuring Elasticsearch

include::etc-elasticsearch.asciidoc[]

The Debian package also has a system configuration file (`/etc/default/elasticsearch`),
which allows you to set the following parameters:

include::sysconfig-file.asciidoc[]

NOTE: Distributions that use `systemd` require that system resource limits be
configured via `systemd` rather than via the `/etc/sysconfig/elasticsearch`
file. See <<systemd>> for more information.

include::connect-clients.asciidoc[]

[[deb-layout]]
==== Directory layout of Debian package

The Debian package places config files, logs, and the data directory in the appropriate
locations for a Debian-based system:


[cols="<h,<,<m,<m",options="header",]
|=======================================================================
| Type | Description | Default Location | Setting
| home
  | Elasticsearch home directory or `$ES_HOME`
  | /usr/share/elasticsearch
 d|

| bin
  | Binary scripts including `elasticsearch` to start a node
    and `elasticsearch-plugin` to install plugins
  | /usr/share/elasticsearch/bin
 d|

| conf
  | Configuration files including `elasticsearch.yml`
  | /etc/elasticsearch
  | <<config-files-location,ES_PATH_CONF>>

| conf
  | Environment variables including heap size, file descriptors.
  | /etc/default/elasticsearch
 d|

| conf
| Generated TLS keys and certificates for the transport and http layer.
| /etc/elasticsearch/certs
d|

| data
  | The location of the data files of each index / shard allocated
    on the node.
  | /var/lib/elasticsearch
  | path.data

| jdk
  | The bundled Java Development Kit used to run Elasticsearch. Can
    be overridden by setting the `ES_JAVA_HOME` environment variable
    in `/etc/default/elasticsearch`.
  | /usr/share/elasticsearch/jdk
 d|

| logs
  | Log files location.
  | /var/log/elasticsearch
  | path.logs

| plugins
  | Plugin files location. Each plugin will be contained in a subdirectory.
  | /usr/share/elasticsearch/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::security-files-reference.asciidoc[]
include::next-steps.asciidoc[]