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