-.TH WIMLIB-IMAGEX "1" "November 2014" "wimlib 1.7.3" "User Commands"
+.TH WIMLIB-IMAGEX "1" "August 2016" "wimlib 1.10.0" "User Commands"
.SH NAME
wimlib-imagex-apply \- Extract one image, or all images, from a WIM archive
.SH SYNOPSIS
.IP \[bu]
Reparse points other than symbolic links and junction points.
.IP \[bu]
-Certain file attributes such as compression, encryption, and sparseness.
+Certain file attributes such as compression and encryption.
.IP \[bu]
Short (DOS) names for files.
.IP \[bu]
.IP \[bu]
All names of all files, including names in the Win32 namespace, DOS namespace,
Win32+DOS namespace, and POSIX namespace. This includes hard links.
-.PP
-However, there are also several known limitations of the NTFS volume extraction
-mode:
-.IP \[bu] 4
-Encrypted files will not be extracted.
.IP \[bu]
-wimlib v1.7.0 and later: Sparse file attributes will not be extracted (same
-behavior as ImageX/DISM/WIMGAPI). wimlib v1.6.2 and earlier: 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.
+Object IDs.
+.PP
+However, a limitation of the NTFS volume extraction mode is that encrypted files
+will not be extracted.
.PP
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
-\fBwimlib-imagex\fR on UNIX-like systems in addition to with
-\fBwimlib-imagex\fR on Windows. 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.
-.PP
-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
-\fBwimlib-imagex 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).
-.PP
-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.
-.PP
-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).
+mode, it is possible (and fully supported) to restore an image of an actual
+Windows installation using \fBwimlib-imagex\fR on UNIX-like systems as an
+alternative to using \fBwimlib-imagex\fR on Windows. 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 or
+later) in the "sources" directory.
+.PP
+Note that to actually boot Windows (Vista or later) from an applied
+"install.wim" image, you also need to mark the partition as "bootable" and set
+up various boot files, such as \\BOOTMGR and \\BOOT\\BCD. The latter task is
+most easily accomplished by running the "bcdboot.exe" program from a live
+Windows system (such as Windows PE), but there are other options as well.
.SH DIRECTORY EXTRACTION (WINDOWS)
On Windows, \fBwimlib-imagex apply\fR and \fBwimlib-imagex extract\fR
natively support Windows-specific and NTFS-specific data. For best results, the
set if the user does not have permission to set them, which can be a problem if
\fBwimlib-imagex\fR is run as a non-Administrator.
.IP \[bu]
-File attributes, including hidden, sparse, compressed, encrypted, etc, when
-supported by the filesystem.
+File attributes, including hidden, compressed, encrypted, etc, when supported by
+the filesystem.
.IP \[bu]
DOS names (8.3) names of files; however, the failure to set them is not
considered an error condition.
.IP \[bu]
-Hard links, if supported by the filesystem.
+Hard links, if supported by the target filesystem.
+.IP \[bu]
+Object IDs, if supported by the target filesystem.
.PP
Additional notes about extracting files on Windows:
.IP \[bu] 4
concatenated together on standard input. They can be provided in any order,
with the exception of the first part, which must be first.
.SH PIPABLE WIMS
-As of wimlib 1.5.0, \fBwimlib-imagex apply\fR supports applying a WIM from a
+Since wimlib v1.5.0, \fBwimlib-imagex apply\fR supports applying a WIM from a
nonseekable file, such as a pipe, provided that the WIM was captured with
-\fB--pipable\fR (see \fBwimlib-imagex 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 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:
+\fB--pipable\fR (see \fBwimlib-imagex 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 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
UNIX-like systems.
.TP
\fB--unix-data\fR
-(UNIX-like systems only) Restore UNIX owners, groups, modes, and device IDs
-(major and minor numbers) that were captured by \fBwimlib-imagex capture\fR
-with the \fB--unix-data\fR option. As of wimlib v1.7.0, you can backup and
-restore not only the standard UNIX file permission information, but also
-character device nodes, block device nodes, named pipes (FIFOs), and UNIX domain
-sockets.
+(UNIX-like systems only) Restore UNIX-specific metadata and special files that
+were captured by \fBwimlib-imagex capture\fR with the \fB--unix-data\fR option.
+This includes: standard UNIX file permissions (owner, group, and mode); device
+nodes, named pipes, and sockets; and extended attributes (Linux-only).
.TP
\fB--no-acls\fR
Do not restore security descriptors on extracted files and directories.
have an effect in the unlikely case that the WIM image for some reason has a
filename containing one of these characters.
.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
-well. However, it is not guaranteed, and in particular a WIM image captured with
-\fBwimlib-imagex\fR on a POSIX-compliant system could contain such files. By
-default, invalid names will be ignored, and if there are multiple names
-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.
+On Windows, filenames are case-insensitive(*), cannot include control
+characters, and cannot include the characters '/', \'\\0', '\\', ':', '*', '?',
+\'"', '<', '>', or '|'. Ordinarily, files in WIM images should meet these
+conditions as well. However, it is not guaranteed, and in particular a WIM image
+captured with \fBwimlib-imagex\fR on a POSIX-compliant system could contain such
+files. By default, invalid names will be ignored, and if there are multiple
+names 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.
+.IP ""
+(*) Unless the ObCaseInsensitive setting has been set to 0 in the Windows
+registry, in which case certain software, including the Windows version of
+\fBwimlib-imagex\fR, will honor case-sensitive filenames on NTFS and other
+compatible filesystems.
.TP
\fB--wimboot\fR
Windows only: Instead of extracting the files themselves, extract "pointer
-files" back to the WIM archive. This can result in significant space savings.
+files" back to the WIM archive(s). This can result in significant space savings.
However, it comes at several potential costs, such as not being able to delete
-the WIM archive and possibly having slower access to files. See Microsoft's
+the WIM archive(s) and possibly having slower access to files. See Microsoft's
documentation for "WIMBoot" for more information.
.IP ""
If it exists, the [PrepopulateList] section of the file
.IP ""
In addition, this option works best when running on Windows 8.1 Update 1 or
later, since that is the first version of Windows that contains the Windows
-Overlay File System Filter Driver ("WOF"). If the WOF driver is detected,
-wimlib will create the WIMBoot "pointer files" using documented ioctls provided
-by WOF.
+Overlay Filesystem filter driver ("WOF"). If the WOF driver is detected, wimlib
+will create the WIMBoot "pointer files" using documented ioctls provided by WOF.
.IP ""
Otherwise, if the WOF driver is not detected, wimlib will create the reparse
points and edit the file "\\System Volume Information\\WimOverlay.dat" on the
of size 32768, in addition to the default XPRESS chunks of size 4096 that are
created when \fBwimlib-imagex capture\fR is run with the \fB--wimboot\fR
option.
+.TP
+\fB--compact\fR=\fIFORMAT\fR
+Windows-only: compress the extracted files using System Compression, when
+possible. This only works on either Windows 10 or later, or on an older Windows
+to which Microsoft's wofadk.sys driver has been added. Several different
+compression formats may be used with System Compression, and one must be
+specified as \fIFORMAT\fR. The choices are: xpress4k, xpress8k, xpress16k, and
+lzx.
+.IP ""
+Exclusions are handled in the same way as with the \fB--wimboot\fR option.
+That is: if it exists, the [PrepopulateList] section of the file
+\\Windows\\System32\\WimBootCompress.ini in the WIM image will be read, and
+files matching any of the patterns in this section will not be compressed.
+In addition, wimlib has a hardcoded list of files for which it knows, for
+compatibility with the Windows bootloader, to override the requested compression
+format.
.SH NOTES
\fIData integrity\fR: WIM files include SHA1 message digests for file data.
\fBwimlib-imagex apply\fR calculates the SHA1 message digest of every file
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
+WIMs, which usually contain LZMS-compressed solid resources 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.
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":
+Extract the first image from the Windows PE image on the Windows (Vista or
+later) installation media to the directory "boot":
.RS
.PP
wimlib-imagex apply /mnt/windows/sources/boot.wim 1 boot
.RE
.PP
On Windows, apply an image of an entire volume, for example from "install.wim"
-which can be found on the Windows Vista/7/8 installation media:
+which can be found on the Windows (Vista or later) installation media:
.RS
.PP
wimlib-imagex apply install.wim 1 E:\\
.PP
Note that before running either of the above commands, an NTFS filesystem may
need to be created on the partition, for example with format.exe on Windows or
-\fBmkntfs\fR(8) (part of NTFS-3g) on UNIX-like systems. For example, you might
+\fBmkntfs\fR(8) (part of NTFS-3G) on UNIX-like systems. For example, you might
run:
.RS
.PP
git://wimlib.net / wimlib / blobdiff