Repository: logging-log4j2 Updated Branches: refs/heads/master 9d32793b1 -> b96e13342
[LOG4J2-1699] Configurable Log File Permissions with PosixFilePermission. Apply doc patch. Project: http://git-wip-us.apache.org/repos/asf/logging-log4j2/repo Commit: http://git-wip-us.apache.org/repos/asf/logging-log4j2/commit/b96e1334 Tree: http://git-wip-us.apache.org/repos/asf/logging-log4j2/tree/b96e1334 Diff: http://git-wip-us.apache.org/repos/asf/logging-log4j2/diff/b96e1334 Branch: refs/heads/master Commit: b96e13342dc4cd514d75253212decb9ec1188c18 Parents: 9d32793 Author: Pierrick HYMBERT <[email protected]> Authored: Fri Jun 23 14:54:08 2017 -0700 Committer: Gary Gregory <[email protected]> Committed: Fri Jun 23 14:54:08 2017 -0700 ---------------------------------------------------------------------- src/site/xdoc/manual/appenders.xml | 177 +++++++++++++++++++++++++++++++- 1 file changed, 175 insertions(+), 2 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/logging-log4j2/blob/b96e1334/src/site/xdoc/manual/appenders.xml ---------------------------------------------------------------------- diff --git a/src/site/xdoc/manual/appenders.xml b/src/site/xdoc/manual/appenders.xml index e5ef6ad..ba1bf7d 100644 --- a/src/site/xdoc/manual/appenders.xml +++ b/src/site/xdoc/manual/appenders.xml @@ -644,7 +644,6 @@ CREATE TABLE logs ( the file lock is "advisory" meaning that other applications can perform operations on the file without acquiring a lock. The default value is false.</td> </tr> - <tr> <td>name</td> <td>String</td> @@ -658,6 +657,31 @@ CREATE TABLE logs ( caller, instead. You must set this to <code>false</code> when wrapping this Appender in a <a href="#FailoverAppender">FailoverAppender</a>.</td> </tr> + <tr> + <td>filePermissions</td> + <td>String</td> + <td><p>File attribute permissions in POSIX format to apply whenever the file is created.</p> + <p>Underlying files system shall support <a class="javadoc" href="https://docs.oracle.com/javase/7/docs/api/java/nio/file/attribute/PosixFileAttributeView.html";>POSIX</a> file attribute view.</p> + <p>Examples: rw------- or rw-rw-rw- etc...</p></td> + </tr> + <tr> + <td>fileOwner</td> + <td>String</td> + <td><p>File owner to define whenever the file is created.</p> + <p>Changing file's owner may be restricted for security reason and Operation not permitted IOException thrown. + Only processes with an effective user ID equal to the user ID + of the file or with appropriate privileges may change the ownership of a file + if <a href="http://www.gnu.org/software/libc/manual/html_node/Options-for-Files.html";>_POSIX_CHOWN_RESTRICTED</a> is in effect for path.</p> + <p>Underlying files system shall support file <a class="javadoc" href="https://docs.oracle.com/javase/7/docs/api/java/nio/file/attribute/FileOwnerAttributeView.html";>owner</a> attribute view.</p> + </td> + </tr> + <tr> + <td>fileGroup</td> + <td>String</td> + <td><p>File group to define whenever the file is created.</p> + <p>Underlying files system shall support <a class="javadoc" href="https://docs.oracle.com/javase/7/docs/api/java/nio/file/attribute/PosixFileAttributeView.html";>POSIX</a> file attribute view.</p> + </td> + </tr> </table> <p> Here is a sample File configuration: @@ -2509,8 +2533,10 @@ public class JpaLogEntity extends AbstractLogEventWrapperEntity { is configured, RollingFileAppender will use the <a href="#DefaultRolloverStrategy">DefaultRolloverStrategy</a>. Since log4j-2.5, a <a href="#CustomDeleteOnRollover">custom delete action</a> can be configured in the DefaultRolloverStrategy to run at rollover. Since 2.8 if no file name is configured then - <a href="DirectWriteRolloverStrategy">DirectWriteRolloverStrategy</a> will be used instead of + <a href="#DirectWriteRolloverStrategy">DirectWriteRolloverStrategy</a> will be used instead of DefaultRolloverStrategy. + Since log4j-2.8.3, a <a href="#CustomPosixViewAttributeOnRollover">custom POSIX file attribute view action</a> can be configured in the + DefaultRolloverStrategy to run at rollover, if not defined, inherited POSIX file attribute view from the RollingFileAppender will be applied. </p> <p> File locking is not supported by the RollingFileAppender. @@ -2613,6 +2639,31 @@ public class JpaLogEntity extends AbstractLogEventWrapperEntity { caller, instead. You must set this to <code>false</code> when wrapping this Appender in a <a href="#FailoverAppender">FailoverAppender</a>.</td> </tr> + <tr> + <td>filePermissions</td> + <td>String</td> + <td><p>File attribute permissions in POSIX format to apply whenever the file is created.</p> + <p>Underlying files system shall support <a class="javadoc" href="https://docs.oracle.com/javase/7/docs/api/java/nio/file/attribute/PosixFileAttributeView.html";>POSIX</a> file attribute view.</p> + <p>Examples: rw------- or rw-rw-rw- etc...</p></td> + </tr> + <tr> + <td>fileOwner</td> + <td>String</td> + <td><p>File owner to define whenever the file is created.</p> + <p>Changing file's owner may be restricted for security reason and Operation not permitted IOException thrown. + Only processes with an effective user ID equal to the user ID + of the file or with appropriate privileges may change the ownership of a file + if <a href="http://www.gnu.org/software/libc/manual/html_node/Options-for-Files.html";>_POSIX_CHOWN_RESTRICTED</a> is in effect for path.</p> + <p>Underlying files system shall support file <a class="javadoc" href="https://docs.oracle.com/javase/7/docs/api/java/nio/file/attribute/FileOwnerAttributeView.html";>owner</a> attribute view.</p> + </td> + </tr> + <tr> + <td>fileGroup</td> + <td>String</td> + <td><p>File group to define whenever the file is created.</p> + <p>Underlying files system shall support <a class="javadoc" href="https://docs.oracle.com/javase/7/docs/api/java/nio/file/attribute/PosixFileAttributeView.html";>POSIX</a> file attribute view.</p> + </td> + </tr> </table> <a name="TriggeringPolicies"/> <h4>Triggering Policies</h4> @@ -3455,6 +3506,103 @@ public class JpaLogEntity extends AbstractLogEventWrapperEntity { </Root> </Loggers> </Configuration>]]></pre> + + <a name="CustomPosixViewAttributeOnRollover"/> + <h5>Log Archive File Attribute View Policy: Custom file attribute on Rollover</h5> + <p> + Log4j-2.8.3 introduces a <tt>PosixViewAttribute</tt> action that gives users more control + over which file attribute permissions, owner and group should be applied. + The PosixViewAttribute action lets users configure one or more conditions that select the eligible files + relative to a base directory. + </p> + <table> + <caption align="top">PosixViewAttribute Parameters</caption> + <tr> + <th>Parameter Name</th> + <th>Type</th> + <th>Description</th> + </tr> + <tr> + <td>basePath</td> + <td>String</td> + <td><em>Required.</em> Base path from where to start scanning for files to apply attributes.</td> + </tr> + <tr> + <td>maxDepth</td> + <td>int</td> + <td>The maximum number of levels of directories to visit. A value of 0 + means that only the starting file (the base path itself) is visited, + unless denied by the security manager. A value of + Integer.MAX_VALUE indicates that all levels should be visited. The default is 1, + meaning only the files in the specified base directory.</td> + </tr> + <tr> + <td>followLinks</td> + <td>boolean</td> + <td>Whether to follow symbolic links. Default is false.</td> + </tr> + <tr> + <td>pathConditions</td> + <td>PathCondition[]</td> + <td>see <a href="#DeletePathCondition">DeletePathCondition</a></td> + </tr> + <tr> + <td>filePermissions</td> + <td>String</td> + <td><p>File attribute permissions in POSIX format to apply when action is executed.</p> + <p>Underlying files system shall support <a class="javadoc" href="https://docs.oracle.com/javase/7/docs/api/java/nio/file/attribute/PosixFileAttributeView.html";>POSIX</a> file attribute view.</p> + <p>Examples: rw------- or rw-rw-rw- etc...</p></td> + </tr> + <tr> + <td>fileOwner</td> + <td>String</td> + <td><p>File owner to define when action is executed.</p> + <p>Changing file's owner may be restricted for security reason and Operation not permitted IOException thrown. + Only processes with an effective user ID equal to the user ID + of the file or with appropriate privileges may change the ownership of a file + if <a href="http://www.gnu.org/software/libc/manual/html_node/Options-for-Files.html";>_POSIX_CHOWN_RESTRICTED</a> is in effect for path.</p> + <p>Underlying files system shall support file <a class="javadoc" href="https://docs.oracle.com/javase/7/docs/api/java/nio/file/attribute/FileOwnerAttributeView.html";>owner</a> attribute view.</p> + </td> + </tr> + <tr> + <td>fileGroup</td> + <td>String</td> + <td><p>File group to define whene action is executed.</p> + <p>Underlying files system shall support <a class="javadoc" href="https://docs.oracle.com/javase/7/docs/api/java/nio/file/attribute/PosixFileAttributeView.html";>POSIX</a> file attribute view.</p> + </td> + </tr> + </table> + + <p> + Below is a sample configuration that uses a RollingFileAppender and defines different POSIX file attribute view for current and rolled log files. + </p> + + <pre class="prettyprint linenums"><![CDATA[<?xml version="1.0" encoding="UTF-8"?> +<Configuration status="trace" name="MyApp" packages=""> + <Properties> + <Property name="baseDir">logs</Property> + </Properties> + <Appenders> + <RollingFile name="RollingFile" fileName="${baseDir}/app.log" + filePattern="${baseDir}/$${date:yyyy-MM}/app-%d{yyyyMMdd}.log.gz" + filePermissions="rw-------"> + <PatternLayout pattern="%d %p %c{1.} [%t] %m%n" /> + <CronTriggeringPolicy schedule="0 0 0 * * ?"/> + <DefaultRolloverStrategy stopCustomActionsOnError="true"> + <PosixViewAttribute basePath="${baseDir}/$${date:yyyy-MM}" filePermissions="r--r--r--"> + <IfFileName glob="*.gz" /> + </PosixViewAttribute> + </DefaultRolloverStrategy> + </RollingFile> + </Appenders> + + <Loggers> + <Root level="error"> + <AppenderRef ref="RollingFile"/> + </Root> + </Loggers> + +</Configuration>]]></pre> </subsection> <a name="RollingRandomAccessFileAppender" /> @@ -3602,6 +3750,31 @@ public class JpaLogEntity extends AbstractLogEventWrapperEntity { caller, instead. You must set this to <code>false</code> when wrapping this Appender in a <a href="#FailoverAppender">FailoverAppender</a>.</td> </tr> + <tr> + <td>filePermissions</td> + <td>String</td> + <td><p>File attribute permissions in POSIX format to apply whenever the file is created.</p> + <p>Underlying files system shall support <a class="javadoc" href="https://docs.oracle.com/javase/7/docs/api/java/nio/file/attribute/PosixFileAttributeView.html";>POSIX</a> file attribute view.</p> + <p>Examples: <code>rw-------</code> or <code>rw-rw-rw-</code> etc...</p></td> + </tr> + <tr> + <td>fileOwner</td> + <td>String</td> + <td><p>File owner to define whenever the file is created.</p> + <p>Changing file's owner may be restricted for security reason and Operation not permitted IOException thrown. + Only processes with an effective user ID equal to the user ID + of the file or with appropriate privileges may change the ownership of a file + if <a href="http://www.gnu.org/software/libc/manual/html_node/Options-for-Files.html";>_POSIX_CHOWN_RESTRICTED</a> is in effect for path.</p> + <p>Underlying files system shall support file <a class="javadoc" href="https://docs.oracle.com/javase/7/docs/api/java/nio/file/attribute/FileOwnerAttributeView.html";>owner</a> attribute view.</p> + </td> + </tr> + <tr> + <td>fileGroup</td> + <td>String</td> + <td><p>File group to define whenever the file is created.</p> + <p>Underlying files system shall support <a class="javadoc" href="https://docs.oracle.com/javase/7/docs/api/java/nio/file/attribute/PosixFileAttributeView.html";>POSIX</a> file attribute view.</p> + </td> + </tr> </table> <a name="FRFA_TriggeringPolicies" /> <h4>Triggering Policies</h4>
