[role="xpack"]
[[ls-security]]
=== Configuring Security in Logstash
++++
<titleabbrev>Configuring Security</titleabbrev>
++++

The Logstash {es} plugins (
{logstash-ref}/plugins-outputs-elasticsearch.html[output],
{logstash-ref}/plugins-inputs-elasticsearch.html[input],
{logstash-ref}/plugins-filters-elasticsearch.html[filter]
and {logstash-ref}/monitoring-logstash.html[monitoring])
support authentication and encryption over HTTP.

To use Logstash with a secured cluster, you need to configure authentication
credentials for Logstash. Logstash throws an exception and the processing
pipeline is halted if authentication fails.

If encryption is enabled on the cluster, you also need to enable TLS/SSL in the
Logstash configuration.

If you want to monitor your Logstash instance with {monitoring}, and store the
monitoring data in a secured {es} cluster, you must configure Logstash
with a username and password for a user with the appropriate permissions.

In addition to configuring authentication credentials for Logstash, you need
to grant authorized users permission to access the Logstash indices.

[float]
[[ls-http-auth-basic]]
==== Configuring Logstash to use Basic Authentication

Logstash needs to be able to manage index templates, create indices,
and write and delete documents in the indices it creates.

To set up authentication credentials for Logstash:

. Create a `logstash_writer` role that has the `manage_index_templates` and
`monitor` cluster privileges, and the `write`, `delete`, and `create_index`
privileges  for the Logstash indices. You can create roles from the **Management >
Roles** UI in {kib} or through the `role` API:
+
[source, sh]
---------------------------------------------------------------
POST _xpack/security/role/logstash_writer
{
  "cluster": ["manage_index_templates", "monitor"],
  "indices": [
    {
      "names": [ "logstash-*" ], <1>
      "privileges": ["write","delete","create_index"]
    }
  ]
}
---------------------------------------------------------------

<1> If you use a custom Logstash index pattern, specify that pattern
instead of the default `logstash-*` pattern.

. Create a `logstash_internal` user and assign it the `logstash_writer` role.
You can create users from the **Management > Users** UI in {kib} or through
the `user` API:
+
[source, sh]
---------------------------------------------------------------
POST _xpack/security/user/logstash_internal
{
  "password" : "x-pack-test-password",
  "roles" : [ "logstash_writer"],
  "full_name" : "Internal Logstash User"
}
---------------------------------------------------------------

. Configure Logstash to authenticate as the `logstash_internal` user you just
created. You configure credentials separately for each of the {es} plugins in
your Logstash `.conf` file. For example:
+
[source,js]
--------------------------------------------------
input {
  elasticsearch {
    ...
    user => logstash_internal
    password => x-pack-test-password
  }
}
filter {
  elasticsearch {
    ...
    user => logstash_internal
    password => x-pack-test-password
  }
}
output {
  elasticsearch {
    ...
    user => logstash_internal
    password => x-pack-test-password
  }
}
--------------------------------------------------

[float]
[[ls-user-access]]
==== Granting Users Access to the Logstash Indices

To access the indices Logstash creates, users need the `read` and
`view_index_metadata` privileges:

. Create a `logstash_reader` role that has the `read` and `view_index_metadata`
privileges  for the Logstash indices. You can create roles from the
**Management > Roles** UI in {kib} or through the `role` API:
+
[source, sh]
---------------------------------------------------------------
POST _xpack/security/role/logstash_reader
{
  "indices": [
    {
      "names": [ "logstash-*" ], <1>
      "privileges": ["read","view_index_metadata"]
    }
  ]
}
---------------------------------------------------------------

<1> If you use a custom Logstash index pattern, specify that pattern
instead of the default `logstash-*` pattern.

. Assign your Logstash users the `logstash_reader` role. If the Logstash user
will be using
{logstash-ref}/logstash-centralized-pipeline-management.html[centralized pipeline management],
also assign the `logstash_admin` role. You can create and manage users from the
**Management > Users** UI in {kib} or through the `user` API:
+
[source, sh]
---------------------------------------------------------------
POST _xpack/security/user/logstash_user
{
  "password" : "x-pack-test-password",
  "roles" : [ "logstash_reader", "logstash_admin"], <1>
  "full_name" : "Kibana User for Logstash"
}
---------------------------------------------------------------

<1> `logstash_admin` is a built-in role that provides access to `.logstash-*`
indices for managing configurations.

[float]
[[ls-http-auth-pki]]
==== Configuring the {es} Output to use PKI Authentication

The `elasticsearch` output supports PKI authentication. To use an X.509
client-certificate for authentication, you configure the `keystore` and
`keystore_password` options in your Logstash `.conf` file:

[source,js]
--------------------------------------------------
output {
  elasticsearch {
    ...
    keystore => /path/to/keystore.jks
    keystore_password => realpassword
    truststore =>  /path/to/truststore.jks <1>
    truststore_password =>  realpassword
  }
}
--------------------------------------------------
<1> If you use a separate truststore, the truststore path and password are
also required.

[float]
[[ls-http-ssl]]
==== Configuring Logstash to use TLS Encryption

If TLS encryption is enabled on the {es} cluster, you need to
configure the `ssl` and `cacert` options in your Logstash `.conf` file:

[source,js]
--------------------------------------------------
output {
  elasticsearch {
    ...
    ssl => true
    cacert => '/path/to/cert.pem' <1>
  }
}
--------------------------------------------------
<1> The path to the local `.pem` file that contains the Certificate
    Authority's certificate.

[float]
[[ls-monitoring-user]]
==== Configuring Credentials for Logstash Monitoring

If you plan to ship Logstash {logstash-ref}/monitoring-logstash.html[monitoring]
data to a secure cluster, you need to configure the username and password that
Logstash uses to authenticate for shipping monitoring data.

{security} comes preconfigured with a
{xpack-ref}/setting-up-authentication.html#built-in-users[`logstash_system` built-in user]
for this purpose. This user has the minimum permissions necessary for the
monitoring function, and _should not_ be used for any other purpose - it is
specifically _not intended_ for use within a Logstash pipeline.

By default, the `logstash_system` user does not have a password. The user will
not be enabled until you set a password. Set the password through the change
password API:

[source,js]
---------------------------------------------------------------------
PUT _xpack/security/user/logstash_system/_password
{
  "password": "t0p.s3cr3t"
}
---------------------------------------------------------------------
// CONSOLE

Then configure the user and password in the `logstash.yml` configuration file:

[source,yaml]
----------------------------------------------------------
xpack.monitoring.elasticsearch.username: logstash_system
xpack.monitoring.elasticsearch.password: t0p.s3cr3t
----------------------------------------------------------

If you initially installed an older version of {xpack}, and then upgraded, the
`logstash_system` user may have defaulted to `disabled` for security reasons.
You can enable the user through the `user` API:

[source,js]
---------------------------------------------------------------------
PUT _xpack/security/user/logstash_system/_enable
---------------------------------------------------------------------
// CONSOLE

[float]
[[ls-pipeline-management-user]]
==== Configuring Credentials for Centralized Pipeline Management

If you plan to use Logstash
{logstash-ref}/logstash-centralized-pipeline-management.html[centralized pipeline management],
you need to configure the username and password that Logstash uses for managing
configurations.

You configure the user and password in the `logstash.yml` configuration file:

[source,yaml]
----------------------------------------------------------
xpack.management.elasticsearch.username: logstash_admin_user <1>
xpack.management.elasticsearch.password: t0p.s3cr3t
----------------------------------------------------------

<1> The user you specify here must have the built-in `logstash_admin` role as
well as the `logstash_writer` role that you created earlier.
