X-Git-Url: https://wimlib.net/git/?a=blobdiff_plain;ds=sidebyside;f=doc%2Fimagex-apply.1.in;h=5db59f92a7f0fd0ac91fb559aacef08c14a54d7f;hb=df7f6ca9f3d34b5133667ad35f800b7afcabe434;hp=8012066f23458cc842ca9a5062fa148955785417;hpb=ef8f45b98b5c4db398321cd36d052ccbb9c3784a;p=wimlib diff --git a/doc/imagex-apply.1.in b/doc/imagex-apply.1.in index 8012066f..5db59f92 100644 --- a/doc/imagex-apply.1.in +++ b/doc/imagex-apply.1.in @@ -1,23 +1,221 @@ -.TH IMAGEX "1" "May 2012" "imagex (wimlib) wimlib @VERSION@" "User Commands" +.TH IMAGEX "1" "April 2013" "@IMAGEX_PROGNAME@ @VERSION@" "User Commands" .SH NAME -imagex apply \- Extract one image, or all images, from a WIM archive +@IMAGEX_PROGNAME@-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]... +\fB@IMAGEX_PROGNAME@ 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. +\fB@IMAGEX_PROGNAME@ 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 \fB@IMAGEX_PROGNAME@ 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. + +\fB@IMAGEX_PROGNAME@ 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 +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). + +.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 +\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). + +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 \fB@IMAGEX_PROGNAME@ 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_PROGNAME@ apply mywim.swm 1 dir --ref="mywim*.swm" +.RE +.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. + +\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. + +\fB--hardlink\fR, \fB--symlink\fR, and \fB--unix-data\fR are not supported on +Windows. + +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. .SH OPTIONS .TP 6 @@ -26,27 +224,106 @@ 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--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 +links that are marked in the WIM image as being fixed are assumed to have +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. + +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. + +.SH NOTES + +\fB@IMAGEX_PROGNAME@ 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 \fB@IMAGEX_PROGNAME@ apply\fR don't have a \fB/verify\fR option like +Microsoft's 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 \fB@IMAGEX_PROGNAME@ 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 +@IMAGEX_PROGNAME@ 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 +@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: +.RS +.PP +@IMAGEX_PROGNAME@ 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_PROGNAME@ apply /media/windows/sources/install.wim 1 /dev/sda2 +.RE +.PP .SH SEE ALSO -.BR imagex (1) +.BR @IMAGEX_PROGNAME@ (1)