From a88c050a05cc2727225497cbe2ce16f0c5a1766f Mon Sep 17 00:00:00 2001
From: Albert Zaharovits <albert.zaharovits@gmail.com>
Date: Tue, 15 Jan 2019 14:29:32 +0200
Subject: [PATCH] Docs be explicit on how to turn off deprecated auditing
 (#37316)

Just be explicit about turning off the deprecated audit log appender
because we really want people to turn it off.
---
 .../security/auditing/output-logfile.asciidoc | 35 ++++++++++++++++---
 1 file changed, 30 insertions(+), 5 deletions(-)

diff --git a/x-pack/docs/en/security/auditing/output-logfile.asciidoc b/x-pack/docs/en/security/auditing/output-logfile.asciidoc
index 382307e893f..ac7128852b9 100644
--- a/x-pack/docs/en/security/auditing/output-logfile.asciidoc
+++ b/x-pack/docs/en/security/auditing/output-logfile.asciidoc
@@ -7,11 +7,36 @@ the `<clustername>_audit.log` file in the logs directory. To maintain
 compatibility with releases prior to 6.5.0, a `<clustername>_access.log` file
 is also generated. They differ in the output format but the contents
 are similar. For systems that are not ingesting the audit file for search or
-analytics it is strongly recommended to only keep the newer format.
-Turning off the deprecated output format can be achieved by disabling the logger
-in the `log4j2.properties` file (hint: there is a config comment
-about it).
-For more information, see {ref}/logging.html#configuring-logging-levels[configuring-logging].
+analytics it is strongly recommended to keep only the newer format.
+
+To turn off the deprecated output format, you can disable the logger in the
+`log4j2.properties` file: 
+
+[source, properties]
+--------------------------------------------------
+# change info to off
+# logger.xpack_security_audit_deprecated_logfile.level = info
+logger.xpack_security_audit_deprecated_logfile.level = off
+--------------------------------------------------
+
+Alternatively, use the
+{ref}/cluster-update-settings.html[cluster update settings API] to dynamically
+configure the logger:
+
+[source,js]
+--------------------------------------------------
+PUT /_cluster/settings
+{
+  "persistent": {
+    "logger.org.elasticsearch.xpack.security.audit.logfile.DeprecatedLoggingAuditTrail": "off"
+  }
+}
+--------------------------------------------------
+// CONSOLE
+
+NOTE: If you overwrite the `log4j2.properties` and do not specify appenders for
+any of the audit trails, audit events are forwarded to the root appender, which
+by default points to the `elasticsearch.log` file.
 
 
 [float]