225 lines
7.2 KiB
Plaintext
225 lines
7.2 KiB
Plaintext
[[logstash]]
|
|
=== Logstash and Security
|
|
|
|
The Logstash Elasticsearch 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 SSL in the
|
|
Logstash configuration.
|
|
|
|
If you wish to monitor your logstash instance with x-pack monitoring, and store
|
|
the monitoring data in a secured elasticsearch 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` cluster
|
|
privilege, and the `write`, `delete`, and `create_index` privileges for the
|
|
Logstash indices. You can create roles from the **Management > Roles** UI in
|
|
Kibana 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 Kibana 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 Elasticsearch
|
|
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 Kibana 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. You can create
|
|
and manage users from the **Management > Users** UI in Kibana or through
|
|
the `user` API:
|
|
+
|
|
[source, sh]
|
|
---------------------------------------------------------------
|
|
POST _xpack/security/user/logstash_user
|
|
{
|
|
"password" : "x-pack-test-password",
|
|
"roles" : [ "logstash_reader"],
|
|
"full_name" : "Kibana User"
|
|
}
|
|
---------------------------------------------------------------
|
|
|
|
[float]
|
|
[[ls-http-auth-pki]]
|
|
===== Configuring the elasticsearch 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 Elasticsearch 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 Logstash Monitoring
|
|
|
|
If you wish to ship Logstash {logstash-ref}/monitoring-logstash.html[monitoring]
|
|
data to a secure cluster, Logstash must be configured with a username and password.
|
|
|
|
X-Pack security comes preconfigured with a `logstash_system` 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` does not have a password. The user will not be enabled until
|
|
a password is set. Set the password through the reset password API:
|
|
|
|
[source,js]
|
|
---------------------------------------------------------------------
|
|
PUT _xpack/security/user/logstash_system/_password
|
|
{
|
|
"password": "t0p.s3cr3t"
|
|
}
|
|
---------------------------------------------------------------------
|
|
// CONSOLE
|
|
|
|
Then configure the user and password in your `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 X-Pack, and then upgraded, then
|
|
the `logstash_system` user may have defaulted to disabled for security reasons.
|
|
You can enable the user with the following API call:
|
|
|
|
[source,js]
|
|
---------------------------------------------------------------------
|
|
PUT _xpack/security/user/logstash_system/_enable
|
|
---------------------------------------------------------------------
|
|
// CONSOLE
|
|
|