X-Git-Url: https://wimlib.net/git/?p=wimlib;a=blobdiff_plain;f=doc%2Fimagex-apply.1.in;h=b7b87a2eca716ea586f0647e1118cdb1d9f9ff3c;hp=b4b16eaeec7fcbe1508992b3e857797ec071ed0c;hb=34ed0b6497707b151adea37586c63a395cee589c;hpb=64f1e9b6bb2bb4d5b16240ae731bd8a84117cc98 diff --git a/doc/imagex-apply.1.in b/doc/imagex-apply.1.in index b4b16eae..b7b87a2e 100644 --- a/doc/imagex-apply.1.in +++ b/doc/imagex-apply.1.in @@ -1,124 +1,138 @@ -.TH IMAGEX "1" "September 2012" "imagex (wimlib) wimlib @VERSION@" "User Commands" +.TH WIMLIB-IMAGEX "1" "August 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. This command is also available as simply +\fBwimapply\fR if the appropriate hard link or batch file has been installed. .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 -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. -\fITARGET\fR can specify a directory on any type of filesystem. - -In the normal mode of extraction, the following information will be extracted -from the WIM image(s): - -.IP \[bu] 4 -The default (unnamed) data stream of each file -.IP \[bu] -Hard links, if supported by the underlying filesystem -.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). - +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. (\fB@IMAGEX_PROGNAME@ mount\fR is not +supported on Windows.) .PP -In the normal mode of extraction, the following information will \fInot\fR be -extracted from the WIM image(s): - +\fIIMAGE\fR specifies the WIM image in \fIWIMFILE\fR to extract. It may be a +1-based index of an image in \fIWIMFILE\fR, the name of an image in +\fIWIMFILE\fR, or the keyword "all" to indicate that all images in \fIWIMFILE\fR +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 to. If \fITARGET\fR +specifies a directory, the WIM image is extracted to that directory (see +\fBDIRECTORY EXTRACTION (UNIX)\fR or \fBDIRECTORY EXTRACTION (WINDOWS)\fR). +Similarly, if \fITARGET\fR specifies a non-existent file, a directory is created +in that location and the WIM image is extracted to that directory. +.PP +If \fIIMAGE\fR is specified as "all", then all the images in \fIWIMFILE\fR are +actually extracted into subdirectories of \fITARGET\fR, each of which is given +the name of the corresponding image, falling back to the image index in the case +of an image with no name or a name not valid as a filename. +.PP +Alternatively, on UNIX-like systems 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 (see \fBNTFS VOLUME EXTRACTION (UNIX)\fR). Only a single +image can be extracted in this mode, and only extracting to the root of the NTFS +volume (not a subdirectory thereof) is supported. +.PP +\fIWIMFILE\fR may be "-" to read the WIM from standard input rather than from a +file, but see \fBPIPABLE WIMS\fR for more information. +.PP +\fB@IMAGEX_PROGNAME@ apply\fR supports applying images from stand-alone WIMs as +well as split WIMs. See \fBSPLIT WIMS\fR. +.SH DIRECTORY EXTRACTION (UNIX) +This section documents how \fB@IMAGEX_PROGNAME@ apply\fR (and also +\fB@IMAGEX_PROGNAME@ extract\fR) extract a WIM image (or a possibly a subset +thereof, in the case of \fB@IMAGEX_PROGNAME@ extract\fR) to a directory on +UNIX-like systems. See \fBDIRECTORY EXTRACTION (WINDOWS)\fR for the +corresponding documentation for Windows. + +As mentioned, a WIM image can be applied to a directory on a UNIX-like system by +providing a \fITARGET\fR directory. However, it is important to keep in mind +that the WIM format was designed for Windows, and as a result WIM files can +contain data or metadata that cannot be represented on UNIX-like systems. The +main information that \fB@IMAGEX_PROGNAME@\fR will \fInot\fR be able to extract +on UNIX-like systems is the following: .IP \[bu] 4 -Security descriptors (file permissions) +Windows security descriptors (which include the file owner, group, and ACLs). .IP \[bu] -The alternate (named) data streams for each file +Named data streams. .IP \[bu] -Reparse points other than symbolic links and junction points +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 \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. - -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 ---without-ntfs-3g 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: - +Short (DOS) names for files. +.IP \[bu] +File creation timestamps. +.PP +Notes: Unsupported data and metadata is simply not extracted, but +\fB@IMAGEX_PROGNAME@\fR will attempt to warn you when the contents of the WIM +image can't be exactly represented when extracted. Last access and last +modification timestamps are specified to 100 nanosecond granularity in the WIM +file, but will only be extracted to the highest precision supported by the +underlying operating system, C library, and filesystem. +.SH NTFS VOLUME EXTRACTION (UNIX) +This section documents how \fB@IMAGEX_PROGNAME@ apply\fR extracts a WIM image +directly to an NTFS volume image on UNIX-like systems. See \fBDIRECTORY EXTRACTION +(WINDOWS)\fR for the corresponding documentation for Windows. +.PP +As mentioned, \fB@IMAGEX_PROGNAME@\fR running on a UNIX-like system can apply a +WIM image directly to an NTFS volume by specifying \fITARGET\fR as a regular file +or block device containing an NTFS filesystem. The NTFS filesystem need not 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 provided +with \fBntfs-3g\fR. +.PP +In this NTFS volume extraction mode, the WIM image is extracted to the root of +the NTFS volume in a way preserves almost all information contained in the WIM +image. It therefore does not suffer from the limitations described in +\fBDIRECTORY EXTRACTION (UNIX)\fR. This support relies on libntfs-3g to write +to the NTFS volume and handle NTFS-specific and Windows-specific data. +.PP +Please note that this NTFS volume 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 +This NTFS volume extraction mode attempts to extract as much information as +possible, including: .IP \[bu] 4 -The data streams of all files, including the un-named data stream as well as all +All data streams of all files, including the unnamed 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. +File and directory creation, access, and modification timestamps, using the +native NTFS resolution of 100 nanoseconds. .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. +Windows security descriptors, including all components (owner, group, DACL, and +SACL). .IP \[bu] -File attribute flags are applied. +DOS/Windows file attribute flags. .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. - +All names of all files, including names in the Win32 namespace, DOS namespace, +Win32+DOS namespace, and POSIX namespace. This includes hard links. .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 -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 +Currently, the only known limitation (in terms of exactly extracting all data +and metadata) is that the extraction of encrypted files is not expected to work +properly. +.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-like systems 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 @@ -133,15 +147,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 @@ -150,80 +162,277 @@ 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 DIRECTORY EXTRACTION (WINDOWS) +On Windows, \fB@IMAGEX_PROGNAME@ apply\fR and \fB@IMAGEX_PROGNAME@ extract\fR +natively support Windows-specific and NTFS-specific data. For best results, the +target directory should be located on an NTFS volume and \fB@IMAGEX_PROGNAME@\fR +should be run with Administrator privileges; however, non-NTFS filesystems and +running without Administrator privileges are also supported. +.PP +On Windows, \fB@IMAGEX_PROGNAME@ apply\fR and \fB@IMAGEX_PROGNAME@ extract\fR +try to extract as much data and metadata as possible, including: +.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 target volume. +.IP \[bu] +Reparse points, including symbolic links, junction points, and other reparse +points, if supported by the target volume. (Note: see \fB--rpfix\fR and +\fB--norpfix\fR for documentation on exactly how absolute symbolic links and +junctions are extracted.) However, as per the default security settings of +Windows, it is impossible to create a symbolic link or junction point without +Administrator privileges; therefore, you must run \fB@IMAGEX_PROGNAME@\fR as the +Administrator if you wish to fully restore an image containing symbolic links +and/or junction points. (Otherwise, merely a warning will be issued when a +symbolic link or junction point cannot be extracted due to insufficient +privileges.) +.IP \[bu] +File and directory creation, access, and modification timestamps, to the highest +resolution supported by the target volume. +.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 +descriptors for individual files or directories may be omitted or only partially +set if the user does not have permission to set them, which can be a problem if +\fB@IMAGEX_PROGNAME@\fR is run as a non-Administrator. +.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 +\fB@IMAGEX_PROGNAME@\fR will issue a warning when it is unable to extract the +exact metadata and data of the WIM image, for example due to features mentioned +above not being supported by the target filesystem. +.IP \[bu] +Since encrypted files (with FILE_ATTRIBUTE_ENCRYPTED) are not stored in +plaintext in the WIM image, \fB@IMAGEX_PROGNAME@\fR cannot restore encrypted +files to filesystems not supporting encryption. (The current behavior is to +just extract the encrypted data anyway.) Furthermore, even if encrypted files +are restored to a filesystem that supports encryption, they will only be +decryptable if the decryption key is available. +.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 +As a special case, if you are applying an image from standard input from a split +WIM that is also pipable (as described in \fBPIPABLE WIMS\fR), the \fB--ref\fR +option is unneeded; instead you must ensure that all the split WIM parts are +concatenated together on standard input. They can be provided in any order, +with the exception of the first part, which must be first. +.SH PIPABLE WIMS +As of wimlib 1.5.0, \fB@IMAGEX_PROGNAME@ apply\fR supports applying a WIM from a +nonseekable file, such as a pipe, provided that the WIM was captured with +\fB--pipable\fR (see \fB@IMAGEX_PROGNAME@ capture\fR(1)). To use standard input +as the WIM, specify "-" as \fIWIMFILE\fR. A useful use of this ability is to +apply an image from a WIM while streaming it from a webserver; for example, to +apply the first image from a WIM file to an NTFS volume on /dev/sda1: +.PP +.RS +wget -O - http://myserver/mywim.wim | wimapply - 1 /dev/sda1 +.RE +.PP +(The above also used the \fBwimapply\fR abbreviation for \fB@IMAGEX_PROGNAME@ +apply\fR.) Note: WIM files are \fInot\fR pipable by default; you have to +explicitly capture them with \fB--pipable\fR, and they are \fInot\fR compatible +with Microsoft's software. See \fB@IMAGEX_PROGNAME@ capture\fR(1) for more +information. +.PP +It is possible to apply an image from a pipable WIM split into multiple parts; +see \fBSPLIT WIMS\fR. .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 "" +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 "" +Reparse point fixups are never done in the NTFS volume extraction mode on +UNIX-like systems. +.IP "" +\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 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. +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. +.IP "" +However, hard-linked extraction mode does have some additional quirks. Named +data streams will not be extracted, and files can be hard linked even if their +metadata is not fully consistent. .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. +instead. .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. - +\fB--unix-data\fR +(UNIX-like systems only) By default, in the directory 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 +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. On Windows, 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 +\fB@IMAGEX_PROGNAME@\fR does not have permission to set the desired one. Also, +on UNIX-like systems, this flag can also be combined with \fB--unix-data\fR to +cause \fB@IMAGEX_PROGNAME@\fR to fail immediately if the UNIX owner, group, or +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 POSIX-compliant systems, filenames are case-sensitive and may contain any +byte except '\\0' and \'/', so on a POSIX-compliant system 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 a POSIX-compliant system 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 - -\fBimagex apply\fR does not yet support split WIMs. - -\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 sure that the files are extracted correctly, even -though we don't provide 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. - +\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 that need to be +extracted 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. 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. .SH EXAMPLES -.SS Normal extraction mode -Extract the first image from the Windows PE image from the Windows Vista/7/8 +Extract the first image from the Windows PE image on 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 /mnt/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: +Same as above, but using the \fBwimapply\fR abbreviation: .RS .PP -image apply /media/windows8/sources/boot.wim all boot --hardlink +wimapply /media/windows/sources/boot.wim 1 boot .RE .PP -.SS NTFS extraction mode -Verbosely apply a WIM image to a NTFS filesystem image: +On Windows, apply an image of an entire volume, for example from "install.wim" +which can be found on the Windows Vista/7/8 installation media: .RS .PP -imagex apply mywim.wim 1 fsimage.ntfs --verbose +@IMAGEX_PROGNAME@ apply install.wim 1 E:\\ .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.) +Same as above, but running on a UNIX-like system where the corresponding +partition is /dev/sda2: .RS .PP -mkntfs /dev/sda2 && imagex apply /media/windows/sources/install.wim 1 /dev/sda2 +@IMAGEX_PROGNAME@ apply install.wim 1 /dev/sda2 +.RE +.PP +Note that before running either of the above commands, an NTFS filesystem may +need to be created on the partition, for example with format.exe on Windows or +\fBmkntfs\fR(8) (part of NTFS-3g) on UNIX-like systems. For example, you might +run: +.RS +.PP +mkntfs /dev/sda2 && wimapply install.wim 1 /dev/sda2 +.RE +.PP +(Of course don't do that if you don't want to destroy all existing data on the +partition!) +.PP +An example of applying a pipable WIM from a pipe can be found in \fBPIPABLE +WIMS\fR, and an example of applying a split WIM can be found in \fBSPLIT +WIMS\fR. +.PP +And finally, just for fun, a silly way to recursively copy a directory tree +\fIsrc\fR to \fIdst\fR (but subject to the documented limitations, e.g. +platform and filesystem-dependent, of the capture and apply functionality of +\fB@IMAGEX_PROGNAME@\fR): +.RS +.PP +@IMAGEX_PROGNAME@ capture src - | @IMAGEX_PROGNAME@ apply - dst .RE .PP - .SH SEE ALSO -.BR imagex (1) - +.BR @IMAGEX_PROGNAME@ (1) +.BR @IMAGEX_PROGNAME@-capture (1) +.BR @IMAGEX_PROGNAME@-extract (1) +.BR @IMAGEX_PROGNAME@-info (1)