X-Git-Url: https://wimlib.net/git/?p=wimlib;a=blobdiff_plain;f=doc%2Fimagex-apply.1.in;h=b7a1936df829fbd23caa0583f0e75ac16f5ab789;hp=8012066f23458cc842ca9a5062fa148955785417;hb=a3c287beb780cb26efef17fca6d15331f285eb9c;hpb=ef8f45b98b5c4db398321cd36d052ccbb9c3784a

diff --git a/doc/imagex-apply.1.in b/doc/imagex-apply.1.in
index 8012066f..b7a1936d 100644
--- a/doc/imagex-apply.1.in
+++ b/doc/imagex-apply.1.in
@@ -1,52 +1,369 @@
-.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_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
+\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
+\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.  \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
+\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 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.  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
+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
+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 (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
+\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.
+.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
+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:
+.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).
+.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
+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.
+.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
+Additional notes about extracting files on Windows:
+.IP \[bu] 4
+Encrypted files will be extracted as raw encrypted data if the filesystem
+does not support encryption.
+.IP \[bu]
+Compressed files and directories (with the compression attribute set) will be
+extracted as uncompressed if the filesystem does not support transparent
+compression.
+.IP \[bu]
+Files with names that cannot be represented on Windows will not
+be extracted by default; see \fB--include-invalid-names\fR.
+.IP \[bu]
+Files with full paths over 260 characters (MAX_PATH) are extracted by using the
+\\\\?\\-prefixed path hack.  But beware that such files will be inaccessible to
+most Windows software and may not be able to be deleted easily.
+.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
+.fi
+.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
-
-\fBimagex apply\fR extracts the specified image from \fIWIMFILE\fR to
-\fIDIRECTORY\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.
-
 .SH OPTIONS
 .TP 6
 \fB--check\fR
 When reading \fIWIMFILE\fR, verify its integrity if the integrity table is
 present.
 .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--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.
+.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.
+(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
-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.
+(UNIX only) This option is similar to \fB--hardlink\fR, except symbolic links are created
+instead.
 .TP
-\fB--verbose\fR
-Print the path to of each file or directory within the WIM image as it is extracted.
-
+\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--include-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--include-invalid-names\fR, all names will be sanitized and
+extracted in some form.
+.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.
+.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
-.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 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
+@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 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
+.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
 .SH SEE ALSO
-.BR imagex (1)
-
+.BR @IMAGEX_PROGNAME@ (1)
+.BR @IMAGEX_PROGNAME@-extract (1)
+.BR @IMAGEX_PROGNAME@-info (1)