[[installation]]
= Installation

[partintro]
--
Curator can be installed in a variety of ways, depending on what meets your
needs.  It is important to note that Curator only requires access to a client
node in the Elasticsearch cluster to work.  It need not be installed on one of
the nodes in the cluster if you do not want it that way.

IMPORTANT: If you plan on using SSL/TLS to connect to Elasticsearch, you may
  encounter issues with older versions of Python and outdated libraries.  The
  binary packages have been compiled with up-to-date versions for your
  convenience. See the <<security,security>> page for more information.

* <<pip,pip>>, the easiest way to use and upgrade.
* <<apt-repository,APT Repository>>, installs a single, binary package!
* <<yum-repository,YUM Repository>>, installs a single, binary package!
* <<windows-zip,Windows Zip Package>>
* <<windows-msi,Windows MSI Installer>>
* <<python-source,Source Code>>
--

[[pip]]
== pip
This installation procedure utilizes
https://pip.pypa.io/en/latest/installing.html[python pip], and requires that the
target machine has internet connectivity.

---------------------------------
pip install elasticsearch-curator
---------------------------------

=== Upgrading with pip

If you already have Elasticsearch Curator installed, and want to upgrade to the
latest version, use the `-U` flag:

------------------------------------
pip install -U elasticsearch-curator
------------------------------------

=== Installing a specific version with pip

The `-U` flag uninstalls the current version (if any), then installs the latest
version, or a specified one.  Specify a specific version by adding `==` followed
by the version you'd like to install, like this:

-------------------------------------------
pip install -U elasticsearch-curator==3.5.1
-------------------------------------------

=== System-wide vs. User-only installation

The above commands each imply a system-wide installation.  This usually
requires super-user access, or the `sudo` command.  There is a way to install
Curator into a path for just the current user, using the `--user` flag.

----------------------------------------
pip install --user elasticsearch-curator
----------------------------------------

This will result in the `curator` end-point being installed in the current
user's home directory, in the `.local` directory, in the `bin` subdirectory. The
full path might look something like this:

-----------------------------
/home/user/.local/bin/curator
-----------------------------

You can make an alias or a symlink to this so you can call it more easily.

The `--user` flag can also be used in conjunction with the `-U` flag:

----------------------------------------
pip install -U --user elasticsearch-curator==3.5.1
----------------------------------------

&nbsp;


[[apt-repository]]
== APT repository

We use the PGP key
http://pgp.mit.edu/pks/lookup?op=vindex&search=0xD27D666CD88E42B4[D88E42B4],
Elastic's Signing Key, with fingerprint

    4609 5ACC 8548 582C 1A26 99A9 D27D 666C D88E 42B4

to sign all our packages. PGP is available from http://pgp.mit.edu.

=== Signing Key

Download and install the Public Signing Key:

[source,sh]
--------------------------------------------------
wget -qO - https://packages.elastic.co/GPG-KEY-elasticsearch | sudo apt-key add -
--------------------------------------------------

=== Direct Package Download Link

* https://packages.elastic.co/curator/{curator_major}/debian/pool/main/p/python/elasticsearch-curator_{curator_version}_amd64.deb[Elasticsearch Curator {curator_version} Binary Package (DEB)]

=== Repository Configuration

Add the following in your `/etc/apt/sources.list.d/` directory in a file with a
`.list` suffix, for example `curator.list`

["source","sh",subs="attributes,callouts"]
--------------------------------------------------
deb http://packages.elastic.co/curator/{curator_major}/debian stable main
--------------------------------------------------

After running `sudo apt-get update`, the repository is ready for use.

[WARNING]
==================================================
Use the file edit method described above to add the Curator repository.  Do not
use `add-apt-repository` as it will add a `deb-src` entry as well, but we do not
provide a source package. If you have added the `deb-src` entry, you will see an
error like the following:

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

Just delete the `deb-src` entry from the `/etc/apt/sources.list.d/curator.list`
file and the installation should work as expected.
==================================================

[[apt-binary]]
=== Binary Package Installation

Starting with version 4.1.2, Curator comes with a binary version.  What this
really means is that the source is compiled, and all required libraries are
bundled with the `curator` binary, so there are no conflicts.

The binary packages resulting from the creation process have been tested on
Debian 8, and Ubuntu 12.04, 14.04, & 16.04.  It was also tested on Debian 7, but
that failed due to a libc library mismatch. This binary package may work on
other similar or derivative variants, but they have not been tested.

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

This will install the necessary files into `/opt/elasticsearch-curator` and
make a symlink at `/usr/bin/curator` that points to the `curator` binary in the
aforementioned directory.

[WARNING]
====================================================
The `elasticsearch-curator` binary package cannot coexist with the older
`python-elasticsearch-curator` packages.  This collision is explicitly defined
in packages since 4.1.2, but not in previous packages.  If it is installed, you
_must_ uninstall the `python-elasticsearch-curator` package before installing
the `elasticsearch-curator` binary package.
====================================================

[[yum-repository]]
== YUM repository

We use the PGP key
http://pgp.mit.edu/pks/lookup?op=vindex&search=0xD27D666CD88E42B4[D88E42B4],
Elastic's Signing Key, with fingerprint

    4609 5ACC 8548 582C 1A26 99A9 D27D 666C D88E 42B4

to sign all our packages. It is available from http://pgp.mit.edu.

=== Signing Key

Download and install the public signing key:

[source,sh]
--------------------------------------------------
rpm --import https://packages.elastic.co/GPG-KEY-elasticsearch
--------------------------------------------------

=== Direct Package Download Link

* https://packages.elastic.co/curator/{curator_major}/centos/6/Packages/elasticsearch-curator-{curator_version}-1.x86_64.rpm[Elasticsearch Curator {curator_version} RHEL/CentOS 6 Binary Package (RPM)]
* https://packages.elastic.co/curator/{curator_major}/centos/7/Packages/elasticsearch-curator-{curator_version}-1.x86_64.rpm[Elasticsearch Curator {curator_version} RHEL/CentOS 7 Binary Package (RPM)]

=== Repository Configuration

Add the following in your `/etc/yum.repos.d/` directory in a file with a `.repo`
suffix, for example `curator.repo`

[WARNING]
========================================
The repositories are different for CentOS/RHEL 6 and 7 due to library and path
differences.  Be sure to use the correct version for your system!

RHEL/CentOS 6:
["source","sh",subs="attributes,callouts"]
--------------------------------------------------
[curator-{curator_major}]
name=CentOS/RHEL 6 repository for Elasticsearch Curator {curator_major}.x packages
baseurl=http://packages.elastic.co/curator/{curator_major}/centos/6
gpgcheck=1
gpgkey=http://packages.elastic.co/GPG-KEY-elasticsearch
enabled=1
--------------------------------------------------

RHEL/CentOS 7:
["source","sh",subs="attributes,callouts"]
--------------------------------------------------
[curator-{curator_major}]
name=CentOS/RHEL 7 repository for Elasticsearch Curator {curator_major}.x packages
baseurl=http://packages.elastic.co/curator/{curator_major}/centos/7
gpgcheck=1
gpgkey=http://packages.elastic.co/GPG-KEY-elasticsearch
enabled=1
--------------------------------------------------
=========================================

[[yum-binary]]
=== Binary Package Installation

Starting with version 4.1.2, Curator comes with a binary version.  What this
really means is that the source is compiled, and all required libraries are
bundled with the `curator` binary, so there are no conflicts.

There are separate binary packages for RedHat variants. The binary packages
resulting from the creation process have been tested on CentOS 6 & 7, with a
different binary for each. They may work on similar variants and/or derivatives,
but they have not been tested.

[source,sh]
----------------------------------------
yum install elasticsearch-curator
----------------------------------------

This will install the necessary files into `/opt/elasticsearch-curator` and
make a symlink at `/usr/bin/curator` that points to the `curator` binary in the
aforementioned directory.

[WARNING]
====================================================
The `elasticsearch-curator` binary package cannot coexist with the older
`python-elasticsearch-curator` packages.  This collision is explicitly defined
in packages since 4.1.2, but not in previous packages.  If it is installed, you
_must_ uninstall the `python-elasticsearch-curator` package before installing
the `elasticsearch-curator` binary package.
====================================================

[[windows-zip]]
== Windows Binary Zip Package
If you do not wish to install and maintain Python on Windows, there is a
compiled binary version available.  It is in a directory with EXE
files and all necessary libraries that Python requires.  You can navigate to the
directory and run the `curator` command just as you otherwise would.

WARNING: If you do have Python installed, do not uncompress the zip file into
your Python directory.  It can cause library path collisions which will prevent
Curator from properly functioning.

* https://packages.elastic.co/curator/{curator_major}/windows/curator-{curator_version}-win32.zip[Download Curator]
** https://packages.elastic.co/curator/{curator_major}/windows/curator-{curator_version}-win32.zip.md5.txt[MD5]
** https://packages.elastic.co/curator/{curator_major}/windows/curator-{curator_version}-win32.zip.sha1.txt[SHA1]


[[windows-msi]]
== Windows MSI Installer
There is now a rudimentary MSI installer available for you to try.  One known
issue is that in-place upgrades are not possible.  Subsequent installs will be
side-by-side.  The recommended course of action is to uninstall the old version,
then install the new one.

The installation will default to `"C:\Program Files (x86)\elasticsearch-curator"`.
The same binaries and libraries found in the Windows Binary Package will be installed
into this directory.

* https://packages.elastic.co/curator/{curator_major}/windows/elasticsearch-curator-{curator_version}-win32.msi[Download Curator Installer]
** https://packages.elastic.co/curator/{curator_major}/windows/elasticsearch-curator-{curator_version}-win32.msi.md5.txt[MD5]
** https://packages.elastic.co/curator/{curator_major}/windows/elasticsearch-curator-{curator_version}-win32.msi.sha1.txt[SHA1]


[[python-source]]
== Installation from source

Installing or Curator from source is also possible.  In order to do so requires
that all dependent libraries are installed first.

If you have `pip` installed, then you can install from a gzipped file.  If not,
you have to uncompress the gzipped file and run `python setup.py install`.

That might look like this:

[source,sh]
--------------------------------------
wget https://pypi.python.org/packages/source/p/package/package-#.#.#.tar.gz
tar zxf package-#.#.#.tar.gz
cd package-#.#.#
python setup.py install
--------------------------------------

The dependencies are as follows

=== setuptools

Download https://bootstrap.pypa.io/ez_setup.py[ez_setup.py] and run it using the
target Python version. The script will download the appropriate version and
install it for you:

[source,sh]
-----------
wget https://bootstrap.pypa.io/ez_setup.py -O - | python
-----------

Note that you will need to invoke the command with superuser privileges to
install to the system Python:

[source,sh]
-----------
wget https://bootstrap.pypa.io/ez_setup.py -O - | sudo python
-----------

Alternatively, setuptools may be installed to a user-local path:

[source,sh]
-----------
wget https://bootstrap.pypa.io/ez_setup.py -O - | python - --user
-----------

&nbsp;

=== Urllib3
Download and install the https://github.com/shazow/urllib3[urllib3] dependency
(1.8.3 or greater):

. `wget https://pypi.python.org/packages/source/u/urllib3/urllib3-1.12.tar.gz`
. `pip install urllib3-1.12.tar.gz`

or uncompress and run `python setup.py install`

&nbsp;

=== click
Download and install the http://click.pocoo.org/[click] dependency (6.0 or
greater):

. `wget https://pypi.python.org/packages/source/c/click/click-6.3.tar.gz -O click-6.3.tar.gz`
. `pip install click-6.3.tar.gz`

or uncompress and run `python setup.py install`

&nbsp;

=== certifi
Download and install the `certifi` dependency.  Always use the most recent
version:

. `wget https://github.com/certifi/python-certifi/archive/2016.09.26.tar.gz -O certifi.tar.gz`
. `pip install certifi.tar.gz`

&nbsp;

=== PyYAML
Download and install the http://pyyaml.org/wiki/PyYAML/[PyYAML] dependency (3.10
or greater):

. `wget http://pyyaml.org/download/pyyaml/PyYAML-3.11.tar.gz -O PyYAML-3.11.tar.gz`
. `pip install PyYAML-3.11.tar.gz`

or uncompress and run `python setup.py install`

&nbsp;

=== voluptuous
Download and install the https://github.com/alecthomas/voluptuous[voluptuous]
dependency (0.9.3 or greater):

. `wget https://github.com/alecthomas/voluptuous/archive/0.9.3.tar.gz`
. `pip install 0.9.3.tar.gz`

or uncompress and run `python setup.py install`

&nbsp;

=== elasticsearch (python module)
Download and install the https://github.com/elastic/elasticsearch-py[elasticsearch-py] dependency:

. `wget https://github.com/elastic/elasticsearch-py/archive/`+pass:attributes[{es_py_version}].tar.gz -O elasticsearch-py.tar.gz+
. `pip install elasticsearch-py.tar.gz`

or uncompress and run `python setup.py install`

&nbsp;

=== elasticsearch-curator (python module)
Download and install Curator:

. `wget https://github.com/elastic/curator/archive/v`+pass:attributes[{curator_version}].tar.gz -O elasticsearch-curator.tar.gz+
. `pip install elasticsearch-curator.tar.gz`

or uncompress and run `python setup.py install`.  At this point you could also
run `run_curator.py` from the source directory as well.