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.

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

add section for syslog-drain-url protocols, certificates and troubleshooting hints #548

Conversation

corporatemax
Copy link
Contributor

@corporatemax corporatemax commented Mar 14, 2025

We get customer tickets where customers ask for help when configuring their syslog drains.

In my team we planned to enhance the documentation with a section about the protocols, certificates and some hints for troubleshooting common problems with syslog drains.

@corporatemax corporatemax changed the title add section for syslog-drain-url protocols add section for syslog-drain-url protocols, certificates and troubleshooting hints Mar 19, 2025
@corporatemax corporatemax marked this pull request as ready for review March 19, 2025 16:27
Copy link
Contributor

@chombium chombium left a comment

Choose a reason for hiding this comment

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

Hi @corporatemax, I've added few suggestions for improvements.

* Use the syslog scheme for endpoints that do not require TLS.
* Use the https scheme when shipping logs to an HTTPS endpoint.

If you need to use TLS with a custom Certificate Authority (CA), ensure that you provide the necessary CA certificate. For mTLS configuration, both the client certificate and the key must be provided. Additionally, when using mTLS with a custom CA, include the client certificate, the client key, and the CA certificate.
Copy link
Contributor

Choose a reason for hiding this comment

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

  • It is better to always add the CA, in order to be sure that the connection will be successful. Otherwise, the qpp developers rely on the OS certificates brought with the stemcell, or on the certificates added by the foundation's admins. In both cases, it's more unreliable and not recommended to lean on that as you never know if and how the certificates will be maintained (exchanged, rotated etc.) It is always recommended to pass the CAs when creating Syslog drains.
  • You always have to have the CA of the remote host and the certificate and key for the Syslog Agent for mTLS independently if it's a custom or well known CA.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Ok, I know wrote that the CA certificate is necessay for TLS and mTLS.

$ awk 'NF {sub(/\r/, ""); printf "%s\\n",$0;}' cert.pem | sed 's/\\n$//' | tr -d '\n'
</pre>

The `cf create-user-provided-service` command accepts any JSON payload without validating the certificates or credentials while creating the syslog drain. In older syslog agent versions, there is no error message for wrong certificates or credentials; you can only validate in your target log service if your syslog drain was configured correctly. To troubleshoot your certificates, you can use the openssl command line tool.
Copy link
Contributor

Choose a reason for hiding this comment

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

There are still no newer versions where the app devs can see the errors from the Syslog Agent when establishing connection. The app devs need help from the platform operators to solve connection problems. You can update this paragraph when the PR is merged.

@chombium
Copy link
Contributor

@ctlong This might interest you as well.

@chombium
Copy link
Contributor

@corporatemax ah, and please squash all the commits in a single commit.

@corporatemax corporatemax force-pushed the enhance-syslog-drain-documentation branch from a44bd54 to b76914e Compare March 20, 2025 12:24
fix command format and reformulate certificate combinations

add hint for certificate troubleshooting with openssl

fix typo

style edits for consistency within the docs

make CA necessary

Capitalize Syslog Agent throughout file

remove Diego Cell
@corporatemax corporatemax force-pushed the enhance-syslog-drain-documentation branch from 0dd433a to cc995d4 Compare March 20, 2025 15:38
Copy link
Contributor

@chombium chombium left a comment

Choose a reason for hiding this comment

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

LGTM!

@anita-flegg anita-flegg merged commit 0f041e8 into cloudfoundry:master Mar 27, 2025
1 check passed
@anita-flegg
Copy link
Contributor

@pspinrad , You may want to cherry-pick these updates to your branches.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

None yet

3 participants