-.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
image can't be exactly represented when extracted. Last access and last
modification timestamps are specified to 100 nanosecond granularity in the WIM
file, but will only be extracted to the highest precision supported by the
-underlying operating system, C library, and filesystem.
+underlying operating system, C library, and filesystem. Compressed files will
+be extracted as uncompressed, while encrypted files will not be extracted at
+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.
All names of all files, including names in the Win32 namespace, DOS namespace,
Win32+DOS namespace, and POSIX namespace. This includes hard links.
.PP
-Currently, the only known limitation (in terms of exactly extracting all data
-and metadata) is that the extraction of encrypted files is not expected to work
-properly.
+However, there are also several known limitations of the NTFS volume extraction
+mode:
+.IP \[bu] 4
+Encrypted files will not be extracted.
+.IP \[bu]
+Although sparse file attributes will be applied, the full data will be extracted
+to each sparse file, so extracted "sparse" files may not actually contain any
+sparse regions.
.PP
-Since all (or almost all) information from the WIM image is restored in this
+Regardless, since almost all information from the WIM image is restored in this
mode, it is possible to restore an image of an actual Windows installation using
\fB@IMAGEX_PROGNAME@\fR on UNIX-like systems in addition to with
\fB@IMAGEX_PROGNAME@\fR on Windows. In the examples at the end of this manual
.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. (The current behavior is to
-just extract the encrypted data anyway.) Furthermore, even if encrypted files
-are restored to a filesystem that supports encryption, they will only be
+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.
+.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 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
\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