vy commented on code in PR #2796: URL: https://github.com/apache/logging-log4j2/pull/2796#discussion_r1705394781
########## src/site/antora/modules/ROOT/pages/manual/appenders/network.adoc: ########## @@ -0,0 +1,980 @@ +//// + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with + the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. +//// + += Network Appenders +:open-book: 📖 Review Comment: @ppkarwasz, please stop defining this property in every single file. Either define it in `antora.yml` and `antora.tmpl.yml` globally and choose a different name that describes its purpose, e.g., `reference-manual-symbol`; or use the unicode character at use sites. ########## src/site/antora/modules/ROOT/pages/manual/appenders/network.adoc: ########## @@ -0,0 +1,980 @@ +//// + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with + the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. +//// + += Network Appenders +:open-book: 📖 + Review Comment: ```suggestion This section guides you through xref:manual/appenders.adoc[appenders] that use simple network protocols to transmit log events to a remote host. ``` ########## src/site/antora/modules/ROOT/pages/manual/appenders/network.adoc: ########## @@ -0,0 +1,980 @@ +//// + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with + the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. +//// + += Network Appenders +:open-book: 📖 + +[#common-configuration] +== Common concerns + +[#tls-configuration] +=== TLS Configuration + +All network appenders support TLS (formerly known as SSL) connections. +The TLS layer can be configured: + +* Either globally using configuration properties. +See xref:manual/systemproperties.adoc#properties-transport-security[Transport Security] +for more details. +* Or by providing a nested <<SslConfiguration,`SSL`>> Log4j component. + +[#SslConfiguration] +==== `Ssl` + +The `Ssl` component supports the following configuration options: + +[#SslConfiguration-attributes] +.`Ssl` configuration attributes +[cols="1m,1,1,5"] +|=== +| Attribute | Type | Default value | Description + +| [[SslConfiguration-attr-protocol]]protocol +| `String` +| `TLS` +a| +It specifies the +https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#SSLContext[`SSLContext` algorithm] +that https://docs.oracle.com/javase/8/docs/technotes/guides/security/jsse/JSSERefGuide.html[JSSE] will use. + +[NOTE] +==== +This setting can only be used to reduce the highest version of TLS to be used. + +To disable older TLS versions, see +https://docs.oracle.com/javase/8/docs/technotes/guides/security/jsse/JSSERefGuide.html#InstallationAndCustomization[JSSE documentation]. +==== + +| [[SslConfiguration-attr-verifyHostName]]verifyHostName +| `boolean` +| `false` +| +If `true`, the host name in X509 certificate will be compared to the requested host name. +In the case of a mismatch, the connection will fail. + +See also +xref:manual/systemproperties.adoc#log4j2.sslVerifyHostName[`log4j2.sslVerifyHostName`]. +|=== + +[#SslConfiguration-elements] +.`Ssl` nested elements +[cols="1m,1,4"] +|=== +| Type | Multiplicity | Description + +| [[SslConfiguration-element-KeyStore]]<<KeyStoreConfiguration,`KeyStore`>> +| zero or one +| +It specifies the +https://docs.oracle.com/javase/8/docs/api/java/security/KeyStore.html[`KeyStore`] +to use for TLS client authentication. + +| [[SslConfiguration-element-TrustStore]]<<TrustStoreConfiguration,`TrustStore`>> +| zero or one +| +It specifies the trust roots to use for TLS server authentication. + +|=== + +xref:plugin-reference.adoc#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-net-ssl-SslConfiguration[{open-book} Plugin reference for `SSL`] + +[#KeyStoreConfiguration] +==== KeyStore + +The `KeyStore` is meant to contain your private keys and certificates, and determines which authentication credentials to send to the remote host. + +[#KeyStoreConfiguration-attributes] +.`KeyStore` configuration attributes +[cols="1m,1,1,5"] +|=== +| Attribute | Type | Default value | Description + +| [[KeyStoreConfiguration-attr-location]]location +| https://docs.oracle.com/javase/{java-target-version}/docs/api/java/nio/file/Path.html[`Path`] or +https://docs.oracle.com/javase/{java-target-version}/docs/api/java/net/URI.html[`URI`] +| +| +The location of the private key store. + +See also xref:manual/systemproperties.adoc#log4j2.keyStoreLocation[`log4j2.keyStoreLocation`]. + +| [[KeyStoreConfiguration-attr-password]]password +| `String` +| `null` +| +The password for the private key store. + +See also xref:manual/systemproperties.adoc#log4j2.keyStorePassword[`log4j2.keyStorePassword`]. + +| [[KeyStoreConfiguration-attr-passwordEnvironmentVariable]]passwordEnvironmentVariable +| `String` +| `null` +| +The name of the environment variable that contains the password for the private key store. + +See also xref:manual/systemproperties.adoc#log4j2.keyStorePasswordEnvironmentVariable[`log4j2.keyStorePasswordEnvironmentVariable`]. + +| [[KeyStoreConfiguration-attr-passwordFile]]passwordFile +| https://docs.oracle.com/javase/{java-target-version}/docs/api/java/nio/file/Path.html[`Path`] +| `null` +| +The name of a file that contains the password for the private key store. + +See also xref:manual/systemproperties.adoc#log4j2.keyStorePasswordFile[`log4j2.keyStorePasswordFile`]. + +| [[KeyStoreConfiguration-attr-type]]type +| https://docs.oracle.com/javase/{java-target-version}/docs/technotes/guides/security/StandardNames.html#KeyStore[`KeyStore`] +| https://docs.oracle.com/javase/{java-target-version}/docs/api/java/security/KeyStore.html#getDefaultType--[_JVM dependent_] +| +The type of private key store. +See https://docs.oracle.com/javase/{java-target-version}/docs/technotes/guides/security/StandardNames.html#KeyStore[`KeyStore` standard types]. + +See also xref:manual/systemproperties.adoc#log4j2.keyStoreType[`log4j2.keyStoreType`]. + +| [[KeyStoreConfiguration-attr-keyManagerFactoryAlgorithm]]keyManagerFactoryAlgorithm +| https://docs.oracle.com/javase/{java-target-version}/docs/technotes/guides/security/StandardNames.html#KeyManagerFactory[`KeyManagerFactory`] +|https://docs.oracle.com/javase/{java-target-version}/docs/api/javax/net/ssl/KeyManagerFactory.html#getDefaultAlgorithm--[_JVM dependent_] +| +Name of the https://docs.oracle.com/javase/{java-target-version}/docs/api/javax/net/ssl/KeyManagerFactory.html[`KeyManagerFactory`] implementation to use for the private key store. +See https://docs.oracle.com/javase/{java-target-version}/docs/technotes/guides/security/StandardNames.html#KeyManagerFactory[`KeyManagerFactory` standard names]. + +See also xref:manual/systemproperties.adoc#log4j2.keyStoreKeyManagerFactoryAlgorithm[`log4j2.keyStoreKeyManagerFactoryAlgorithm`]. +|=== + +xref:plugin-reference.adoc#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-net-ssl-KeyStoreConfiguration[{open-book} Plugin reference for `KeyStore`] + +[#TrustStoreConfiguration] +==== TrustStore + +The trust store is meant to contain the CA certificates you are willing to trust when a remote party presents its certificate. +It determines whether the remote authentication credentials (and thus the connection) should be trusted. + +[#TrustStoreConfiguration-attributes] +.`TrustStore` configuration attributes +[cols="1m,1,1,5"] +|=== +| Attribute | Type | Default value | Description + +| [[TrustStoreConfiguration-attr-location]]location +| https://docs.oracle.com/javase/{java-target-version}/docs/api/java/nio/file/Path.html[`Path`] or +https://docs.oracle.com/javase/{java-target-version}/docs/api/java/net/URI.html[`URI`] +| +| +The location of the trust store. + +See also xref:manual/systemproperties.adoc#log4j2.trustStoreLocation[`log4j2.trustStoreLocation`]. + +| [[TrustStoreConfiguration-attr-password]]password +| `String` +| `null` +| +The password for the trust store. + +See also xref:manual/systemproperties.adoc#log4j2.trustStorePassword[`log4j2.trustStorePassword`]. + +| [[TrustStoreConfiguration-attr-passwordEnvironmentVariable]]passwordEnvironmentVariable +| `String` +| `null` +| +The name of the environment variable that contains the password for the trust store. + +See also xref:manual/systemproperties.adoc#log4j2.trustStorePasswordEnvironmentVariable[`log4j2.trustStorePasswordEnvironmentVariable`]. + +| [[TrustStoreConfiguration-attr-passwordFile]]passwordFile +| https://docs.oracle.com/javase/{java-target-version}/docs/api/java/nio/file/Path.html[`Path`] +| `null` +| +The name of a file that contains the password for the trust store. + +See also xref:manual/systemproperties.adoc#log4j2.trustStorePasswordFile[`log4j2.trustStorePasswordFile`]. + +| [[TrustStoreConfiguration-attr-type]]type +| https://docs.oracle.com/javase/{java-target-version}/docs/technotes/guides/security/StandardNames.html#KeyStore[`KeyStore`] +| https://docs.oracle.com/javase/{java-target-version}/docs/api/java/security/KeyStore.html#getDefaultType--[_JVM dependent_] +| +The type of trust store. +See https://docs.oracle.com/javase/{java-target-version}/docs/technotes/guides/security/StandardNames.html#KeyStore[`KeyStore` standard types]. + +See also xref:manual/systemproperties.adoc#log4j2.trustStoreType[`log4j2.trustStoreType`]. + +| [[TrustStoreConfiguration-attr-keyManagerFactoryAlgorithm]]keyManagerFactoryAlgorithm +| https://docs.oracle.com/javase/{java-target-version}/docs/technotes/guides/security/StandardNames.html#KeyManagerFactory[`KeyManagerFactory`] +|https://docs.oracle.com/javase/{java-target-version}/docs/api/javax/net/ssl/KeyManagerFactory.html#getDefaultAlgorithm--[_JVM dependent_] +| +Name of the https://docs.oracle.com/javase/{java-target-version}/docs/api/javax/net/ssl/KeyManagerFactory.html[`KeyManagerFactory`] implementation to use for the trust store. +See https://docs.oracle.com/javase/{java-target-version}/docs/technotes/guides/security/StandardNames.html#KeyManagerFactory[`KeyManagerFactory` standard names]. + +See also xref:manual/systemproperties.adoc#log4j2.trustStoreKeyManagerFactoryAlgorithm[`log4j2.trustStoreKeyManagerFactoryAlgorithm`]. +|=== + +xref:plugin-reference.adoc#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-net-ssl-TrustStoreConfiguration[{open-book} Plugin reference for `TrustStore`] + +[#SslConfiguration-examples] +==== TLS configuration example + +This is an example of TLS configuration: + +[tabs] +==== +XML:: ++ +.Snippet from an example {antora-examples-url}/manual/appenders/network/ssl.xml[`log4j2.xml`] +[source,xml,indent=0] +---- +include::example$manual/appenders/network/ssl.xml[tag=ssl] +---- + +JSON:: ++ +.Snippet from an example {antora-examples-url}/manual/appenders/network/ssl.json[`log4j2.json`] +[source,json,indent=0] +---- +include::example$manual/appenders/network/ssl.json[tag=ssl] +---- + +YAML:: ++ +.Snippet from an example {antora-examples-url}/manual/appenders/network/ssl.yaml[`log4j2.yaml`] +[source,yaml,indent=0] +---- +include::example$manual/appenders/network/ssl.yaml[tag=ssl] +---- + +Properties:: ++ +.Snippet from an example {antora-examples-url}/manual/appenders/network/ssl.properties[`log4j2.properties`] +[source,properties,indent=0] +---- +include::example$manual/appenders/network/ssl.properties[tag=ssl] +---- +==== + +[#HttpAppender] +== HTTP Appender + +The HTTP Appender sends log events over HTTP, by wrapping them in an HTTP request. +The `Content-Type` HTTP header is set based on the +link:../javadoc/log4j-core/org/apache/logging/log4j/core/Layout.html#getContentType()[`getContentType()`] +method of the +<<HttpAppender-element-Layout,nested layout>>. +Additional headers can be configured using the nested +<<HttpAppender-element-Property,`Property` elements>>. + +If the appender receives a response with status code different from `2xx`, an exception is thrown. +See also <<HttpAppender-attr-ignoreExceptions,`ignoreExceptions`>> configuration attribute. + +[NOTE] +==== +The implementation uses +https://docs.oracle.com/javase/{java-target-version}/docs/api/java/net/HttpURLConnection.html[`HttpURLConnection`] +under the hood. +==== + +[#HttpAppender-attributes] +.HTTP Appender configuration attributes +[cols="1m,1,1,5"] +|=== +| Attribute | Type | Default value | Description + +4+h| Required + +| [[HttpAppender-attr-name]]name +| `String` +| +| The name of the appender. + +| [[HttpAppender-attr-url]]url +| https://docs.oracle.com/javase/8/docs/api/java/net/URL.html[`URL`] +| +| The URL of the HTTP server. +Only the `http` and `https` schemas are supported. + +4+h| Optional + +| [[HttpAppender-attr-connectTimeoutMillis]]connectTimeoutMillis +| `int` +| `0` +| +The connect timeout in milliseconds. +If `0` the timeout is infinite. + +| [[HttpAppender-attr-readTimeoutMillis]]readTimeoutMillis +| `int` +| `0` +|The socket read timeout in milliseconds. +If `0` the timeout is infinite. + +| [[HttpAppender-attr-ignoreExceptions]]ignoreExceptions +| `boolean` +| `true` +| If `false`, logging exception will be forwarded to the caller of the logging statement. +Otherwise, they will be ignored. + +Logging exceptions are always also logged to xref:manual/status-logger.adoc[] + +| [[HttpAppender-attr-method]]method +| `String` +| `POST` +| The HTTP method to use. + +| [[HttpAppender-attr-verifyHostName]]verifyHostName +| `boolean` +| `true` +| +If `true`, the host name in X509 certificate will be compared to the requested host name. +In the case of a mismatch, the connection will fail. + +|=== + +[#HttpAppender-elements] +.HTTP Appender nested elements +[cols="1m,1,4"] +|=== +| Type | Multiplicity | Description + +| [[HttpAppender-element-Filter]]xref:manual/filters.adoc[`Filter`] +| zero or one +| +Allows filtering log events just before they are formatted and sent. + +See also xref:manual/filters.adoc#appender-stage[appender filtering stage]. + +| [[HttpAppender-element-Layout]]xref:manual/layouts.adoc[`Layout`] +| **one** +| +Formats log events. +The choice of the layout is also responsible for the `Content-Type` header of HTTP requests. + +See xref:manual/layouts.adoc[] for more information. + +| [[HttpAppender-element-Property]]xref:plugin-reference.adoc#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-config-Property[`Property`] +| zero or more +| Additional HTTP headers to use. + +The values support +xref:manual/configuration.adoc#lazy-property-substitution[runtime property substitution] +and are evaluated in a +xref:manual/lookups.adoc#global-context[_global context_]. + +| [[HttpAppender-element-SslConfiguration]]<<SslConfiguration,`SSL`>> +| zero or one +| +It specifies the TLS parameters to use. +See <<tls-configuration>> for more details. + +|=== + +xref:plugin-reference.adoc#org-apache-logging-log4j_log4j-core_org-apache-logging-log4j-core-appender-HttpAppender[{open-book} Plugin reference for `HTTP`] + +[#HttpAppender-examples] +=== Configuration examples + +Here is a sample Http Appender configuration snippet: + +[tabs] +==== +XML:: ++ +.Snippet from an example {antora-examples-url}/manual/appenders/network/http.xml[`log4j2.xml`] +[source,xml,indent=0] +---- +include::example$manual/appenders/network/http.xml[tag=appender] +---- + +JSON:: ++ +.Snippet from an example {antora-examples-url}/manual/appenders/network/http.json[`log4j2.json`] +[source,json,indent=0] +---- +include::example$manual/appenders/network/http.json[tag=appender] +---- + +YAML:: ++ +.Snippet from an example {antora-examples-url}/manual/appenders/network/http.yaml[`log4j2.yaml`] +[source,yaml,indent=0] +---- +include::example$manual/appenders/network/http.yaml[tag=appender] +---- + +Properties:: ++ +.Snippet from an example {antora-examples-url}/manual/appenders/network/http.properties[`log4j2.properties`] +[source,properties,indent=0] +---- +include::example$manual/appenders/network/http.properties[tag=appender] +---- +==== + +<1> This HTTP header is evaluated once at configuration time. +<2> This HTTP header is evaluated at each log event. + +[[SMTPAppender]] +== SMTP Appender + +The SMTP writes log events to an e-mail service using +https://jakarta.ee/specifications/mail/1.6/[Jakarta Mail 1.6 or higher]. + +[IMPORTANT] +==== +Unlike what happens with +xref:manual/filters.adoc#appender-stage[most appenders], the SMTP does **not** discard log events that are denied by the +<<SmtpAppender-element-Filter,`Filter`>> element. + +All the log events received by the appender are added to a cyclic log event buffer as context. +If the filter accepts a message, an e-mail is sent. +==== + +[#SmtpAppender-attributes] +.SMTP Appender configuration attributes +[cols="1m,1,2,5"] +|=== +| Attribute | Type | Default value | Description + +4+h| Required + +| [[SmtpAppender-attr-name]]name +| `String` +| +| The name of the appender. + +4+h| Optional + +| [[SmtpAppender-attr-bufferSize]]bufferSize +| `int` +| `512` +| +The maximum number of log events to be buffered for inclusion in a single message. + +| [[SmtpAppender-attr-ignoreExceptions]]ignoreExceptions +| `boolean` +| `true` +| If `false`, logging exception will be forwarded to the caller of the logging statement. +Otherwise, they will be ignored. + +Logging exceptions are always also logged to xref:manual/status-logger.adoc[] + +| [[SmtpAppender-attr-smtpDebug]]smtpDebug +| `boolean` +| `false` +| +When set to `true` turns on the session debugging. +In the reference implementation of Jakarta Mail +(https://projects.eclipse.org/projects/ee4j.angus[Eclipse Angus]) +this will cause log messages to be printed on `System.out`. + +See the javadoc of +https://jakarta.ee/specifications/mail/2.1/apidocs/jakarta.mail/jakarta/mail/session#setDebug(boolean)[`Session.setDebug()`] +for more details. + +| [[SmtpAppender-attr-]]smtpProtocol +| `String` +| `smtp` +a| +The Jakarta Mail transport protocol. +Most implementations provide: + +`smtp`:: +SMTP + +`smtps`:: +SMTP over TLS + +| [[SmtpAppender-attr-smtpHost]]smtpHost +| `String` +| `localhost` +| +The SMTP hostname to send to. + +| [[SmtpAppender-attr-Port]]smtpPort +| `int` +a| +`25`:: for `smtp` +`465`:: for `smtps` +|The SMTP port to send to. + +| [[SmtpAppender-attr-smtpUsername]]smtpUsername +| `String` +| +| +The username used to authenticate against the SMTP server. + +| [[SmtpAppender-attr-smtpPassword]]smtpPassword +| `String` +| +|The password used to authenticate against the SMTP server. + + +4+h| https://datatracker.ietf.org/doc/html/rfc5322[RFC 822 message] fields + +| [[SmtpAppender-attr-from]]from +| https://jakarta.ee/specifications/mail/2.1/apidocs/jakarta.mail/jakarta/mail/internet/internetaddress[`InternetAddress[]`] Review Comment: Array notations break the AsciiDoc syntax:  ########## src/site/antora/modules/ROOT/pages/manual/appenders/network.adoc: ########## @@ -0,0 +1,980 @@ +//// + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with + the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. +//// + += Network Appenders Review Comment: ```suggestion = Network appenders ``` -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
