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