X-Git-Url: https://wimlib.net/git/?p=wimlib;a=blobdiff_plain;f=doc%2Fimagex-apply.1.in;h=e9dd4684fd6a663daae20fb0ba6ba3e5d5387b25;hp=d66034ef7278aae28741dc525ba549d8b7b1ad84;hb=512d3f87a1e7b59ca19ae6d6965dbcf7f4a17c15;hpb=370533dcb819ad11d6424e7e0284915eb501812b diff --git a/doc/imagex-apply.1.in b/doc/imagex-apply.1.in index d66034ef..e9dd4684 100644 --- a/doc/imagex-apply.1.in +++ b/doc/imagex-apply.1.in @@ -1,23 +1,194 @@ -.TH IMAGEX "1" "May 2012" "imagex (wimlib) wimlib @VERSION@" "User Commands" +.TH IMAGEX "1" "September 2012" "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_NUM\fR | \fIIMAGE_NAME\fR | all] \ -\fIDIRECTORY\fR [\fIOPTION\fR]... +\fBimagex apply\fR \fIWIMFILE\fR \fIIMAGE\fR \fITARGET\fR [\fIOPTION\fR]... .SH DESCRIPTION .PP -\fBimagex apply\fR extracts the specified image from \fIWIMFILE\fR to -\fIDIRECTORY\fR. +\fBimagex apply\fR extracts an image, or all images, from the Windows Imaging +(WIM) file \fIWIMFILE\fR. -The image to extract may be specified by \fIIMAGE_NUM\fR, which must be an -integer that is an index of an image in the WIM file, starting at 1. -Alternatively, it may be the name of an image in the WIM file. It also may be -the keyword \fBall\fR, which indicates that all images in the WIM are to be -extracted. If the keyword \fBall\fR is given, the images are extracted into -subdirectories of \fIDIRECTORY\fR that will be named after the image names. +\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 WIM. 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 will be +extracted with the root 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 will be named after the image names, +falling back to the image indices if there is 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 will be extracted +from the WIM image(s): + +.IP \[bu] 4 +The default (unnamed) data stream of each file +.IP \[bu] +Hard links, if supported by the underlying filesystem +.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) +.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. \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. + +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. + +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 + +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. + +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 +\. ... etc. +.RE + +To apply the first image of this split WIM to the directory "dir", we would do: +.PP +.RS +imagex apply mywim.swm 1 dir --ref="mywim*.swm" +.RE +.PP .SH OPTIONS .TP 6 @@ -26,22 +197,70 @@ 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 is already +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. Files of this type are already hard linked together inside the -WIM to save space. +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 -When extracting a file from the WIM that is identical to a file that is already -extracted, create a symbolic link using \fBsymlink\fR (3) rather than creating a -separate file. Files of this type are already hard linked together inside the -WIM to save space. +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. +Print the path to of each file or directory within the WIM image as it is +extracted, and some additional informational messages. .TP -\fB--verify\fR -This option is currently unsupported. +\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. + +.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 sure that the files 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 specified. + +.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 +Verbosely apply a WIM image to a NTFS filesystem image: +.RS +.PP +imagex apply mywim.wim 1 fsimage.ntfs --verbose +.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)