mirror of
https://github.com/elastic/logstash.git
synced 2025-04-24 14:47:19 -04:00
260 lines
9 KiB
Text
260 lines
9 KiB
Text
[role="xpack"]
|
|
[[ls-security]]
|
|
=== Configuring Security in Logstash
|
|
[subs="attributes"]
|
|
++++
|
|
<titleabbrev>{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:
|
|
|
|
. Use the the **Management > Roles** UI in {kib} or the `role` API to create a
|
|
`logstash_writer` role. For *cluster* privileges, add `manage_index_templates` and `monitor`.
|
|
For *indices* privileges, add `write`, `create`, `delete`, and `create_index`.
|
|
+
|
|
If you plan to use {ref}/getting-started-index-lifecycle-management.html[index lifecycle
|
|
management], also add `manage_ilm` for cluster and `manage` and `manage_ilm` for indices.
|
|
+
|
|
[source, sh]
|
|
---------------------------------------------------------------
|
|
POST _xpack/security/role/logstash_writer
|
|
{
|
|
"cluster": ["manage_index_templates", "monitor", "manage_ilm"], <1>
|
|
"indices": [
|
|
{
|
|
"names": [ "logstash-*" ], <2>
|
|
"privileges": ["write","create","delete","create_index","manage","manage_ilm"] <3>
|
|
}
|
|
]
|
|
}
|
|
---------------------------------------------------------------
|
|
<1> The cluster needs the `manage_ilm` privilege if
|
|
{ref}/getting-started-index-lifecycle-management.html[index lifecycle management]
|
|
is enabled.
|
|
<2> If you use a custom Logstash index pattern, specify your custom pattern
|
|
instead of the default `logstash-*` pattern.
|
|
<3> If {ref}/getting-started-index-lifecycle-management.html[index lifecycle
|
|
management] is enabled, the role requires the `manage` and `manage_ilm`
|
|
privileges to load index lifecycle policies, create rollover aliases, and create
|
|
and manage rollover indices.
|
|
|
|
. 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
|
|
{ref}/built-in-users.html[`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.
|