:modulename: nginx

//TODO: Remove release-state override before merging.

[id="{beatname_lc}-installation-configuration"]
== {beatname_uc} quick start: installation and configuration

++++
<titleabbrev>Quick start: installation and configuration</titleabbrev>
++++

This guide describes how to get started quickly with log collection.
You'll learn how to:

* install {beatname_uc} on each system you want to monitor
* specify the location of your log files
* parse log data into fields and send it to {es}
* visualize the log data in {kib}

[role="screenshot"]
image::./images/kibana-system.png[{beatname_uc} System dashboard]

//TODO: We should replace this with an nginx dashboard rather than system

[float]
=== Before you begin

You need {es} for storing and searching your data, and {kib} for visualizing and
managing it.

include::{libbeat-dir}/tab-widgets/spinup-stack-widget.asciidoc[]

[float]
[[installation]]
=== Step 1: Install {beatname_uc}

Install {beatname_uc} on all the servers you want to monitor.

To download and install {beatname_uc}, use the commands that work with your
system:

include::{libbeat-dir}/tab-widgets/install-widget.asciidoc[]

[float]
[[other-installation-options]]
==== Other installation options

* <<setup-repositories,APT or YUM>>
* https://www.elastic.co/downloads/beats/{beatname_lc}[Download page]
* <<running-on-docker,Docker>>
* <<running-on-kubernetes,Kubernetes>>
* <<running-on-cloudfoundry,Cloud Foundry>>

[float]
[[set-connection]]
=== Step 2: Connect to the {stack}

include::{libbeat-dir}/shared/connecting-to-es.asciidoc[]

[float]
[[collect-log-data]]
=== Step 3: Collect log data

There are several ways to collect log data with {beatname_uc}:

* Data collection modules -- simplify the collection, parsing,
and visualization of common log formats
* ECS loggers -- structure and format
application logs into ECS-compatible JSON
* Manual {beatname_uc} configuration

[float]
[[enable-modules]]
==== Enable and configure data collection modules

. Identify the modules you need to enable. To see a list of available
<<filebeat-modules,modules>>, run:
+
--
include::{libbeat-dir}/tab-widgets/list-modules-widget.asciidoc[]
--

. From the installation directory, enable one or more modules. For example, the
following command enables the +{modulename}+ module config:
+
--
include::{libbeat-dir}/tab-widgets/enable-modules-widget.asciidoc[]
--

. In the module config under `modules.d`, change the module settings to match
your environment.
+
For example, log locations are set based on the OS. If your logs aren't in
default locations, set the `paths` variable:
+
--
[source,yaml]
----
- module: nginx
  access:
    var.paths: ["/var/log/nginx/access.log*"] <1>
----
--

To see the full list of variables for a module, see the documentation under
<<filebeat-modules>>.

include::{libbeat-dir}/shared/config-check.asciidoc[]

[float]
[[collect-application-logs]]
==== Enable and configure ECS loggers for application log collection

While {beatname_uc} can be used to ingest raw, plain-text application logs,
we recommend structuring your logs at ingest time. This lets you extract fields,
like log level and exception stack traces.

Elastic simplifies this process by providing application log formatters in a variety
of popular programming languages. These plugins format your logs into ECS-compatible JSON,
which removes the need to manually parse logs.

See {ecs-logging-ref}/intro.html[ECS loggers] to get started.

[float]
[[manual-configuration]]
==== Configure {beatname_uc} manually

If you're unable to find a module for your file type, or can't change your application's
log output, see <<configuration-filebeat-options,configure the input>> manually.

[float]
[[setup-assets]]
=== Step 4: Set up assets

{beatname_uc} comes with predefined assets for parsing, indexing, and
visualizing your data. To load these assets:

. Make sure the user specified in +{beatname_lc}.yml+ is
<<privileges-to-setup-beats,authorized to set up {beatname_uc}>>.

. From the installation directory, run:
+
--
include::{libbeat-dir}/tab-widgets/setup-widget.asciidoc[]
--
+
`-e` is optional and sends output to standard error instead of the configured log output.

This step loads the recommended {ref}/index-templates.html[index template] for writing to {es}
and deploys the sample dashboards for visualizing the data in {kib}.

This step does not load the ingest pipelines used to parse log lines. By
default, ingest pipelines are set up automatically the first time you run the
module and connect to {es}.

[TIP]
=====
A connection to {es} (or {ess}) is required to set up the initial
environment. If you're using a different output, such as {ls}, see:

* <<load-template-manually>>
* <<load-kibana-dashboards>>
* <<load-ingest-pipelines>>
=====

[float]
[[start]]
=== Step 5: Start {beatname_uc}

Before starting {beatname_uc}, modify the user credentials in
+{beatname_lc}.yml+ and specify a user who is
<<privileges-to-publish-events,authorized to publish events>>.

To start {beatname_uc}, run:

// tag::start-step[]
:requires-sudo:
include::{libbeat-dir}/tab-widgets/start-widget.asciidoc[]
:requires-sudo!:
// end::start-step[]

{beatname_uc} should begin streaming events to {es}.

[float]
[[view-data]]
=== Step 6: View your data in {kib}

include::{libbeat-dir}/shared/opendashboards.asciidoc[tag=open-dashboards-intro]

include::{libbeat-dir}/shared/opendashboards.asciidoc[tag=open-dashboards]

[float]
=== What's next?

Now that you have your logs streaming into {es}, learn how to unify your logs,
metrics, uptime, and application performance data.

include::{libbeat-dir}/shared/obs-apps.asciidoc[]

:modulename!:
