Initial support for resuming extraction from split pipable WIMs
[wimlib] / doc / imagex-apply.1.in
1 .TH WIMLIB-IMAGEX "1" "August 2013" "@IMAGEX_PROGNAME@ @VERSION@" "User Commands"
2 .SH NAME
3 @IMAGEX_PROGNAME@-apply \- Extract one image, or all images, from a WIM archive
4 .SH SYNOPSIS
5 \fB@IMAGEX_PROGNAME@ apply\fR \fIWIMFILE\fR [\fIIMAGE\fR] \fITARGET\fR [\fIOPTION\fR...]
6 .SH DESCRIPTION
7 \fB@IMAGEX_PROGNAME@ 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 \fB@IMAGEX_PROGNAME@ extract\fR or
14 \fB@IMAGEX_PROGNAME@ mount\fR instead.  (\fB@IMAGEX_PROGNAME@ 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 \fB@IMAGEX_PROGNAME@ 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
26 \fBDIRECTORY EXTRACTION (UNIX)\fR or \fBDIRECTORY EXTRACTION (WINDOWS)\fR).
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 \fB@IMAGEX_PROGNAME@ apply\fR supports applying images from stand-alone WIMs as
45 well as split WIMs.  See \fBSPLIT WIMS\fR.
46 .SH DIRECTORY EXTRACTION (UNIX)
47 This section documents how \fB@IMAGEX_PROGNAME@ apply\fR (and also
48 \fB@IMAGEX_PROGNAME@ extract\fR) extract a WIM image (or a possibly a subset
49 thereof, in the case of \fB@IMAGEX_PROGNAME@ extract\fR) to a directory on
50 UNIX-like systems.  See \fBDIRECTORY EXTRACTION (WINDOWS)\fR for the
51 corresponding documentation for Windows.
52
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 \fB@IMAGEX_PROGNAME@\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 \fB@IMAGEX_PROGNAME@\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.
78 .SH NTFS VOLUME EXTRACTION (UNIX)
79 This section documents how \fB@IMAGEX_PROGNAME@ apply\fR extracts a WIM image
80 directly to an NTFS volume image on UNIX-like systems.  See \fBDIRECTORY EXTRACTION
81 (WINDOWS)\fR for the corresponding documentation for Windows.
82 .PP
83 As mentioned, \fB@IMAGEX_PROGNAME@\fR running on a UNIX-like system can apply a
84 WIM image directly to an NTFS volume by specifying \fITARGET\fR as a regular file
85 or block device containing an NTFS filesystem.  The NTFS filesystem need not be
86 empty, although it's expected that it be empty for the intended use cases.  A
87 new NTFS filesystem can be created using the \fBmkntfs\fR(8) command provided
88 with \fBntfs-3g\fR.
89 .PP
90 In this NTFS volume extraction mode, the WIM image is extracted to the root of
91 the NTFS volume in a way preserves almost all information contained in the WIM
92 image.  It therefore does not suffer from the limitations described in
93 \fBDIRECTORY EXTRACTION (UNIX)\fR.  This support relies on libntfs-3g to write
94 to the NTFS volume and handle NTFS-specific and Windows-specific data.
95 .PP
96 Please note that this NTFS volume extraction mode is \fInot\fR entered if
97 \fITARGET\fR is a directory, even if an NTFS filesystem is mounted on
98 \fITARGET\fR.  You must specify the NTFS volume itself (and it must be
99 unmounted, and you must have permission to write to it).
100 .PP
101 This NTFS volume extraction mode attempts to extract as much information as
102 possible, including:
103 .IP \[bu] 4
104 All data streams of all files, including the unnamed data stream as well as all
105 named data streams.
106 .IP \[bu]
107 Reparse points, including symbolic links, junction points, and other reparse
108 points.
109 .IP \[bu]
110 File and directory creation, access, and modification timestamps, using the
111 native NTFS resolution of 100 nanoseconds.
112 .IP \[bu]
113 Windows security descriptors, including all components (owner, group, DACL, and
114 SACL).
115 .IP \[bu]
116 DOS/Windows file attribute flags.
117 .IP \[bu]
118 All names of all files, including names in the Win32 namespace, DOS namespace,
119 Win32+DOS namespace, and POSIX namespace.  This includes hard links.
120 .PP
121 Currently, the only known limitation (in terms of exactly extracting all data
122 and metadata) is that the extraction of encrypted files is not expected to work
123 properly.
124 .PP
125 Since all (or almost all) information from the WIM image is restored in this
126 mode, it is possible to restore an image of an actual Windows installation using
127 \fB@IMAGEX_PROGNAME@\fR on UNIX-like systems in addition to with
128 \fB@IMAGEX_PROGNAME@\fR on Windows.  In the examples at the end of this manual
129 page, there is an example of applying an image from the "install.wim" file
130 contained in the installation media for Windows Vista, Windows 7, and Windows 8
131 in the "sources" directory.
132 .PP
133 But in order to actually boot Windows from an applied image, you must understand
134 the boot process of Windows versions Vista and later.  Basically, it is the
135 following:
136 .nr step 1 1
137 .IP \n[step]. 3
138 The Master Boot Record loads the Volume Boot Record (also called the Boot
139 Sector) of the active partition, which is on an NTFS filesystem.  This partition
140 is called the "system partition".
141 .IP \n+[step].
142 The "bootmgr" program on the "system partition" is loaded (\\BOOTMGR).
143 .IP \n+[step].
144 bootmgr loads the Boot Configuration Data (\\Boot\\BCD) from the "system
145 partition".
146 .IP \n+[step].
147 Based on the information contained in the Boot Configuration Data, a loader for
148 the Windows kernel is executed from the "Boot" partition, which is where Windows
149 is installed.
150 .PP
151 So let's say you applied an image from an existing "install.wim" as in the
152 example, or you've applied a custom Windows image that you've created using the
153 \fB@IMAGEX_PROGNAME@ capture\fR (1) command.  You've just applied the "Boot" partition, or
154 the main Windows partition, but there is no "System" partition yet (i.e.  no
155 \\BOOTMGR and no \\Boot\\BCD).
156 .PP
157 A "System" partition can be created created by running the "bcdboot.exe" program
158 from within Windows or Windows PE.  Alternatively, you can capture a separate
159 WIM image containing the "System" partition.  Or, the "System" partition may the
160 same as the "Boot" partition, so the two "partitions" may be combined in one WIM
161 image.  However, as the \\Boot\\BCD file contains the Windows bootloader
162 configuration, a WIM containing it can only be used on systems where you are
163 setting up the same bootloader configuration, including the same partition
164 layout.
165 .PP
166 Besides setting up the files on the "System" partition, don't forget to set the
167 bootable flag on it, and have a master boot record that loads the bootable
168 partition (Windows' MBR does, and SYSLINUX provides an equivalent MBR).
169 .SH DIRECTORY EXTRACTION (WINDOWS)
170 On Windows, \fB@IMAGEX_PROGNAME@ apply\fR and \fB@IMAGEX_PROGNAME@ extract\fR
171 natively support Windows-specific and NTFS-specific data.  For best results, the
172 target directory should be located on an NTFS volume and \fB@IMAGEX_PROGNAME@\fR
173 should be run with Administrator privileges; however, non-NTFS filesystems and
174 running without Administrator privileges are also supported.
175 .PP
176 On Windows, \fB@IMAGEX_PROGNAME@ apply\fR and \fB@IMAGEX_PROGNAME@ extract\fR
177 try to extract as much data and metadata as possible, including:
178 .IP \[bu] 4
179 All data streams of all files.  This includes the default file contents, as well
180 as named data streams if supported by the target volume.
181 .IP \[bu]
182 Reparse points, including symbolic links, junction points, and other reparse
183 points, if supported by the target volume.  (Note: see \fB--rpfix\fR and
184 \fB--norpfix\fR for documentation on exactly how absolute symbolic links and
185 junctions are extracted.)  However, as per the default security settings of
186 Windows, it is impossible to create a symbolic link or junction point without
187 Administrator privileges; therefore, you must run \fB@IMAGEX_PROGNAME@\fR as the
188 Administrator if you wish to fully restore an image containing symbolic links
189 and/or junction points.  (Otherwise, merely a warning will be issued when a
190 symbolic link or junction point cannot be extracted due to insufficient
191 privileges.)
192 .IP \[bu]
193 File and directory creation, access, and modification timestamps, to the highest
194 resolution supported by the target volume.
195 .IP \[bu]
196 Security descriptors, if supported by the filesystem and \fB--no-acls\fR is not
197 specified.  Furthermore, unless \fB--strict-acls\fR is specified, the security
198 descriptors for individual files or directories may be omitted or only partially
199 set if the user does not have permission to set them, which can be a problem if
200 \fB@IMAGEX_PROGNAME@\fR is run as a non-Administrator.
201 .IP \[bu]
202 File attributes, including hidden, sparse, compressed, encrypted, etc, when
203 supported by the filesystem.
204 .IP \[bu]
205 DOS names (8.3) names of files; however, the failure to set them is not
206 considered an error condition.
207 .IP \[bu]
208 Hard links, if supported by the filesystem.
209 .PP
210 Additional notes about extracting files on Windows:
211 .IP \[bu] 4
212 \fB@IMAGEX_PROGNAME@\fR will issue a warning when it is unable to extract the
213 exact metadata and data of the WIM image, for example due to features mentioned
214 above not being supported by the target filesystem.
215 .IP \[bu]
216 Since encrypted files (with FILE_ATTRIBUTE_ENCRYPTED) are not stored in
217 plaintext in the WIM image, \fB@IMAGEX_PROGNAME@\fR cannot restore encrypted
218 files to filesystems not supporting encryption.  (The current behavior is to
219 just extract the encrypted data anyway.)  Furthermore, even if encrypted files
220 are restored to a filesystem that supports encryption, they will only be
221 decryptable if the decryption key is available.
222 .IP \[bu]
223 Files with names that cannot be represented on Windows will not
224 be extracted by default; see \fB--include-invalid-names\fR.
225 .IP \[bu]
226 Files with full paths over 260 characters (MAX_PATH) are extracted by using the
227 \\\\?\\-prefixed path hack.  But beware that such files will be inaccessible to
228 most Windows software and may not be able to be deleted easily.
229 .SH SPLIT WIMS
230 You may use \fB@IMAGEX_PROGNAME@ apply\fR to apply images from a split WIM.  The
231 \fIWIMFILE\fR argument is used to specify the first part of the split WIM, and
232 the \fB--refs\fR="\fIGLOB\fR" option is used to provide a shell-style file glob
233 that specifies the additional parts of the split WIM.  \fIGLOB\fR is expected to
234 be a single string on the command line, so \fIGLOB\fR must be quoted so that it
235 is protected against shell expansion.  \fIGLOB\fR must expand to all parts of
236 the split WIM, except optionally the first part which may either omitted or
237 included in the glob (but the first part MUST be specified as \fIWIMFILE\fR as
238 well).
239 .PP
240 Here's an example.  The names for the split WIMs usually go something like:
241 .RS
242 .PP
243 .nf
244 mywim.swm
245 mywim2.swm
246 mywim3.swm
247 mywim4.swm
248 mywim5.swm
249 .RE
250 .fi
251 .PP
252 To apply the first image of this split WIM to the directory "dir", run:
253 .PP
254 .RS
255 @IMAGEX_PROGNAME@ apply mywim.swm 1 dir --ref="mywim*.swm"
256 .RE
257 .PP
258 As a special case, if you are applying an image from standard input from a split
259 WIM that is also pipable (as described in \fBPIPABLE WIMS\fR), the \fB--ref\fR
260 option is unneeded; instead you must ensure that all the split WIM parts are
261 concatenated together on standard input.  They can be provided in any order,
262 with the exception of the first part, which must be first.
263 .SH PIPABLE WIMS
264 As of wimlib 1.5.0, \fB@IMAGEX_PROGNAME@ apply\fR supports applying a WIM from a
265 nonseekable file, such as a pipe, provided that the WIM was captured with
266 \fB--pipable\fR (see \fB@IMAGEX_PROGNAME@ capture\fR(1)).  To use standard input
267 as the WIM, specify "-" as \fIWIMFILE\fR.  A useful use of this ability is to
268 apply an image from a WIM while streaming it from a webserver; for example, to
269 apply the first image from a WIM file to an NTFS volume on /dev/sda1:
270 .PP
271 .RS
272 wget -O - http://myserver/mywim.wim | wimapply - 1 /dev/sda1
273 .RE
274 .PP
275 (The above also used the \fBwimapply\fR abbreviation for \fB@IMAGEX_PROGNAME@
276 apply\fR.) Note: WIM files are \fInot\fR pipable by default; you have to
277 explicitly capture them with \fB--pipable\fR, and they are \fInot\fR compatible
278 with Microsoft's software.  See \fB@IMAGEX_PROGNAME@ capture\fR(1) for more
279 information.
280 .PP
281 It is possible to apply an image from a pipable WIM split into multiple parts;
282 see \fBSPLIT WIMS\fR.
283 .SH OPTIONS
284 .TP 6
285 \fB--check\fR
286 When reading \fIWIMFILE\fR, verify its integrity if the integrity table is
287 present.
288 .TP
289 \fB--ref\fR="\fIGLOB\fR"
290 File glob of additional split WIM parts that are part of the split WIM being
291 applied.  See \fBSPLIT_WIMS\fR.
292 .TP
293 \fB--rpfix\fR, \fB--norpfix\fR
294 Set whether to fix targets of absolute symbolic links (reparse points in Windows
295 terminology) or not.  When enabled (\fB--rpfix\fR), extracted absolute symbolic
296 links that are marked in the WIM image as being fixed are assumed to have
297 absolute targets relative to the image root, and therefore have the actual root
298 of extraction prepended to their targets.  The intention is that you can apply
299 an image containing absolute symbolic links and still have them be valid after
300 it has been applied to any location.
301 .IP ""
302 The default behavior is \fB--rpfix\fR if any images in \fIWIMFILE\fR have been
303 captured with reparse-point fixups done.  Otherwise, it is \fB--norpfix\fR.
304 .IP ""
305 Reparse point fixups are never done in the NTFS volume extraction mode on
306 UNIX-like systems.
307 .IP ""
308 \fB--verbose\fR
309 Print the path to of each file or directory within the WIM image as it is
310 extracted.
311 .TP
312 \fB--hardlink\fR
313 When extracting a file from the WIM that is identical to a file that has already
314 extracted, create a hard link rather than creating a separate file.  This option
315 causes all identical files to be hard-linked, overriding the hard link groups
316 that are specified in the WIM image(s).  In the case of extracting all images
317 from the WIM, files may be hard-linked even if they are in different WIM images.
318 .IP ""
319 However, hard-linked extraction mode does have some additional quirks.  Named
320 data streams will not be extracted, and files can be hard linked even if their
321 metadata is not fully consistent.
322 .TP
323 \fB--symlink\fR
324 This option is similar to \fB--hardlink\fR, except symbolic links are created
325 instead.
326 .TP
327 \fB--unix-data\fR
328 (UNIX-like systems only)  By default, in the directory extraction mode on UNIX,
329 \fB@IMAGEX_PROGNAME@ apply\fR will ignore both Windows-style security
330 descriptors and UNIX-specific file owners, groups, and modes set when using
331 \fB@IMAGEX_PROGNAME@ capture\fR with the \fB--unix-data\fR flag.  By passing
332 \fB--unix-data\fR to \fB@IMAGEX_PROGNAME@ apply\fR instead, this causes this
333 UNIX-specific data to be restored when available.  However, by default, if
334 \fB@IMAGEX_PROGNAME@\fR does not have permission to set the UNIX owner, group or
335 file mode on an extracted file, a warning will be printed and it will not be
336 considered an error condition; use \fB--strict-acls\fR to get stricter behavior.
337 .TP
338 \fB--no-acls\fR
339 Do not restore security descriptors on extracted files and directories.
340 .TP
341 \fB--strict-acls\fR
342 Fail immediately if the full security descriptor of any file or directory cannot
343 be set exactly as specified in the WIM file.  On Windows, the default behavior
344 without this option is to fall back to setting a security descriptor with the
345 SACL omitted, then only the default inherited security descriptor, if
346 \fB@IMAGEX_PROGNAME@\fR does not have permission to set the desired one.  Also,
347 on UNIX-like systems, this flag can also be combined with \fB--unix-data\fR to
348 cause \fB@IMAGEX_PROGNAME@\fR to fail immediately if the UNIX owner, group, or
349 mode on an extracted file cannot be set for any reason.
350 .TP
351 \fB--include-invalid-names\fR
352 Extract files and directories with invalid names by replacing characters and
353 appending a suffix rather than ignoring them.  The meaning of this is
354 platform-dependent.
355 .IP "" 6
356 On POSIX-compliant systems, filenames are case-sensitive and may contain any
357 byte except '\\0' and \'/', so on a POSIX-compliant system this option will only
358 have an effect in the unlikely case that the WIM image for some reason has a
359 filename containing one of these characters.
360 .IP "" 6
361 On Windows, filenames are case-insensitive, cannot include the characters '/',
362 \'\\0', '\\', ':', '*', '?', '"', '<', '>', or '|', and cannot end with a space
363 or period.  Ordinarily, files in WIM images should meet these conditions as
364 well. However, it is not guaranteed, and in particular a WIM image captured with
365 \fB@IMAGEX_PROGNAME@\fR on a POSIX-compliant system could contain such files.  By
366 default, invalid names will be ignored, and if there are multiple names
367 differing only in case, one will be chosen to extract arbitrarily; however, with
368 \fB--include-invalid-names\fR, all names will be sanitized and extracted in some
369 form.
370 .TP
371 \fB--resume\fR
372 TODO
373 .SH NOTES
374 \fB@IMAGEX_PROGNAME@ apply\fR calculates the SHA1 message digest of every file
375 stream it extracts and verifies that it is the same as the SHA1 message digest
376 provided in the WIM file.  It is an error if the message digests don't match.
377 It's also considered to be an error if any WIM resources that need to be
378 extracted cannot be found in the stream lookup table.  So you can be fairly
379 certain that the file streams are extracted correctly, even though
380 \fB@IMAGEX_PROGNAME@ apply\fR don't have a \fB/verify\fR option like Microsoft's
381 ImageX does.  Note that this is separate from the integrity table of the WIM,
382 which provides SHA1 message digests over raw chunks of the entire WIM file and
383 is checked separately if the \fB--check\fR option is specified.
384 .SH EXAMPLES
385 Extract the first image from the Windows PE image on the Windows Vista/7/8
386 installation media to the directory "boot":
387 .RS
388 .PP
389 @IMAGEX_PROGNAME@ apply /mnt/windows/sources/boot.wim 1 boot
390 .RE
391 .PP
392 Same as above, but using the \fBwimapply\fR abbreviation:
393 .RS
394 .PP
395 wimapply /media/windows/sources/boot.wim 1 boot
396 .RE
397 .PP
398 On Windows, apply an image of an entire volume, for example from "install.wim"
399 which can be found on the Windows Vista/7/8 installation media:
400 .RS
401 .PP
402 @IMAGEX_PROGNAME@ apply install.wim 1 E:\\
403 .RE
404 .PP
405 Same as above, but running on a UNIX-like system where the corresponding
406 partition is /dev/sda2:
407 .RS
408 .PP
409 @IMAGEX_PROGNAME@ apply install.wim 1 /dev/sda2
410 .RE
411 .PP
412 Note that before running either of the above commands, an NTFS filesystem may
413 need to be created on the partition, for example with format.exe on Windows or
414 \fBmkntfs\fR(8) (part of NTFS-3g) on UNIX-like systems.  For example, you might
415 run:
416 .RS
417 .PP
418 mkntfs /dev/sda2 && wimapply install.wim 1 /dev/sda2
419 .RE
420 .PP
421 (Of course don't do that if you don't want to destroy all existing data on the
422 partition!)
423 .PP
424 An example of applying a pipable WIM from a pipe can be found in \fBPIPABLE
425 WIMS\fR, and an example of applying a split WIM can be found in \fBSPLIT
426 WIMS\fR.
427 .PP
428 And finally, just for fun, a silly way to recursively copy a directory tree
429 \fIsrc\fR to \fIdst\fR (but subject to the documented limitations, e.g.
430 platform and filesystem-dependent, of the capture and apply functionality of
431 \fB@IMAGEX_PROGNAME@\fR):
432 .RS
433 .PP
434 @IMAGEX_PROGNAME@ capture src - | @IMAGEX_PROGNAME@ apply - dst
435 .RE
436 .PP
437 .SH SEE ALSO
438 .BR @IMAGEX_PROGNAME@ (1)
439 .BR @IMAGEX_PROGNAME@-capture (1)
440 .BR @IMAGEX_PROGNAME@-extract (1)
441 .BR @IMAGEX_PROGNAME@-info (1)