-.TH WIMLIB-IMAGEX "1" "December 2013" "@IMAGEX_PROGNAME@ @VERSION@" "User Commands"
+.TH WIMLIB-IMAGEX "1" "January 2014" "@IMAGEX_PROGNAME@ @VERSION@" "User Commands"
.SH NAME
@IMAGEX_PROGNAME@-apply \- Extract one image, or all images, from a WIM archive
.SH SYNOPSIS
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
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, 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
-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.
+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":
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)
git://wimlib.net / wimlib / blobdiff