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