imagex-apply.1.in: Add notes about Windows permissions being annoying

[wimlib] / doc / imagex-apply.1.in

diff --git a/doc/imagex-apply.1.in b/doc/imagex-apply.1.in
index 1b76adb01ba9f73994e52682adf08907104afe2d..c1ede60b6a66ed0aa8cd2063695793fdd4b70f6f 100644 (file)
--- a/doc/imagex-apply.1.in
+++ b/doc/imagex-apply.1.in
@@ -232,6 +232,24 @@ be extracted by default; see \fB--include-invalid-names\fR.
 Files with full paths over 260 characters (the so-called MAX_PATH) will be
 extracted, but beware that such files will be inaccessible to most Windows
 software and may not be able to be deleted easily.
 Files with full paths over 260 characters (the so-called MAX_PATH) will be
 extracted, but beware that such files will be inaccessible to most Windows
 software and may not be able to be deleted easily.

+.IP \[bu]
+On Windows, unless the \fB--no-acls\fR option is specified, wimlib will attempt
+to restore files' security descriptors exactly as they are provided in the WIM
+image.  Beware that typical Windows installations contain files whose security
+descriptors do not allow the Administrator to delete them.  Therefore, such
+files will not be able to be deleted, or in some cases even read, after
+extracting, unless processed with a specialized program that knows to acquire
+the SE_RESTORE_NAME and/or SE_BACKUP_NAME privileges which allow overriding
+access control lists.  This is not a bug in wimlib, which works as designed to
+correctly restore the data that was archived, but rather a problem with the
+access rights Windows uses on certain files.  But if you just want the file data
+and don't care about security descriptors, use \fB--no-acls\fR to skip restoring
+all security descriptors.
+.IP \[bu]
+A similar caveat to the above applies to file attributes such as Readonly,
+Hidden, and System.  By design, on Windows wimlib will restore such file
+attributes; therefore, extracted files may have those attributes.  If this is
+not what you want, use the \fB--no-attributes\fR option.

 .SH SPLIT WIMS
 You may use \fB@IMAGEX_PROGNAME@ apply\fR to apply images from a split WIM.  The
 \fIWIMFILE\fR argument must specify the first part of the split WIM, while the
 .SH SPLIT WIMS
 You may use \fB@IMAGEX_PROGNAME@ apply\fR to apply images from a split WIM.  The
 \fIWIMFILE\fR argument must specify the first part of the split WIM, while the


@@ -352,6 +370,9 @@ combined with \fB--unix-data\fR to cause \fB@IMAGEX_PROGNAME@\fR to fail
 immediately if the UNIX owner, group, or mode on an extracted file cannot be set
 for any reason.
 .TP
 immediately if the UNIX owner, group, or mode on an extracted file cannot be set
 for any reason.
 .TP

+\fB--no-attributes\fR
+Do not restore Windows file attributes such as readonly, hidden, etc.
+.TP

 \fB--include-invalid-names\fR
 Extract files and directories with invalid names by replacing characters and
 appending a suffix rather than ignoring them.  Exactly what is considered an
 \fB--include-invalid-names\fR
 Extract files and directories with invalid names by replacing characters and
 appending a suffix rather than ignoring them.  Exactly what is considered an