imagex apply documentation
[wimlib] / doc / imagex-apply.1.in
1 .TH IMAGEX "1" "May 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 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 \fBTARGET\fR specifies where to extract the WIM image(s) to.  If \fBTARGET\fR
20 specifies a directory, the WIM image(s) are extracted to that directory.  If
21 \fBTARGET\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 \fBTARGET\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 .SH NORMAL MODE
27
28 The normal extraction mode is entered when \fBTARGET\fR is a directory or
29 non-existent file.  If a single WIM image is being extracted, it will be
30 extracted with the root of the image corresponding to the directory named by
31 \fBTARGET\fR; or, if the keyword \fBall\fR is given, the images are extracted
32 into subdirectories of \fITARGET\fR that will be named after the image names,
33 falling back to the image indices if there is an image with no name.
34
35 In the normal mode of extraction, the following information will be extracted
36 from the WIM image(s):
37
38 .IP \[bu] 4
39 The default (unnamed) data streams of each file
40 .IP \[bu]
41 Hard links, if supported by the underlying filesystem
42 .IP \[bu]
43 File and directory creation, access, and modification timestamps to the nearest
44 microsecond, if supported by the underlying filesystem
45 .IP \[bu]
46 Symbolic links and junction points, although they will not necessarily point to
47 the desired location (for example, the target of the link may contain a Windows
48 drive letter).
49
50 .PP
51 In the normal mode of extraction, the following information will \fInot\fR be
52 extracted from the WIM image(s):
53
54 .IP \[bu] 4
55 Security descriptors (file permissions)
56 .IP \[bu]
57 The alternate (named) data streams for each file
58 .IP \[bu]
59 Reparse points other than symbolic links and junction points
60 .IP \[bu]
61 Certain file attributes such as compression, encryption, and sparseness.
62 .IP \[bu]
63 Short (DOS) names for files
64
65 .SH NTFS MODE
66
67 A special extraction mode is entered when \fBTARGET\fR is a regular file or
68 block device.  \fBTARGET\fR is interpreted as an NTFS volume and opened using
69 libntfs-3g.  If successful, the WIM image is extracted to the root of the NTFS
70 volume in a special mode that preserves all, or almost all, information
71 contained in the WIM.  \fBIMAGE\fR may not be "all" for this action.
72
73 The NTFS volume does not need to be empty, although it's expected that it be
74 empty for the intended use cases.  A new NTFS filesystem can be created using
75 the \fBmkntfs\fR (8) command.
76
77 The NTFS extraction mode is not available if wimlib was compiled using the
78 --without-ntfs-3g option.
79
80 In the NTFS extraction mode, the following information will be extracted from
81 the WIM image:
82
83 .IP \[bu] 4
84 The data streams of all files, including the un-named data stream as well as all
85 named data streams.
86 .IP \[bu]
87 Reparse points, including symbolic links, junction points, and other reparse
88 points.
89 .IP \[bu]
90 Hard links.
91 .IP \[bu]
92 File and directory creation, access, and modification timestamps are set to the
93 100-nanosecond resolution values specified in the WIM file.
94 .IP \[bu] 4
95 The security descriptor for each file is applied if there is one specified in
96 the WIM.
97 .IP \[bu]
98 File attribute flags are applied.
99 .IP \[bu]
100 Short (DOS) names for files are extracted.  The corresponding long name for each
101 DOS name is made to be a Win32 name.  Any additional names for the file in the
102 same directory are made to be names in the POSIX namespace.
103
104 .PP
105
106 In the NTFS extraction mode, we restore enough information from the WIM that it
107 is possible, in most cases, to restore or install an image of an actual Windows
108 installation. In the examples at the end of this manual page, we show an example
109 of applying an image from the "install.wim" file contained in the installation
110 media for Windows Vista, Windows 7, and Windows 8 in the "sources" directory.
111
112 In order to actually boot Windows from an applied image, you must understand the
113 boot process of Windows versions Vista and later.  Basically, it is the
114 following:
115
116 .nr step 1 1
117 .IP \n[step]. 3
118 The Master Boot Record loads the Volume Boot Record (also called the Boot
119 Sector) of the active partition, which is on an NTFS filesystem.  This partition
120 is called the "system partition".
121 .IP \n+[step].
122 The "bootmgr" program on the "system partition" is loaded (\\BOOTMGR).
123 .IP \n+[step].
124 bootmgr loads the Boot Configuration Data (\\Boot\\BCD) from the "system
125 partition".
126 .IP \n+[step].
127 Based on the information contained in the Boot Configuration Data, a loader for
128 the Windows kernel is executed from the "Boot" partition, which is where Windows
129 is installed.
130
131 .PP
132
133 So let's say you applied an image from an existing "install.wim" as in the
134 example, or you've applied a custom Windows image that you've created using the
135 \fBimagex capture\fR (1) command.  You've just applied the "Boot" partition, or
136 the main Windows partition, but there is no "System" partition yet (i.e.  no
137 \\BOOTMGR and no \\Boot\\BCD).
138
139 A "System" partition can be created created by running the "bcdboot.exe" program
140 from within Windows or Windows PE.  Alternatively, you can capture a separate
141 WIM image containing the "System" partition.  Or, the "System" partition may the
142 same as the "Boot" partition, so the two "partitions" may be combined in one WIM
143 image.  However, as the \\Boot\\BCD file contains the Windows bootloader
144 configuration, a WIM containing it can only be used on systems where you are
145 setting up the same bootloader configuration, including the same partition
146 layout.
147
148 Besides setting up the files on the "System" partition, don't forget to set the
149 bootable flag on it, and have a master boot record that loads the bootable
150 partition (Windows' MBR does, and SYSLINUX provides an equivalent MBR).
151
152 .SH OPTIONS
153 .TP 6
154 \fB--check\fR
155 When reading \fIWIMFILE\fR, verify its integrity if the integrity table is
156 present.
157 .TP
158 \fB--hardlink\fR
159 When extracting a file from the WIM that is identical to a file that has already
160 extracted, create a hard link using \fBlink\fR (3) rather than creating a
161 separate file.  This option causes all identical files to be hard-linked,
162 overriding the hard link groups that are specified in the WIM image(s).  In the
163 case of extracting all images from the WIM, files may be hard-linked even if
164 they are in different WIM images.  This option is not available in the NTFS
165 extraction mode.
166 .TP
167 \fB--symlink\fR
168 This option is similar to \fB--hardlink\fR, except symbolic links are created
169 instead.  This option is not available in the NTFS extraction mode.
170 .TP
171 \fB--verbose\fR
172 Print the path to of each file or directory within the WIM image as it is
173 extracted, and some additional informational messages.
174
175 .SH EXAMPLES
176 .SS Normal extraction mode
177 Extract the first image from the Windows PE image from the Windows Vista/7/8
178 installation media to the directory "boot":
179 .RS
180 .PP
181 image apply /media/windows/sources/boot.wim 1 boot
182 .RE
183 .PP
184 Extract all images from the Windows PE image from the Windows Vista/7/8
185 installation media to the directory "boot", and hard link all identical files:
186 .RS
187 .PP
188 image apply /media/windows8/sources/boot.wim all boot --hardlink
189 .RE
190 .PP
191 .SS NTFS extraction mode
192 Verbosely apply a WIM image to a NTFS filesystem image:
193 .RS
194 .PP
195 imagex apply mywim.wim 1 fsimage.ntfs --verbose
196 .RE
197 .PP
198 Create a new NTFS filesystem on the partition /dev/sda2 and apply the first
199 image in the Windows Vista/7/8 installation WIM to it.  (Obviously, only do this
200 if you want to erase everything on that partition.)
201 .RS
202 .PP
203 mkntfs /dev/sda2 && imagex apply /media/windows/sources/install.wim 1 /dev/sda2
204 .RE
205 .PP
206
207 .SH SEE ALSO
208 .BR imagex (1)
209