X-Git-Url: https://wimlib.net/git/?p=wimlib;a=blobdiff_plain;f=doc%2Fimagex-apply.1.in;h=d60c53d64acbc6386c92b1fca3e2b9e61086b81b;hp=7e09a9497d6e41188388a69c9dc1c55a02d9a446;hb=a381a9e10a60c7790fe33255c949bf55b5872a8d;hpb=bec7f491bd14b1da3aae7054edd72575dcf77a4f diff --git a/doc/imagex-apply.1.in b/doc/imagex-apply.1.in index 7e09a949..d60c53d6 100644 --- a/doc/imagex-apply.1.in +++ b/doc/imagex-apply.1.in @@ -1,23 +1,219 @@ -.TH IMAGEX "1" "May 2012" "imagex (wimlib) wimlib @VERSION@" "User Commands" +.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 +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. +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 +UNIX version. + +\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 mostly the same behavior as Microsoft's ImageX. + +\fB--hardlink\fR, \fB--symlink\fR, and \fB--unix-data\fR are not supported on +Windows. + +Other than the differences documented in this section, the Windows version +should be essentially equivalent to the UNIX version. However, one additional +thing to note is that wimlib's Windows version of ImageX is NOT written to be +command-line compatible with Microsoft's version of ImageX, although they are +very similar. .SH OPTIONS .TP 6 @@ -26,29 +222,80 @@ 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 -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. +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 -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--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--verify\fR -This option is currently unsupported. +\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 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. + +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 -.IP -image apply boot.wim all boot --hardlink -.LP -Extract all images in the WIM 'boot.wim' to the directory 'boot', and hard link -all identical files. +.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)