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