X-Git-Url: https://wimlib.net/git/?a=blobdiff_plain;f=doc%2Fimagex-apply.1.in;h=1a6d0a4114e404404f5cdb46c59ed7bd7355c035;hb=ea914185bfdd6d2a000a341566f4dbbb7ecc2319;hp=33c793635948bdb8dca37c0f951ff8ffa4164f81;hpb=2b04e3ff551654916caba6f6fad50908de67b0fd;p=wimlib diff --git a/doc/imagex-apply.1.in b/doc/imagex-apply.1.in index 33c79363..1a6d0a41 100644 --- a/doc/imagex-apply.1.in +++ b/doc/imagex-apply.1.in @@ -1,4 +1,4 @@ -.TH WIMLIB-IMAGEX "1" "August 2013" "@IMAGEX_PROGNAME@ @VERSION@" "User Commands" +.TH WIMLIB-IMAGEX "1" "January 2014" "@IMAGEX_PROGNAME@ @VERSION@" "User Commands" .SH NAME @IMAGEX_PROGNAME@-apply \- Extract one image, or all images, from a WIM archive .SH SYNOPSIS @@ -70,15 +70,16 @@ Short (DOS) names for files. File creation timestamps. .PP Notes: Unsupported data and metadata is simply not extracted, but -\fB@IMAGEX_PROGNAME@\fR always warns 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. +\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. Compressed files will +be extracted as uncompressed, while encrypted files will not be extracted at +all. .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. +directly to an NTFS volume image on UNIX-like systems. .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 @@ -101,8 +102,8 @@ unmounted, and you must have permission to write to it). This NTFS volume extraction mode attempts to extract as much information as possible, including: .IP \[bu] 4 -All data streams of all files, including the unnamed data stream as well as all -named data streams. +All data streams of all files except encrypted 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. @@ -118,11 +119,16 @@ DOS/Windows file attribute flags. All names of all files, including names in the Win32 namespace, DOS namespace, Win32+DOS namespace, and POSIX namespace. This includes hard links. .PP -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. +However, there are also several known limitations of the NTFS volume extraction +mode: +.IP \[bu] 4 +Encrypted files will not be extracted. +.IP \[bu] +Although sparse file attributes will be applied, the full data will be extracted +to each sparse file, so extracted "sparse" files may not actually contain any +sparse regions. .PP -Since all (or almost all) information from the WIM image is restored in this +Regardless, since 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 @@ -209,35 +215,30 @@ Hard links, if supported by the filesystem. .PP Additional notes about extracting files on Windows: .IP \[bu] 4 -\fB@IMAGEX_PROGNAME@\fR will always 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. +\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 +files to filesystems not supporting encryption. Therefore, on such filesystems, +encrypted files will not be extracted. 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. +Files with full paths over 260 characters (the so-called MAX_PATH) will be +extracted, 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: +\fIWIMFILE\fR argument must specify the first part of the split WIM, while the +additional parts of the split WIM must be specified in one or more +\fB--ref\fR="\fIGLOB\fR" options. Since globbing is built into the \fB--ref\fR +option, typically only one \fB--ref\fR option is necessary. For example, the +names for the split WIM parts usually go something like: .RS .PP .nf @@ -265,8 +266,9 @@ 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: +apply an image from a WIM while streaming it from a server. For example, to +apply the first image from a WIM file available on a HTTP server to an NTFS +volume on /dev/sda1, run something like: .PP .RS wget -O - http://myserver/mywim.wim | wimapply - 1 /dev/sda1 @@ -287,27 +289,27 @@ 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. +File glob of additional WIMs or split WIM parts to reference resources from. +See \fBSPLIT_WIMS\fR. This option can be specified multiple times. Note: +\fIGLOB\fR is listed in quotes because it is interpreted by +\fB@IMAGEX_PROGNAME@\fR and may need to be quoted to protect against shell +expansion. .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. +absolute targets relative to the image root, and therefore \fB@IMAGEX_PROGNAME@ +apply\fR prepends the absolute path to the extraction target directory 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 @@ -340,24 +342,26 @@ 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. +be set exactly as specified in the WIM file. If this option is not specified, +when \fB@IMAGEX_PROGNAME@\fR on Windows does not have permission to set a +security descriptor on an extracted file, it falls back to setting it only +partially (e.g. with SACL omitted), and in the worst case omits it entirely. +However, this should only be a problem when running \fB@IMAGEX_PROGNAME@\fR +without Administrator rights. 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 +appending a suffix rather than ignoring them. Exactly what is considered an +"invalid" name is platform-dependent. +.IP "" 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 +.IP "" 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 @@ -368,16 +372,26 @@ 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 +\fIData integrity\fR: WIM files include SHA1 message digests for file data. \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. +it extracts and issues an error if it is not equal to the SHA1 message digest +provided in the WIM. (This default behavior seems equivalent to the +\fB/verify\fR option of ImageX.) 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 +\fIESD files\fR: wimlib v1.6.0 and later can extract files from version 3584 +WIMs, which usually contain LZMS-compressed solid blocks and may carry the +\fI.esd\fR file extension rather than \fI.wim\fR. However, \fI.esd\fR files +downloaded directly by the Windows 8 web downloader have encrypted segments, and +wimlib cannot extract such files until they are first decrypted. +.PP +\fIDirectory traversal attacks\fR: wimlib validates filenames before extracting +them and is not vulnerable to directory traversal attacks. This is in contrast +to Microsoft WIMGAPI/Imagex/Dism which can override arbitrary files on the +target drive when extracting a malicious WIM file containing files named +\fI..\fR or containing path separators. .SH EXAMPLES Extract the first image from the Windows PE image on the Windows Vista/7/8 installation media to the directory "boot": @@ -421,16 +435,6 @@ partition!) 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_PROGNAME@ (1) .BR @IMAGEX_PROGNAME@-capture (1)