Doc fixes
[wimlib] / doc / imagex-apply.1.in
1 .TH IMAGEX "1" "March 2013" "imagex (wimlib) wimlib @VERSION@" "User Commands"
2 .SH NAME
3 imagex-apply \- Extract one image, or all images, from a WIM archive
4
5 .SH SYNOPSIS
6 \fBimagex apply\fR \fIWIMFILE\fR \fIIMAGE\fR \fITARGET\fR [\fIOPTION\fR]...
7
8 .SH DESCRIPTION
9 .PP
10
11 \fBimagex apply\fR extracts an image, or all images, from the Windows Imaging
12 (WIM) file \fIWIMFILE\fR.
13
14 Note: this man page primarily documents the UNIX behavior.  See \fBWINDOWS
15 VERSION\fR for information specific to the Windows build of wimlib.
16
17 \fIIMAGE\fR specifies the WIM image to extract.  It may be a 1-based index of an
18 image in the WIM, the name of an image in the WIM, or the keyword "all" to
19 indicate that all images are to be extracted.  Use the \fBimagex info\fR (1)
20 command to show what images a WIM file contains.
21
22 \fITARGET\fR specifies where to extract the WIM image(s) to.  If \fITARGET\fR
23 specifies a directory, the WIM image(s) are extracted to that directory.  If
24 \fITARGET\fR specifies a non-existent file, a directory is created in that
25 location and the WIM image(s) are extracted to that directory.  If \fITARGET\fR
26 specifies a regular file or block device, it is interpreted as a NTFS volume to
27 which the WIM image is to be extracted.
28
29 \fBimagex apply\fR supports applying images from stand-alone WIMs as well as
30 split WIMs.  See \fBSPLIT WIMS\fR.
31
32 .SH NORMAL MODE
33
34 The normal extraction mode is entered when \fITARGET\fR is a directory or
35 non-existent file.  If a single WIM image is being extracted, it is extracted
36 with the root directory of the image corresponding to the directory named by
37 \fITARGET\fR; or, if the keyword \fBall\fR is given, the images are extracted
38 into subdirectories of \fITARGET\fR that are be named after the image names,
39 falling back to the image index for an image with no name.  \fITARGET\fR can
40 specify a directory on any type of filesystem.
41
42 In the normal mode of extraction, the following information is extracted from
43 the WIM image(s):
44
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 microsecond, if supported by the underlying filesystem
52 .IP \[bu]
53 Symbolic links and junction points, although they will not necessarily point to
54 the desired location (for example, the target of the link may contain a Windows
55 drive letter).
56
57 .PP
58 In the normal mode of extraction, the following information will \fInot\fR be
59 extracted from the WIM image(s):
60
61 .IP \[bu] 4
62 Security descriptors (file permissions) except through the extensions available
63 through the \fB--unix-data\fR option
64 .IP \[bu]
65 The alternate (named) data streams for each file
66 .IP \[bu]
67 Reparse points other than symbolic links and junction points
68 .IP \[bu]
69 Certain file attributes such as compression, encryption, and sparseness.
70 .IP \[bu]
71 Short (DOS) names for files
72
73 .SH NTFS MODE
74
75 A special extraction mode is entered when \fITARGET\fR is a regular file or
76 block device.  If this is the case, \fITARGET\fR is interpreted as an NTFS
77 volume and opened using libntfs-3g.  If successful, the WIM image is extracted
78 to the root of the NTFS volume in a special mode that preserves all information
79 contained in the WIM image.  \fIIMAGE\fR may not be "all" for this action.
80
81 The NTFS volume does not need to be empty, although it's expected that it be
82 empty for the intended use cases.  A new NTFS filesystem can be created using
83 the \fBmkntfs\fR (8) command.
84
85 The NTFS extraction mode is not available if wimlib was compiled using the
86 \fB--without-ntfs-3g\fR option.
87
88 Please note that the NTFS extraction mode is \fInot\fR entered if \fITARGET\fR
89 is a directory, even if a NTFS filesystem is mounted on \fITARGET\fR.  You must
90 specify the NTFS volume itself (and it must be unmounted, and you must have
91 permission to write to it).
92
93 In the NTFS extraction mode, the following information will be extracted from
94 the WIM image:
95
96 .IP \[bu] 4
97 The data streams of all files, including the un-named data stream as well as all
98 named data streams.
99 .IP \[bu]
100 Reparse points, including symbolic links, junction points, and other reparse
101 points.
102 .IP \[bu]
103 Hard links.
104 .IP \[bu]
105 File and directory creation, access, and modification timestamps are set to the
106 100-nanosecond resolution values specified in the WIM file.
107 .IP \[bu] 4
108 The security descriptor for each file is applied if there is one specified in
109 the WIM.
110 .IP \[bu]
111 File attribute flags are applied.
112 .IP \[bu]
113 Short (DOS) names for files are extracted.  The corresponding long name for each
114 DOS name is made to be a Win32 name.  Any additional names for the file in the
115 same directory are made to be names in the POSIX namespace.
116
117 .PP
118
119 Since all information from the WIM image is restored in the NTFS extraction
120 mode, it is possible to restore an image of an actual Windows installation. In
121 the examples at the end of this manual page, there is an example of applying an
122 image from the "install.wim" file contained in the installation media for
123 Windows Vista, Windows 7, and Windows 8 in the "sources" directory.
124
125 But in order to actually boot Windows from an applied image, you must understand
126 the boot process of Windows versions Vista and later.  Basically, it is the
127 following:
128
129 .nr step 1 1
130 .IP \n[step]. 3
131 The Master Boot Record loads the Volume Boot Record (also called the Boot
132 Sector) of the active partition, which is on an NTFS filesystem.  This partition
133 is called the "system partition".
134 .IP \n+[step].
135 The "bootmgr" program on the "system partition" is loaded (\\BOOTMGR).
136 .IP \n+[step].
137 bootmgr loads the Boot Configuration Data (\\Boot\\BCD) from the "system
138 partition".
139 .IP \n+[step].
140 Based on the information contained in the Boot Configuration Data, a loader for
141 the Windows kernel is executed from the "Boot" partition, which is where Windows
142 is installed.
143
144 .PP
145
146 So let's say you applied an image from an existing "install.wim" as in the
147 example, or you've applied a custom Windows image that you've created using the
148 \fBimagex capture\fR (1) command.  You've just applied the "Boot" partition, or
149 the main Windows partition, but there is no "System" partition yet (i.e.  no
150 \\BOOTMGR and no \\Boot\\BCD).
151
152 A "System" partition can be created created by running the "bcdboot.exe" program
153 from within Windows or Windows PE.  Alternatively, you can capture a separate
154 WIM image containing the "System" partition.  Or, the "System" partition may the
155 same as the "Boot" partition, so the two "partitions" may be combined in one WIM
156 image.  However, as the \\Boot\\BCD file contains the Windows bootloader
157 configuration, a WIM containing it can only be used on systems where you are
158 setting up the same bootloader configuration, including the same partition
159 layout.
160
161 Besides setting up the files on the "System" partition, don't forget to set the
162 bootable flag on it, and have a master boot record that loads the bootable
163 partition (Windows' MBR does, and SYSLINUX provides an equivalent MBR).
164
165 .SH SPLIT WIMS
166
167 You may use \fBimagex apply\fR to apply images from a split WIM.  The
168 \fIWIMFILE\fR argument is used to specify the first part of the split WIM, and
169 the \fB--refs\fR="\fIGLOB\fR" option is used to provide a shell-style file glob
170 that specifies the additional parts of the split WIM.  \fIGLOB\fR is expected to
171 be a single string on the command line, so \fIGLOB\fR must be quoted so that it
172 is protected against shell expansion.  \fIGLOB\fR must expand to all parts of
173 the split WIM, except optionally the first part which may either omitted or
174 included in the glob (but the first part MUST be specified as \fIWIMFILE\fR as
175 well).
176
177 Here's an example.  The names for the split WIMs usually go something like:
178
179 .RS
180 .PP
181 .nf
182 mywim.swm
183 mywim2.swm
184 mywim3.swm
185 mywim4.swm
186 mywim5.swm
187 .RE
188
189 To apply the first image of this split WIM to the directory "dir", run:
190 .PP
191 .RS
192 imagex apply mywim.swm 1 dir --ref="mywim*.swm"
193 .RE
194 .PP
195
196 .SH WINDOWS VERSION
197
198 This section documents the differences between \fBimagex apply\fR in the Windows
199 builds of wimlib versus the rest of this man page, which is written to document
200 UNIX version.
201
202 \fBimagex apply\fR does not have separate "normal" and "NTFS" modes on Windows.
203 There is simply one mode, and it uses the Windows API to apply NTFS-specific
204 information, including alternate data streams, reparse points, hard links, and
205 file attributes.  So, you essentially get the advantages of the "NTFS mode"
206 documented above, but you can apply the WIM image to any directory, not just an
207 entire NTFS volume.  This is mostly the same behavior as Microsoft's ImageX.
208
209 \fB--hardlink\fR, \fB--symlink\fR, and \fB--unix-data\fR are not supported on
210 Windows.
211
212 Other than the differences documented in this section, the Windows version
213 should be essentially equivalent to the UNIX version.  However, one additional
214 thing to note is that wimlib's Windows version of ImageX is NOT written to be
215 command-line compatible with Microsoft's version of ImageX, although they are
216 very similar.
217
218 .SH OPTIONS
219 .TP 6
220 \fB--check\fR
221 When reading \fIWIMFILE\fR, verify its integrity if the integrity table is
222 present.
223 .TP
224 \fB--hardlink\fR
225 When extracting a file from the WIM that is identical to a file that has already
226 extracted, create a hard link rather than creating a separate file.  This option
227 causes all identical files to be hard-linked, overriding the hard link groups
228 that are specified in the WIM image(s).  In the case of extracting all images
229 from the WIM, files may be hard-linked even if they are in different WIM images.
230 This option is not available in the NTFS extraction mode.
231 .TP
232 \fB--symlink\fR
233 This option is similar to \fB--hardlink\fR, except symbolic links are created
234 instead.  This option is not available in the NTFS extraction mode.
235 .TP
236 \fB--verbose\fR
237 Print the path to of each file or directory within the WIM image as it is
238 extracted, and some additional informational messages.
239 .TP
240 \fB--ref\fR="\fIGLOB\fR"
241 File glob of additional split WIM parts that are part of the split WIM being
242 applied.  See \fBSPLIT_WIMS\fR.
243 .TP
244 \fB--unix-data\fR
245 This option may only be given in the normal extraction mode (not NTFS).
246 By default, in the normal extraction mode, \fBimagex apply\fR will ignore both
247 Windows-style security descriptors and UNIX-specific file owners, groups, and
248 modes set when using \fBimagex capture\fR with the \fB--unix-data\fR flag.  By
249 passing \fB--unix-data\fR to \fBimagex apply\fR instead, this causes this
250 UNIX-specific data to be restored when available.
251
252 .SH NOTES
253
254 \fBimagex apply\fR calculates the SHA1 message digest of every file stream it
255 extracts and verifies that it is the same as the SHA1 message digest provided in
256 the WIM file.  It is an error if the message digests don't match.  It's also
257 considered to be an error if any WIM resources cannot be found in the stream
258 lookup table.  So you can be fairly certain that the file streams are extracted
259 correctly, even though \fBimagex apply\fR don't have a \fB/verify\fR option like
260 Microsoft's version of imagex does.  Please note that this is separate from the
261 integrity table of the WIM, which provides SHA1 message digests over raw chunks
262 of the entire WIM file and is checked separately if the \fB--check\fR option is
263 specified.
264
265 You cannot use \fBimagex apply\fR to apply a WIM from a pipe (such as standard
266 input) because the WIM file format is not designed for this.
267
268 .SH EXAMPLES
269 .SS Normal extraction mode
270 Extract the first image from the Windows PE image from the Windows Vista/7/8
271 installation media to the directory "boot":
272 .RS
273 .PP
274 image apply /media/windows/sources/boot.wim 1 boot
275 .RE
276 .PP
277 Extract all images from the Windows PE image from the Windows Vista/7/8
278 installation media to the directory "boot", and hard link all identical files:
279 .RS
280 .PP
281 image apply /media/windows8/sources/boot.wim all boot --hardlink
282 .RE
283 .PP
284 .SS NTFS extraction mode
285 Apply a WIM image to a NTFS filesystem image:
286 .RS
287 .PP
288 imagex apply mywim.wim 1 fsimage.ntfs
289 .RE
290 .PP
291 Create a new NTFS filesystem on the partition /dev/sda2 and apply the first
292 image in the Windows Vista/7/8 installation WIM to it.  (Obviously, only do this
293 if you want to erase everything on that partition.)
294 .RS
295 .PP
296 mkntfs /dev/sda2 && imagex apply /media/windows/sources/install.wim 1 /dev/sda2
297 .RE
298 .PP
299
300 .SH SEE ALSO
301 .BR imagex (1)
302