//////////////////////////////////////////////////////////////////////////
//// This content is shared by all Elastic Beats. Make sure you keep the
//// descriptions here generic enough to work for all Beats that include
//// this file. When using cross references, make sure that the cross
//// references resolve correctly for any files that include this one.
//// Use the appropriate variables defined in the index.asciidoc file to
//// resolve Beat names: beatname_uc and beatname_lc
//// Use the following include to pull this content into a doc file:
//// include::../../libbeat/docs/shared-template-load.asciidoc[]
//// This content must be embedded underneath a level 3 heading.
//////////////////////////////////////////////////////////////////////////

ifndef::only-elasticsearch[]
NOTE: A connection to Elasticsearch is required to load the index template. If
the output is not Elasticsearch, you must
<<load-template-manually,load the template manually>>. 
endif::only-elasticsearch[]

In Elasticsearch, {ref}/indices-templates.html[index
templates] are used to define settings and mappings that determine how fields
should be analyzed.

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 template automatically
after successfully connecting to Elasticsearch. If the template already exists,
it's not overwritten unless you configure {beatname_uc} to do so.

[[load-template-auto]]
==== Configure template loading

By default, {beatname_uc} automatically loads the recommended template file,
+fields.yml+, if the Elasticsearch output is enabled. If you want to use the
default index template, no additional configuration is required. Otherwise, you
can change the defaults in the +{beatname_lc}.yml+ config file
to:

* **Load a different template**
+
[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.

* **Overwrite an existing template**
+
[source,yaml]
-----
setup.template.overwrite: true
-----

* **Disable automatic template loading** 
+
[source,yaml]
-----
setup.template.enabled: false
-----
+
If you disable automatic template loading, you need to
<<load-template-manually,load the template manually>>.

* **Change the index name**
+
By default, {beatname_uc} writes events to indices named
+{beatname_lc}-{version}-yyyy.MM.dd+, where `yyyy.MM.dd` is the date when the
events were indexed. To use a different name, you set the
<<index-option-es,`index`>> option in the Elasticsearch output. The value
that you specify should include the root name of the index plus version and
date information. You also need to configure the `setup.template.name` and
`setup.template.pattern` options to match the new name. For example:
+
["source","sh",subs="attributes,callouts"]
-----
output.elasticsearch.index: "customname-%{[beat.version]}-%{+yyyy.MM.dd}"
setup.template.name: "customname"
setup.template.pattern: "customname-*"
-----
ifndef::deprecate_dashboard_loading,no_dashboards[]
+
If you're using pre-built Kibana dashboards, also set the
`setup.dashboards.index` option. For example: 
+
[source, yaml]
----
setup.dashboards.index: "customname-*"
----
endif::[]

ifdef::deprecate_dashboard_loading[]
+
Remember to change the index name when you load dashboards via the Kibana UI.
endif::[]

See <<configuration-template>> for the full list of configuration options.


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

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

If you are connecting to a secured Elasticsearch cluster, make sure you've
configured credentials as described in <<{beatname_lc}-configuration>>.

If the host running {beatname_uc} does not have direct connectivity to
Elasticsearch, 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::only-elasticsearch[]
:disable_logstash: {sp}-E output.logstash.enabled=false
endif::only-elasticsearch[]

ifdef::only-elasticsearch[]
:disable_logstash:
endif::only-elasticsearch[]

ifeval::["{requires-sudo}"=="yes"]

include::./shared-note-sudo.asciidoc[]

endif::[]

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

ifdef::mac_os[]
*mac:*

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

ifdef::linux_os[]
*linux:*

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


ifdef::docker_platform[]
*docker:*

["source","sh",subs="attributes"]
----------------------------------------------------------------------
docker run {dockerimage} setup --template{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 --template{disable_logstash} -E 'output.elasticsearch.hosts=["localhost:9200"]'
----------------------------------------------------------------------
endif::win_os[]

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

If you've already used {beatname_uc} to index data into Elasticsearch,
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.

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

If the host running {beatname_uc} does not have direct connectivity to
Elasticsearch, 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
----
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 {stack-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/_template/{beatname_lc}-{stack-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/_template/{beatname_lc}-{stack-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/_template/{beatname_lc}-{stack-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/_template/{beatname_lc}-{stack-version}
----
endif::win_os[]
