Skip to content

Commit

Permalink
Expand ssl_assert_fingerprint docs (#500)
Browse files Browse the repository at this point in the history
* Add default value notes for ssl_assert_fingerprint

Update the `args.ssl_assert_fingerprint` reference docs, adding the
default value and behavior.

* Add new Manage self-signed certificates section

This new section explains what `ssl_assert_fingerprint` config option
is and how to set it up to send data to an Elasticsearch cluster that
is using a self-signed certificate (or other formally invalid
certificates).
  • Loading branch information
zmoog authored Nov 7, 2023
1 parent c91d466 commit 1bc4295
Show file tree
Hide file tree
Showing 2 changed files with 75 additions and 2 deletions.
4 changes: 2 additions & 2 deletions docs/en/aws-deploy-elastic-serverless-forwarder.asciidoc
Original file line number Diff line number Diff line change
Expand Up @@ -225,7 +225,7 @@ For `elasticsearch` the following arguments are supported:
* `args.es_datastream_name`: Name of data stream or index where logs should be forwarded to. Lambda supports automatic routing of various {aws} service logs to the corresponding data streams for further processing and storage in the {es} cluster. It supports automatic routing of `aws.cloudtrail`, `aws.cloudwatch_logs`, `aws.elb_logs`, `aws.firewall_logs`, `aws.vpcflow`, and `aws.waf` logs. For other log types, if using data streams, you can optionally set its value in the configuration file according to the naming convention for data streams and available integrations. If the `es_datastream_name` is not specified and it cannot be matched with any of the above {aws} services, then the value will be set to `logs-generic-default`. In versions **v0.29.1** and below, this configuration parameter was named `es_index_or_datastream_name`. Rename the configuration parameter to `es_datastream_name` in your `config.yaml` file on the S3 bucket to continue using it in the future version. The older name `es_index_or_datastream_name` is deprecated as of version **v0.30.0**. The related backward compatibility code is removed from version **v1.0.0**.
* `args.batch_max_actions`: (Optional) Maximum number of actions to send in a single bulk request. Default value: 500.
* `args.batch_max_bytes`: (Optional) Maximum size in bytes to send in a single bulk request. Default value: 10485760 (10MB).
* `args.ssl_assert_fingerprint`: (Optional) SSL fingerprint for self-signed SSL certificate on HTTPS transport.
* `args.ssl_assert_fingerprint`: (Optional) SSL fingerprint for self-signed SSL certificate on HTTPS transport. The default value is an empty string, meaning the HTTP client requires a valid certificate.

For `logstash` the following arguments are supported:

Expand All @@ -234,7 +234,7 @@ For `logstash` the following arguments are supported:
* `args.password`: (Optional) Password of the {ls} instance to connect to. Mandatory if HTTP Basic authentication is enabled in {ls}.
* `args.max_batch_size`: (Optional) Maximum number of events to send in a single HTTP(s) request. Default value: 500
* `args.compression_level`: (Optional) The GZIP compression level for HTTP(s) requests towards {ls}. It can be any integer value between 1 (minimum compression, best performance, highest amount of bytes sent) and 9 (maximum compression, worst performance, lowest amount of bytes sent). Default value: 1
* `args.ssl_assert_fingerprint`: (Optional) SSL fingerprint for self-signed SSL certificate on HTTPS transport.
* `args.ssl_assert_fingerprint`: (Optional) SSL fingerprint for self-signed SSL certificate on HTTPS transport. The default value is an empty string, meaning the HTTP client requires a valid certificate.

[discrete]
[[aws-serverless-forwarder-define-deploy-parameters]]
Expand Down
73 changes: 73 additions & 0 deletions docs/en/aws-elastic-serverless-forwarder-configuration.asciidoc
Original file line number Diff line number Diff line change
Expand Up @@ -569,3 +569,76 @@ image:images/multiline-regexp-test-repl-main.png[Add your test message to Multil

[role="screenshot"]
image:images/multiline-regexp-test-repl-run.png[View the test results]

[discrete]
[[aws-serverless-manage-self-signed-certificates]]
== Manage self-signed certificates

From v1.5.0, ESF introduced the SSL fingerprint option to access Elasticsearch clusters using self-signed certificates.

[discrete]
[[aws-serverless-manage-self-signed-certificates-config]]
=== Configuration options

To set the `ssl_assert_fingerprint` option, you must edit the config file stored in the S3 bucket.

Suppose you have a `config.yml` file stored in the bucket with the following content:

[source, yaml]
----
inputs:
- type: "s3-sqs"
id: "arn:aws:sqs:eu-west-1:123456789:dev-access-logs"
outputs:
- type: "elasticsearch"
args:
api_key: "<REDACTED>"
es_datastream_name: "logs-aws.s3access-default"
batch_max_actions: 500
batch_max_bytes: 10485760
ssl_assert_fingerprint: ""
----

If the configuration omits the `ssl_assert_fingerprint` or, like in this example, is empty (the default option), the HTTP client validates the certificates of Elasticsearch clusters.

[discrete]
[[aaws-serverless-manage-self-signed-certificates-get-ssl-fingerprint]]
=== Get the SSL fingerprint

The next step is to get the fingerprint of the HTTPS certificate your Elasticsearch cluster is using now.

You can use OpenSSL to get the fingerprint for your certificate. Here's an example using an Elasticsearch cluster hosted on Elastic Cloud:

[source, shell]
----
$ openssl s_client \
-connect my-deployment.es.eastus2.azure.elastic-cloud.com:443 \
-showcerts </dev/null 2>/dev/null | openssl x509 -noout -fingerprint
SHA1 Fingerprint=1C:46:32:75:AA:D6:F1:E2:8E:10:A3:64:44:B1:36:C9:7D:44:35:B4
----

You can use your DNS name, IP address, and port number instead of `my-deployment.es.eastus2.azure.elastic-cloud.com:443` from the above example.

Copy your fingerprint value for the next step.

[discrete]
[[aaws-serverless-manage-self-signed-certificates-set-ssl-fingerprint]]
=== Set the SSL fingerprint

As a final step, edit your `config.yml` file to use the SSL fingerprint:

[source, yaml]
----
inputs:
- type: "s3-sqs"
id: "arn:aws:sqs:eu-west-1:123456789:dev-access-logs"
outputs:
- type: "elasticsearch"
args:
api_key: "<REDACTED>"
es_datastream_name: "logs-aws.s3access-default"
batch_max_actions: 500
batch_max_bytes: 10485760
ssl_assert_fingerprint: "1C:46:32:75:AA:D6:F1:E2:8E:10:A3:64:44:B1:36:C9:7D:44:35:B4"
----

0 comments on commit 1bc4295

Please sign in to comment.