[[filebeat-getting-started]]
== Getting Started With Filebeat

To get started with your own Filebeat setup, install and configure these related products:

 * Elasticsearch for storage and indexing the data.
 * Kibana for the UI.
 * Logstash (optional) for inserting data into Elasticsearch.

See {libbeat}/getting-started.html[Getting Started with Beats and the Elastic Stack] for more information.

After installing the Elastic Stack, read the following topics to learn how to install, configure, and run Filebeat:

* <<filebeat-installation>>
* <<filebeat-configuration>>
* <<config-filebeat-logstash>>
* <<filebeat-template>>
* <<filebeat-starting>>
* <<filebeat-index-pattern>>
* <<filebeat-modules-quickstart>>
* <<command-line-options>>
* <<directory-layout>>

[[filebeat-installation]]
=== Step 1: Installing Filebeat

Before running Filebeat, you need to install and configure the Elastic stack. See
{libbeat}/getting-started.html[Getting Started with Beats and the Elastic Stack].

include::../../libbeat/docs/shared-download-and-install.asciidoc[]

[[deb]]
*deb:*

ifeval::["{release-state}"=="unreleased"]

Version {version} of {beatname_uc} has not yet been released.

endif::[]

ifeval::["{release-state}"!="unreleased"]

["source","sh",subs="attributes,callouts"]
------------------------------------------------
curl -L -O https://artifacts.elastic.co/downloads/beats/filebeat/filebeat-{version}-amd64.deb
sudo dpkg -i filebeat-{version}-amd64.deb
------------------------------------------------

endif::[]

[[rpm]]
*rpm:*

ifeval::["{release-state}"=="unreleased"]

Version {version} of {beatname_uc} has not yet been released.

endif::[]

ifeval::["{release-state}"!="unreleased"]

["source","sh",subs="attributes,callouts"]
------------------------------------------------
curl -L -O https://artifacts.elastic.co/downloads/beats/filebeat/filebeat-{version}-x86_64.rpm
sudo rpm -vi filebeat-{version}-x86_64.rpm
------------------------------------------------

endif::[]

[[mac]]
*mac:*

ifeval::["{release-state}"=="unreleased"]

Version {version} of {beatname_uc} has not yet been released.

endif::[]

ifeval::["{release-state}"!="unreleased"]

["source","sh",subs="attributes,callouts"]
------------------------------------------------
curl -L -O https://artifacts.elastic.co/downloads/beats/filebeat/filebeat-{version}-darwin-x86_64.tar.gz
tar xzvf filebeat-{version}-darwin-x86_64.tar.gz
------------------------------------------------

endif::[]

[[docker]]
*docker:*

ifeval::["{release-state}"=="unreleased"]

Version {stack-version} of {beatname_uc} has not yet been released.

endif::[]

ifeval::["{release-state}"!="unreleased"]

["source", "shell", subs="attributes"]
------------------------------------------------
docker pull {dockerimage}
------------------------------------------------

endif::[]

[[win]]
*win:*

ifeval::["{release-state}"=="unreleased"]

Version {version} of {beatname_uc} has not yet been released.

endif::[]

ifeval::["{release-state}"!="unreleased"]

. Download the Filebeat Windows zip file from the
https://www.elastic.co/downloads/beats/filebeat[downloads page].

. Extract the contents of the zip file into `C:\Program Files`.

. Rename the `filebeat-<version>-windows` directory to `Filebeat`.

. Open a PowerShell prompt as an Administrator (right-click the PowerShell icon and select *Run As Administrator*). If you are running Windows XP, you may need to download and install PowerShell.

. From the PowerShell prompt, run the following commands to install Filebeat as a
Windows service:
+
[source,shell]
----------------------------------------------------------------------
PS > cd 'C:\Program Files\Filebeat'
PS C:\Program Files\Filebeat> .\install-service-filebeat.ps1
----------------------------------------------------------------------

NOTE: If script execution is disabled on your system, you need to set the execution policy for the current session to allow the script to run. For example: `PowerShell.exe -ExecutionPolicy UnRestricted -File .\install-service-filebeat.ps1`.

endif::[]

[[filebeat-configuration]]
=== Step 2: Configuring Filebeat

TIP: <<filebeat-modules-overview,Filebeat modules>> provide the fastest getting
started experience for common log formats. See <<filebeat-modules-quickstart>>
to learn how to get started with modules. If you use Filebeat modules to get
started, you can skip the content in this section, including the remaining
getting started steps, and go directly to the <<filebeat-modules-quickstart>>
page. 

include::../../libbeat/docs/shared-configuring.asciidoc[]

Here is a sample of the `filebeat` section of the `filebeat.yml` file. Filebeat uses predefined
default values for most configuration options.

[source,yaml]
-------------------------------------------------------------------------------------
filebeat.prospectors:
- input_type: log
  paths:
    - /var/log/*.log
    #- c:\programdata\elasticsearch\logs\*
-------------------------------------------------------------------------------------

To configure Filebeat:

. Define the path (or paths) to your log files.
+
For the most basic Filebeat configuration, you can define a single prospector with a single path. For example:
+
[source,yaml]
-------------------------------------------------------------------------------------
filebeat.prospectors:
- input_type: log
  paths:
    - /var/log/*.log
-------------------------------------------------------------------------------------
+
The prospector in this example harvests all files in the path `/var/log/*.log`, which means
that Filebeat will harvest all files in the directory `/var/log/` that end with `.log`. All patterns supported
by https://golang.org/pkg/path/filepath/#Glob[Golang Glob] are also supported here.
+
To fetch all files from a predefined level of subdirectories, the following pattern can be used:
`/var/log/*/*.log`. This fetches all `.log` files from the subfolders of `/var/log`. It does not
fetch log files from the `/var/log` folder itself. Currently it is not possible to recursively
fetch all files in all subdirectories of a directory.

. If you are sending output to Elasticsearch, set the IP address and port where Filebeat can find the Elasticsearch installation:
+
[source,yaml]
----------------------------------------------------------------------
output.elasticsearch:
  hosts: ["192.168.1.42:9200"]
----------------------------------------------------------------------
+
If you are sending output to Logstash, see <<config-filebeat-logstash>> instead.

TIP: To test your configuration file, change to the directory where the Filebeat
binary is installed, and run Filebeat in the foreground with the following
options specified: +./filebeat -configtest -e+. Make sure your config files are
in the path expected by Filebeat (see <<directory-layout>>). If you
installed from DEB or RPM packages, run +./filebeat.sh -configtest -e+.

Before starting Filebeat, you should look at the configuration options in the
configuration file, for example `C:\Program Files\Filebeat\filebeat.yml` or
`/etc/filebeat/filebeat.yml`. For more information about these options,
see <<filebeat-configuration-details>>.

[[config-filebeat-logstash]]
=== Step 3: Configuring Filebeat to Use Logstash

:allplatforms:
include::../../libbeat/docs/shared-logstash-config.asciidoc[]

[[filebeat-template]]
=== Step 4: Loading the Index Template in Elasticsearch

:allplatforms:
include::../../libbeat/docs/shared-template-load.asciidoc[]

[[filebeat-starting]]
=== Step 5: Starting Filebeat

Start Filebeat by issuing the appropriate command for your platform. 

NOTE: If you use an init.d script to start Filebeat on deb or rpm, you can't
specify command line flags (see <<command-line-options>>). To specify flags,
start Filebeat in the foreground.

*deb:*

[source,shell]
----------------------------------------------------------------------
sudo /etc/init.d/filebeat start
----------------------------------------------------------------------

*rpm:*

[source,shell]
----------------------------------------------------------------------
sudo /etc/init.d/filebeat start
----------------------------------------------------------------------

*docker:*

["source", "shell", subs="attributes"]
----------------------------------------------------------------------
docker run {dockerimage}
----------------------------------------------------------------------

*mac:*

[source,shell]
----------------------------------------------------------------------
sudo chown root filebeat.yml <1>
sudo ./filebeat -e -c filebeat.yml -d "publish"
----------------------------------------------------------------------
<1> You'll be running Filebeat as root, so you need to change ownership
of the configuration file (see
{libbeat}/config-file-permissions.html[Config File Ownership and Permissions]
in the _Beats Platform Reference_).

*win:*

[source,shell]
----------------------------------------------------------------------
PS C:\Program Files\Filebeat> Start-Service filebeat
----------------------------------------------------------------------

By default, Windows log files are stored in `C:\ProgramData\filebeat\Logs`.

Filebeat is now ready to send log files to your defined output.

[[filebeat-index-pattern]]
=== Step 6: Loading the Kibana Index Pattern

We don't offer prebuilt dashboards for visualizing Filebeat data. However, to make it easier for you to explore Filebeat
data in Kibana, we've created a Filebeat index pattern: `filebeat-*`. To load this pattern, you can use the script
that's provided for importing dashboards:

[source,shell]
----------------------------------------------------------------------
./scripts/import_dashboards -only-index
----------------------------------------------------------------------

For more information about running the script, see
{libbeat}/import-dashboards.html[Importing Existing Beat Dashboards] in the _Beats Platform Reference_.

After you've created the index pattern, you can select the `filebeat-*` index pattern in Kibana to explore
Filebeat data.

image:./images/filebeat-discover-tab.png[]

TIP: If you don't see `filebeat-*` in the list of available index patterns, try refreshing the page in your browser.

