1WIMAPPLY(1)                      User Commands                     WIMAPPLY(1)
2
3
4

NAME

6       wimapply - Apply a WIM image
7

SYNOPSIS

9       wimapply WIMFILE [IMAGE] TARGET [OPTION...]
10

DESCRIPTION

12       wimapply,  or equivalently wimlib-imagex apply, extracts ("applies") an
13       image, or all images, from the Windows Imaging (WIM) archive WIMFILE.
14
15       IMAGE specifies the image in WIMFILE to extract.  It may be the 1-based
16       index  of an image, the name of an image, or the keyword "all" to spec‐
17       ify all images.  It may be omitted if WIMFILE contains only one  image.
18       You can use wiminfo(1) to list the images contained in WIMFILE.
19
20       TARGET  specifies where to extract the image(s) to.  If TARGET is a di‐
21       rectory, then the image(s) will be extracted to that directory  as  per
22       DIRECTORY EXTRACTION (UNIX) or DIRECTORY EXTRACTION (WINDOWS).  If TAR‐
23       GET does not exist, then a directory will be created there first.   Al‐
24       ternatively,  if  TARGET  specifies a UNIX block device, then the image
25       will be extracted to it as described in NTFS VOLUME EXTRACTION (UNIX).
26
27       Note that wimapply is designed to extract, or "apply", full WIM images.
28       If you instead want to extract only certain files or directories from a
29       WIM image, use wimextract(1) instead.
30
31       If IMAGE is "all", then all images in WIMFILE will  be  extracted  into
32       subdirectories  of  TARGET  named after the images, falling back to the
33       image index when an image has no name or an unusual name.  This is  not
34       yet supported in NTFS VOLUME EXTRACTION (UNIX) mode.
35
36       If WIMFILE is "-", then the WIM is read from standard input rather than
37       from disk.  See PIPABLE WIMS for more information.
38

DIRECTORY EXTRACTION (UNIX)

40       On UNIX-like systems, a WIM image may  be  extracted  to  a  directory.
41       This  mode  has  the  limitation that NTFS or Windows-specific metadata
42       will not be extracted.  Although some concepts such as hard links, sym‐
43       bolic  links,  last access timestamps, and last modification timestamps
44       will be translated to their UNIX equivalents, other  metadata  will  be
45       lost  (with  warnings given).  Notably, the following types of metadata
46       will not be extracted in this mode:
47
48       •   Windows file attribute flags
49
50       •   Windows security descriptors (e.g. file owners and DACLs)
51
52       •   File creation timestamps
53
54       •   Reparse points other than symbolic links and junction points
55
56       •   Named data streams
57
58       •   Short filenames (also known as 8.3 names or DOS names).
59
60       •   Object IDs
61
62       These same limitations apply to wimextract.  As such, this mode is most
63       useful  in  situations where NTFS or Windows-specific metadata is unim‐
64       portant, e.g. when wanting to extract specific  files,  or  when  doing
65       file  archiving only on UNIX-like systems, possibly in combination with
66       --unix-data.  When Windows-specific metadata is important, then  either
67       the  NTFS  VOLUME EXTRACTION (UNIX) mode should be used, or the Windows
68       version of wimlib should be used (see DIRECTORY EXTRACTION (WINDOWS)).
69

NTFS VOLUME EXTRACTION (UNIX)

71       On UNIX-like systems, TARGET may also be specified as  a  block  device
72       (e.g.   /dev/sda3)  containing an unmounted NTFS volume.  In this mode,
73       wimapply uses libntfs-3g to apply the specified WIM image to  the  root
74       directory  of the NTFS volume.  The target volume should be empty, e.g.
75       newly created by mkntfs(8).  In this mode, NTFS-specific  and  Windows-
76       specific data and metadata will be extracted, including the following:
77
78       •   All data streams of all files except encrypted files, including the
79           unnamed data stream as well as all named data streams.
80
81       •   Reparse points, including  symbolic  links,  junction  points,  and
82           other reparse points.
83
84       •   File  and  directory creation, access, and modification timestamps,
85           using the native NTFS resolution of 100 nanoseconds.
86
87       •   Windows security  descriptors,  including  all  components  (owner,
88           group, DACL, and SACL).
89
90       •   Windows file attribute flags
91
92       •   All names of all files, including names in the Win32 namespace, DOS
93           namespace, Win32+DOS namespace, and POSIX namespace.  This includes
94           hard links.
95
96       •   Object IDs.
97
98       However, encrypted files will not be extracted.
99
100       Restoring  extended  attributes (EAs) is also not yet supported in this
101       mode.
102
103       Regardless, since almost all information from the WIM image is restored
104       in  this mode, it is possible (and fully supported) to restore an image
105       of an actual Windows installation using wimapply on a UNIX-like  system
106       as  an  alternative to using wimapply or DISM on Windows.  In the EXAM‐
107       PLES section below, there is an example of applying an  image  from  an
108       "install.wim" file as may be found in the Windows installation media.
109
110       Note  that  to  actually  boot Windows (Vista or later) from an applied
111       "install.wim" image, you also need to mark the partition as  "bootable"
112       and  set  up  various  boot files, such as \BOOTMGR and \BOOT\BCD.  The
113       latter task is most easily accomplished by running bcdboot.exe  from  a
114       live  Windows system such as Windows PE, but there are other options as
115       well.
116
117       Finally, note that this mode uses libntfs-3g  directly,  without  going
118       through  the ntfs-3g(8) driver.  Hence, there is no special support for
119       applying a WIM image to a directory on which  an  NTFS  filesystem  has
120       been  mounted using ntfs-3g(8); you have to unmount it first.  There is
121       also no support for applying a WIM image to some  subdirectory  of  the
122       NTFS volume; you can only apply to the root directory.
123

DIRECTORY EXTRACTION (WINDOWS)

125       On  Windows,  wimapply  (and wimextract) natively support NTFS and Win‐
126       dows-specific metadata.  For best results, the target directory  should
127       be  located on an NTFS volume and the program should be run with Admin‐
128       istrator privileges; however, non-NTFS filesystems and running  without
129       Administrator privileges are also supported, subject to limitations.
130
131       On Windows, wimapply tries to extract as much data and metadata as pos‐
132       sible, including:
133
134       •   All data streams of all files.  This includes the default file con‐
135           tents,  as  well  as  named data streams if supported by the target
136           volume.
137
138       •   Reparse points, including  symbolic  links,  junction  points,  and
139           other reparse points, if supported by the target volume.  Restoring
140           symlinks requires Administrator privileges.  Also see  --rpfix  and
141           --norpfix  for details on how absolute symbolic links and junctions
142           are extracted.
143
144       •   File and directory creation, access, and  modification  timestamps,
145           to the highest resolution supported by the target volume.
146
147       •   Security  descriptors, if supported by the filesystem and --no-acls
148           is not specified.  Note that this, in general, requires Administra‐
149           tor privileges, and may be only partially successful if the program
150           is run without Administrator privileges (see --strict-acls).
151
152       •   File attribute  flags,  including  hidden,  compressed,  encrypted,
153           sparse, etc, when supported by the filesystem.
154
155       •   Short filenames (also known as 8.3 names or DOS names).
156
157       •   Hard links, if supported by the target filesystem.
158
159       •   Object IDs, if supported by the target filesystem.
160
161       •   Extended attributes (EAs), if supported by the target filesystem.
162
163       Additional notes about extracting files on Windows:
164
165wimapply  will  issue warnings if unable to extract the exact meta‐
166           data and data of the WIM image due to  limitations  of  the  target
167           filesystem.
168
169       •   Since  encrypted  files  (with  FILE_ATTRIBUTE_ENCRYPTED)  are  not
170           stored in plaintext in the WIM image, wimapply cannot  restore  en‐
171           crypted files to filesystems not supporting encryption.  Therefore,
172           on such filesystems, encrypted files will not be  extracted.   Fur‐
173           thermore, even if encrypted files are restored to a filesystem that
174           supports encryption, they will only be decryptable if  the  decryp‐
175           tion key is available.
176
177       •   Files  with names that cannot be represented on Windows will not be
178           extracted by default; see --include-invalid-names.
179
180       •   Files with full paths over 260 characters (the so-called  MAX_PATH)
181           will  be extracted, but beware that such files will be inaccessible
182           to most Windows software and may not be able to be deleted easily.
183
184       •   On Windows, unless the --no-acls option is specified,  wimlib  will
185           attempt  to restore files' security descriptors exactly as they are
186           provided in the WIM image.  Beware that typical  Windows  installa‐
187           tions contain files whose security descriptors do not allow the Ad‐
188           ministrator to delete them.  Therefore, such files will not be able
189           to be deleted, or in some cases even read, after extracting, unless
190           processed with a specialized program  that  knows  to  acquire  the
191           SE_RESTORE_NAME  and/or SE_BACKUP_NAME privileges which allow over‐
192           riding access control lists.  This is not a bug  in  wimlib,  which
193           works  as designed to correctly restore the data that was archived,
194           but rather a problem with the access rights Windows uses on certain
195           files.  But if you just want the file data and don't care about se‐
196           curity descriptors, use --no-acls to skip  restoring  all  security
197           descriptors.
198
199       •   A  similar  caveat  to the above applies to file attributes such as
200           Readonly, Hidden, and System.  By design, on  Windows  wimlib  will
201           restore  such  file attributes; therefore, extracted files may have
202           those attributes.  If this is not what you want, use  the  --no-at‐
203           tributes option.
204

SPLIT WIMS

206       You may use wimapply to apply images from a split WIM, or wimextract to
207       extract files from a split WIM.  The WIMFILE argument must specify  the
208       first  part  of  the split WIM, while the additional parts of the split
209       WIM must be specified in one or more --ref="GLOB" options.  Since glob‐
210       bing is built into the --ref option, typically only one --ref option is
211       necessary.  For example, the names for the split WIM parts  usually  go
212       something like:
213
214              mywim.swm
215              mywim2.swm
216              mywim3.swm
217              mywim4.swm
218              mywim5.swm
219
220       To apply the first image of this split WIM to the directory "dir", run:
221
222              wimapply mywim.swm 1 dir --ref="mywim*.swm"
223

PIPABLE WIMS

225       wimapply  also supports applying a WIM from a nonseekable file, such as
226       a pipe, provided that the WIM was captured in the  wimlib-specific  pi‐
227       pable  format using --pipable (see wimcapture(1)).  To use standard in‐
228       put as the WIM, specify "-" as WIMFILE.  A possible use of this feature
229       is  to apply a WIM image being streamed from the network.  For example,
230       to apply the first image from a WIM file available on a HTTP server  to
231       an NTFS volume on /dev/sda1, run something like:
232
233              wget -O - http://myserver/mywim.wim | wimapply - 1 /dev/sda1
234
235       Pipable  WIMs  may  also be split into multiple parts, just like normal
236       WIMs.  To apply a split pipable WIM from a pipe, the parts must be con‐
237       catenated  and  all  written  to the pipe.  The first part must be sent
238       first, but the remaining parts may be sent in any order.
239

OPTIONS

241       --check
242             Before applying the image, verify the integrity of WIMFILE if  it
243             has extra integrity information.
244
245       --ref="GLOB"
246             File  glob of additional WIMs or split WIM parts to reference re‐
247             sources from.  See SPLIT_WIMS.  This option can be specified mul‐
248             tiple times.  Note: GLOB is listed in quotes because it is inter‐
249             preted by wimapply and may need to be quoted to  protect  against
250             shell expansion.
251
252       --rpfix, --norpfix
253             Set  whether  to  fix targets of absolute symbolic links (reparse
254             points in Windows terminology) or not.  When  enabled  (--rpfix),
255             extracted  absolute symbolic links that are marked in the WIM im‐
256             age as being fixed are assumed to have absolute targets  relative
257             to  the  image root, and therefore wimapply prepends the absolute
258             path to the extraction target directory to  their  targets.   The
259             intention is that you can apply an image containing absolute sym‐
260             bolic links and still have them be valid after it  has  been  ap‐
261             plied to any location.
262
263             The  default  behavior  is  --rpfix if any images in WIMFILE have
264             been captured with reparse-point fixups done.  Otherwise,  it  is
265             --norpfix.
266
267             Reparse point fixups are never done in the NTFS volume extraction
268             mode on UNIX-like systems.
269
270       --unix-data
271             (UNIX-like systems only)  Restore UNIX-specific metadata and spe‐
272             cial  files that were captured by wimcapture with the --unix-data
273             option.  This includes: standard UNIX  file  permissions  (owner,
274             group, and mode); device nodes, named pipes, and sockets; and ex‐
275             tended attributes (Linux-only).
276
277       --no-acls
278             Do not restore security descriptors on extracted files and direc‐
279             tories.
280
281       --strict-acls
282             Fail  immediately  if the full security descriptor of any file or
283             directory cannot be set exactly as specified in the WIM file.  If
284             this  option  is not specified, when wimapply on Windows does not
285             have permission to set a  security  descriptor  on  an  extracted
286             file,  it falls back to setting it only partially (e.g. with SACL
287             omitted), and in the worst case omits it entirely.  However, this
288             should  only  be a problem when running wimapply without Adminis‐
289             trator rights.  Also, on UNIX-like systems, this flag can also be
290             combined  with --unix-data to cause wimapply to issue an error if
291             UNIX permissions are unable to be applied to an extracted file.
292
293       --no-attributes
294             Do not restore Windows file attributes such as readonly,  hidden,
295             etc.
296
297       --include-invalid-names
298             Extract  files  and  directories  with invalid names by replacing
299             characters and appending a suffix rather than ignoring them.  Ex‐
300             actly what is considered an "invalid" name is platform-dependent.
301
302             On  POSIX-compliant systems, filenames are case-sensitive and may
303             contain any byte except '\0' and ´/',  so  on  a  POSIX-compliant
304             system  this option will only have an effect in the unlikely case
305             that the WIM image for some reason has a filename containing  one
306             of these characters.
307
308             On  Windows,  filenames  are  case-insensitive(*), cannot include
309             control characters, and cannot include the characters '/',  ´\0',
310             '\',  ':', '*', '?', ´"', '<', '>', or '|'.  Ordinarily, files in
311             WIM images should meet these conditions as well. However,  it  is
312             not  guaranteed, and in particular a WIM image captured with wim‐
313             capture on a POSIX-compliant system could contain such files.  By
314             default, invalid names will be ignored, and if there are multiple
315             names differing only in case, one will be chosen to extract arbi‐
316             trarily; however, with --include-invalid-names, all names will be
317             sanitized and extracted in some form.
318
319             (*) Unless the ObCaseInsensitive setting has been set to 0 in the
320             Windows  registry,  in which case certain software, including the
321             Windows version of wimapply, will honor case-sensitive  filenames
322             on NTFS and other compatible filesystems.
323
324       --wimboot
325             Windows only: Instead of extracting the files themselves, extract
326             "pointer files" back to the WIM archive(s).  This can  result  in
327             significant  space  savings.  However, it comes at several poten‐
328             tial costs, such as not being able to delete the  WIM  archive(s)
329             and possibly having slower access to files.  See Microsoft's doc‐
330             umentation for "WIMBoot" for more information.
331
332             If it exists, the [PrepopulateList] section  of  the  file  \Win‐
333             dows\System32\WimBootCompress.ini  in the WIM image will be read.
334             Files matching any of these patterns will be extracted  normally,
335             not  as  WIMBoot  "pointer  files".   This is helpful for certain
336             files that Windows needs to read early in the boot process.
337
338             This option only works when the program is run as an  Administra‐
339             tor and the target volume is NTFS or another filesystem that sup‐
340             ports reparse points.
341
342             In addition, this option works best when running on  Windows  8.1
343             Update  1  or  later,  since that is the first version of Windows
344             that  contains  the  Windows  Overlay  Filesystem  filter  driver
345             ("WOF").   If  the WOF driver is detected, wimlib will create the
346             WIMBoot "pointer files" using documented ioctls provided by WOF.
347
348             Otherwise, if the WOF driver is not detected, wimlib will  create
349             the  reparse  points  and  edit the file "\System Volume Informa‐
350             tion\WimOverlay.dat" on the target volume manually.  This is  po‐
351             tentially  subject  to problems, since although the code works in
352             certain tested cases, neither of these data formats  is  actually
353             documented  by  Microsoft.   Before overwriting this file, wimlib
354             will save  the  previous  version  in  "\System  Volume  Informa‐
355             tion\WimOverlay.wimlib_backup",  which  you potentially could re‐
356             store if you needed to.
357
358             You actually can still do a --wimboot extraction even if the  WIM
359             image  is not marked as "WIMBoot-compatible".  This option causes
360             the extracted files to be set as "externally backed" by  the  WIM
361             file.   Microsoft's  driver which implements this "external back‐
362             ing" functionality seemingly does not care whether  the  image(s)
363             in  the  WIM are really marked as WIMBoot-compatible.  Therefore,
364             the "WIMBoot-compatible" tag (<WIMBOOT> in the XML data) seems to
365             be  a  marker for intent only.  In addition, the Microsoft driver
366             can externally back files from WIM files that use  XPRESS  chunks
367             of  size  8192, 16384, and 32768, or LZX chunks of size 32768, in
368             addition to the default XPRESS chunks of size 4096 that are  cre‐
369             ated when wimcapture is run with the --wimboot option.
370
371       --compact=FORMAT
372             Windows-only:  compress the extracted files using System Compres‐
373             sion, when possible.  This only works on  either  Windows  10  or
374             later,  or  on  an  older Windows to which Microsoft's wofadk.sys
375             driver has been added.  Several different compression formats may
376             be  used  with  System  Compression, and one must be specified as
377             FORMAT.  The choices are: xpress4k, xpress8k, xpress16k, and lzx.
378
379             Exclusions are handled in the same way as with the --wimboot  op‐
380             tion.   That  is:  if it exists, the [PrepopulateList] section of
381             the file \Windows\System32\WimBootCompress.ini in the  WIM  image
382             will be read, and files matching any of the patterns in this sec‐
383             tion will not be compressed.  In addition, wimlib has a hardcoded
384             list of files for which it knows, for compatibility with the Win‐
385             dows bootloader, to override the requested compression format.
386
387       --recover-data
388             If a file is corrupted (its stored hash doesn't match its  actual
389             hash,  or  some  parts  of it can't be decompressed), extract the
390             corrupted file anyway with a warning, rather than  aborting  with
391             an  error.   This  may be useful to recover data if a WIM archive
392             was corrupted.  Note that recovering data is  not  guaranteed  to
393             succeed, as it depends on the type of corruption that occurred.
394

NOTES

396       Data  integrity:  WIM  files include checksums of file data.  To detect
397       accidental  (non-malicious)  data  corruption,  wimlib  calculates  the
398       checksum  of  every file it extracts and issues an error if it does not
399       have the expected value, unless the  --recover-data  option  is  given.
400       (This  default  behavior  seems equivalent to the /verify option of Im‐
401       ageX.)  In addition, a WIM file can include an integrity  table  (extra
402       checksums)  over  the raw data of the entire WIM file.  For performance
403       reasons wimlib does not check the integrity table by default,  but  the
404       --check option can be passed to make it do so.
405
406       ESD  files:  wimlib  can  extract  files from solid-compressed WIMs, or
407       "ESD" (.esd) files, just like from normal WIM (.wim)  files.   However,
408       Microsoft sometimes distributes ESD files with encrypted segments; wim‐
409       lib cannot extract such files until they are first decrypted.
410
411       Security: wimlib has been carefully written to validate all  input  and
412       is  believed  to  be  secure  against some types of attacks which often
413       plague other file archiving programs, e.g. directory traversal  attacks
414       (which, as it happens, Microsoft's WIM software is vulnerable to).  Im‐
415       portant parts of wimlib, e.g. the decompressors, have  also  been  fuzz
416       tested.   However,  wimlib is not currently designed to protect against
417       some types of denial-of-service (DOS) attacks, e.g.  memory  exhaustion
418       or "zip bombs".
419

EXAMPLES

421       Extract  the first image from the Windows PE WIM on the Windows instal‐
422       lation media to the directory "boot":
423
424              wimapply /mnt/windows/sources/boot.wim 1 boot
425
426       On Windows, apply an image of an entire volume, for example  from  "in‐
427       stall.wim" which can be found on the Windows installation media:
428
429              wimapply install.wim 1 E:\
430
431       Same  as above, but running on a UNIX-like system where the correspond‐
432       ing partition is /dev/sda2:
433
434              wimapply install.wim 1 /dev/sda2
435
436       Note that before running either of the above commands, an NTFS filesys‐
437       tem  may  need  to  be  created on the partition, for example with for‐
438       mat.exe on Windows or mkntfs(8) on UNIX-like systems.  For example,  on
439       UNIX you might run:
440
441              mkntfs /dev/sda2 && wimapply install.wim 1 /dev/sda2
442
443       (Of course don't do that if you don't want to destroy all existing data
444       on the partition!)
445
446       See SPLIT WIMS and PIPABLE WIMS for examples of applying split and  pi‐
447       pable WIMs, respectively.
448

SEE ALSO

450       wimlib-imagex(1) wimcapture(1) wimextract(1) wiminfo(1)
451
452
453
454wimlib 1.13.5                    December 2021                     WIMAPPLY(1)
Impressum