-.TH IMAGEX "1" "April 2013" "@IMAGEX_PROGNAME@ @VERSION@" "User Commands"
+.TH IMAGEX "1" "May 2013" "@IMAGEX_PROGNAME@ @VERSION@" "User Commands"
.SH NAME
@IMAGEX_PROGNAME@-apply \- Extract one image, or all images, from a WIM archive
.SH SYNOPSIS
-\fB@IMAGEX_PROGNAME@ apply\fR \fIWIMFILE\fR \fIIMAGE\fR \fITARGET\fR [\fIOPTION\fR]...
+\fB@IMAGEX_PROGNAME@ apply\fR \fIWIMFILE\fR [\fIIMAGE\fR] \fITARGET\fR [\fIOPTION\fR...]
.SH DESCRIPTION
.PP
-\fB@IMAGEX_PROGNAME@ apply\fR extracts an image, or all images, from the Windows Imaging
-(WIM) file \fIWIMFILE\fR.
+\fB@IMAGEX_PROGNAME@ 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.
+This command is designed to extract, or "apply", one or more full WIM images.
+If you instead want to extract only certain files or directories contained in a
+WIM image, consider using \fB@IMAGEX_PROGNAME@ extract\fR or
+\fB@IMAGEX_PROGNAME@ mount\fR instead.
\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 \fB@IMAGEX_PROGNAME@ info\fR (1)
-command to show what images a WIM file contains.
+indicate that all images are to be extracted. Use the \fB@IMAGEX_PROGNAME@
+info\fR (1) command to show what images a WIM file contains. \fIIMAGE\fR may be
+omitted if \fIWIMFILE\fR contains only one image.
\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.
+location and the WIM image(s) are extracted to that directory. Alternatively,
+on UNIX only, if \fITARGET\fR specifies a regular file or block device, it is
+interpreted as an NTFS volume to which the WIM image is to be extracted.
-\fB@IMAGEX_PROGNAME@ apply\fR supports applying images from stand-alone WIMs as well as
-split WIMs. See \fBSPLIT WIMS\fR.
+\fB@IMAGEX_PROGNAME@ apply\fR supports applying images from stand-alone WIMs as
+well as split WIMs. See \fBSPLIT WIMS\fR.
-.SH NORMAL MODE
+.SH NORMAL MODE (UNIX)
-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.
+This section documents how files are extracted on UNIX from the WIM image to a
+directory. See \fBWINDOWS VERSION\fR for the corresponding documentation for
+the Windows version.
-In the normal mode of extraction, the following information is extracted from
-the WIM image(s):
+On UNIX, 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 on UNIX, the following information is
+extracted from the WIM image(s):
.IP \[bu] 4
The default (unnamed) data stream of each file
100 nanoseconds, if supported by the underlying filesystem, operating system,
and C library
.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).
+Symbolic links and junction points. Drive letters will be stripped.
+(Note: see \fB--rpfix\fR and \fB--norpfix\fR for documentation on how absolute
+symbolic links and junctions are applied.)
.PP
-In the normal mode of extraction, the following information will \fInot\fR be
-extracted from the WIM image(s):
+However, in the "normal" mode of extraction on UNIX, 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
.IP \[bu]
Short (DOS) names for files
-.SH NTFS MODE
+.SH NTFS MODE (UNIX)
-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.
+This section documents how files are extracted directly to an NTFS volume image
+on UNIX. See \fBWINDOWS VERSION\fR for the corresponding documentation for the
+Windows version.
+
+On UNIX, 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
\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
+is a directory, even if an 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:
+In the NTFS extraction mode on UNIX, 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
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.
-
+However, the extraction of encrypted files is not supported in this mode.
+.PP
+Since all (or 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 in addition to with \fB@IMAGEX_PROGNAME@\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:
mywim4.swm
mywim5.swm
.RE
+.nf
To apply the first image of this split WIM to the directory "dir", run:
.PP
.SH WINDOWS VERSION
-This section documents the differences between \fB@IMAGEX_PROGNAME@ apply\fR in the Windows
-builds of wimlib versus the rest of this man page, which is written to document
-the UNIX build.
+The Windows version of \fB@IMAGEX_PROGNAME@ apply\fR acts similarly to the
+corresponding command of Microsoft's ImageX. For best results, the target
+directory should be on an NTFS volume and you should be running with
+Administrator privileges; however, non-NTFS filesystems and running without
+Administrator privileges are also supported.
-\fB@IMAGEX_PROGNAME@ 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.
+On Windows, \fB@IMAGEX_PROGNAME@ apply\fR tries to extract as much data as
+possible. This includes:
-\fB--hardlink\fR, \fB--symlink\fR, and \fB--unix-data\fR are not supported on
-Windows.
+.IP \[bu] 4
+All data streams of all files. This includes the default file contents, as well
+as named data streams if supported by the filesystem.
+.IP \[bu]
+Reparse points, including symbolic links, junction points, and other reparse
+points, if supported by the underlying filesystem. (Note: see
+\fB--rpfix\fR and \fB--norpfix\fR for documentation on how absolute symbolic
+links and junctions are applied.)
+.IP \[bu]
+File and directory creation, access, and modification timestamps.
+.IP \[bu]
+Security descriptors, if supported by the filesystem and \fB--no-acls\fR is not
+specified. Furthermore, unless \fB--strict-acls\fR is specified, the security
+descriptor for individual files or directories may be omitted or only partially
+set if the user does not have permission to set them.
+.IP \[bu]
+File attributes, including hidden, sparse, 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.
-Except for the differences documented in this section, the Windows build of
-\fB@IMAGEX_PROGNAME@ 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.
+.PP
+Note: encrypted files will be extracted as raw encrypted data if the filesystem
+does not support encryption. Compressed files and directories (with the
+compression attribute set) will be extracted as uncompressed if the filesystem
+does not support transparent compression.
.SH OPTIONS
.TP 6
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 on UNIX, \fB@IMAGEX_PROGNAME@ apply\fR
-will ignore both Windows-style security descriptors and UNIX-specific file
-owners, groups, and modes set when using \fB@IMAGEX_PROGNAME@ capture\fR with
-the \fB--unix-data\fR flag. By passing \fB--unix-data\fR to
-\fB@IMAGEX_PROGNAME@ apply\fR instead, this causes this UNIX-specific data to be
-restored when available.
-.TP
-\fB--no-acls\fR
-In the NTFS apply mode, do not apply security descriptors. This flag is also
-available in the native Win32 build of wimlib and may be useful when running
-\fB@IMAGEX_PROGNAME@\fR as a non-administrator.
-.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. 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 we do not have
-permission to set the desired one.
-.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
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's been applied to any location.
+it has been applied to any location.
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.
+Reparse point fixups are never done in the NTFS extraction mode on UNIX.
+.TP
+\fB--verbose\fR
+Print the path to of each file or directory within the WIM image as it is
+extracted.
+.TP
+\fB--hardlink\fR
+(UNIX only) 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
+(UNIX only) This option is similar to \fB--hardlink\fR, except symbolic links are created
+instead.
+.TP
+\fB--unix-data\fR
+(UNIX only) By default, in the normal extraction mode on UNIX,
+\fB@IMAGEX_PROGNAME@ apply\fR will ignore both Windows-style security
+descriptors and UNIX-specific file owners, groups, and modes set when
+using \fB@IMAGEX_PROGNAME@ capture\fR with the \fB--unix-data\fR flag.
+By passing \fB--unix-data\fR to \fB@IMAGEX_PROGNAME@ apply\fR instead,
+this causes this UNIX-specific data to be restored when available. However, by
+default, if \fB@IMAGEX_PROGNAME@\fR does not have permission to set the UNIX
+owner, group or file mode on an extracted file, a warning will be printed and it
+will not be considered an error condition; use \fB--strict-acls\fR to get
+stricter behavior.
+.TP
+\fB--no-acls\fR
+(Windows only) Do not restore security descriptors on extracted files and directories.
+.TP
+\fB--strict-acls\fR
+On Windows: Fail immediately if the full security descriptor of any file or
+directory cannot be set exactly as specified in the WIM file. 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
+we do not have permission to set the desired one. On UNIX: with
+\fB--unix-data\fR, fail immediately if the UNIX owner, group, or file mode on an
+extracted file cannot be set for any reason.
+
.SH NOTES
\fB@IMAGEX_PROGNAME@ apply\fR calculates the SHA1 message digest of every file stream it
input) because the WIM file format is not designed for this.
.SH EXAMPLES
-.SS Normal extraction mode
+.SS Applying a WIM image to a directory (both UNIX and Windows)
Extract the first image from the Windows PE image from the Windows Vista/7/8
installation media to the directory "boot":
.RS
@IMAGEX_PROGNAME@ apply /media/windows8/sources/boot.wim all boot --hardlink
.RE
.PP
-.SS NTFS extraction mode
-Apply a WIM image to a NTFS filesystem image:
+.SS Applying a WIM image directly to a NTFS volume image (UNIX only)
+Apply a WIM image to an NTFS filesystem image:
.RS
.PP
@IMAGEX_PROGNAME@ apply mywim.wim 1 fsimage.ntfs
.SH SEE ALSO
.BR @IMAGEX_PROGNAME@ (1)
-
+.BR @IMAGEX_PROGNAME@-extract (1)
+.BR @IMAGEX_PROGNAME@-info (1)
git://wimlib.net / wimlib / blobdiff