Github user afine commented on a diff in the pull request: https://github.com/apache/zookeeper/pull/338#discussion_r135346005 --- 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 + zk...@hadoop.com, server principal is zookeeper/192.168....@hadoop.com</para> + <programlisting> + user=zookeeper/192.168.1.3 operation=serverStart result=success + session=0x19344730000 user=192.168.1.2,zk...@hadoop.com ip=192.168.1.2 operation=create znode=/a result=success + session=0x19344730000 user=192.168.1.2,zk...@hadoop.com ip=192.168.1.2 operation=create znode=/a result=failure + session=0x19344730000 user=192.168.1.2,zk...@hadoop.com ip=192.168.1.2 operation=setData znode=/a result=failure + session=0x19344730000 user=192.168.1.2,zk...@hadoop.com ip=192.168.1.2 operation=setData znode=/a result=success + session=0x19344730000 user=192.168.1.2,zk...@hadoop.com ip=192.168.1.2 operation=setAcl znode=/a acl=world:anyone:cdrwa result=failure + session=0x19344730000 user=192.168.1.2,zk...@hadoop.com ip=192.168.1.2 operation=setAcl znode=/a acl=world:anyone:cdrwa result=success + session=0x19344730000 user=192.168.1.2,zk...@hadoop.com ip=192.168.1.2 operation=create znode=/b result=success + session=0x19344730000 user=192.168.1.2,zk...@hadoop.com ip=192.168.1.2 operation=setData znode=/b result=success + session=0x19344730000 user=192.168.1.2,zk...@hadoop.com ip=192.168.1.2 operation=delete znode=/b result=success + session=0x19344730000 user=192.168.1.2,zk...@hadoop.com ip=192.168.1.2 operation=multiOperation result=failure + session=0x19344730000 user=192.168.1.2,zk...@hadoop.com ip=192.168.1.2 operation=delete znode=/a result=failure + session=0x19344730000 user=192.168.1.2,zk...@hadoop.com ip=192.168.1.2 operation=delete znode=/a result=success + session=0x19344730001 user=192.168.1.2,zk...@hadoop.com 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,zk...@hadoop.com 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> + # + # zk audit logging + # + zookeeper.auditlog.file=zookeeper_audit.log + zookeeper.auditlog.threshold=INFO + audit.logger=INFO, RFAAUDIT + log4j.logger.org.apache.zookeeper.audit.ZKAuditLogger=${audit.logger} + log4j.additivity.org.apache.zookeeper.audit.ZKAuditLogger=false + log4j.appender.RFAAUDIT=org.apache.log4j.RollingFileAppender + log4j.appender.RFAAUDIT.File=${zookeeper.log.dir}/${zookeeper.auditlog.file} + log4j.appender.RFAAUDIT.layout=org.apache.log4j.PatternLayout + log4j.appender.RFAAUDIT.layout.ConversionPattern=%d{ISO8601} %p %c{2}: %m%n + log4j.appender.RFAAUDIT.Threshold=${zookeeper.auditlog.threshold} + + # Max log file size of 10MB + log4j.appender.RFAAUDIT.MaxFileSize=10MB + log4j.appender.RFAAUDIT.MaxBackupIndex=10 + </programlisting> + <para>Change above configuration to customize the auditlog file, number of backups, max file size etc.</para> + </section> + <section id="ch_zkAuditUser"> + <title>Who is taken as user in audit logs?</title> + <para>By default there are only four authentication provider</para> --- End diff -- "providers"
--- 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 infrastruct...@apache.org or file a JIRA ticket with INFRA. ---