-.TH WIMLIB-IMAGEX "1" "August 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
all.
.SH NTFS VOLUME EXTRACTION (UNIX)
This section documents how \fB@IMAGEX_PROGNAME@ apply\fR extracts a WIM image
-directly to an NTFS volume image on UNIX-like systems. See \fBDIRECTORY EXTRACTION
-(WINDOWS)\fR for the corresponding documentation for Windows.
+directly to an NTFS volume image on UNIX-like systems.
.PP
As mentioned, \fB@IMAGEX_PROGNAME@\fR running on a UNIX-like system can apply a
WIM image directly to an NTFS volume by specifying \fITARGET\fR as a regular file
This NTFS volume extraction mode attempts to extract as much information as
possible, including:
.IP \[bu] 4
-All data streams of all files, including the unnamed data stream as well as all
-named data streams.
+All data streams of all files except encrypted files, including the unnamed data
+stream as well as all named data streams.
.IP \[bu]
Reparse points, including symbolic links, junction points, and other reparse
points.
.IP \[bu]
Since encrypted files (with FILE_ATTRIBUTE_ENCRYPTED) are not stored in
plaintext in the WIM image, \fB@IMAGEX_PROGNAME@\fR cannot restore encrypted
-files to filesystems not supporting encryption. Therefore, such files are not
-extracted. Furthermore, even if encrypted files are restored to a filesystem
-that supports encryption, they will only be decryptable if the decryption key is
-available.
+files to filesystems not supporting encryption. Therefore, on such filesystems,
+encrypted files will not be extracted. Furthermore, even if encrypted
+files are restored to a filesystem that supports encryption, they will only be
+decryptable if the decryption key is available.
.IP \[bu]
Files with names that cannot be represented on Windows will not
be extracted by default; see \fB--include-invalid-names\fR.
.IP \[bu]
-Files with full paths over 260 characters (MAX_PATH) are extracted by using the
-\\\\?\\-prefixed path hack. 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.
.SH SPLIT WIMS
You may use \fB@IMAGEX_PROGNAME@ apply\fR to apply images from a split WIM. The
-\fIWIMFILE\fR argument is used to specify the first part of the split WIM, and
-the \fB--refs\fR="\fIGLOB\fR" option is used to provide a shell-style file glob
-that specifies the additional parts of the split WIM. \fIGLOB\fR is expected to
-be a single string on the command line, so \fIGLOB\fR must be quoted so that it
-is protected against shell expansion. \fIGLOB\fR must expand to all parts of
-the split WIM, except optionally the first part which may either omitted or
-included in the glob (but the first part MUST be specified as \fIWIMFILE\fR as
-well).
-.PP
-Here's an example. The names for the split WIMs usually go something like:
+\fIWIMFILE\fR argument must specify the first part of the split WIM, while the
+additional parts of the split WIM must be specified in one or more
+\fB--ref\fR="\fIGLOB\fR" options. Since globbing is built into the \fB--ref\fR
+option, typically only one \fB--ref\fR option is necessary. For example, the
+names for the split WIM parts usually go something like:
.RS
.PP
.nf
nonseekable file, such as a pipe, provided that the WIM was captured with
\fB--pipable\fR (see \fB@IMAGEX_PROGNAME@ capture\fR(1)). To use standard input
as the WIM, specify "-" as \fIWIMFILE\fR. A useful use of this ability is to
-apply an image from a WIM while streaming it from a webserver; for example, to
-apply the first image from a WIM file to an NTFS volume on /dev/sda1:
+apply an image from a WIM while streaming it from a server. For example, to
+apply the first image from a WIM file available on a HTTP server to an NTFS
+volume on /dev/sda1, run something like:
.PP
.RS
wget -O - http://myserver/mywim.wim | wimapply - 1 /dev/sda1
present.
.TP
\fB--ref\fR="\fIGLOB\fR"
-File glob of additional split WIM parts that are part of the split WIM being
-applied. See \fBSPLIT_WIMS\fR.
+File glob of additional WIMs or split WIM parts to reference resources from.
+See \fBSPLIT_WIMS\fR. This option can be specified multiple times. Note:
+\fIGLOB\fR is listed in quotes because it is interpreted by
+\fB@IMAGEX_PROGNAME@\fR and may need to be quoted to protect against shell
+expansion.
.TP
\fB--rpfix\fR, \fB--norpfix\fR
Set whether to fix targets of absolute symbolic links (reparse points in Windows
terminology) or not. When enabled (\fB--rpfix\fR), extracted absolute symbolic
links that are marked in the WIM image as being fixed are assumed to have
-absolute targets relative to the image root, and therefore have the actual root
-of extraction prepended to their targets. The intention is that you can apply
-an image containing absolute symbolic links and still have them be valid after
-it has been applied to any location.
+absolute targets relative to the image root, and therefore \fB@IMAGEX_PROGNAME@
+apply\fR prepends the absolute path to the extraction target directory to their
+targets. The intention is that you can apply an image containing absolute
+symbolic links and still have them be valid after it has been applied to any
+location.
.IP ""
The default behavior is \fB--rpfix\fR if any images in \fIWIMFILE\fR have been
captured with reparse-point fixups done. Otherwise, it is \fB--norpfix\fR.
.IP ""
Reparse point fixups are never done in the NTFS volume extraction mode on
UNIX-like systems.
-.IP ""
-\fB--verbose\fR
-Print the path to of each file or directory within the WIM image as it is
-extracted.
.TP
\fB--hardlink\fR
When extracting a file from the WIM that is identical to a file that has already
.TP
\fB--strict-acls\fR
Fail immediately if the full security descriptor of any file or directory cannot
-be set exactly as specified in the WIM file. On Windows, the default behavior
-without this option is to fall back to setting a security descriptor with the
-SACL omitted, then only the default inherited security descriptor, if
-\fB@IMAGEX_PROGNAME@\fR does not have permission to set the desired one. Also,
-on UNIX-like systems, this flag can also be 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.
+be set exactly as specified in the WIM file. If this option is not specified,
+when \fB@IMAGEX_PROGNAME@\fR on Windows does not have permission to set a
+security descriptor on an extracted file, it falls back to setting it only
+partially (e.g. with SACL omitted), and in the worst case omits it entirely.
+However, this should only be a problem when running \fB@IMAGEX_PROGNAME@\fR
+without Administrator rights. Also, on UNIX-like systems, this flag can also be
+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
+\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. The meaning of this is
-platform-dependent.
-.IP "" 6
+appending a suffix rather than ignoring them. Exactly what is considered an
+"invalid" name is platform-dependent.
+.IP ""
On POSIX-compliant systems, filenames are case-sensitive and may contain any
byte except '\\0' and \'/', so on a POSIX-compliant system this option will only
have an effect in the unlikely case that the WIM image for some reason has a
filename containing one of these characters.
-.IP "" 6
+.IP ""
On Windows, filenames are case-insensitive, cannot include the characters '/',
\'\\0', '\\', ':', '*', '?', '"', '<', '>', or '|', and cannot end with a space
or period. Ordinarily, files in WIM images should meet these conditions as
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--resume\fR
-TODO
.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