//////////////////////////////////////////////////////////////////////////
//// 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[]
//// If you want to include conditional content, you also need to
//// add the following doc attribute definition  before the
//// include statement so that you have:
//// :allplatforms:
//// include::../../libbeat/docs/shared-template-load.asciidoc[]
//// This content must be embedded underneath a level 3 heading.
//////////////////////////////////////////////////////////////////////////


In Elasticsearch, {elasticsearch}/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 for template loading 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.

If you want to disable automatic template loading, or you want to load your own template, 
you can change the settings for template loading in the {beatname_uc} configuration file. If you 
choose to disable automatic template loading, you need to load the template manually. 
For more information, see:

* <<load-template-auto>> - supported for Elasticsearch output only
* <<load-template-manually>> - required for Logstash output

[[load-template-auto]]
==== Configuring Template Loading

By default, {beatname_uc} automatically loads the recommended template file, +{beatname_lc}.template.json+,
if Elasticsearch output is enabled. You can configure {beatname_lc} to load a different template
by adjusting the `template.name` and `template.path` options in +{beatname_lc}.yml+ file:

["source","yaml",subs="attributes,callouts"]
----------------------------------------------------------------------
output.elasticsearch:
  hosts: ["localhost:9200"]
  template.name: "{beatname_lc}"
  template.path: "{beatname_lc}.template.json"
  template.overwrite: false
----------------------------------------------------------------------

By default, if a template already exists in the index, it is not overwritten. To overwrite an existing
template, set `template.overwrite: true` in the configuration file.

To disable automatic template loading, comment out the template part under the Elasticsearch output.

The options for auto loading the template are not supported if you are using the
Logstash output.

[[load-template-manually]]
==== Loading the Template Manually

If you disable automatic template loading, you need to run the following command to load the template:

ifdef::allplatforms[]

*deb or rpm:*

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

*mac:*

["source","sh",subs="attributes,callouts"]
----------------------------------------------------------------------
cd {beatname_lc}-{version}-darwin-x86_64
curl -H 'Content-Type: application/json' -XPUT 'http://localhost:9200/_template/{beatname_lc}' -d@{beatname_lc}.template.json
----------------------------------------------------------------------

*docker:*

["source", "sh", subs="attributes"]
----------------------------------------------------------------------
docker run --rm {dockerimage} curl -H 'Content-Type: application/json' -XPUT 'http://localhost:9200/_template/{beatname_lc}' -d@{beatname_lc}.template.json
----------------------------------------------------------------------

*win:*

endif::allplatforms[]

["source","sh",subs="attributes,callouts"]
----------------------------------------------------------------------
PS C:\Program Files{backslash}{beatname_uc}> Invoke-WebRequest -Method Put -InFile {beatname_lc}.template.json -Uri  http://localhost:9200/_template/{beatname_lc}?pretty -ContentType application/json
----------------------------------------------------------------------

where `localhost:9200` is the IP and port where Elasticsearch is listening.

NOTE: 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:

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