X-Git-Url: https://wimlib.net/git/?p=wimlib;a=blobdiff_plain;f=doc%2Fimagex-apply.1.in;h=6043d025842bed27d7bab9a32ef665b459d848e8;hp=2612870711b4a9cc18f88d33adfc39aec0b1f36c;hb=2f1f50993984f88df675f0c3302cf4fa52982f05;hpb=c55f2da2961e8412e93722b2e8b6ec7c9779d80b diff --git a/doc/imagex-apply.1.in b/doc/imagex-apply.1.in index 26128707..6043d025 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 @@ -79,8 +79,7 @@ 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 @@ -103,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. @@ -222,29 +221,24 @@ 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. Therefore, such files are not -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. +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 @@ -272,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 @@ -294,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 @@ -347,24 +342,29 @@ 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--no-attributes\fR +Do not restore Windows file attributes such as readonly, hidden, etc. .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 @@ -374,20 +374,27 @@ 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. -.TP -\fB--resume\fR -TODO .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 overwrite 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": @@ -431,16 +438,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)