[[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-command-line>>
* <<directory-layout>>


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

To download and install Filebeat, use the commands that work with your system
(<<deb, deb>> for Debian/Ubuntu, <<rpm, rpm>> for Redhat/Centos/Fedora, <<mac,
mac>> for OS X, and <<win, win>> for Windows).

[NOTE]
==================================================
If you use Apt or Yum, you can <<setup-repositories,install Filebeat from our repositories>> to update to the newest version more easily.

See our https://www.elastic.co/downloads/beats/filebeat[download page] for other installation options, such as 32-bit images.

==================================================

[[deb]]
*deb:*

["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
------------------------------------------------

[[rpm]]
*rpm:*

["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
------------------------------------------------

[[mac]]
*mac:*

["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
------------------------------------------------

[[win]]
*win:*

. 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.

. 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`.

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>>.

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

To configure Filebeat, you edit the configuration file. For rpm and deb, you'll
find the configuration file at `/etc/filebeat/filebeat.yml`. For mac and win, look in
the archive that you just extracted. There’s also a full example configuration file
called `filebeat.full.yml` that shows all non-deprecated options.

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+.

See <<filebeat-configuration-details>> for more details about each configuration option.

[[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 <<filebeat-command-line>>). 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
----------------------------------------------------------------------

*mac:*

[source,shell]
----------------------------------------------------------------------
sudo ./filebeat -e -c filebeat.yml -d "publish"
----------------------------------------------------------------------

*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.
