X-Git-Url: https://wimlib.net/git/?a=blobdiff_plain;f=doc%2Fimagex-apply.1.in;h=c1ede60b6a66ed0aa8cd2063695793fdd4b70f6f;hb=c6e7b292539deadd827b95c1e393112f5a1adf46;hp=0c536df2d51619135926815a126de879cccf5de8;hpb=da295f258b60e1593de305385c0669eac4b76644;p=wimlib diff --git a/doc/imagex-apply.1.in b/doc/imagex-apply.1.in index 0c536df2..c1ede60b 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,17 +221,35 @@ 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. +.IP \[bu] +On Windows, unless the \fB--no-acls\fR option is specified, wimlib will attempt +to restore files' security descriptors exactly as they are provided in the WIM +image. Beware that typical Windows installations contain files whose security +descriptors do not allow the Administrator to delete them. Therefore, such +files will not be able to be deleted, or in some cases even read, after +extracting, unless processed with a specialized program that knows to acquire +the SE_RESTORE_NAME and/or SE_BACKUP_NAME privileges which allow overriding +access control lists. This is not a bug in wimlib, which works as designed to +correctly restore the data that was archived, but rather a problem with the +access rights Windows uses on certain files. But if you just want the file data +and don't care about security descriptors, use \fB--no-acls\fR to skip restoring +all security descriptors. +.IP \[bu] +A similar caveat to the above applies to file attributes such as Readonly, +Hidden, and System. By design, on Windows wimlib will restore such file +attributes; therefore, extracted files may have those attributes. If this is +not what you want, use the \fB--no-attributes\fR option. .SH SPLIT WIMS You may use \fB@IMAGEX_PROGNAME@ apply\fR to apply images from a split WIM. The \fIWIMFILE\fR argument must specify the first part of the split WIM, while the @@ -267,8 +284,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 @@ -299,20 +317,17 @@ expansion. 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 @@ -345,24 +360,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 @@ -373,16 +393,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 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": @@ -426,16 +456,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)