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 759bbd86e3b0cd02ed4df137f1c5f50ba3232569..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


@@ -372,22 +393,26 @@ differing only in case, one will be chosen to extract arbitrarily; however, with
 \fB--include-invalid-names\fR, all names will be sanitized and extracted in some
 form.
 .SH NOTES
 \fB--include-invalid-names\fR, all names will be sanitized and extracted in some
 form.
 .SH NOTES

+\fIData integrity\fR:  WIM files include SHA1 message digests for file data.

 \fB@IMAGEX_PROGNAME@ apply\fR calculates the SHA1 message digest of every file
 \fB@IMAGEX_PROGNAME@ apply\fR calculates the SHA1 message digest of every file

-stream it extracts and verifies that it is the same as the SHA1 message digest
-provided in the WIM file.  It is an error if the message digests don't match.
-It's also considered to be an error if any WIM resources that need to be
-extracted cannot be found in the stream lookup table.  So you can be fairly
-certain that the file streams are extracted correctly, even though
-\fB@IMAGEX_PROGNAME@ apply\fR don't have a \fB/verify\fR option like Microsoft's
-ImageX does.  Note that this is separate from the integrity table of the WIM,
-which provides SHA1 message digests over raw chunks of the entire WIM file and
-is checked separately if the \fB--check\fR option is specified.
-.PP
-wimlib v1.6.0 and later can extract files from version 3584 WIMs, which usually
-use packed, LZMS-compressed streams and may carry the \fI.esd\fR file extension
-rather than \fI.wim\fR.  However, \fI.esd\fR files downloaded directly by the
-Windows 8 web downloader have encrypted segments, and wimlib cannot extract such
-files until they are first decrypted.
+it extracts and issues an error if it is not equal to the SHA1 message digest
+provided in the WIM.  (This default behavior seems equivalent to the
+\fB/verify\fR option of ImageX.)  Note that this is separate from the integrity
+table of the WIM, which provides SHA1 message digests over raw chunks of the
+entire WIM file and is checked separately if the \fB--check\fR option is
+specified.
+.PP
+\fIESD files\fR: wimlib v1.6.0 and later can extract files from version 3584
+WIMs, which usually contain LZMS-compressed solid blocks and may carry the
+\fI.esd\fR file extension rather than \fI.wim\fR.  However, \fI.esd\fR files
+downloaded directly by the Windows 8 web downloader have encrypted segments, and
+wimlib cannot extract such files until they are first decrypted.
+.PP
+\fIDirectory traversal attacks\fR:  wimlib validates filenames before extracting
+them and is not vulnerable to directory traversal attacks.  This is in contrast
+to Microsoft WIMGAPI/Imagex/Dism which can overwrite arbitrary files on the
+target drive when extracting a malicious WIM file containing files named
+\fI..\fR or containing path separators.

 .SH EXAMPLES
 Extract the first image from the Windows PE image on the Windows Vista/7/8
 installation media to the directory "boot":
 .SH EXAMPLES
 Extract the first image from the Windows PE image on the Windows Vista/7/8
 installation media to the directory "boot":


@@ -431,16 +456,6 @@ partition!)
 An example of applying a pipable WIM from a pipe can be found in \fBPIPABLE
 WIMS\fR, and an example of applying a split WIM can be found in \fBSPLIT
 WIMS\fR.
 An example of applying a pipable WIM from a pipe can be found in \fBPIPABLE
 WIMS\fR, and an example of applying a split WIM can be found in \fBSPLIT
 WIMS\fR.

-.PP
-And finally, just for fun, a silly way to recursively copy a directory tree
-\fIsrc\fR to \fIdst\fR (but subject to the documented limitations, e.g.
-platform and filesystem-dependent, of the capture and apply functionality of
-\fB@IMAGEX_PROGNAME@\fR):
-.RS
-.PP
-@IMAGEX_PROGNAME@ capture src - | @IMAGEX_PROGNAME@ apply - dst
-.RE
-.PP

 .SH SEE ALSO
 .BR @IMAGEX_PROGNAME@ (1)
 .BR @IMAGEX_PROGNAME@-capture (1)
 .SH SEE ALSO
 .BR @IMAGEX_PROGNAME@ (1)
 .BR @IMAGEX_PROGNAME@-capture (1)