+++ /dev/null
-.TH WIMLIB-IMAGEX "1" "March 2014" "@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...]
-.SH DESCRIPTION
-\fB@IMAGEX_PROGNAME@ apply\fR extracts an image, or all images, from the Windows
-Imaging (WIM) file \fIWIMFILE\fR. This command is also available as simply
-\fBwimapply\fR if the appropriate hard link or batch file has been installed.
-.PP
-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. (\fB@IMAGEX_PROGNAME@ mount\fR is not
-supported on Windows.)
-.PP
-\fIIMAGE\fR specifies the WIM image in \fIWIMFILE\fR to extract. It may be a
-1-based index of an image in \fIWIMFILE\fR, the name of an image in
-\fIWIMFILE\fR, or the keyword "all" to indicate that all images in \fIWIMFILE\fR
-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.
-.PP
-\fITARGET\fR specifies where to extract the WIM image to. If \fITARGET\fR
-specifies a directory, the WIM image is extracted to that directory (see
-\fBDIRECTORY EXTRACTION (UNIX)\fR or \fBDIRECTORY EXTRACTION (WINDOWS)\fR).
-Similarly, if \fITARGET\fR specifies a non-existent file, a directory is created
-in that location and the WIM image is extracted to that directory.
-.PP
-If \fIIMAGE\fR is specified as "all", then all the images in \fIWIMFILE\fR are
-actually extracted into subdirectories of \fITARGET\fR, each of which is given
-the name of the corresponding image, falling back to the image index in the case
-of an image with no name or a name not valid as a filename.
-.PP
-Alternatively, on UNIX-like systems 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 (see \fBNTFS VOLUME EXTRACTION (UNIX)\fR). Only a single
-image can be extracted in this mode, and only extracting to the root of the NTFS
-volume (not a subdirectory thereof) is supported.
-.PP
-\fIWIMFILE\fR may be "-" to read the WIM from standard input rather than from a
-file, but see \fBPIPABLE WIMS\fR for more information.
-.PP
-\fB@IMAGEX_PROGNAME@ apply\fR supports applying images from stand-alone WIMs as
-well as split WIMs. See \fBSPLIT WIMS\fR.
-.SH DIRECTORY EXTRACTION (UNIX)
-This section documents how \fB@IMAGEX_PROGNAME@ apply\fR (and also
-\fB@IMAGEX_PROGNAME@ extract\fR) extract a WIM image (or a possibly a subset
-thereof, in the case of \fB@IMAGEX_PROGNAME@ extract\fR) to a directory on
-UNIX-like systems. See \fBDIRECTORY EXTRACTION (WINDOWS)\fR for the
-corresponding documentation for Windows.
-
-As mentioned, a WIM image can be applied to a directory on a UNIX-like system by
-providing a \fITARGET\fR directory. However, it is important to keep in mind
-that the WIM format was designed for Windows, and as a result WIM files can
-contain data or metadata that cannot be represented on UNIX-like systems. The
-main information that \fB@IMAGEX_PROGNAME@\fR will \fInot\fR be able to extract
-on UNIX-like systems is the following:
-.IP \[bu] 4
-Windows security descriptors (which include the file owner, group, and ACLs).
-.IP \[bu]
-Named data streams.
-.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.
-.IP \[bu]
-File creation timestamps.
-.PP
-Notes: Unsupported data and metadata is simply not extracted, but
-\fB@IMAGEX_PROGNAME@\fR will attempt to warn you when the contents of the WIM
-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. 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.
-.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
-or block device containing an NTFS filesystem. The NTFS filesystem need not 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 provided
-with \fBntfs-3g\fR.
-.PP
-In this NTFS volume extraction mode, the WIM image is extracted to the root of
-the NTFS volume in a way preserves almost all information contained in the WIM
-image. It therefore does not suffer from the limitations described in
-\fBDIRECTORY EXTRACTION (UNIX)\fR. This support relies on libntfs-3g to write
-to the NTFS volume and handle NTFS-specific and Windows-specific data.
-.PP
-Please note that this NTFS volume extraction mode is \fInot\fR entered if
-\fITARGET\fR 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).
-.PP
-This NTFS volume extraction mode attempts to extract as much information as
-possible, including:
-.IP \[bu] 4
-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.
-.IP \[bu]
-File and directory creation, access, and modification timestamps, using the
-native NTFS resolution of 100 nanoseconds.
-.IP \[bu]
-Windows security descriptors, including all components (owner, group, DACL, and
-SACL).
-.IP \[bu]
-DOS/Windows file attribute flags.
-.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]
-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
-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
-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
-\fB@IMAGEX_PROGNAME@ 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).
-.SH DIRECTORY EXTRACTION (WINDOWS)
-On Windows, \fB@IMAGEX_PROGNAME@ apply\fR and \fB@IMAGEX_PROGNAME@ extract\fR
-natively support Windows-specific and NTFS-specific data. For best results, the
-target directory should be located on an NTFS volume and \fB@IMAGEX_PROGNAME@\fR
-should be run with Administrator privileges; however, non-NTFS filesystems and
-running without Administrator privileges are also supported.
-.PP
-On Windows, \fB@IMAGEX_PROGNAME@ apply\fR and \fB@IMAGEX_PROGNAME@ extract\fR
-try to extract as much data and metadata as possible, including:
-.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 target volume.
-.IP \[bu]
-Reparse points, including symbolic links, junction points, and other reparse
-points, if supported by the target volume. (Note: see \fB--rpfix\fR and
-\fB--norpfix\fR for documentation on exactly how absolute symbolic links and
-junctions are extracted.) However, as per the default security settings of
-Windows, it is impossible to create a symbolic link or junction point without
-Administrator privileges; therefore, you must run \fB@IMAGEX_PROGNAME@\fR as the
-Administrator if you wish to fully restore an image containing symbolic links
-and/or junction points. (Otherwise, merely a warning will be issued when a
-symbolic link or junction point cannot be extracted due to insufficient
-privileges.)
-.IP \[bu]
-File and directory creation, access, and modification timestamps, to the highest
-resolution supported by the target volume.
-.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
-descriptors for individual files or directories may be omitted or only partially
-set if the user does not have permission to set them, which can be a problem if
-\fB@IMAGEX_PROGNAME@\fR is run as a non-Administrator.
-.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.
-.PP
-Additional notes about extracting files on Windows:
-.IP \[bu] 4
-\fB@IMAGEX_PROGNAME@\fR will issue a warning when it is unable to extract the
-exact metadata and data of the WIM image, for example due to features mentioned
-above not being supported by the target filesystem.
-.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. 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 (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 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
-mywim.swm
-mywim2.swm
-mywim3.swm
-mywim4.swm
-mywim5.swm
-.RE
-.fi
-.PP
-To apply the first image of this split WIM to the directory "dir", run:
-.PP
-.RS
-@IMAGEX_PROGNAME@ apply mywim.swm 1 dir --ref="mywim*.swm"
-.RE
-.PP
-As a special case, if you are applying an image from standard input from a split
-WIM that is also pipable (as described in \fBPIPABLE WIMS\fR), the \fB--ref\fR
-option is unneeded; instead you must ensure that all the split WIM parts are
-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, \fB@IMAGEX_PROGNAME@ 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 \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 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
-.RE
-.PP
-(The above also used the \fBwimapply\fR abbreviation for \fB@IMAGEX_PROGNAME@
-apply\fR.) Note: WIM files are \fInot\fR pipable by default; you have to
-explicitly capture them with \fB--pipable\fR, and they are \fInot\fR compatible
-with Microsoft's software. See \fB@IMAGEX_PROGNAME@ capture\fR(1) for more
-information.
-.PP
-It is possible to apply an image from a pipable WIM split into multiple parts;
-see \fBSPLIT WIMS\fR.
-.SH OPTIONS
-.TP 6
-\fB--check\fR
-When reading \fIWIMFILE\fR, verify its integrity if the integrity table is
-present.
-.TP
-\fB--ref\fR="\fIGLOB\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 \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.
-.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.
-.IP ""
-However, hard-linked extraction mode does have some additional quirks. Named
-data streams will not be extracted, and files can be hard linked even if their
-metadata is not fully consistent.
-.TP
-\fB--symlink\fR
-This option is similar to \fB--hardlink\fR, except symbolic links are created
-instead.
-.TP
-\fB--unix-data\fR
-(UNIX-like systems only) By default, in the directory 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
-Do not restore security descriptors on extracted files and directories.
-.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. 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. 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 ""
-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
-\fB@IMAGEX_PROGNAME@\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.
-.TP
-\fB--wimboot\fR
-Windows only: Instead of extracting the files themselves, extract "pointer
-files" back to the original WIM. This is only expected to work on Windows 8.1
-and later, since only those versions of Windows contain the Windows Overlay File
-System Filter Driver that is necessary for this feature. See Microsoft's
-documentation for "WIMBoot" for more information.
-.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
-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":
-.RS
-.PP
-@IMAGEX_PROGNAME@ apply /mnt/windows/sources/boot.wim 1 boot
-.RE
-.PP
-Same as above, but using the \fBwimapply\fR abbreviation:
-.RS
-.PP
-wimapply /media/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:
-.RS
-.PP
-@IMAGEX_PROGNAME@ apply install.wim 1 E:\\
-.RE
-.PP
-Same as above, but running on a UNIX-like system where the corresponding
-partition is /dev/sda2:
-.RS
-.PP
-@IMAGEX_PROGNAME@ apply install.wim 1 /dev/sda2
-.RE
-.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
-run:
-.RS
-.PP
-mkntfs /dev/sda2 && wimapply install.wim 1 /dev/sda2
-.RE
-.PP
-(Of course don't do that if you don't want to destroy all existing data on the
-partition!)
-.PP
-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.
-.SH SEE ALSO
-.BR @IMAGEX_PROGNAME@ (1)
-.BR @IMAGEX_PROGNAME@-capture (1)
-.BR @IMAGEX_PROGNAME@-extract (1)
-.BR @IMAGEX_PROGNAME@-info (1)
git://wimlib.net / wimlib / blobdiff