From c040dac396c3ec1aa42fda92672cd5632e91b6d5 Mon Sep 17 00:00:00 2001 From: Eric Biggers Date: Sun, 12 May 2013 13:26:05 -0500 Subject: [PATCH] imagex-apply.1.in: Update man page --- doc/imagex-apply.1.in | 226 ++++++++++++++++++++++++------------------ 1 file changed, 132 insertions(+), 94 deletions(-) diff --git a/doc/imagex-apply.1.in b/doc/imagex-apply.1.in index b078ba0b..c8a96a04 100644 --- a/doc/imagex-apply.1.in +++ b/doc/imagex-apply.1.in @@ -8,39 +8,45 @@ .SH DESCRIPTION .PP -\fB@IMAGEX_PROGNAME@ apply\fR extracts an image, or all images, from the Windows Imaging -(WIM) file \fIWIMFILE\fR. +\fB@IMAGEX_PROGNAME@ apply\fR extracts an image, or all images, from the Windows +Imaging (WIM) file \fIWIMFILE\fR. -Note: this man page primarily documents the UNIX behavior. See \fBWINDOWS -VERSION\fR for information specific to the Windows build of wimlib. +This command is designed to extract, or "apply", one or more full WIM images. +If you 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. \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. +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. +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. -\fB@IMAGEX_PROGNAME@ apply\fR supports applying images from stand-alone WIMs as well as -split WIMs. See \fBSPLIT WIMS\fR. +\fB@IMAGEX_PROGNAME@ apply\fR supports applying images from stand-alone WIMs as +well as split WIMs. See \fBSPLIT WIMS\fR. -.SH NORMAL MODE +.SH NORMAL MODE (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. +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. -In the normal mode of extraction, the following information is extracted from -the WIM image(s): +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. + +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 stream of each file @@ -56,8 +62,8 @@ 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): +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) except through the extensions available @@ -71,13 +77,18 @@ Certain file attributes such as compression, encryption, and sparseness. .IP \[bu] Short (DOS) names for files -.SH NTFS MODE +.SH NTFS MODE (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. +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. + +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. 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 @@ -87,12 +98,12 @@ 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 +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). -In the NTFS extraction mode, the following information will be extracted from -the WIM image: +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 @@ -116,13 +127,15 @@ 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. - +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. +.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: @@ -186,6 +199,7 @@ mywim3.swm mywim4.swm mywim5.swm .RE +.nf To apply the first image of this split WIM to the directory "dir", run: .PP @@ -196,26 +210,44 @@ To apply the first image of this split WIM to the directory "dir", run: .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. +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. -\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. +On Windows, \fB@IMAGEX_PROGNAME@ apply\fR tries to extract as much data as +possible. This includes: -\fB--hardlink\fR, \fB--symlink\fR, and \fB--unix-data\fR are not supported on -Windows. +.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. -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. +.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. .SH OPTIONS .TP 6 @@ -223,45 +255,10 @@ similar. 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 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 -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, 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 -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. 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 @@ -273,6 +270,46 @@ 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. +.TP +\fB--verbose\fR +Print the path to of each file or directory within the WIM image as it is +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. .SH NOTES @@ -291,7 +328,7 @@ You cannot use \fB@IMAGEX_PROGNAME@ apply\fR to apply a WIM from a pipe (such as 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 @@ -306,8 +343,8 @@ installation media to the directory "boot", and hard link all identical files: @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: +.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_PROGNAME@ apply mywim.wim 1 fsimage.ntfs @@ -325,3 +362,4 @@ mkntfs /dev/sda2 && @IMAGEX_PROGNAME@ apply /media/windows/sources/install.wim 1 .SH SEE ALSO .BR @IMAGEX_PROGNAME@ (1) .BR @IMAGEX_PROGNAME@-extract (1) +.BR @IMAGEX_PROGNAME@-info (1) -- 2.43.0