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