Fix some typos
[wimlib] / doc / man1 / wimapply.1
1 .TH WIMAPPLY "1" "May 2019" "wimlib 1.13.1" "User Commands"
2 .SH NAME
3 wimapply \- Apply a WIM image
4 .SH SYNOPSIS
5 \fBwimapply\fR \fIWIMFILE\fR [\fIIMAGE\fR] \fITARGET\fR [\fIOPTION\fR...]
6 .SH DESCRIPTION
7 \fBwimapply\fR, or equivalently \fBwimlib-imagex apply\fR, extracts ("applies")
8 an image, or all images, from the Windows Imaging (WIM) archive \fIWIMFILE\fR.
9 .PP
10 \fIIMAGE\fR specifies the image in \fIWIMFILE\fR to extract.  It may be the
11 1-based index of an image, the name of an image, or the keyword "all" to specify
12 all images.  It may be omitted if \fIWIMFILE\fR contains only one image.  You
13 can use \fBwiminfo\fR(1) to list the images contained in \fIWIMFILE\fR.
14 .PP
15 \fITARGET\fR specifies where to extract the image(s) to.  If \fITARGET\fR is a
16 directory, then the image(s) will be extracted to that directory as per
17 \fBDIRECTORY EXTRACTION (UNIX)\fR or \fBDIRECTORY EXTRACTION (WINDOWS)\fR.  If
18 \fITARGET\fR does not exist, then a directory will be created there first.
19 Alternatively, if \fITARGET\fR specifies a UNIX block device, then the image
20 will be extracted to it as described in \fBNTFS VOLUME EXTRACTION (UNIX)\fR.
21 .PP
22 Note that \fBwimapply\fR is designed to extract, or "apply", full WIM images.
23 If you instead want to extract only certain files or directories from a WIM
24 image, use \fBwimextract\fR(1) instead.
25 .PP
26 If \fIIMAGE\fR is "all", then all images in \fIWIMFILE\fR will be extracted into
27 subdirectories of \fITARGET\fR named after the images, falling back to the image
28 index when an image has no name or an unusual name.  This is not yet supported
29 in \fBNTFS VOLUME EXTRACTION (UNIX)\fR mode.
30 .PP
31 If \fIWIMFILE\fR is "-", then the WIM is read from standard input rather than
32 from disk.  See \fBPIPABLE WIMS\fR for more information.
33 .SH DIRECTORY EXTRACTION (UNIX)
34 On UNIX-like systems, a WIM image may be extracted to a directory.  This mode
35 has the limitation that NTFS or Windows-specific metadata will not be extracted.
36 Although some concepts such as hard links, symbolic links, last access
37 timestamps, and last modification timestamps will be translated to their UNIX
38 equivalents, other metadata will be lost (with warnings given).  Notably, the
39 following types of metadata will \fInot\fR be extracted in this mode:
40 .IP \[bu] 4
41 Windows file attribute flags
42 .IP \[bu]
43 Windows security descriptors (e.g. file owners and DACLs)
44 .IP \[bu]
45 File creation timestamps
46 .IP \[bu]
47 Reparse points other than symbolic links and junction points
48 .IP \[bu]
49 Named data streams
50 .IP \[bu]
51 Short filenames (also known as 8.3 names or DOS names).
52 .IP \[bu]
53 Object IDs
54 .PP
55 These same limitations apply to \fBwimextract\fR.  As such, this mode is most
56 useful in situations where NTFS or Windows-specific metadata is unimportant,
57 e.g. when wanting to extract specific files, or when doing file archiving only
58 on UNIX-like systems, possibly in combination with \fB--unix-data\fR.  When
59 Windows-specific metadata is important, then either the \fBNTFS VOLUME
60 EXTRACTION (UNIX)\fR mode should be used, or the Windows version of wimlib
61 should be used (see \fBDIRECTORY EXTRACTION (WINDOWS)\fR).
62 .SH NTFS VOLUME EXTRACTION (UNIX)
63 On UNIX-like systems, \fITARGET\fR may also be specified as a block device (e.g.
64 /dev/sda3) containing an unmounted NTFS volume.  In this mode, \fBwimapply\fR
65 uses libntfs-3g to apply the specified WIM image to the root directory of the
66 NTFS volume.  The target volume should be empty, e.g. newly created by
67 \fBmkntfs\fR(8).  In this mode, NTFS-specific and Windows-specific data and
68 metadata will be extracted, including the following:
69 .IP \[bu] 4
70 All data streams of all files except encrypted files, including the unnamed data
71 stream as well as all named data streams.
72 .IP \[bu]
73 Reparse points, including symbolic links, junction points, and other reparse
74 points.
75 .IP \[bu]
76 File and directory creation, access, and modification timestamps, using the
77 native NTFS resolution of 100 nanoseconds.
78 .IP \[bu]
79 Windows security descriptors, including all components (owner, group, DACL, and
80 SACL).
81 .IP \[bu]
82 Windows file attribute flags
83 .IP \[bu]
84 All names of all files, including names in the Win32 namespace, DOS namespace,
85 Win32+DOS namespace, and POSIX namespace.  This includes hard links.
86 .IP \[bu]
87 Object IDs.
88 .PP
89 However, encrypted files will not be extracted.
90 .PP
91 Restoring extended attributes (EAs) is also not yet supported in this mode.
92 .PP
93 Regardless, since almost all information from the WIM image is restored in this
94 mode, it is possible (and fully supported) to restore an image of an actual
95 Windows installation using \fBwimapply\fR on a UNIX-like system as an
96 alternative to using \fBwimapply\fR or DISM on Windows.  In the \fBEXAMPLES\fR
97 section below, there is an example of applying an image from an "install.wim"
98 file as may be found in the Windows installation media.
99 .PP
100 Note that to actually boot Windows (Vista or later) from an applied
101 "install.wim" image, you also need to mark the partition as "bootable" and set
102 up various boot files, such as \\BOOTMGR and \\BOOT\\BCD.  The latter task is
103 most easily accomplished by running bcdboot.exe from a live Windows system such
104 as Windows PE, but there are other options as well.
105 .PP
106 Finally, note that this mode uses libntfs-3g directly, without going through the
107 \fBntfs-3g\fR(8) driver.  Hence, there is no special support for applying a WIM
108 image to a directory on which an NTFS filesystem has been mounted using
109 \fBntfs-3g\fR(8); you have to unmount it first.  There is also no support for
110 applying a WIM image to some subdirectory of the NTFS volume; you can only apply
111 to the root directory.
112 .SH DIRECTORY EXTRACTION (WINDOWS)
113 On Windows, \fBwimapply\fR (and \fBwimextract\fR) natively support NTFS and
114 Windows-specific metadata.  For best results, the target directory should be
115 located on an NTFS volume and the program should be run with Administrator
116 privileges; however, non-NTFS filesystems and running without Administrator
117 privileges are also supported, subject to limitations.
118 .PP
119 On Windows, \fBwimapply\fR tries to extract as much data and metadata as
120 possible, including:
121 .IP \[bu] 4
122 All data streams of all files.  This includes the default file contents, as well
123 as named data streams if supported by the target volume.
124 .IP \[bu]
125 Reparse points, including symbolic links, junction points, and other reparse
126 points, if supported by the target volume.  Restoring symlinks requires
127 Administrator privileges.  Also see \fB--rpfix\fR and \fB--norpfix\fR for
128 details on how absolute symbolic links and junctions are extracted.
129 .IP \[bu]
130 File and directory creation, access, and modification timestamps, to the highest
131 resolution supported by the target volume.
132 .IP \[bu]
133 Security descriptors, if supported by the filesystem and \fB--no-acls\fR is not
134 specified.  Note that this, in general, requires Administrator privileges, and
135 may be only partially successful if the program is run without Administrator
136 privileges (see \fB--strict-acls\fR).
137 .IP \[bu]
138 File attribute flags, including hidden, compressed, encrypted, sparse, etc, when
139 supported by the filesystem.
140 .IP \[bu]
141 Short filenames (also known as 8.3 names or DOS names).
142 .IP \[bu]
143 Hard links, if supported by the target filesystem.
144 .IP \[bu]
145 Object IDs, if supported by the target filesystem.
146 .IP \[bu]
147 Extended attributes (EAs), if supported by the target filesystem.
148 .PP
149 Additional notes about extracting files on Windows:
150 .IP \[bu] 4
151 \fBwimapply\fR will issue warnings if unable to extract the exact metadata and
152 data of the WIM image due to limitations of the target filesystem.
153 .IP \[bu]
154 Since encrypted files (with FILE_ATTRIBUTE_ENCRYPTED) are not stored in
155 plaintext in the WIM image, \fBwimapply\fR cannot restore encrypted files to
156 filesystems not supporting encryption.  Therefore, on such filesystems,
157 encrypted files will not be extracted.  Furthermore, even if encrypted files are
158 restored to a filesystem that supports encryption, they will only be decryptable
159 if the decryption key is available.
160 .IP \[bu]
161 Files with names that cannot be represented on Windows will not
162 be extracted by default; see \fB--include-invalid-names\fR.
163 .IP \[bu]
164 Files with full paths over 260 characters (the so-called MAX_PATH) will be
165 extracted, but beware that such files will be inaccessible to most Windows
166 software and may not be able to be deleted easily.
167 .IP \[bu]
168 On Windows, unless the \fB--no-acls\fR option is specified, wimlib will attempt
169 to restore files' security descriptors exactly as they are provided in the WIM
170 image.  Beware that typical Windows installations contain files whose security
171 descriptors do not allow the Administrator to delete them.  Therefore, such
172 files will not be able to be deleted, or in some cases even read, after
173 extracting, unless processed with a specialized program that knows to acquire
174 the SE_RESTORE_NAME and/or SE_BACKUP_NAME privileges which allow overriding
175 access control lists.  This is not a bug in wimlib, which works as designed to
176 correctly restore the data that was archived, but rather a problem with the
177 access rights Windows uses on certain files.  But if you just want the file data
178 and don't care about security descriptors, use \fB--no-acls\fR to skip restoring
179 all security descriptors.
180 .IP \[bu]
181 A similar caveat to the above applies to file attributes such as Readonly,
182 Hidden, and System.  By design, on Windows wimlib will restore such file
183 attributes; therefore, extracted files may have those attributes.  If this is
184 not what you want, use the \fB--no-attributes\fR option.
185 .SH SPLIT WIMS
186 You may use \fBwimapply\fR to apply images from a split WIM, or \fBwimextract\fR
187 to extract files from a split WIM.  The \fIWIMFILE\fR argument must specify the
188 first part of the split WIM, while the additional parts of the split WIM must be
189 specified in one or more \fB--ref\fR="\fIGLOB\fR" options.  Since globbing is
190 built into the \fB--ref\fR option, typically only one \fB--ref\fR option is
191 necessary.  For example, the names for the split WIM parts usually go something
192 like:
193 .RS
194 .PP
195 .nf
196 mywim.swm
197 mywim2.swm
198 mywim3.swm
199 mywim4.swm
200 mywim5.swm
201 .RE
202 .fi
203 .PP
204 To apply the first image of this split WIM to the directory "dir", run:
205 .PP
206 .RS
207 wimapply mywim.swm 1 dir --ref="mywim*.swm"
208 .RE
209 .PP
210 .SH PIPABLE WIMS
211 \fBwimapply\fR also supports applying a WIM from a nonseekable file, such as a
212 pipe, provided that the WIM was captured in the wimlib-specific pipable format
213 using \fB--pipable\fR (see \fBwimcapture\fR(1)).  To use standard input as the
214 WIM, specify "-" as \fIWIMFILE\fR.  A possible use of this feature is to apply a
215 WIM image being streamed from the network.  For example, to apply the first
216 image from a WIM file available on a HTTP server to an NTFS volume on /dev/sda1,
217 run something like:
218 .PP
219 .RS
220 wget -O - http://myserver/mywim.wim | wimapply - 1 /dev/sda1
221 .RE
222 .PP
223 Pipable WIMs may also be split into multiple parts, just like normal WIMs.  To
224 apply a split pipable WIM from a pipe, the parts must be concatenated and all
225 written to the pipe.  The first part must be sent first, but the remaining parts
226 may be sent in any order.
227 .SH OPTIONS
228 .TP 6
229 \fB--check\fR
230 Before applying the image, verify the integrity of \fIWIMFILE\fR if it has extra
231 integrity information.
232 .TP
233 \fB--ref\fR="\fIGLOB\fR"
234 File glob of additional WIMs or split WIM parts to reference resources from.
235 See \fBSPLIT_WIMS\fR.  This option can be specified multiple times.  Note:
236 \fIGLOB\fR is listed in quotes because it is interpreted by \fBwimapply\fR and
237 may need to be quoted to protect against shell expansion.
238 .TP
239 \fB--rpfix\fR, \fB--norpfix\fR
240 Set whether to fix targets of absolute symbolic links (reparse points in Windows
241 terminology) or not.  When enabled (\fB--rpfix\fR), extracted absolute symbolic
242 links that are marked in the WIM image as being fixed are assumed to have
243 absolute targets relative to the image root, and therefore \fBwimapply\fR
244 prepends the absolute path to the extraction target directory to their targets.
245 The intention is that you can apply an image containing absolute symbolic links
246 and still have them be valid after it has been applied to any location.
247 .IP ""
248 The default behavior is \fB--rpfix\fR if any images in \fIWIMFILE\fR have been
249 captured with reparse-point fixups done.  Otherwise, it is \fB--norpfix\fR.
250 .IP ""
251 Reparse point fixups are never done in the NTFS volume extraction mode on
252 UNIX-like systems.
253 .TP
254 \fB--unix-data\fR
255 (UNIX-like systems only)  Restore UNIX-specific metadata and special files that
256 were captured by \fBwimcapture\fR with the \fB--unix-data\fR option.  This
257 includes: standard UNIX file permissions (owner, group, and mode); device nodes,
258 named pipes, and sockets; and extended attributes (Linux-only).
259 .TP
260 \fB--no-acls\fR
261 Do not restore security descriptors on extracted files and directories.
262 .TP
263 \fB--strict-acls\fR
264 Fail immediately if the full security descriptor of any file or directory cannot
265 be set exactly as specified in the WIM file.  If this option is not specified,
266 when \fBwimapply\fR on Windows does not have permission to set a security
267 descriptor on an extracted file, it falls back to setting it only partially
268 (e.g. with SACL omitted), and in the worst case omits it entirely.  However,
269 this should only be a problem when running \fBwimapply\fR without Administrator
270 rights.  Also, on UNIX-like systems, this flag can also be combined with
271 \fB--unix-data\fR to cause \fBwimapply\fR to issue an error if UNIX permissions
272 are unable to be applied to an extracted file.
273 .TP
274 \fB--no-attributes\fR
275 Do not restore Windows file attributes such as readonly, hidden, etc.
276 .TP
277 \fB--include-invalid-names\fR
278 Extract files and directories with invalid names by replacing characters and
279 appending a suffix rather than ignoring them.  Exactly what is considered an
280 "invalid" name is platform-dependent.
281 .IP ""
282 On POSIX-compliant systems, filenames are case-sensitive and may contain any
283 byte except '\\0' and \'/', so on a POSIX-compliant system this option will only
284 have an effect in the unlikely case that the WIM image for some reason has a
285 filename containing one of these characters.
286 .IP ""
287 On Windows, filenames are case-insensitive(*), cannot include control
288 characters, and cannot include the characters '/', \'\\0', '\\', ':', '*', '?',
289 \'"', '<', '>', or '|'.  Ordinarily, files in WIM images should meet these
290 conditions as well. However, it is not guaranteed, and in particular a WIM image
291 captured with \fBwimcapture\fR on a POSIX-compliant system could contain such
292 files.  By default, invalid names will be ignored, and if there are multiple
293 names differing only in case, one will be chosen to extract arbitrarily;
294 however, with \fB--include-invalid-names\fR, all names will be sanitized and
295 extracted in some form.
296 .IP ""
297 (*) Unless the ObCaseInsensitive setting has been set to 0 in the Windows
298 registry, in which case certain software, including the Windows version of
299 \fBwimapply\fR, will honor case-sensitive filenames on NTFS and other compatible
300 filesystems.
301 .TP
302 \fB--wimboot\fR
303 Windows only: Instead of extracting the files themselves, extract "pointer
304 files" back to the WIM archive(s).  This can result in significant space savings.
305 However, it comes at several potential costs, such as not being able to delete
306 the WIM archive(s) and possibly having slower access to files.  See Microsoft's
307 documentation for "WIMBoot" for more information.
308 .IP ""
309 If it exists, the [PrepopulateList] section of the file
310 \\Windows\\System32\\WimBootCompress.ini in the WIM image will be read.  Files
311 matching any of these patterns will be extracted normally, not as WIMBoot
312 "pointer files".  This is helpful for certain files that Windows needs to read
313 early in the boot process.
314 .IP ""
315 This option only works when the program is run as an Administrator and the
316 target volume is NTFS or another filesystem that supports reparse points.
317 .IP ""
318 In addition, this option works best when running on Windows 8.1 Update 1 or
319 later, since that is the first version of Windows that contains the Windows
320 Overlay Filesystem filter driver ("WOF").  If the WOF driver is detected, wimlib
321 will create the WIMBoot "pointer files" using documented ioctls provided by WOF.
322 .IP ""
323 Otherwise, if the WOF driver is not detected, wimlib will create the reparse
324 points and edit the file "\\System Volume Information\\WimOverlay.dat" on the
325 target volume manually.  This is potentially subject to problems, since although
326 the code works in certain tested cases, neither of these data formats is
327 actually documented by Microsoft.  Before overwriting this file, wimlib will
328 save the previous version in "\\System Volume
329 Information\\WimOverlay.wimlib_backup", which you potentially could restore if
330 you needed to.
331 .IP ""
332 You actually can still do a \fB--wimboot\fR extraction even if the WIM image is
333 not marked as "WIMBoot-compatible".  This option causes the extracted files to
334 be set as "externally backed" by the WIM file.  Microsoft's driver which
335 implements this "external backing" functionality seemingly does not care whether
336 the image(s) in the WIM are really marked as WIMBoot-compatible.  Therefore, the
337 "WIMBoot-compatible" tag (<WIMBOOT> in the XML data) seems to be a marker for
338 intent only.  In addition, the Microsoft driver can externally back files from
339 WIM files that use XPRESS chunks of size 8192, 16384, and 32768, or LZX chunks
340 of size 32768, in addition to the default XPRESS chunks of size 4096 that are
341 created when \fBwimcapture\fR is run with the \fB--wimboot\fR option.
342 .TP
343 \fB--compact\fR=\fIFORMAT\fR
344 Windows-only: compress the extracted files using System Compression, when
345 possible.  This only works on either Windows 10 or later, or on an older Windows
346 to which Microsoft's wofadk.sys driver has been added.  Several different
347 compression formats may be used with System Compression, and one must be
348 specified as \fIFORMAT\fR.  The choices are: xpress4k, xpress8k, xpress16k, and
349 lzx.
350 .IP ""
351 Exclusions are handled in the same way as with the \fB--wimboot\fR option.
352 That is: if it exists, the [PrepopulateList] section of the file
353 \\Windows\\System32\\WimBootCompress.ini in the WIM image will be read, and
354 files matching any of the patterns in this section will not be compressed.
355 In addition, wimlib has a hardcoded list of files for which it knows, for
356 compatibility with the Windows bootloader, to override the requested compression
357 format.
358 .SH NOTES
359 \fIData integrity\fR: WIM files include checksums of file data.  To detect
360 accidental (non-malicious) data corruption, wimlib calculates the checksum of
361 every file it extracts and issues an error if it does not have the expected
362 value.  (This default behavior seems equivalent to the \fB/verify\fR option of
363 ImageX.)  In addition, a WIM file can include an integrity table (extra
364 checksums) over the raw data of the entire WIM file.  For performance reasons
365 wimlib does not check the integrity table by default, but the \fB--check\fR
366 option can be passed to make it do so.
367 .PP
368 \fIESD files\fR: wimlib can extract files from solid-compressed WIMs, or "ESD"
369 (.esd) files, just like from normal WIM (.wim) files.  However, Microsoft
370 sometimes distributes ESD files with encrypted segments; wimlib cannot extract
371 such files until they are first decrypted.
372 .PP
373 \fISecurity\fR: wimlib has been carefully written to validate all input and is
374 believed to be secure against some types of attacks which often plague other
375 file archiving programs, e.g. directory traversal attacks (which, as it happens,
376 Microsoft's WIM software is vulnerable to).  Important parts of wimlib, e.g. the
377 decompressors, have also been fuzz tested.  However, wimlib is not currently
378 designed to protect against some types of denial-of-service (DOS) attacks, e.g.
379 memory exhaustion or "zip bombs".
380 .SH EXAMPLES
381 Extract the first image from the Windows PE WIM on the Windows installation
382 media to the directory "boot":
383 .RS
384 .PP
385 wimapply /mnt/windows/sources/boot.wim 1 boot
386 .RE
387 .PP
388 On Windows, apply an image of an entire volume, for example from "install.wim"
389 which can be found on the Windows installation media:
390 .RS
391 .PP
392 wimapply install.wim 1 E:\\
393 .RE
394 .PP
395 Same as above, but running on a UNIX-like system where the corresponding
396 partition is /dev/sda2:
397 .RS
398 .PP
399 wimapply install.wim 1 /dev/sda2
400 .RE
401 .PP
402 Note that before running either of the above commands, an NTFS filesystem may
403 need to be created on the partition, for example with format.exe on Windows or
404 \fBmkntfs\fR(8) on UNIX-like systems.  For example, on UNIX you might run:
405 .RS
406 .PP
407 mkntfs /dev/sda2 && wimapply install.wim 1 /dev/sda2
408 .RE
409 .PP
410 (Of course don't do that if you don't want to destroy all existing data on the
411 partition!)
412 .PP
413 See \fBSPLIT WIMS\fR and \fBPIPABLE WIMS\fR for examples of applying split and
414 pipable WIMs, respectively.
415 .SH SEE ALSO
416 .BR wimlib-imagex (1)
417 .BR wimcapture (1)
418 .BR wimextract (1)
419 .BR wiminfo (1)