Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

enhancement(deps)!: remove openssl legacy provider flag and update docs #18609

Merged
merged 12 commits into from
Sep 20, 2023
Merged

enhancement(deps)!: remove openssl legacy provider flag and update docs #18609

Show file tree
Hide file tree
Changes from 8 commits
Commits
Show all changes
12 commits
Select commit Hold shift + click to select a range
ea480d6
enhancement(deps)!: remove openssl legacy provider flag and update do…
dsmith3197 Sep 19, 2023
b5648e8
fix website build
dsmith3197 Sep 19, 2023
bdb9724
fix website build
dsmith3197 Sep 19, 2023
22d3558
fix website build
dsmith3197 Sep 19, 2023
f8dc18e
add back flag and set to false
dsmith3197 Sep 19, 2023
3479e86
add back flag and set to false
dsmith3197 Sep 19, 2023
1e8eb51
update upgrade guide
dsmith3197 Sep 19, 2023
b5cdfe0
add authors
dsmith3197 Sep 19, 2023
0f78f31
feedback
dsmith3197 Sep 20, 2023
c2f3acd
Merge branch 'master' into dougsmith/openssl-conf
dsmith3197 Sep 20, 2023
ddcce64
update deprecations.md
dsmith3197 Sep 20, 2023
5b6cf86
update docs to mention default file location
dsmith3197 Sep 20, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 3 additions & 2 deletions Cargo.lock
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

2 changes: 0 additions & 2 deletions Cargo.toml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -385,8 +385,6 @@ nix = { git = "https://github.com/vectordotdev/nix.git", branch = "memfd/gnu/mus
# The `heim` crates depend on `ntapi` 0.3.7 on Windows, but that version has an
# unaligned access bug fixed in the following revision.
ntapi = { git = "https://github.com/MSxDOS/ntapi.git", rev = "24fc1e47677fc9f6e38e5f154e6011dc9b270da6" }
# 300.1.3+3.1.2 + a commit that re-adds force-engine flag. Can be removed after next release of openssl-src.
openssl-src = { git = "https://github.com/alexcrichton/openssl-src-rs", ref = "26dc3c81d8ebee5f7ec40835e29bf9f37e648ab2" }

[features]
# Default features for *-unknown-linux-gnu and *-apple-darwin
Expand Down
4 changes: 2 additions & 2 deletions src/cli.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -202,8 +202,8 @@ pub struct RootOpts {
#[arg(
long,
env = "VECTOR_OPENSSL_LEGACY_PROVIDER",
default_value = "true",
default_missing_value = "true",
default_value = "false",
default_missing_value = "false",
num_args = 0..=1,
require_equals = true,
action = ArgAction::Set
Expand Down
26 changes: 0 additions & 26 deletions website/content/en/highlights/2023-09-06-0-33-0-upgrade-guide.md
View file
Open in desktop

This file was deleted.

24 changes: 22 additions & 2 deletions website/content/en/highlights/2023-09-26-0-33-0-upgrade-guide.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
date: "2023-09-26"
title: "0.33 Upgrade Guide"
description: "An upgrade guide that addresses breaking changes in 0.33.0"
authors: ["spencergilbert", "neuronull"]
authors: ["spencergilbert", "neuronull", "pront", "dsmith3197"]
release: "0.33.0"
hide_on_release_notes: false
badges:
Expand All @@ -12,11 +12,17 @@ badges:
Vector's 0.33.0 release includes **breaking changes**:

1. [Behavior of the `datadog_logs` sink's `endpoint` setting](#datadog-logs-endpoint)
1. [Disable OpenSSL legacy provider by default](#openssl-legacy-provider)

Vector's 0.33.0 release includes **deprecations**:
and **deprecations**:

1. [Default config location change](#default-config-location-change)
1. [Renaming the `armv7` rpm package](#armv7-rename)

and **potentially impactful changes**:

1. [Async runtime default number of worker threads](#runtime-worker-threads)

We cover them below to help you upgrade quickly:

## Upgrade guide
Expand All @@ -34,9 +40,23 @@ with the other Datadog sinks, which use the `endpoint` as a base URL that the AP
With this release, the `datadog_logs` sink's behavior is now consistent with the other
Datadog sinks for the `endpoint` setting.

#### Disable OpenSSL legacy provider by default {#openssl-legacy-provider}

Vector upgraded the version of OpenSSL that it statically compiles in to v3.1.x in the 0.32.0 release.
Following our deprecation policy, v0.33.0 now disables the legacy OpenSSL provider by default. It can be
enabled through the [OpenSSL configuration options](https://www.openssl.org/docs/manmaster/man5/config.html)
dsmith3197 marked this conversation as resolved.
Show resolved Hide resolved
exposed through environment variables, particularly `OPENSSL_CONF`.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The only concrete and relevant env variable is OPENSSL_CONF to specify an OpenSSL config file to use.
I think mentioning "variables" and "particularly" is vague, misleading and confusing.

While outside of the scope of this PR, I still think Vector should document a complete example like I gave in the other closed PR. That should make it very clear how to use this functionality.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks, I wasn't sure if OPENSSL_CONF was the only relevant environment variable, hence the reason I was vague. I updated the wording using your suggestion 🙂

Copy link
Contributor

@hhromic hhromic Sep 20, 2023 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

There is one more thing to consider maybe.

Vector's vendored OpenSSL library actually looks by default for /usr/local/ssl/openssl.cnf, which likely does not exist in most user's systems by default. The OPENSSL_CONF variable actually allows to override this to wherever you need.

So, technically, if a user has an OpenSSL config in that path, Vector will pick it up automatically without needing OPENSSL_CONF. This behaviour can be suprising for them (maybe). Therefore, I'm not sure if this should be mentioned somewhere too.

Perhaps a dedicated "Vector and SSL/TLS" documentation section is necessary to explain all these nuances?
Examples of using OPENSSL_CONF could go there for instance.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I agree that it would be useful to go into detail on this topic in the documentation. Given your expertise in the area, is this something you'd be willing to contribute? If not, I can open an issue to track this work.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

As I mentioned in the other PR where I investigated all of this, I'm more than happy to contribute documentation on the subject. As a starting point, can the Vector team suggest where in the documentation it would be suitable to open a new section/page for this topic?

At the moment it is hard for me to see where it would best fit in https://vector.dev/docs/ :(

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks! I think this topic is worthy of its own page - https://vector.dev/docs/reference/configuration/tls seems like a good location. You can add this by creating a new markdown file similar to https://github.com/vectordotdev/vector/blob/master/website/content/en/docs/reference/configuration/unit-tests.md

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for the pointer! Will work on it in the coming days.
I have one more ask, how can I quickly generate locally a render of the docs website?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

You should be able to run make serve in the website directory to spin up a local instance.



### Deprecations

#### Default config location change {#default-config-location-change}

The default config location `/etc/vector/vector.toml` which is used by Vector `0.32.0` is now deprecated. This location will still be used in `0.33.0`. The new default path is `/etc/vector/vector.yaml`, please migrate to this new default path or specify the config path explicitly.

Vector `0.33.0` will attempt to load `/etc/vector/vector.toml` first, and if it is not present, it will fallback to `/etc/vector/vector.yaml`. However, Vector release `0.34.0` will automatically load `/etc/vector/vector.yaml` only.


#### Renaming the `armv7` rpm package {#armv7-rename}

The `armv7` rpm package, `vector-<version>-1.armv7.rpm`, is now published as
Expand Down
2 changes: 1 addition & 1 deletion website/cue/reference/cli.cue
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -634,7 +634,7 @@ cli: {
}
VECTOR_OPENSSL_LEGACY_PROVIDER: {
description: "Load the OpenSSL legacy provider."
type: bool: default: true
type: bool: default: false
}
VECTOR_OPENSSL_NO_PROBE: {
description: """
Expand Down
4 changes: 3 additions & 1 deletion website/cue/reference/components/sinks.cue
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -644,7 +644,9 @@ components: sinks: [Name=string]: {
title: "Transport Layer Security (TLS)"
body: """
Vector uses [OpenSSL](\(urls.openssl)) for TLS protocols due to OpenSSL's maturity. You can
enable and adjust TLS behavior using the [`tls.*`](#tls) options.
enable and adjust TLS behavior via the [`tls.*`](#tls) options and/or via the
[OpenSSL configuration options](\(urls.openssl_conf)) exposed through environment variables,
particularly `OPENSSL_CONF`.
dsmith3197 marked this conversation as resolved.
Show resolved Hide resolved
"""
}
}
Expand Down
8 changes: 5 additions & 3 deletions website/cue/reference/components/sources.cue
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -356,9 +356,11 @@ components: sources: [Name=string]: {
_tls: {
title: "Transport Layer Security (TLS)"
body: """
Vector uses [OpenSSL](\(urls.openssl)) for TLS protocols. You can
adjust TLS behavior via the `tls.*` options.
"""
Vector uses [OpenSSL](\(urls.openssl)) for TLS protocols due to OpenSSL's maturity. You can
enable and adjust TLS behavior via the `tls.*` options and/or via the
[OpenSSL configuration options](\(urls.openssl_conf)) exposed through environment variables,
particularly `OPENSSL_CONF`.
"""
}

if features.collect != _|_ {
Expand Down
8 changes: 5 additions & 3 deletions website/cue/reference/components/sources/opentelemetry.cue
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -198,9 +198,11 @@ components: sources: opentelemetry: {
tls: {
title: "Transport Layer Security (TLS)"
body: """
Vector uses [OpenSSL](\(urls.openssl)) for TLS protocols. You can
adjust TLS behavior via the `grpc.tls.*` and `http.tls.*` options.
"""
Vector uses [OpenSSL](\(urls.openssl)) for TLS protocols due to OpenSSL's maturity. You can
enable and adjust TLS behavior via the `grpc.tls.*` and `http.tls.*` options and/or via the
[OpenSSL configuration options](\(urls.openssl_conf)) exposed through environment variables,
particularly `OPENSSL_CONF`.
"""
}
}
}
1 change: 1 addition & 0 deletions website/cue/reference/urls.cue
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -383,6 +383,7 @@ urls: {
nixos: "https://nixos.org/"
nixpkgs_9682: "\(github)/NixOS/nixpkgs/issues/9682"
openssl: "https://www.openssl.org/"
openssl_conf: "https://www.openssl.org/docs/manmaster/man5/config.html"
dsmith3197 marked this conversation as resolved.
Show resolved Hide resolved
opentelemetry: "https://opentelemetry.io"
opentelemetry_protocol: "\(opentelemetry)/docs/reference/specification/protocol/otlp/"
order_of_ops: "\(wikipedia)/wiki/Order_of_operations"
Expand Down