More wimlib-imagex man pages updates
[wimlib] / doc / imagex-apply.1.in
1 .TH IMAGEX "1" "April 2013" "@IMAGEX_PROGNAME@ @VERSION@" "User Commands"
2 .SH NAME
3 @IMAGEX_PROGNAME@-apply \- Extract one image, or all images, from a WIM archive
4
5 .SH SYNOPSIS
6 \fB@IMAGEX_PROGNAME@ apply\fR \fIWIMFILE\fR [\fIIMAGE\fR] \fITARGET\fR [\fIOPTION\fR...]
7
8 .SH DESCRIPTION
9 .PP
10
11 \fB@IMAGEX_PROGNAME@ apply\fR extracts an image, or all images, from the Windows
12 Imaging (WIM) file \fIWIMFILE\fR.
13
14 This command is designed to extract, or "apply", one or more full WIM images.
15 If you instead want to extract only certain files or directories contained in a
16 WIM image, consider using \fB@IMAGEX_PROGNAME@ extract\fR or
17 \fB@IMAGEX_PROGNAME@ mount\fR instead.
18
19 \fIIMAGE\fR specifies the WIM image to extract.  It may be a 1-based index of an
20 image in the WIM, the name of an image in the WIM, or the keyword "all" to
21 indicate that all images are to be extracted.  Use the \fB@IMAGEX_PROGNAME@
22 info\fR (1) command to show what images a WIM file contains.  \fIIMAGE\fR may be
23 omitted if \fIWIMFILE\fR contains only one image.
24
25 \fITARGET\fR specifies where to extract the WIM image(s) to.  If \fITARGET\fR
26 specifies a directory, the WIM image(s) are extracted to that directory.  If
27 \fITARGET\fR specifies a non-existent file, a directory is created in that
28 location and the WIM image(s) are extracted to that directory.  Alternatively,
29 on UNIX only, if \fITARGET\fR specifies a regular file or block device, it is
30 interpreted as an NTFS volume to which the WIM image is to be extracted.
31
32 \fB@IMAGEX_PROGNAME@ apply\fR supports applying images from stand-alone WIMs as
33 well as split WIMs.  See \fBSPLIT WIMS\fR.
34
35 .SH NORMAL MODE (UNIX)
36
37 This section documents how files are extracted on UNIX from the WIM image to a
38 directory.  See \fBWINDOWS VERSION\fR for the corresponding documentation for
39 the Windows version.
40
41 On UNIX, the "normal" extraction mode is entered when \fITARGET\fR is a
42 directory or non-existent file.  If a single WIM image is being extracted, it is
43 extracted with the root directory of the image corresponding to the directory
44 named by \fITARGET\fR; or, if the keyword \fBall\fR is given, the images are
45 extracted into subdirectories of \fITARGET\fR that are be named after the image
46 names, falling back to the image index for an image with no name.  \fITARGET\fR
47 can specify a directory on any type of filesystem.
48
49 In the "normal" mode of extraction on UNIX, the following information is
50 extracted from the WIM image(s):
51
52 .IP \[bu] 4
53 The default (unnamed) data stream of each file
54 .IP \[bu]
55 Hard links
56 .IP \[bu]
57 File and directory creation, access, and modification timestamps to the nearest
58 100 nanoseconds, if supported by the underlying filesystem, operating system,
59 and C library
60 .IP \[bu]
61 Symbolic links and junction points.  Drive letters will be stripped.
62 (Note: see \fB--rpfix\fR and \fB--norpfix\fR for documentation on how absolute
63 symbolic links and junctions are applied.)
64
65 .PP
66 However, in the "normal" mode of extraction on UNIX, the following information
67 will \fInot\fR be extracted from the WIM image(s):
68
69 .IP \[bu] 4
70 Security descriptors (file permissions) except through the extensions available
71 through the \fB--unix-data\fR option
72 .IP \[bu]
73 The alternate (named) data streams for each file
74 .IP \[bu]
75 Reparse points other than symbolic links and junction points
76 .IP \[bu]
77 Certain file attributes such as compression, encryption, and sparseness.
78 .IP \[bu]
79 Short (DOS) names for files
80
81 .SH NTFS MODE (UNIX)
82
83 This section documents how files are extracted directly to an NTFS volume image
84 on UNIX.  See \fBWINDOWS VERSION\fR for the corresponding documentation for the
85 Windows version.
86
87 On UNIX, a special extraction mode is entered when \fITARGET\fR is a regular
88 file or block device.  If this is the case, \fITARGET\fR is interpreted as an
89 NTFS volume and opened using libntfs-3g.  If successful, the WIM image is
90 extracted to the root of the NTFS volume in a special mode that preserves all
91 information contained in the WIM image.  \fIIMAGE\fR may not be "all" for this
92 action.
93
94 The NTFS volume does not need to be empty, although it's expected that it be
95 empty for the intended use cases.  A new NTFS filesystem can be created using
96 the \fBmkntfs\fR (8) command.
97
98 The NTFS extraction mode is not available if wimlib was compiled using the
99 \fB--without-ntfs-3g\fR option.
100
101 Please note that the NTFS extraction mode is \fInot\fR entered if \fITARGET\fR
102 is a directory, even if an NTFS filesystem is mounted on \fITARGET\fR.  You must
103 specify the NTFS volume itself (and it must be unmounted, and you must have
104 permission to write to it).
105
106 In the NTFS extraction mode on UNIX, the following information will be extracted
107 from the WIM image:
108
109 .IP \[bu] 4
110 The data streams of all files, including the un-named data stream as well as all
111 named data streams.
112 .IP \[bu]
113 Reparse points, including symbolic links, junction points, and other reparse
114 points.
115 .IP \[bu]
116 Hard links.
117 .IP \[bu]
118 File and directory creation, access, and modification timestamps are set to the
119 100-nanosecond resolution values specified in the WIM file.
120 .IP \[bu] 4
121 The security descriptor for each file is applied if there is one specified in
122 the WIM.
123 .IP \[bu]
124 File attribute flags are applied.
125 .IP \[bu]
126 Short (DOS) names for files are extracted.  The corresponding long name for each
127 DOS name is made to be a Win32 name.  Any additional names for the file in the
128 same directory are made to be names in the POSIX namespace.
129
130 .PP
131 However, the extraction of encrypted files is not supported in this mode.
132 .PP
133 Since all (or almost all) information from the WIM image is restored in this
134 mode, it is possible to restore an image of an actual Windows installation using
135 \fB@IMAGEX_PROGNAME@\fR on UNIX in addition to with \fB@IMAGEX_PROGNAME@\fR on
136 Windows.  In the examples at the end of this manual page, there is an example of
137 applying an image from the "install.wim" file contained in the installation
138 media for Windows Vista, Windows 7, and Windows 8 in the "sources" directory.
139 .PP
140 But in order to actually boot Windows from an applied image, you must understand
141 the boot process of Windows versions Vista and later.  Basically, it is the
142 following:
143
144 .nr step 1 1
145 .IP \n[step]. 3
146 The Master Boot Record loads the Volume Boot Record (also called the Boot
147 Sector) of the active partition, which is on an NTFS filesystem.  This partition
148 is called the "system partition".
149 .IP \n+[step].
150 The "bootmgr" program on the "system partition" is loaded (\\BOOTMGR).
151 .IP \n+[step].
152 bootmgr loads the Boot Configuration Data (\\Boot\\BCD) from the "system
153 partition".
154 .IP \n+[step].
155 Based on the information contained in the Boot Configuration Data, a loader for
156 the Windows kernel is executed from the "Boot" partition, which is where Windows
157 is installed.
158
159 .PP
160
161 So let's say you applied an image from an existing "install.wim" as in the
162 example, or you've applied a custom Windows image that you've created using the
163 \fB@IMAGEX_PROGNAME@ capture\fR (1) command.  You've just applied the "Boot" partition, or
164 the main Windows partition, but there is no "System" partition yet (i.e.  no
165 \\BOOTMGR and no \\Boot\\BCD).
166
167 A "System" partition can be created created by running the "bcdboot.exe" program
168 from within Windows or Windows PE.  Alternatively, you can capture a separate
169 WIM image containing the "System" partition.  Or, the "System" partition may the
170 same as the "Boot" partition, so the two "partitions" may be combined in one WIM
171 image.  However, as the \\Boot\\BCD file contains the Windows bootloader
172 configuration, a WIM containing it can only be used on systems where you are
173 setting up the same bootloader configuration, including the same partition
174 layout.
175
176 Besides setting up the files on the "System" partition, don't forget to set the
177 bootable flag on it, and have a master boot record that loads the bootable
178 partition (Windows' MBR does, and SYSLINUX provides an equivalent MBR).
179
180 .SH SPLIT WIMS
181
182 You may use \fB@IMAGEX_PROGNAME@ apply\fR to apply images from a split WIM.  The
183 \fIWIMFILE\fR argument is used to specify the first part of the split WIM, and
184 the \fB--refs\fR="\fIGLOB\fR" option is used to provide a shell-style file glob
185 that specifies the additional parts of the split WIM.  \fIGLOB\fR is expected to
186 be a single string on the command line, so \fIGLOB\fR must be quoted so that it
187 is protected against shell expansion.  \fIGLOB\fR must expand to all parts of
188 the split WIM, except optionally the first part which may either omitted or
189 included in the glob (but the first part MUST be specified as \fIWIMFILE\fR as
190 well).
191
192 Here's an example.  The names for the split WIMs usually go something like:
193
194 .RS
195 .PP
196 .nf
197 mywim.swm
198 mywim2.swm
199 mywim3.swm
200 mywim4.swm
201 mywim5.swm
202 .RE
203 .nf
204
205 To apply the first image of this split WIM to the directory "dir", run:
206 .PP
207 .RS
208 @IMAGEX_PROGNAME@ apply mywim.swm 1 dir --ref="mywim*.swm"
209 .RE
210 .PP
211
212 .SH WINDOWS VERSION
213
214 The Windows version of \fB@IMAGEX_PROGNAME@ apply\fR acts similarly to the
215 corresponding command of Microsoft's ImageX.  For best results, the target
216 directory should be on an NTFS volume and you should be running with
217 Administrator privileges; however, non-NTFS filesystems and running without
218 Administrator privileges are also supported.
219
220 On Windows, \fB@IMAGEX_PROGNAME@ apply\fR tries to extract as much data as
221 possible.  This includes:
222
223 .IP \[bu] 4
224 All data streams of all files.  This includes the default file contents, as well
225 as named data streams if supported by the filesystem.
226 .IP \[bu]
227 Reparse points, including symbolic links, junction points, and other reparse
228 points, if supported by the underlying filesystem.  (Note: see
229 \fB--rpfix\fR and \fB--norpfix\fR for documentation on how absolute symbolic
230 links and junctions are applied.)
231 .IP \[bu]
232 File and directory creation, access, and modification timestamps.
233 .IP \[bu]
234 Security descriptors, if supported by the filesystem and \fB--no-acls\fR is not
235 specified.  Furthermore, unless \fB--strict-acls\fR is specified, the security
236 descriptor for individual files or directories may be omitted or only partially
237 set if the user does not have permission to set them.
238 .IP \[bu]
239 File attributes, including hidden, sparse, compressed, encrypted, etc, when
240 supported by the filesystem.
241 .IP \[bu]
242 DOS names (8.3) names of files; however, the failure to set them is not
243 considered an error condition.
244 .IP \[bu]
245 Hard links, if supported by the filesystem.
246
247 .PP
248 Note: encrypted files will be extracted as raw encrypted data if the filesystem
249 does not support encryption.  Compressed files and directories (with the
250 compression attribute set) will be extracted as uncompressed if the filesystem
251 does not support transparent compression.
252
253 .SH OPTIONS
254 .TP 6
255 \fB--check\fR
256 When reading \fIWIMFILE\fR, verify its integrity if the integrity table is
257 present.
258 .TP
259 \fB--ref\fR="\fIGLOB\fR"
260 File glob of additional split WIM parts that are part of the split WIM being
261 applied.  See \fBSPLIT_WIMS\fR.
262 .TP
263 \fB--rpfix\fR, \fB--norpfix\fR
264 Set whether to fix targets of absolute symbolic links (reparse points in Windows
265 terminology) or not.  When enabled (\fB--rpfix\fR), extracted absolute symbolic
266 links that are marked in the WIM image as being fixed are assumed to have
267 absolute targets relative to the image root, and therefore have the actual root
268 of extraction prepended to their targets.  The intention is that you can apply
269 an image containing absolute symbolic links and still have them be valid after
270 it has been applied to any location.
271
272 The default behavior is \fB--rpfix\fR if any images in \fIWIMFILE\fR have been
273 captured with reparse-point fixups done.  Otherwise, it is \fB--norpfix\fR.
274
275 Reparse point fixups are never done in the NTFS extraction mode on UNIX.
276 .TP
277 \fB--verbose\fR
278 Print the path to of each file or directory within the WIM image as it is
279 extracted.
280 .TP
281 \fB--hardlink\fR
282 (UNIX only) When extracting a file from the WIM that is identical to a file that
283 has already extracted, create a hard link rather than creating a separate file.
284 This option causes all identical files to be hard-linked, overriding the hard
285 link groups that are specified in the WIM image(s).  In the case of extracting
286 all images from the WIM, files may be hard-linked even if they are in different
287 WIM images.  This option is not available in the NTFS extraction mode.
288 .TP
289 \fB--symlink\fR
290 (UNIX only) This option is similar to \fB--hardlink\fR, except symbolic links are created
291 instead.
292 .TP
293 \fB--unix-data\fR
294 (UNIX only)  By default, in the normal extraction mode on UNIX,
295 \fB@IMAGEX_PROGNAME@ apply\fR will ignore both Windows-style security
296 descriptors and UNIX-specific file owners, groups, and modes set when
297 using \fB@IMAGEX_PROGNAME@ capture\fR with the \fB--unix-data\fR flag.
298 By passing \fB--unix-data\fR to \fB@IMAGEX_PROGNAME@ apply\fR instead,
299 this causes this UNIX-specific data to be restored when available.  However, by
300 default, if \fB@IMAGEX_PROGNAME@\fR does not have permission to set the UNIX
301 owner, group or file mode on an extracted file, a warning will be printed and it
302 will not be considered an error condition; use \fB--strict-acls\fR to get
303 stricter behavior.
304 .TP
305 \fB--no-acls\fR
306 (Windows only) Do not restore security descriptors on extracted files and directories.
307 .TP
308 \fB--strict-acls\fR
309 On Windows: Fail immediately if the full security descriptor of any file or
310 directory cannot be set exactly as specified in the WIM file.  The default
311 behavior without this option is to fall back to setting a security descriptor
312 with the SACL omitted, then only the default inherited security descriptor, if
313 we do not have permission to set the desired one.  On UNIX: with
314 \fB--unix-data\fR, fail immediately if the UNIX owner, group, or file mode on an
315 extracted file cannot be set for any reason.
316
317 .SH NOTES
318
319 \fB@IMAGEX_PROGNAME@ apply\fR calculates the SHA1 message digest of every file stream it
320 extracts and verifies that it is the same as the SHA1 message digest provided in
321 the WIM file.  It is an error if the message digests don't match.  It's also
322 considered to be an error if any WIM resources cannot be found in the stream
323 lookup table.  So you can be fairly certain that the file streams are extracted
324 correctly, even though \fB@IMAGEX_PROGNAME@ apply\fR don't have a \fB/verify\fR option like
325 Microsoft's ImageX does.  Please note that this is separate from the integrity
326 table of the WIM, which provides SHA1 message digests over raw chunks of the
327 entire WIM file and is checked separately if the \fB--check\fR option is
328 specified.
329
330 You cannot use \fB@IMAGEX_PROGNAME@ apply\fR to apply a WIM from a pipe (such as standard
331 input) because the WIM file format is not designed for this.
332
333 .SH EXAMPLES
334 .SS Applying a WIM image to a directory (both UNIX and Windows)
335 Extract the first image from the Windows PE image from the Windows Vista/7/8
336 installation media to the directory "boot":
337 .RS
338 .PP
339 @IMAGEX_PROGNAME@ apply /media/windows/sources/boot.wim 1 boot
340 .RE
341 .PP
342 Extract all images from the Windows PE image from the Windows Vista/7/8
343 installation media to the directory "boot", and hard link all identical files:
344 .RS
345 .PP
346 @IMAGEX_PROGNAME@ apply /media/windows8/sources/boot.wim all boot --hardlink
347 .RE
348 .PP
349 .SS Applying a WIM image directly to a NTFS volume image (UNIX only)
350 Apply a WIM image to an NTFS filesystem image:
351 .RS
352 .PP
353 @IMAGEX_PROGNAME@ apply mywim.wim 1 fsimage.ntfs
354 .RE
355 .PP
356 Create a new NTFS filesystem on the partition /dev/sda2 and apply the first
357 image in the Windows Vista/7/8 installation WIM to it.  (Obviously, only do this
358 if you want to erase everything on that partition.)
359 .RS
360 .PP
361 mkntfs /dev/sda2 && @IMAGEX_PROGNAME@ apply /media/windows/sources/install.wim 1 /dev/sda2
362 .RE
363 .PP
364
365 .SH SEE ALSO
366 .BR @IMAGEX_PROGNAME@ (1)
367 .BR @IMAGEX_PROGNAME@-extract (1)
368 .BR @IMAGEX_PROGNAME@-info (1)