-.TH IMAGEX "1" "September 2012" "imagex (wimlib) wimlib @VERSION@" "User Commands"
+.TH IMAGEX "1" "March 2013" "imagex (wimlib) wimlib @VERSION@" "User Commands"
.SH NAME
-imagex apply \- Extract one image, or all images, from a WIM archive
+imagex-apply \- Extract one image, or all images, from a WIM archive
.SH SYNOPSIS
\fBimagex apply\fR \fIWIMFILE\fR \fIIMAGE\fR \fITARGET\fR [\fIOPTION\fR]...
\fBimagex apply\fR extracts an image, or all images, from the Windows Imaging
(WIM) file \fIWIMFILE\fR.
+Note: this man page primarily documents the UNIX behavior. See \fBWINDOWS
+VERSION\fR for information specific to the Windows build of wimlib.
+
\fIIMAGE\fR specifies the WIM image to extract. It may be a 1-based index of an
image in the WIM, the name of an image in the WIM, or the keyword "all" to
indicate that all images are to be extracted. Use the \fBimagex info\fR (1)
.IP \[bu] 4
The default (unnamed) data stream of each file
.IP \[bu]
-Hard links, if supported by the underlying filesystem
+Hard links
.IP \[bu]
File and directory creation, access, and modification timestamps to the nearest
microsecond, if supported by the underlying filesystem
extracted from the WIM image(s):
.IP \[bu] 4
-Security descriptors (file permissions)
+Security descriptors (file permissions) except through the extensions available
+through the \fB--unix-data\fR option
.IP \[bu]
The alternate (named) data streams for each file
.IP \[bu]
A special extraction mode is entered when \fITARGET\fR is a regular file or
block device. If this is the case, \fITARGET\fR is interpreted as an NTFS
volume and opened using libntfs-3g. If successful, the WIM image is extracted
-to the root of the NTFS volume in a special mode that preserves all, or almost
-all, information contained in the WIM. \fIIMAGE\fR may not be "all" for this
-action.
+to the root of the NTFS volume in a special mode that preserves all information
+contained in the WIM image. \fIIMAGE\fR may not be "all" for this action.
The NTFS volume does not need to be empty, although it's expected that it be
empty for the intended use cases. A new NTFS filesystem can be created using
the \fBmkntfs\fR (8) command.
The NTFS extraction mode is not available if wimlib was compiled using the
---without-ntfs-3g option.
+\fB--without-ntfs-3g\fR option.
Please note that the NTFS extraction mode is \fInot\fR entered if \fITARGET\fR
is a directory, even if a NTFS filesystem is mounted on \fITARGET\fR. You must
.PP
-In the NTFS extraction mode, we restore enough information from the WIM that it
-is possible, in most cases, to restore or install an image of an actual Windows
-installation. In the examples at the end of this manual page, we show an example
-of applying an image from the "install.wim" file contained in the installation
-media for Windows Vista, Windows 7, and Windows 8 in the "sources" directory.
+Since all information from the WIM image is restored in the NTFS extraction
+mode, it is possible to restore an image of an actual Windows installation. In
+the examples at the end of this manual page, there is an example of applying an
+image from the "install.wim" file contained in the installation media for
+Windows Vista, Windows 7, and Windows 8 in the "sources" directory.
-In order to actually boot Windows from an applied image, you must understand the
-boot process of Windows versions Vista and later. Basically, it is the
+But in order to actually boot Windows from an applied image, you must understand
+the boot process of Windows versions Vista and later. Basically, it is the
following:
.nr step 1 1
well).
Here's an example. The names for the split WIMs usually go something like:
-
+
.RS
.PP
.nf
mywim3.swm
mywim4.swm
mywim5.swm
-\. ... etc.
.RE
-To apply the first image of this split WIM to the directory "dir", we would do:
+To apply the first image of this split WIM to the directory "dir", run:
.PP
.RS
imagex apply mywim.swm 1 dir --ref="mywim*.swm"
.RE
.PP
+.SH WINDOWS VERSION
+
+This section documents the differences between \fBimagex apply\fR in the Windows
+builds of wimlib versus the rest of this man page, which is written to document
+UNIX version.
+
+\fBimagex apply\fR does not have separate "normal" and "NTFS" modes on Windows.
+There is simply one mode, and it uses the Windows API to apply NTFS-specific
+information, including alternate data streams, reparse points, hard links, and
+file attributes. So, you essentially get the advantages of the "NTFS mode"
+documented above, but you can apply the WIM image to any directory, not just an
+entire NTFS volume. This is mostly the same behavior as Microsoft's ImageX.
+
+\fB--hardlink\fR, \fB--symlink\fR, and \fB--unix-data\fR are not supported on
+Windows.
+
+Other than the differences documented in this section, the Windows version
+should be essentially equivalent to the UNIX version. However, one additional
+thing to note is that wimlib's Windows version of ImageX is NOT written to be
+command-line compatible with Microsoft's version of ImageX, although they are
+very similar.
+
.SH OPTIONS
.TP 6
\fB--check\fR
.TP
\fB--hardlink\fR
When extracting a file from the WIM that is identical to a file that has already
-extracted, create a hard link using \fBlink\fR (3) rather than creating a
-separate file. This option causes all identical files to be hard-linked,
-overriding the hard link groups that are specified in the WIM image(s). In the
-case of extracting all images from the WIM, files may be hard-linked even if
-they are in different WIM images. This option is not available in the NTFS
-extraction mode.
+extracted, create a hard link rather than creating a separate file. This option
+causes all identical files to be hard-linked, overriding the hard link groups
+that are specified in the WIM image(s). In the case of extracting all images
+from the WIM, files may be hard-linked even if they are in different WIM images.
+This option is not available in the NTFS extraction mode.
.TP
\fB--symlink\fR
This option is similar to \fB--hardlink\fR, except symbolic links are created
\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.
+.TP
+\fB--unix-data\fR
+This option may only be given in the normal extraction mode (not NTFS).
+By default, in the normal extraction mode, \fBimagex apply\fR will ignore both
+Windows-style security descriptors and UNIX-specific file owners, groups, and
+modes set when using \fBimagex capture\fR with the \fB--unix-data\fR flag. By
+passing \fB--unix-data\fR to \fBimagex apply\fR instead, this causes this
+UNIX-specific data to be restored when available.
.SH NOTES
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 cannot be found in the stream
lookup table. So you can be fairly certain that the file streams are extracted
-correctly, even though we don't provide a \fB/verify\fR option like Microsoft's
-version of imagex does. Please 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
+correctly, even though \fBimagex apply\fR don't have a \fB/verify\fR option like
+Microsoft's version of imagex does. Please 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.
+You cannot use \fBimagex apply\fR to apply a WIM from a pipe (such as standard
+input) because the WIM file format is not designed for this.
+
.SH EXAMPLES
.SS Normal extraction mode
Extract the first image from the Windows PE image from the Windows Vista/7/8
.RE
.PP
.SS NTFS extraction mode
-Verbosely apply a WIM image to a NTFS filesystem image:
+Apply a WIM image to a NTFS filesystem image:
.RS
.PP
-imagex apply mywim.wim 1 fsimage.ntfs --verbose
+imagex apply mywim.wim 1 fsimage.ntfs
.RE
.PP
Create a new NTFS filesystem on the partition /dev/sda2 and apply the first
git://wimlib.net / wimlib / blobdiff