Update version to 1.6.3-BETA

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

diff --git a/doc/imagex-apply.1.in b/doc/imagex-apply.1.in
index 1a6d0a4114e404404f5cdb46c59ed7bd7355c035..e869174d10ba87c85e4f5bb6230493a457622823 100644 (file)
--- a/doc/imagex-apply.1.in
+++ b/doc/imagex-apply.1.in
@@ -1,4 +1,4 @@
-.TH WIMLIB-IMAGEX "1" "January 2014" "@IMAGEX_PROGNAME@ @VERSION@" "User Commands"
+.TH WIMLIB-IMAGEX "1" "March 2014" "@IMAGEX_PROGNAME@ @VERSION@" "User Commands"

 .SH NAME
 @IMAGEX_PROGNAME@-apply \- Extract one image, or all images, from a WIM archive
 .SH SYNOPSIS
 .SH NAME
 @IMAGEX_PROGNAME@-apply \- Extract one image, or all images, from a WIM archive
 .SH SYNOPSIS


@@ -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


@@ -371,6 +392,13 @@ default, invalid names will be ignored, and if there are multiple names
 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.
 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.

+.TP
+\fB--wimboot\fR
+Windows only: Instead of extracting the files themselves, extract "pointer
+files" back to the original WIM.  This is only expected to work on Windows 8.1
+and later, since only those versions of Windows contain the Windows Overlay File
+System Filter Driver that is necessary for this feature.  See Microsoft's
+documentation for "WIMBoot" for more information.

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


@@ -389,7 +417,7 @@ 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
 .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 override arbitrary files on the
+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
 target drive when extracting a malicious WIM file containing files named
 \fI..\fR or containing path separators.
 .SH EXAMPLES