.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 .SH SYNOPSIS \fBimagex apply\fR \fIWIMFILE\fR \fIIMAGE\fR \fITARGET\fR [\fIOPTION\fR]... .SH DESCRIPTION .PP \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) command to show what images a WIM file contains. \fITARGET\fR specifies where to extract the WIM image(s) to. If \fITARGET\fR specifies a directory, the WIM image(s) are extracted to that directory. If \fITARGET\fR specifies a non-existent file, a directory is created in that location and the WIM image(s) are extracted to that directory. If \fITARGET\fR specifies a regular file or block device, it is interpreted as a NTFS volume to which the WIM image is to be extracted. \fBimagex apply\fR supports applying images from stand-alone WIMs as well as split WIMs. See \fBSPLIT WIMS\fR. .SH NORMAL MODE The normal extraction mode is entered when \fITARGET\fR is a directory or non-existent file. If a single WIM image is being extracted, it is extracted with the root directory of the image corresponding to the directory named by \fITARGET\fR; or, if the keyword \fBall\fR is given, the images are extracted into subdirectories of \fITARGET\fR that are be named after the image names, falling back to the image index for an image with no name. \fITARGET\fR can specify a directory on any type of filesystem. In the normal mode of extraction, the following information is extracted from the WIM image(s): .IP \[bu] 4 The default (unnamed) data stream of each file .IP \[bu] Hard links .IP \[bu] File and directory creation, access, and modification timestamps to the nearest microsecond, if supported by the underlying filesystem .IP \[bu] Symbolic links and junction points, although they will not necessarily point to the desired location (for example, the target of the link may contain a Windows drive letter). .PP In the normal mode of extraction, the following information will \fInot\fR be extracted from the WIM image(s): .IP \[bu] 4 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] Reparse points other than symbolic links and junction points .IP \[bu] Certain file attributes such as compression, encryption, and sparseness. .IP \[bu] Short (DOS) names for files .SH NTFS MODE 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 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 \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 specify the NTFS volume itself (and it must be unmounted, and you must have permission to write to it). In the NTFS extraction mode, the following information will be extracted from the WIM image: .IP \[bu] 4 The data streams of all files, including the un-named data stream as well as all named data streams. .IP \[bu] Reparse points, including symbolic links, junction points, and other reparse points. .IP \[bu] Hard links. .IP \[bu] File and directory creation, access, and modification timestamps are set to the 100-nanosecond resolution values specified in the WIM file. .IP \[bu] 4 The security descriptor for each file is applied if there is one specified in the WIM. .IP \[bu] File attribute flags are applied. .IP \[bu] Short (DOS) names for files are extracted. The corresponding long name for each DOS name is made to be a Win32 name. Any additional names for the file in the same directory are made to be names in the POSIX namespace. .PP 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. 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 .IP \n[step]. 3 The Master Boot Record loads the Volume Boot Record (also called the Boot Sector) of the active partition, which is on an NTFS filesystem. This partition is called the "system partition". .IP \n+[step]. The "bootmgr" program on the "system partition" is loaded (\\BOOTMGR). .IP \n+[step]. bootmgr loads the Boot Configuration Data (\\Boot\\BCD) from the "system partition". .IP \n+[step]. Based on the information contained in the Boot Configuration Data, a loader for the Windows kernel is executed from the "Boot" partition, which is where Windows is installed. .PP So let's say you applied an image from an existing "install.wim" as in the example, or you've applied a custom Windows image that you've created using the \fBimagex capture\fR (1) command. You've just applied the "Boot" partition, or the main Windows partition, but there is no "System" partition yet (i.e. no \\BOOTMGR and no \\Boot\\BCD). A "System" partition can be created created by running the "bcdboot.exe" program from within Windows or Windows PE. Alternatively, you can capture a separate WIM image containing the "System" partition. Or, the "System" partition may the same as the "Boot" partition, so the two "partitions" may be combined in one WIM image. However, as the \\Boot\\BCD file contains the Windows bootloader configuration, a WIM containing it can only be used on systems where you are setting up the same bootloader configuration, including the same partition layout. Besides setting up the files on the "System" partition, don't forget to set the bootable flag on it, and have a master boot record that loads the bootable partition (Windows' MBR does, and SYSLINUX provides an equivalent MBR). .SH SPLIT WIMS You may use \fBimagex 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). Here's an example. The names for the split WIMs usually go something like: .RS .PP .nf mywim.swm mywim2.swm mywim3.swm mywim4.swm mywim5.swm .RE 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 the UNIX build. \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 essentially the same behavior as Microsoft's ImageX. \fB--hardlink\fR, \fB--symlink\fR, and \fB--unix-data\fR are not supported on Windows. Except for the differences documented in this section, the Windows build of \fBimagex apply\fR should be essentially equivalent to the UNIX build. However, one additional thing to note is that wimlib's Windows ImageX is NOT written to be command-line compatible with Microsoft's ImageX, although they are very similar. .SH OPTIONS .TP 6 \fB--check\fR When reading \fIWIMFILE\fR, verify its integrity if the integrity table is present. .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 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 instead. This option is not available in the NTFS extraction mode. .TP \fB--verbose\fR Print the path to of each file or directory within the WIM image as it is extracted, and some additional informational messages. .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. .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 \fBimagex 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 cannot be found in the stream lookup table. So you can be fairly certain that the file streams are extracted correctly, even though \fBimagex apply\fR don't have a \fB/verify\fR option like Microsoft's 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 installation media to the directory "boot": .RS .PP image apply /media/windows/sources/boot.wim 1 boot .RE .PP Extract all images from the Windows PE image from the Windows Vista/7/8 installation media to the directory "boot", and hard link all identical files: .RS .PP image apply /media/windows8/sources/boot.wim all boot --hardlink .RE .PP .SS NTFS extraction mode Apply a WIM image to a NTFS filesystem image: .RS .PP imagex apply mywim.wim 1 fsimage.ntfs .RE .PP Create a new NTFS filesystem on the partition /dev/sda2 and apply the first image in the Windows Vista/7/8 installation WIM to it. (Obviously, only do this if you want to erase everything on that partition.) .RS .PP mkntfs /dev/sda2 && imagex apply /media/windows/sources/install.wim 1 /dev/sda2 .RE .PP .SH SEE ALSO .BR imagex (1)