wimlib.net Git - wimlib/blob - doc/imagex-apply.1.in

   1 .TH IMAGEX "1" "December 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 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 all information
  75 contained in the WIM image.  \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 Since all information from the WIM image is restored in the NTFS extraction
 116 mode, it is possible to restore an image of an actual Windows installation. In
 117 the examples at the end of this manual page, there is an example of applying an
 118 image from the "install.wim" file contained in the installation media for
 119 Windows Vista, Windows 7, and Windows 8 in the "sources" directory.
 120
 121 But in order to actually boot Windows from an applied image, you must understand
 122 the 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 .RE
 184
 185 To apply the first image of this split WIM to the directory "dir", run:
 186 .PP
 187 .RS
 188 imagex apply mywim.swm 1 dir --ref="mywim*.swm"
 189 .RE
 190 .PP
 191
 192 .SH OPTIONS
 193 .TP 6
 194 \fB--check\fR
 195 When reading \fIWIMFILE\fR, verify its integrity if the integrity table is
 196 present.
 197 .TP
 198 \fB--hardlink\fR
 199 When extracting a file from the WIM that is identical to a file that has already
 200 extracted, create a hard link rather than creating a separate file.  This option
 201 causes all identical files to be hard-linked, overriding the hard link groups
 202 that are specified in the WIM image(s).  In the case of extracting all images
 203 from the WIM, files may be hard-linked even if they are in different WIM images.
 204 This option is not available in the NTFS extraction mode.
 205 .TP
 206 \fB--symlink\fR
 207 This option is similar to \fB--hardlink\fR, except symbolic links are created
 208 instead.  This option is not available in the NTFS extraction mode.
 209 .TP
 210 \fB--verbose\fR
 211 Print the path to of each file or directory within the WIM image as it is
 212 extracted, and some additional informational messages.
 213 .TP
 214 \fB--ref\fR="\fIGLOB\fR"
 215 File glob of additional split WIM parts that are part of the split WIM being
 216 applied.  See \fBSPLIT_WIMS\fR.
 217
 218 .SH NOTES
 219
 220 \fBimagex apply\fR calculates the SHA1 message digest of every file stream it
 221 extracts and verifies that it is the same as the SHA1 message digest provided in
 222 the WIM file.  It is an error if the message digests don't match.  It's also
 223 considered to be an error if any WIM resources cannot be found in the stream
 224 lookup table.  So you can be fairly certain that the file streams are extracted
 225 correctly, even though \fBimagex apply\fR don't have a \fB/verify\fR option like
 226 Microsoft's version of imagex does.  Please note that this is separate from the
 227 integrity table of the WIM, which provides SHA1 message digests over raw chunks
 228 of the entire WIM file and is checked separately if the \fB--check\fR option is
 229 specified.
 230
 231 You cannot use \fBimagex apply\fR to apply a WIM from a pipe (such as standard
 232 input) because the WIM file format is not designed for this.
 233
 234 .SH EXAMPLES
 235 .SS Normal extraction mode
 236 Extract the first image from the Windows PE image from the Windows Vista/7/8
 237 installation media to the directory "boot":
 238 .RS
 239 .PP
 240 image apply /media/windows/sources/boot.wim 1 boot
 241 .RE
 242 .PP
 243 Extract all images from the Windows PE image from the Windows Vista/7/8
 244 installation media to the directory "boot", and hard link all identical files:
 245 .RS
 246 .PP
 247 image apply /media/windows8/sources/boot.wim all boot --hardlink
 248 .RE
 249 .PP
 250 .SS NTFS extraction mode
 251 Apply a WIM image to a NTFS filesystem image:
 252 .RS
 253 .PP
 254 imagex apply mywim.wim 1 fsimage.ntfs
 255 .RE
 256 .PP
 257 Create a new NTFS filesystem on the partition /dev/sda2 and apply the first
 258 image in the Windows Vista/7/8 installation WIM to it.  (Obviously, only do this
 259 if you want to erase everything on that partition.)
 260 .RS
 261 .PP
 262 mkntfs /dev/sda2 && imagex apply /media/windows/sources/install.wim 1 /dev/sda2
 263 .RE
 264 .PP
 265
 266 .SH SEE ALSO
 267 .BR imagex (1)
 268