[id="{beatname_lc}-template"]
== Load the {es} index template

{es} uses {ref}/index-templates.html[index templates] to define:

* Settings that control the behavior of your indices. The settings include the
lifecycle policy used to manage indices as they grow and age.
* Mappings that determine how fields are analyzed. Each mapping sets the
{ref}/mapping-types.html[{es} datatype] to use for a specific data field.

The recommended index template file for {beatname_uc} is installed by the
{beatname_uc} packages. If you accept the default configuration in the
+{beatname_lc}.yml+ config file, {beatname_uc} loads the {ref}/index-templates.html[composable template] automatically
after successfully connecting to {es}. If the template already exists,
it's not overwritten unless you configure {beatname_uc} to do so.

ifndef::no-output-logstash[]
NOTE: A connection to {es} is required to load the index template. If
the output is not {es} (or {ess}), you must
<<load-template-manually,load the template manually>>.
endif::[]

This page shows how to change the default template loading behavior to:

* <<load-custom-template>>
* <<overwrite-template>>
* <<disable-template-loading>>
* <<load-template-manually>>

For a full list of template setup options, see <<configuration-template>>.

[float]
[[load-custom-template]]
=== Load your own index template

To load your own composable index template, set the following options:

[source,yaml]
-----
setup.template.name: "your_template_name"
setup.template.fields: "path/to/fields.yml"
-----

If the template already exists, it’s not overwritten unless you configure
{beatname_uc} to do so.

If your template is still in the legacy format, please set `setup.template.type` to
`legacy`. Please, convert your index template to the composable format, because
in the future support for legacy templates is going to be removed.

[float]
[[overwrite-template]]
=== Overwrite an existing index template

WARNING: Do not enable this option for more than one instance of {beatname_uc}. If you start
multiple instances at the same time, it can overload your {es} with too many
template update requests.

To overwrite a template that's already loaded into {es}, set:

[source,yaml]
-----
setup.template.overwrite: true
-----

[float]
[[disable-template-loading]]
=== Disable automatic index template loading

You may want to disable automatic template loading if you're using an output
other than {es} and need to load the template manually. To disable automatic
template loading, set:

[source,yaml]
-----
setup.template.enabled: false
-----

If you disable automatic template loading, you must load the index template
manually.

[float]
[[load-template-manually]]
=== Load the index template manually

To load the index template manually, run the <<setup-command,`setup`>> command.
A connection to {es} is required.  If another output is enabled, you need to
temporarily disable that output and enable {es} by using the `-E` option.
ifndef::no-output-logstash[]
The examples here assume that Logstash output is enabled.
endif::[]
You can omit the `-E` flags if {es} output is already enabled.

ifndef::apm-server[]
If you are connecting to a secured {es} cluster, make sure you've
configured credentials as described in the <<{beatname_lc}-installation-configuration>>.
endif::[]

If the host running {beatname_uc} does not have direct connectivity to
{es}, see <<load-template-manually-alternate>>.

ifndef::win_only[]
To load the template, use the appropriate command for your system.
endif::win_only[]

ifdef::win_only[]
To load the template:
endif::win_only[]

ifndef::no-output-logstash[]
:disable_logstash: {sp}-E output.logstash.enabled=false
endif::[]

ifdef::no-output-logstash[]
:disable_logstash:
endif::[]

ifdef::requires-sudo[]
include::{libbeat-dir}/shared-note-sudo.asciidoc[]
endif::requires-sudo[]

ifdef::deb_os,rpm_os[]
*deb and rpm:*
["source","sh",subs="attributes"]
----
{beatname_lc} setup --index-management{disable_logstash} -E 'output.elasticsearch.hosts=["localhost:9200"]'
----
endif::deb_os,rpm_os[]

ifdef::mac_os[]
*mac:*

["source","sh",subs="attributes"]
----
./{beatname_lc} setup --index-management{disable_logstash} -E 'output.elasticsearch.hosts=["localhost:9200"]'
----

*brew:*

["source","sh",subs="attributes"]
----
{beatname_lc} setup --index-management{disable_logstash} -E 'output.elasticsearch.hosts=["localhost:9200"]'
----
endif::mac_os[]

ifdef::linux_os[]
*linux:*

["source","sh",subs="attributes"]
----
./{beatname_lc} setup --index-management{disable_logstash} -E 'output.elasticsearch.hosts=["localhost:9200"]'
----
endif::linux_os[]


ifdef::docker_platform[]
*docker:*

["source","sh",subs="attributes"]
----------------------------------------------------------------------
docker run {dockerimage} setup --index-management{disable_logstash} -E 'output.elasticsearch.hosts=["localhost:9200"]'
----------------------------------------------------------------------
endif::docker_platform[]

ifdef::win_os[]
ifndef::win_only[]
*win:*
endif::win_only[]

Open a PowerShell prompt as an Administrator (right-click the PowerShell icon
and select *Run As Administrator*).

From the PowerShell prompt, change to the directory where you installed {beatname_uc},
and run:

["source","sh",subs="attributes"]
----------------------------------------------------------------------
PS > .{backslash}{beatname_lc}.exe setup --index-management{disable_logstash} -E 'output.elasticsearch.hosts=["localhost:9200"]'
----------------------------------------------------------------------
endif::win_os[]

[float]
[[force-kibana-new]]
==== Force Kibana to look at newest documents

If you've already used {beatname_uc} to index data into {es},
the index may contain old documents. After you load the index template,
you can delete the old documents from +{beatname_lc}-*+ to force Kibana to look
at the newest documents.

Use this command:

ifdef::deb_os,rpm_os[]
*deb and rpm:*

["source","sh",subs="attributes"]
----------------------------------------------------------------------
curl -XDELETE 'http://localhost:9200/{beatname_lc}-*'
----------------------------------------------------------------------
endif::deb_os,rpm_os[]

ifdef::mac_os[]
*mac:*

["source","sh",subs="attributes"]
----------------------------------------------------------------------
curl -XDELETE 'http://localhost:9200/{beatname_lc}-*'
----------------------------------------------------------------------
endif::mac_os[]

ifdef::linux_os[]
*linux:*

["source","sh",subs="attributes"]
----------------------------------------------------------------------
curl -XDELETE 'http://localhost:9200/{beatname_lc}-*'
----------------------------------------------------------------------
endif::linux_os[]

ifdef::win_os[]
ifndef::win_only[]
*win:*
endif::win_only[]

["source","sh",subs="attributes"]
----------------------------------------------------------------------
PS > Invoke-RestMethod -Method Delete "http://localhost:9200/{beatname_lc}-*"
----------------------------------------------------------------------
endif::win_os[]

This command deletes all indices that match the pattern +{beat_default_index_prefix}-*+.
Before running this command, make sure you want to delete all indices that match
the pattern.

[float]
[[load-template-manually-alternate]]
=== Load the index template manually (alternate method)

If the host running {beatname_uc} does not have direct connectivity to
{es}, you can export the index template to a file, move it to a
machine that does have connectivity, and then install the template manually.

To export the index template, run:

ifdef::deb_os,rpm_os[]
*deb and rpm:*

["source","sh",subs="attributes"]
----
{beatname_lc} export template > {beatname_lc}.template.json
----
endif::deb_os,rpm_os[]

ifdef::mac_os[]
*mac:*

["source","sh",subs="attributes"]
----
./{beatname_lc} export template > {beatname_lc}.template.json
----

*brew:*

["source","sh",subs="attributes"]
----
{beatname_lc} export template > {beatname_lc}.template.json
----
endif::mac_os[]

ifdef::linux_os[]
*linux:*

["source","sh",subs="attributes"]
----
./{beatname_lc} export template > {beatname_lc}.template.json
----
endif::linux_os[]

ifdef::win_os[]
ifndef::win_only[]
*win:*
endif::win_only[]

["source","sh",subs="attributes"]
----
PS > .{backslash}{beatname_lc}.exe export template --es.version {version} | Out-File -Encoding UTF8 {beatname_lc}.template.json
----
endif::win_os[]

To install the template, run:

ifdef::deb_os,rpm_os[]
*deb and rpm:*

["source","sh",subs="attributes"]
----
curl -XPUT -H 'Content-Type: application/json' http://localhost:9200/_index_template/{beatname_lc}-{version} -d@{beatname_lc}.template.json
----
endif::deb_os,rpm_os[]

ifdef::mac_os[]
*mac:*

["source","sh",subs="attributes"]
----
curl -XPUT -H 'Content-Type: application/json' http://localhost:9200/_index_template/{beatname_lc}-{version} -d@{beatname_lc}.template.json
----
endif::mac_os[]

ifdef::linux_os[]
*linux:*

["source","sh",subs="attributes"]
----
curl -XPUT -H 'Content-Type: application/json' http://localhost:9200/_index_template/{beatname_lc}-{version} -d@{beatname_lc}.template.json
----
endif::linux_os[]

ifdef::win_os[]
ifndef::win_only[]
*win:*
endif::win_only[]

["source","sh",subs="attributes"]
----
PS > Invoke-RestMethod -Method Put -ContentType "application/json" -InFile {beatname_lc}.template.json -Uri http://localhost:9200/_index_template/{beatname_lc}-{version}
----
endif::win_os[]
