Github user arshadmohammad commented on a diff in the pull request:
https://github.com/apache/zookeeper/pull/338#discussion_r136176181
--- Diff: src/docs/src/documentation/content/xdocs/zookeeperAuditLogs.xml
---
@@ -0,0 +1,205 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ Copyright 2002-2004 The Apache Software Foundation
+
+ Licensed 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.
+-->
+<!DOCTYPE article PUBLIC "-//OASIS//DTD Simplified DocBook XML V1.0//EN"
+"http://www.oasis-open.org/docbook/xml/simple/1.0/sdocbook.dtd";>
+<article id="ar_auditLogs">
+ <title>ZooKeeper Audit Logging</title>
+ <articleinfo>
+ <legalnotice>
+ <para>Licensed 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 <ulink
+
url="http://www.apache.org/licenses/LICENSE-2.0";>http://www.apache.org/licenses/LICENSE-2.0</ulink>.</para>
+
+ <para>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.</para>
+ </legalnotice>
+
+ <abstract>
+ <para>This document contains information about Audit Logs in
ZooKeeper.</para>
+ </abstract>
+ </articleinfo>
+ <section id="ch_auditLogs">
+ <title>ZooKeeper Audit Logs</title>
+ <para>Apache ZooKeeper supports audit logs form version 3.5.4. By
default audit logs are disabled. To enable audit
+ logs configure audit.enable=true in conf/zoo.cfg. Audit logs are not
logged on all the ZooKeeper servers, but logged
+ only on the servers where client is connected as depicted in bellow
figure.</para>
+ <mediaobject id="fg_audit" >
+ <imageobject>
+ <imagedata fileref="images/zkAuditLogs.jpg"/>
+ </imageobject>
+ </mediaobject>
+ <para>The audit log captures the detailed information for the
operations that are selected to be audited. The audit
+ information is written as a set of key=value pairs for the following
keys.</para>
+ <table>
+ <title>Audit Log Content</title>
+ <tgroup cols="5" align="left" colsep="1" rowsep="4">
+ <thead>
+ <row>
+ <entry>Key</entry>
+ <entry>Value</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>session</entry>
+ <entry>client session id</entry>
+ </row>
+ <row>
+ <entry>user</entry>
+ <entry>
+ comma separated list of users who are associate
with a client session. To know who is taken as user in audit logs
+ refer section
+ <xref linkend="ch_zkAuditUser"/>
+ </entry>
+ </row>
+ <row>
+ <entry>ip</entry>
+ <entry>client IP address</entry>
+ </row>
+ <row>
+ <entry>operation</entry>
+ <entry>any one of the selected operations for audit.
Possible values are
+ (serverStart| serverStop| create| delete| setData|
setAcl| multiOperation| reconfig| ephemeralZNodeDeleteOnSessionClose)
+ </entry>
+ </row>
+ <row>
+ <entry>znode</entry>
+ <entry>path of the znode</entry>
+ </row>
+ <row>
+ <entry>acl</entry>
+ <entry>String representation of znode ACL like
cdrwa(create, delete,read, write, admin). This is logged
+ only for setAcl operation</entry>
+ </row>
+ <row>
+ <entry>result</entry>
+ <entry>result of the operation. Possible values are
(success|failure|invoked). Result "invoked" is used
+ for serverStop operation because stop is logged
before ensuring that server actually stopped.
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ <para>Below are sample audit logs for all operations, where client is
connected from 192.168.1.2, client principal is
+ [email protected], server principal is
zookeeper/[email protected]</para>
+ <programlisting>
+ user=zookeeper/192.168.1.3 operation=serverStart result=success
+ session=0x19344730000 user=192.168.1.2,[email protected]
ip=192.168.1.2 operation=create znode=/a result=success
+ session=0x19344730000 user=192.168.1.2,[email protected]
ip=192.168.1.2 operation=create znode=/a result=failure
+ session=0x19344730000 user=192.168.1.2,[email protected]
ip=192.168.1.2 operation=setData znode=/a result=failure
+ session=0x19344730000 user=192.168.1.2,[email protected]
ip=192.168.1.2 operation=setData znode=/a result=success
+ session=0x19344730000 user=192.168.1.2,[email protected]
ip=192.168.1.2 operation=setAcl znode=/a acl=world:anyone:cdrwa
result=failure
+ session=0x19344730000 user=192.168.1.2,[email protected]
ip=192.168.1.2 operation=setAcl znode=/a acl=world:anyone:cdrwa
result=success
+ session=0x19344730000 user=192.168.1.2,[email protected]
ip=192.168.1.2 operation=create znode=/b result=success
+ session=0x19344730000 user=192.168.1.2,[email protected]
ip=192.168.1.2 operation=setData znode=/b result=success
+ session=0x19344730000 user=192.168.1.2,[email protected]
ip=192.168.1.2 operation=delete znode=/b result=success
+ session=0x19344730000 user=192.168.1.2,[email protected]
ip=192.168.1.2 operation=multiOperation result=failure
+ session=0x19344730000 user=192.168.1.2,[email protected]
ip=192.168.1.2 operation=delete znode=/a result=failure
+ session=0x19344730000 user=192.168.1.2,[email protected]
ip=192.168.1.2 operation=delete znode=/a result=success
+ session=0x19344730001 user=192.168.1.2,[email protected]
ip=192.168.1.2 operation=create znode=/ephemral result=success
+ session=0x19344730001 user=zookeeper/192.168.1.3
operation=ephemeralZNodeDeletionOnSessionCloseOrExpire znode=/ephemral
result=success
+ session=0x19344730000 user=192.168.1.2,[email protected]
ip=192.168.1.2 operation=reconfig znode=/zookeeper/config result=success
+ user=zookeeper/192.168.1.3 operation=serverStop result=invoked
+ </programlisting>
+ </section>
+ <section id="ch_auditConfig">
+ <title>ZooKeeper Audit Log Configuration</title>
+ <para>By default audit logs are disabled. To enable audit logs
configure audit.enable=true in conf/zoo.cfg. Audit
+ logging is done using log4j. Following is the default log4j
configuration for audit logs in conf/log4j.properties
+ </para>
+ <programlisting>
+ #
--- End diff --
This is important part of the audit log configuration. These will rarely be
changed. I think it is ok to keep it here.
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at [email protected] or file a JIRA ticket
with INFRA.
---
