[wimlib] / doc / man1 / wimlib-imagex-apply.1
1 .TH WIMLIB-IMAGEX "1" "January 2016" "wimlib 1.9.0" "User Commands"
3 wimlib-imagex-apply \- Extract one image, or all images, from a WIM archive
5 \fBwimlib-imagex apply\fR \fIWIMFILE\fR [\fIIMAGE\fR] \fITARGET\fR [\fIOPTION\fR...]
7 \fBwimlib-imagex apply\fR extracts an image, or all images, from the Windows
8 Imaging (WIM) file \fIWIMFILE\fR.  This command is also available as simply
9 \fBwimapply\fR if the appropriate hard link or batch file has been installed.
10 .PP
11 This command is designed to extract, or "apply", one or more full WIM images.
12 If you instead want to extract only certain files or directories contained in a
13 WIM image, consider using \fBwimlib-imagex extract\fR or
14 \fBwimlib-imagex mount\fR instead.  (\fBwimlib-imagex mount\fR is not
15 supported on Windows.)
16 .PP
17 \fIIMAGE\fR specifies the WIM image in \fIWIMFILE\fR to extract.  It may be a
18 1-based index of an image in \fIWIMFILE\fR, the name of an image in
19 \fIWIMFILE\fR, or the keyword "all" to indicate that all images in \fIWIMFILE\fR
20 are to be extracted.  Use the \fBwimlib-imagex info\fR (1) command to show
21 what images a WIM file contains.  \fIIMAGE\fR may be omitted if \fIWIMFILE\fR
22 contains only one image.
23 .PP
24 \fITARGET\fR specifies where to extract the WIM image to.  If \fITARGET\fR
25 specifies a directory, the WIM image is extracted to that directory (see
27 Similarly, if \fITARGET\fR specifies a non-existent file, a directory is created
28 in that location and the WIM image is extracted to that directory.
29 .PP
30 If \fIIMAGE\fR is specified as "all", then all the images in \fIWIMFILE\fR are
31 actually extracted into subdirectories of \fITARGET\fR, each of which is given
32 the name of the corresponding image, falling back to the image index in the case
33 of an image with no name or a name not valid as a filename.
34 .PP
35 Alternatively, on UNIX-like systems only, if \fITARGET\fR specifies a regular
36 file or block device, it is interpreted as an NTFS volume to which the WIM image
37 is to be extracted (see \fBNTFS VOLUME EXTRACTION (UNIX)\fR).  Only a single
38 image can be extracted in this mode, and only extracting to the root of the NTFS
39 volume (not a subdirectory thereof) is supported.
40 .PP
41 \fIWIMFILE\fR may be "-" to read the WIM from standard input rather than from a
42 file, but see \fBPIPABLE WIMS\fR for more information.
43 .PP
44 \fBwimlib-imagex apply\fR supports applying images from stand-alone WIMs as
45 well as split WIMs.  See \fBSPLIT WIMS\fR.
47 This section documents how \fBwimlib-imagex apply\fR (and also
48 \fBwimlib-imagex extract\fR) extract a WIM image (or a possibly a subset
49 thereof, in the case of \fBwimlib-imagex extract\fR) to a directory on
50 UNIX-like systems.  See \fBDIRECTORY EXTRACTION (WINDOWS)\fR for the
51 corresponding documentation for Windows.
52 .PP
53 As mentioned, a WIM image can be applied to a directory on a UNIX-like system by
54 providing a \fITARGET\fR directory.  However, it is important to keep in mind
55 that the WIM format was designed for Windows, and as a result WIM files can
56 contain data or metadata that cannot be represented on UNIX-like systems.  The
57 main information that \fBwimlib-imagex\fR will \fInot\fR be able to extract
58 on UNIX-like systems is the following:
59 .IP \[bu] 4
60 Windows security descriptors (which include the file owner, group, and ACLs).
61 .IP \[bu]
62 Named data streams.
63 .IP \[bu]
64 Reparse points other than symbolic links and junction points.
65 .IP \[bu]
66 Certain file attributes such as compression, encryption, and sparseness.
67 .IP \[bu]
68 Short (DOS) names for files.
69 .IP \[bu]
70 File creation timestamps.
71 .PP
72 Notes: Unsupported data and metadata is simply not extracted, but
73 \fBwimlib-imagex\fR will attempt to warn you when the contents of the WIM
74 image can't be exactly represented when extracted.  Last access and last
75 modification timestamps are specified to 100 nanosecond granularity in the WIM
76 file, but will only be extracted to the highest precision supported by the
77 underlying operating system, C library, and filesystem.  Compressed files will
78 be extracted as uncompressed, while encrypted files will not be extracted at
79 all.
81 This section documents how \fBwimlib-imagex apply\fR extracts a WIM image
82 directly to an NTFS volume image on UNIX-like systems.
83 .PP
84 As mentioned, \fBwimlib-imagex\fR running on a UNIX-like system can apply a
85 WIM image directly to an NTFS volume by specifying \fITARGET\fR as a regular file
86 or block device containing an NTFS filesystem.  The NTFS filesystem need not be
87 empty, although it's expected that it be empty for the intended use cases.  A
88 new NTFS filesystem can be created using the \fBmkntfs\fR(8) command provided
89 with \fBntfs-3g\fR.
90 .PP
91 In this NTFS volume extraction mode, the WIM image is extracted to the root of
92 the NTFS volume in a way preserves almost all information contained in the WIM
93 image.  It therefore does not suffer from the limitations described in
94 \fBDIRECTORY EXTRACTION (UNIX)\fR.  This support relies on libntfs-3g to write
95 to the NTFS volume and handle NTFS-specific and Windows-specific data.
96 .PP
97 Please note that this NTFS volume extraction mode is \fInot\fR entered if
98 \fITARGET\fR is a directory, even if an NTFS filesystem is mounted on
99 \fITARGET\fR.  You must specify the NTFS volume itself (and it must be
100 unmounted, and you must have permission to write to it).
101 .PP
102 This NTFS volume extraction mode attempts to extract as much information as
103 possible, including:
104 .IP \[bu] 4
105 All data streams of all files except encrypted files, including the unnamed data
106 stream as well as all named data streams.
107 .IP \[bu]
108 Reparse points, including symbolic links, junction points, and other reparse
109 points.
110 .IP \[bu]
111 File and directory creation, access, and modification timestamps, using the
112 native NTFS resolution of 100 nanoseconds.
113 .IP \[bu]
114 Windows security descriptors, including all components (owner, group, DACL, and
115 SACL).
116 .IP \[bu]
117 DOS/Windows file attribute flags.
118 .IP \[bu]
119 All names of all files, including names in the Win32 namespace, DOS namespace,
120 Win32+DOS namespace, and POSIX namespace.  This includes hard links.
121 .IP \[bu]
122 Object IDs.
123 .PP
124 However, there are also several known limitations of the NTFS volume extraction
125 mode:
126 .IP \[bu] 4
127 Encrypted files will not be extracted.
128 .IP \[bu]
129 wimlib v1.7.0 and later:  Sparse file attributes will not be extracted (same
130 behavior as ImageX/DISM/WIMGAPI).  wimlib v1.6.2 and earlier:  Although sparse
131 file attributes will be applied, the full data will be extracted to each sparse
132 file, so extracted "sparse" files may not actually contain any sparse regions.
133 .PP
134 Regardless, since almost all information from the WIM image is restored in this
135 mode, it is possible (and fully supported) to restore an image of an actual
136 Windows installation using \fBwimlib-imagex\fR on UNIX-like systems as an
137 alternative to using \fBwimlib-imagex\fR on Windows.  In the examples at the end
138 of this manual page, there is an example of applying an image from the
139 "install.wim" file contained in the installation media for Windows (Vista or
140 later) in the "sources" directory.
141 .PP
142 Note that to actually boot Windows (Vista or later) from an applied
143 "install.wim" image, you also need to mark the partition as "bootable" and set
144 up various boot files, such as \\BOOTMGR and \\BOOT\\BCD.  The latter task is
145 most easily accomplished by running the "bcdboot.exe" program from a live
146 Windows system (such as Windows PE), but there are other options as well.
148 On Windows, \fBwimlib-imagex apply\fR and \fBwimlib-imagex extract\fR
149 natively support Windows-specific and NTFS-specific data.  For best results, the
150 target directory should be located on an NTFS volume and \fBwimlib-imagex\fR
151 should be run with Administrator privileges; however, non-NTFS filesystems and
152 running without Administrator privileges are also supported.
153 .PP
154 On Windows, \fBwimlib-imagex apply\fR and \fBwimlib-imagex extract\fR
155 try to extract as much data and metadata as possible, including:
156 .IP \[bu] 4
157 All data streams of all files.  This includes the default file contents, as well
158 as named data streams if supported by the target volume.
159 .IP \[bu]
160 Reparse points, including symbolic links, junction points, and other reparse
161 points, if supported by the target volume.  (Note: see \fB--rpfix\fR and
162 \fB--norpfix\fR for documentation on exactly how absolute symbolic links and
163 junctions are extracted.)  However, as per the default security settings of
164 Windows, it is impossible to create a symbolic link or junction point without
165 Administrator privileges; therefore, you must run \fBwimlib-imagex\fR as the
166 Administrator if you wish to fully restore an image containing symbolic links
167 and/or junction points.  (Otherwise, merely a warning will be issued when a
168 symbolic link or junction point cannot be extracted due to insufficient
169 privileges.)
170 .IP \[bu]
171 File and directory creation, access, and modification timestamps, to the highest
172 resolution supported by the target volume.
173 .IP \[bu]
174 Security descriptors, if supported by the filesystem and \fB--no-acls\fR is not
175 specified.  Furthermore, unless \fB--strict-acls\fR is specified, the security
176 descriptors for individual files or directories may be omitted or only partially
177 set if the user does not have permission to set them, which can be a problem if
178 \fBwimlib-imagex\fR is run as a non-Administrator.
179 .IP \[bu]
180 File attributes, including hidden, sparse, compressed, encrypted, etc, when
181 supported by the filesystem.
182 .IP \[bu]
183 DOS names (8.3) names of files; however, the failure to set them is not
184 considered an error condition.
185 .IP \[bu]
186 Hard links, if supported by the target filesystem.
187 .IP \[bu]
188 Object IDs, if supported by the target filesystem.
189 .PP
190 Additional notes about extracting files on Windows:
191 .IP \[bu] 4
192 \fBwimlib-imagex\fR will issue a warning when it is unable to extract the
193 exact metadata and data of the WIM image, for example due to features mentioned
194 above not being supported by the target filesystem.
195 .IP \[bu]
196 Since encrypted files (with FILE_ATTRIBUTE_ENCRYPTED) are not stored in
197 plaintext in the WIM image, \fBwimlib-imagex\fR cannot restore encrypted
198 files to filesystems not supporting encryption.  Therefore, on such filesystems,
199 encrypted files will not be extracted.  Furthermore, even if encrypted
200 files are restored to a filesystem that supports encryption, they will only be
201 decryptable if the decryption key is available.
202 .IP \[bu]
203 Files with names that cannot be represented on Windows will not
204 be extracted by default; see \fB--include-invalid-names\fR.
205 .IP \[bu]
206 Files with full paths over 260 characters (the so-called MAX_PATH) will be
207 extracted, but beware that such files will be inaccessible to most Windows
208 software and may not be able to be deleted easily.
209 .IP \[bu]
210 On Windows, unless the \fB--no-acls\fR option is specified, wimlib will attempt
211 to restore files' security descriptors exactly as they are provided in the WIM
212 image.  Beware that typical Windows installations contain files whose security
213 descriptors do not allow the Administrator to delete them.  Therefore, such
214 files will not be able to be deleted, or in some cases even read, after
215 extracting, unless processed with a specialized program that knows to acquire
216 the SE_RESTORE_NAME and/or SE_BACKUP_NAME privileges which allow overriding
217 access control lists.  This is not a bug in wimlib, which works as designed to
218 correctly restore the data that was archived, but rather a problem with the
219 access rights Windows uses on certain files.  But if you just want the file data
220 and don't care about security descriptors, use \fB--no-acls\fR to skip restoring
221 all security descriptors.
222 .IP \[bu]
223 A similar caveat to the above applies to file attributes such as Readonly,
224 Hidden, and System.  By design, on Windows wimlib will restore such file
225 attributes; therefore, extracted files may have those attributes.  If this is
226 not what you want, use the \fB--no-attributes\fR option.
228 You may use \fBwimlib-imagex apply\fR to apply images from a split WIM.  The
229 \fIWIMFILE\fR argument must specify the first part of the split WIM, while the
230 additional parts of the split WIM must be specified in one or more
231 \fB--ref\fR="\fIGLOB\fR" options.  Since globbing is built into the \fB--ref\fR
232 option, typically only one \fB--ref\fR option is necessary.  For example, the
233 names for the split WIM parts usually go something like:
234 .RS
235 .PP
236 .nf
237 mywim.swm
238 mywim2.swm
239 mywim3.swm
240 mywim4.swm
241 mywim5.swm
242 .RE
243 .fi
244 .PP
245 To apply the first image of this split WIM to the directory "dir", run:
246 .PP
247 .RS
248 wimlib-imagex apply mywim.swm 1 dir --ref="mywim*.swm"
249 .RE
250 .PP
251 As a special case, if you are applying an image from standard input from a split
252 WIM that is also pipable (as described in \fBPIPABLE WIMS\fR), the \fB--ref\fR
253 option is unneeded; instead you must ensure that all the split WIM parts are
254 concatenated together on standard input.  They can be provided in any order,
255 with the exception of the first part, which must be first.
257 Since wimlib v1.5.0, \fBwimlib-imagex apply\fR supports applying a WIM from a
258 nonseekable file, such as a pipe, provided that the WIM was captured with
259 \fB--pipable\fR (see \fBwimlib-imagex capture\fR(1)).  To use standard input as
260 the WIM, specify "-" as \fIWIMFILE\fR.  A useful use of this ability is to apply
261 an image from a WIM while streaming it from a server.  For example, to apply the
262 first image from a WIM file available on a HTTP server to an NTFS volume on
263 /dev/sda1, run something like:
264 .PP
265 .RS
266 wget -O - http://myserver/mywim.wim | wimapply - 1 /dev/sda1
267 .RE
268 .PP
269 (The above also used the \fBwimapply\fR abbreviation for \fBwimlib-imagex
270 apply\fR.) Note: WIM files are \fInot\fR pipable by default; you have to
271 explicitly capture them with \fB--pipable\fR, and they are \fInot\fR compatible
272 with Microsoft's software.  See \fBwimlib-imagex capture\fR(1) for more
273 information.
274 .PP
275 It is possible to apply an image from a pipable WIM split into multiple parts;
276 see \fBSPLIT WIMS\fR.
278 .TP 6
279 \fB--check\fR
280 When reading \fIWIMFILE\fR, verify its integrity if the integrity table is
281 present.
282 .TP
283 \fB--ref\fR="\fIGLOB\fR"
284 File glob of additional WIMs or split WIM parts to reference resources from.
285 See \fBSPLIT_WIMS\fR.  This option can be specified multiple times.  Note:
286 \fIGLOB\fR is listed in quotes because it is interpreted by
287 \fBwimlib-imagex\fR and may need to be quoted to protect against shell
288 expansion.
289 .TP
290 \fB--rpfix\fR, \fB--norpfix\fR
291 Set whether to fix targets of absolute symbolic links (reparse points in Windows
292 terminology) or not.  When enabled (\fB--rpfix\fR), extracted absolute symbolic
293 links that are marked in the WIM image as being fixed are assumed to have
294 absolute targets relative to the image root, and therefore \fBwimlib-imagex
295 apply\fR prepends the absolute path to the extraction target directory to their
296 targets.  The intention is that you can apply an image containing absolute
297 symbolic links and still have them be valid after it has been applied to any
298 location.
299 .IP ""
300 The default behavior is \fB--rpfix\fR if any images in \fIWIMFILE\fR have been
301 captured with reparse-point fixups done.  Otherwise, it is \fB--norpfix\fR.
302 .IP ""
303 Reparse point fixups are never done in the NTFS volume extraction mode on
304 UNIX-like systems.
305 .TP
306 \fB--unix-data\fR
307 (UNIX-like systems only)  Restore UNIX owners, groups, modes, and device IDs
308 (major and minor numbers) that were captured by \fBwimlib-imagex capture\fR with
309 the \fB--unix-data\fR option.  Since wimlib v1.7.0, you can backup and restore
310 not only the standard UNIX file permission information, but also character
311 device nodes, block device nodes, named pipes (FIFOs), and UNIX domain sockets.
312 .TP
313 \fB--no-acls\fR
314 Do not restore security descriptors on extracted files and directories.
315 .TP
316 \fB--strict-acls\fR
317 Fail immediately if the full security descriptor of any file or directory cannot
318 be set exactly as specified in the WIM file.  If this option is not specified,
319 when \fBwimlib-imagex\fR on Windows does not have permission to set a
320 security descriptor on an extracted file, it falls back to setting it only
321 partially (e.g. with SACL omitted), and in the worst case omits it entirely.
322 However, this should only be a problem when running \fBwimlib-imagex\fR
323 without Administrator rights.  Also, on UNIX-like systems, this flag can also be
324 combined with \fB--unix-data\fR to cause \fBwimlib-imagex\fR to fail
325 immediately if the UNIX owner, group, or mode on an extracted file cannot be set
326 for any reason.
327 .TP
328 \fB--no-attributes\fR
329 Do not restore Windows file attributes such as readonly, hidden, etc.
330 .TP
331 \fB--include-invalid-names\fR
332 Extract files and directories with invalid names by replacing characters and
333 appending a suffix rather than ignoring them.  Exactly what is considered an
334 "invalid" name is platform-dependent.
335 .IP ""
336 On POSIX-compliant systems, filenames are case-sensitive and may contain any
337 byte except '\\0' and \'/', so on a POSIX-compliant system this option will only
338 have an effect in the unlikely case that the WIM image for some reason has a
339 filename containing one of these characters.
340 .IP ""
341 On Windows, filenames are case-insensitive, cannot include the characters '/',
342 \'\\0', '\\', ':', '*', '?', '"', '<', '>', or '|', and cannot end with a space
343 or period.  Ordinarily, files in WIM images should meet these conditions as
344 well. However, it is not guaranteed, and in particular a WIM image captured with
345 \fBwimlib-imagex\fR on a POSIX-compliant system could contain such files.  By
346 default, invalid names will be ignored, and if there are multiple names
347 differing only in case, one will be chosen to extract arbitrarily; however, with
348 \fB--include-invalid-names\fR, all names will be sanitized and extracted in some
349 form.
350 .TP
351 \fB--wimboot\fR
352 Windows only: Instead of extracting the files themselves, extract "pointer
353 files" back to the WIM archive(s).  This can result in significant space savings.
354 However, it comes at several potential costs, such as not being able to delete
355 the WIM archive(s) and possibly having slower access to files.  See Microsoft's
356 documentation for "WIMBoot" for more information.
357 .IP ""
358 If it exists, the [PrepopulateList] section of the file
359 \\Windows\\System32\\WimBootCompress.ini in the WIM image will be read.  Files
360 matching any of these patterns will be extracted normally, not as WIMBoot
361 "pointer files".  This is helpful for certain files that Windows needs to read
362 early in the boot process.
363 .IP ""
364 This option only works when the program is run as an Administrator and the
365 target volume is NTFS or another filesystem that supports reparse points.
366 .IP ""
367 In addition, this option works best when running on Windows 8.1 Update 1 or
368 later, since that is the first version of Windows that contains the Windows
369 Overlay File System Filter Driver ("WOF").  If the WOF driver is detected,
370 wimlib will create the WIMBoot "pointer files" using documented ioctls provided
371 by WOF.
372 .IP ""
373 Otherwise, if the WOF driver is not detected, wimlib will create the reparse
374 points and edit the file "\\System Volume Information\\WimOverlay.dat" on the
375 target volume manually.  This is potentially subject to problems, since although
376 the code works in certain tested cases, neither of these data formats is
377 actually documented by Microsoft.  Before overwriting this file, wimlib will
378 save the previous version in "\\System Volume
379 Information\\WimOverlay.wimlib_backup", which you potentially could restore if
380 you needed to.
381 .IP ""
382 You actually can still do a \fB--wimboot\fR extraction even if the WIM image is
383 not marked as "WIMBoot-compatible".  This option causes the extracted files to
384 be set as "externally backed" by the WIM file.  Microsoft's driver which
385 implements this "external backing" functionality seemingly does not care whether
386 the image(s) in the WIM are really marked as WIMBoot-compatible.  Therefore, the
387 "WIMBoot-compatible" tag (<WIMBOOT> in the XML data) seems to be a marker for
388 intent only.  In addition, the Microsoft driver can externally back files from
389 WIM files that use XPRESS chunks of size 8192, 16384, and 32768, or LZX chunks
390 of size 32768, in addition to the default XPRESS chunks of size 4096 that are
391 created when \fBwimlib-imagex capture\fR is run with the \fB--wimboot\fR
392 option.
393 .TP
394 \fB--compact\fR=\fIFORMAT\fR
395 Windows-only: compress the extracted files using System Compression, when
396 possible.  This only works on either Windows 10 or later, or on an older Windows
397 to which Microsoft's wofadk.sys driver has been added.  Several different
398 compression formats may be used with System Compression, and one must be
399 specified as \fIFORMAT\fR.  The choices are: xpress4k, xpress8k, xpress16k, and
400 lzx.
401 .IP ""
402 Exclusions are handled in the same way as with the \fB--wimboot\fR option.
403 That is: if it exists, the [PrepopulateList] section of the file
404 \\Windows\\System32\\WimBootCompress.ini in the WIM image will be read, and
405 files matching any of the patterns in this section will not be compressed.
406 In addition, wimlib has a hardcoded list of files for which it knows, for
407 compatibility with the Windows bootloader, to override the requested compression
408 format.
410 \fIData integrity\fR:  WIM files include SHA1 message digests for file data.
411 \fBwimlib-imagex apply\fR calculates the SHA1 message digest of every file
412 it extracts and issues an error if it is not equal to the SHA1 message digest
413 provided in the WIM.  (This default behavior seems equivalent to the
414 \fB/verify\fR option of ImageX.)  Note that this is separate from the integrity
415 table of the WIM, which provides SHA1 message digests over raw chunks of the
416 entire WIM file and is checked separately if the \fB--check\fR option is
417 specified.
418 .PP
419 \fIESD files\fR: wimlib v1.6.0 and later can extract files from version 3584
420 WIMs, which usually contain LZMS-compressed solid resources and may carry the
421 \fI.esd\fR file extension rather than \fI.wim\fR.  However, \fI.esd\fR files
422 downloaded directly by the Windows 8 web downloader have encrypted segments, and
423 wimlib cannot extract such files until they are first decrypted.
424 .PP
425 \fIDirectory traversal attacks\fR:  wimlib validates filenames before extracting
426 them and is not vulnerable to directory traversal attacks.  This is in contrast
427 to Microsoft WIMGAPI/ImageX/DISM which can overwrite arbitrary files on the
428 target drive when extracting a malicious WIM file containing files named
429 \fI..\fR or containing path separators.
431 Extract the first image from the Windows PE image on the Windows (Vista or
432 later) installation media to the directory "boot":
433 .RS
434 .PP
435 wimlib-imagex apply /mnt/windows/sources/boot.wim 1 boot
436 .RE
437 .PP
438 Same as above, but using the \fBwimapply\fR abbreviation:
439 .RS
440 .PP
441 wimapply /media/windows/sources/boot.wim 1 boot
442 .RE
443 .PP
444 On Windows, apply an image of an entire volume, for example from "install.wim"
445 which can be found on the Windows (Vista or later) installation media:
446 .RS
447 .PP
448 wimlib-imagex apply install.wim 1 E:\\
449 .RE
450 .PP
451 Same as above, but running on a UNIX-like system where the corresponding
452 partition is /dev/sda2:
453 .RS
454 .PP
455 wimlib-imagex apply install.wim 1 /dev/sda2
456 .RE
457 .PP
458 Note that before running either of the above commands, an NTFS filesystem may
459 need to be created on the partition, for example with format.exe on Windows or
460 \fBmkntfs\fR(8) (part of NTFS-3g) on UNIX-like systems.  For example, you might
461 run:
462 .RS
463 .PP
464 mkntfs /dev/sda2 && wimapply install.wim 1 /dev/sda2
465 .RE
466 .PP
467 (Of course don't do that if you don't want to destroy all existing data on the
468 partition!)
469 .PP
470 An example of applying a pipable WIM from a pipe can be found in \fBPIPABLE
471 WIMS\fR, and an example of applying a split WIM can be found in \fBSPLIT
472 WIMS\fR.
474 .BR wimlib-imagex (1)
475 .BR wimlib-imagex-capture (1)
476 .BR wimlib-imagex-extract (1)
477 .BR wimlib-imagex-info (1)