Update timestamp code; use utimensat()
[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 100 nanoseconds, if supported by the underlying filesystem, operating system,
52 and C library
53 .IP \[bu]
54 Symbolic links and junction points, although they will not necessarily point to
55 the desired location (for example, the target of the link may contain a Windows
56 drive letter).
57
58 .PP
59 In the normal mode of extraction, the following information will \fInot\fR be
60 extracted from the WIM image(s):
61
62 .IP \[bu] 4
63 Security descriptors (file permissions) except through the extensions available
64 through the \fB--unix-data\fR option
65 .IP \[bu]
66 The alternate (named) data streams for each file
67 .IP \[bu]
68 Reparse points other than symbolic links and junction points
69 .IP \[bu]
70 Certain file attributes such as compression, encryption, and sparseness.
71 .IP \[bu]
72 Short (DOS) names for files
73
74 .SH NTFS MODE
75
76 A special extraction mode is entered when \fITARGET\fR is a regular file or
77 block device.  If this is the case, \fITARGET\fR is interpreted as an NTFS
78 volume and opened using libntfs-3g.  If successful, the WIM image is extracted
79 to the root of the NTFS volume in a special mode that preserves all information
80 contained in the WIM image.  \fIIMAGE\fR may not be "all" for this action.
81
82 The NTFS volume does not need to be empty, although it's expected that it be
83 empty for the intended use cases.  A new NTFS filesystem can be created using
84 the \fBmkntfs\fR (8) command.
85
86 The NTFS extraction mode is not available if wimlib was compiled using the
87 \fB--without-ntfs-3g\fR option.
88
89 Please note that the NTFS extraction mode is \fInot\fR entered if \fITARGET\fR
90 is a directory, even if a NTFS filesystem is mounted on \fITARGET\fR.  You must
91 specify the NTFS volume itself (and it must be unmounted, and you must have
92 permission to write to it).
93
94 In the NTFS extraction mode, the following information will be extracted from
95 the WIM image:
96
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
118 .PP
119
120 Since all information from the WIM image is restored in the NTFS extraction
121 mode, it is possible to restore an image of an actual Windows installation. In
122 the examples at the end of this manual page, there is an example of applying an
123 image from the "install.wim" file contained in the installation media for
124 Windows Vista, Windows 7, and Windows 8 in the "sources" directory.
125
126 But in order to actually boot Windows from an applied image, you must understand
127 the boot process of Windows versions Vista and later.  Basically, it is the
128 following:
129
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
145 .PP
146
147 So let's say you applied an image from an existing "install.wim" as in the
148 example, or you've applied a custom Windows image that you've created using the
149 \fBimagex capture\fR (1) command.  You've just applied the "Boot" partition, or
150 the main Windows partition, but there is no "System" partition yet (i.e.  no
151 \\BOOTMGR and no \\Boot\\BCD).
152
153 A "System" partition can be created created by running the "bcdboot.exe" program
154 from within Windows or Windows PE.  Alternatively, you can capture a separate
155 WIM image containing the "System" partition.  Or, the "System" partition may the
156 same as the "Boot" partition, so the two "partitions" may be combined in one WIM
157 image.  However, as the \\Boot\\BCD file contains the Windows bootloader
158 configuration, a WIM containing it can only be used on systems where you are
159 setting up the same bootloader configuration, including the same partition
160 layout.
161
162 Besides setting up the files on the "System" partition, don't forget to set the
163 bootable flag on it, and have a master boot record that loads the bootable
164 partition (Windows' MBR does, and SYSLINUX provides an equivalent MBR).
165
166 .SH SPLIT WIMS
167
168 You may use \fBimagex apply\fR to apply images from a split WIM.  The
169 \fIWIMFILE\fR argument is used to specify the first part of the split WIM, and
170 the \fB--refs\fR="\fIGLOB\fR" option is used to provide a shell-style file glob
171 that specifies the additional parts of the split WIM.  \fIGLOB\fR is expected to
172 be a single string on the command line, so \fIGLOB\fR must be quoted so that it
173 is protected against shell expansion.  \fIGLOB\fR must expand to all parts of
174 the split WIM, except optionally the first part which may either omitted or
175 included in the glob (but the first part MUST be specified as \fIWIMFILE\fR as
176 well).
177
178 Here's an example.  The names for the split WIMs usually go something like:
179
180 .RS
181 .PP
182 .nf
183 mywim.swm
184 mywim2.swm
185 mywim3.swm
186 mywim4.swm
187 mywim5.swm
188 .RE
189
190 To apply the first image of this split WIM to the directory "dir", run:
191 .PP
192 .RS
193 imagex apply mywim.swm 1 dir --ref="mywim*.swm"
194 .RE
195 .PP
196
197 .SH WINDOWS VERSION
198
199 This section documents the differences between \fBimagex apply\fR in the Windows
200 builds of wimlib versus the rest of this man page, which is written to document
201 the UNIX build.
202
203 \fBimagex apply\fR does not have separate "normal" and "NTFS" modes on Windows.
204 There is simply one mode, and it uses the Windows API to apply NTFS-specific
205 information, including alternate data streams, reparse points, hard links, and
206 file attributes.  So, you essentially get the advantages of the "NTFS mode"
207 documented above, but you can apply the WIM image to any directory, not just an
208 entire NTFS volume.  This is essentially the same behavior as Microsoft's
209 ImageX.
210
211 \fB--hardlink\fR, \fB--symlink\fR, and \fB--unix-data\fR are not supported on
212 Windows.
213
214 Except for the differences documented in this section, the Windows build of
215 \fBimagex apply\fR should be essentially equivalent to the UNIX build.  However,
216 one additional thing to note is that wimlib's Windows ImageX is NOT written to
217 be command-line compatible with Microsoft's ImageX, although they are very
218 similar.
219
220 .SH OPTIONS
221 .TP 6
222 \fB--check\fR
223 When reading \fIWIMFILE\fR, verify its integrity if the integrity table is
224 present.
225 .TP
226 \fB--hardlink\fR
227 When extracting a file from the WIM that is identical to a file that has already
228 extracted, create a hard link rather than creating a separate file.  This option
229 causes all identical files to be hard-linked, overriding the hard link groups
230 that are specified in the WIM image(s).  In the case of extracting all images
231 from the WIM, files may be hard-linked even if they are in different WIM images.
232 This option is not available in the NTFS extraction mode.
233 .TP
234 \fB--symlink\fR
235 This option is similar to \fB--hardlink\fR, except symbolic links are created
236 instead.  This option is not available in the NTFS extraction mode.
237 .TP
238 \fB--verbose\fR
239 Print the path to of each file or directory within the WIM image as it is
240 extracted, and some additional informational messages.
241 .TP
242 \fB--ref\fR="\fIGLOB\fR"
243 File glob of additional split WIM parts that are part of the split WIM being
244 applied.  See \fBSPLIT_WIMS\fR.
245 .TP
246 \fB--unix-data\fR
247 This option may only be given in the normal extraction mode (not NTFS).
248 By default, in the normal extraction mode, \fBimagex apply\fR will ignore both
249 Windows-style security descriptors and UNIX-specific file owners, groups, and
250 modes set when using \fBimagex capture\fR with the \fB--unix-data\fR flag.  By
251 passing \fB--unix-data\fR to \fBimagex apply\fR instead, this causes this
252 UNIX-specific data to be restored when available.
253
254 .SH NOTES
255
256 \fBimagex apply\fR calculates the SHA1 message digest of every file stream it
257 extracts and verifies that it is the same as the SHA1 message digest provided in
258 the WIM file.  It is an error if the message digests don't match.  It's also
259 considered to be an error if any WIM resources cannot be found in the stream
260 lookup table.  So you can be fairly certain that the file streams are extracted
261 correctly, even though \fBimagex apply\fR don't have a \fB/verify\fR option like
262 Microsoft's ImageX does.  Please note that this is separate from the integrity
263 table of the WIM, which provides SHA1 message digests over raw chunks of the
264 entire WIM file and is checked separately if the \fB--check\fR option is
265 specified.
266
267 You cannot use \fBimagex apply\fR to apply a WIM from a pipe (such as standard
268 input) because the WIM file format is not designed for this.
269
270 .SH EXAMPLES
271 .SS Normal extraction mode
272 Extract the first image from the Windows PE image from the Windows Vista/7/8
273 installation media to the directory "boot":
274 .RS
275 .PP
276 image apply /media/windows/sources/boot.wim 1 boot
277 .RE
278 .PP
279 Extract all images from the Windows PE image from the Windows Vista/7/8
280 installation media to the directory "boot", and hard link all identical files:
281 .RS
282 .PP
283 image apply /media/windows8/sources/boot.wim all boot --hardlink
284 .RE
285 .PP
286 .SS NTFS extraction mode
287 Apply a WIM image to a NTFS filesystem image:
288 .RS
289 .PP
290 imagex apply mywim.wim 1 fsimage.ntfs
291 .RE
292 .PP
293 Create a new NTFS filesystem on the partition /dev/sda2 and apply the first
294 image in the Windows Vista/7/8 installation WIM to it.  (Obviously, only do this
295 if you want to erase everything on that partition.)
296 .RS
297 .PP
298 mkntfs /dev/sda2 && imagex apply /media/windows/sources/install.wim 1 /dev/sda2
299 .RE
300 .PP
301
302 .SH SEE ALSO
303 .BR imagex (1)
304