//////////////////////////////////////////////////////////////////////////
//// 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:
//// :standalone:
//// include::../../libbeat/docs/yaml.asciidoc[]
//// Specify :standalone: when this file is pulled into and index. When
//// the file is embedded in another file, do no specify :standalone:
//////////////////////////////////////////////////////////////////////////

ifdef::standalone[]

[[yaml-tips]]
== YAML Tips and Gotchas

endif::[]

The configuration file uses http://yaml.org/[YAML] for its syntax. When you edit the
file to modify configuration settings, there are a few things that you should know.

[float]
=== Use Spaces for Indentation

Indentation is meaningful in YAML. Make sure that you use spaces, rather than tab characters, to indent sections.

In the default configuration files and in all the examples in the documentation,
we use 2 spaces per indentation level. We recommend you do the same.

[float]
=== Look at the Default Config File for Structure

The best way to understand where to define a configuration option is by looking
at the provided sample configuration files. The configuration files contain most
of the default configurations that are available for the Beat. To change a setting,
simply uncomment the line and change the values.

[float]
=== Test Your Config File

You can test your configuration file to verify that the structure is valid.
Simply change to the directory where the binary is installed, and run
the Beat in the foreground with the `-configtest` flag specified. For example:

ifdef::allplatforms[]

["source","shell",subs="attributes"]
----------------------------------------------------------------------
{beatname_lc} -c {beatname_lc}.yml -configtest
----------------------------------------------------------------------

endif::allplatforms[]

ifdef::win[]

["source","shell",subs="attributes"]
----------------------------------------------------------------------
.\winlogbeat.exe -c .\winlogbeat.yml -configtest -e
----------------------------------------------------------------------

endif::win[]

You'll see a message if the Beat finds an error in the file.

[float]
=== Wrap Regular Expressions in Single Quotation Marks

If you need to specify a regular expression in a YAML file, it's a good idea to wrap the regular expression in single quotation marks to work around YAML's tricky rules for string escaping.

For more information about YAML, see http://yaml.org/.

[float]
[[wrap-paths-in-quotes]]
=== Wrap Paths in Single Quotation Marks

Windows paths in particular sometimes contain spaces or characters, such as drive
letters or triple dots, that may be misinterpreted by the YAML parser.

To avoid this problem, it's a good idea to wrap paths in single quotation marks.

[float]
[[avoid-leading-zeros]]
=== Avoid Using Leading Zeros in Numeric Values

If you use a leading zero (for example, `09`) in a numeric field without
wrapping the value in single quotation marks, the value may be interpreted
incorrectly by the YAML parser. If the value is a valid octal, it's converted
to an integer. If not, it's converted to a float.

To prevent unwanted type conversions, avoid using leading zeros in field values,
or wrap the values in single quotation marks.

