X-Git-Url: https://wimlib.net/git/?p=wimlib;a=blobdiff_plain;f=doc%2Fimagex-apply.1.in;h=c7ba4c31063e6bec497d830c75835f5e7377f858;hp=0c81915b2f95fbb05700f1ecc6217e076040fca1;hb=389f993fdf085a9bf120f8a17464e321d6e42898;hpb=f1153575fae2fad42e2b73ff744c25e3a8d01ad0 diff --git a/doc/imagex-apply.1.in b/doc/imagex-apply.1.in index 0c81915b..c7ba4c31 100644 --- a/doc/imagex-apply.1.in +++ b/doc/imagex-apply.1.in @@ -1,58 +1,65 @@ -.TH IMAGEX "1" "May 2012" "imagex (wimlib) wimlib @VERSION@" "User Commands" +.TH IMAGEX "1" "May 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\fR \fITARGET\fR [\fIOPTION\fR]... - +\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. +.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. .PP - -\fBimagex apply\fR extracts an image, or all images, from the Windows Imaging -(WIM) file \fIWIMFILE\fR. - \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. - -\fBTARGET\fR specifies where to extract the WIM image(s) to. If \fBTARGET\fR +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. +.PP +\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 -\fBTARGET\fR specifies a non-existent file, a directory is created in that -location and the WIM image(s) are extracted to that directory. If \fBTARGET\fR -specifies a regular file or block device, it is interpreted as a NTFS volume to -which the WIM image is to be extracted. - -.SH NORMAL MODE - -The normal extraction mode is entered when \fBTARGET\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 -\fBTARGET\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. - -In the normal mode of extraction, the following information will be extracted -from the WIM image(s): - +\fITARGET\fR specifies a non-existent file, a directory is created in that +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. +.PP +\fB@IMAGEX_PROGNAME@ apply\fR supports applying images from stand-alone WIMs as +well as split WIMs. See \fBSPLIT WIMS\fR. +.SH NORMAL MODE (UNIX) +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. +.PP +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. +.PP +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 streams of each file +The default (unnamed) data stream of each file .IP \[bu] -Hard links, if supported by the underlying filesystem +Hard links .IP \[bu] File and directory creation, access, and modification timestamps to the nearest -microsecond, if supported by the underlying filesystem +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) +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] @@ -61,25 +68,32 @@ Reparse points other than symbolic links and junction points 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 \fBTARGET\fR is a regular file or -block device. \fBTARGET\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. \fBIMAGE\fR may not be "all" for this action. - +.SH NTFS MODE (UNIX) +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. +.PP +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. +.PP 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. - +.PP The NTFS extraction mode is not available if wimlib was compiled using the ---without-ntfs-3g option. - -In the NTFS extraction mode, the following information will be extracted from -the WIM image: - +\fB--without-ntfs-3g\fR option. +.PP +Please note that the NTFS 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 +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 named data streams. @@ -100,19 +114,19 @@ File attribute flags are applied. 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 +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. - -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 +.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 @@ -127,15 +141,13 @@ partition". 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 +\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 @@ -144,59 +156,196 @@ 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 WINDOWS VERSION +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. +.PP +On Windows, \fB@IMAGEX_PROGNAME@ apply\fR tries to extract as much data as +possible. This includes: +.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. +.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. +Additional note: files with names that cannot be represented on Windows will not +be extracted by default; see \fB--including-invalid-names\fR. +.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). +.PP +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 +.nf +.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 .SH OPTIONS .TP 6 \fB--check\fR 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 using \fBlink\fR (3) 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. +\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--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. +\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 has been applied to any location. +.IP "" 6 +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 "" 6 +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, and some additional informational messages. - +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. +.TP +\fB--including-invalid-names\fR +Extract files and directories with invalid names by replacing characters and +appending a suffix rather than ignoring them. The meaning of this is +platform-dependent. +.IP "" 6 +On UNIX, filenames are case-sensitive and may contain any byte except '\\0' and +\'/', so on UNIX 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 "" 6 +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 UNIX 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--including-invalid-names\fR, all names will be sanitized and +extracted in some form. .SH NOTES - -\fBimagex apply\fR does not yet support split WIMs. - +\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. +.PP +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 -.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 .PP -image apply /media/windows/sources/boot.wim 1 boot +@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 -image apply /media/windows8/sources/boot.wim all boot --hardlink +@IMAGEX_PROGNAME@ 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: +.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 apply mywim.wim 1 fsimage.ntfs --verbose +@IMAGEX_PROGNAME@ apply mywim.wim 1 fsimage.ntfs .RE .PP Create a new NTFS filesystem on the partition /dev/sda2 and apply the first @@ -204,10 +353,9 @@ 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 +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) +.BR @IMAGEX_PROGNAME@-extract (1) +.BR @IMAGEX_PROGNAME@-info (1)