1 .TH WIMCAPTURE "1" "July 2017" "wimlib 1.12.0" "User Commands"
3 wimcapture, wimappend \- Capture or append a WIM image
5 \fBwimcapture\fR \fISOURCE\fR \fIWIMFILE\fR [\fIIMAGE_NAME\fR \ [\fIIMAGE_DESC\fR]] [\fIOPTION\fR...]
7 \fBwimappend\fR \fISOURCE\fR \fIWIMFILE\fR [\fIIMAGE_NAME\fR \ [\fIIMAGE_DESC\fR]] [\fIOPTION\fR...]
9 The \fBwimcapture\fR (equivalently: \fBwimlib-imagex capture\fR) and
10 \fBwimappend\fR (equivalently: \fBwimlib-imagex append\fR) commands create
11 ("capture") a new Windows Imaging (WIM) image. \fBwimcapture\fR creates a new
12 WIM archive \fIWIMFILE\fR to contain the new image, while \fBwimappend\fR adds
13 the image to the existing WIM archive \fIWIMFILE\fR.
15 \fISOURCE\fR specifies the location of the files from which to create the WIM
16 image. If \fISOURCE\fR is a directory or a symbolic link pointing to a
17 directory, then the image is captured from that directory as per \fBDIRECTORY
18 CAPTURE (UNIX)\fR or \fBDIRECTORY CAPTURE (WINDOWS)\fR. Alternatively, if
19 \fB--source-list\fR is specified, then \fISOURCE\fR is interpreted as a file
20 containing a list of files and directories to include in the image. Still
21 alternatively, if \fISOURCE\fR is a UNIX block device, then an image is captured
22 from the NTFS volume on it as per \fBNTFS VOLUME CAPTURE (UNIX)\fR.
24 \fIIMAGE_NAME\fR and \fIIMAGE_DESC\fR specify the name and description to give
25 the new image. If \fIIMAGE_NAME\fR is unspecified, it defaults to the filename
26 component of \fISOURCE\fR, appending a unique suffix if needed. Otherwise,
27 \fIIMAGE_NAME\fR must be either a name not already used by an image in
28 \fIWIMFILE\fR, or the empty string to create an unnamed image. If
29 \fIIMAGE_DESC\fR is unspecified then the new image is given no description.
31 If \fIWIMFILE\fR is specified as "-", then the \fB--pipable\fR option is assumed
32 and a pipable WIM is written to standard output (this is a wimlib extension).
33 .SH DIRECTORY CAPTURE (UNIX)
34 On UNIX-like systems, if \fISOURCE\fR specifies a directory or a symbolic link
35 to a directory, then the WIM image will be captured from that directory. The
36 directory can be on any type of filesystem, and mountpoints are followed. In
37 this mode, the following types of information are captured:
39 Directories and regular files, and the contents of regular files
43 Symbolic links (translated losslessly to Windows reparse points)
45 Last modification times (mtime) and last access times (atime) with 100
46 nanosecond granularity
48 Files that appear to be sparse will be flagged as such, but their full data will
49 still be stored, subject to the usual compression.
51 With \fB--unix-data\fR: standard UNIX file permissions (owner, group, and mode)
53 With \fB--unix-data\fR: device nodes, named pipes, and sockets
55 With \fB--unix-data\fR: extended attributes (Linux only)
57 There is no support for storing last status change times (ctimes), or hard link
58 information for symlinks (each symlink will be stored as a separate file).
59 Also, filenames and symlink targets which are not valid UTF-8 with the addition
60 of surrogate codepoints are unsupported. Note that if you have a filesystem
61 containing filenames in another multibyte encoding, such as ISO-8859-1, and you
62 wish to archive it with wimlib, you may be able to mount it with an option which
63 causes its filenames to be presented as UTF-8.
64 .SH NTFS VOLUME CAPTURE (UNIX)
65 On UNIX-like systems, \fISOURCE\fR may also be specified as a block device (e.g.
66 /dev/sda3) containing an unmounted NTFS volume. In this mode, \fBwimcapture\fR
67 uses libntfs-3g to capture a WIM image from root directory of the NTFS volume.
68 In this mode, as much data and metadata as possible is captured, including
69 NTFS-specific and Windows-specific metadata:
71 All data streams of all unencrypted files, including the unnamed data stream as
72 well as all named data streams.
74 Reparse points. See \fBREPARSE POINTS AND SYMLINKS\fR for details.
76 File and directory creation, access, and modification timestamps, using the
77 native NTFS resolution of 100 nanoseconds.
79 Windows security descriptors, including all components (owner, group, DACL, and
82 DOS/Windows file attribute flags.
84 All names of all files, including names in the Win32 namespace, DOS namespace,
85 Win32+DOS namespace, and POSIX namespace. This includes hard links.
89 However, the main limitations of this mode are:
91 Encrypted files are excluded.
93 Sparse files will be flagged as such, but their full data will still be stored,
94 subject to the usual compression.
96 Some types of reparse points are transparently dereferenced by Windows but not
97 by NTFS-3G. See \fBREPARSE POINTS AND SYMLINKS\fR.
99 Note that this mode uses libntfs-3g directly, without going through the
100 \fBntfs-3g\fR(8) driver. Hence, there is no special support for capturing a WIM
101 image from a directory on which an NTFS filesystem has been mounted using
102 \fBntfs-3g\fR(8); you have to unmount it first. There is also no support for
103 capturing a subdirectory of the NTFS volume; you can only capture the full
105 .SH DIRECTORY CAPTURE (WINDOWS)
106 On Windows, \fBwimcapture\fR and \fBwimappend\fR natively support
107 Windows-specific and NTFS-specific data. They therefore act similarly to the
108 corresponding commands of Microsoft's ImageX or DISM. For best results, the
109 directory being captured should be on an NTFS volume and the program should be
110 run with Administrator privileges; however, non-NTFS filesystems and running
111 without Administrator privileges are also supported, subject to limitations.
113 On Windows, \fBwimcapture\fR and \fBwimappend\fR try to capture as much data and
114 metadata as possible, including:
116 All data streams of all files.
118 Reparse points, if supported by the source filesystem. See \fBREPARSE POINTS
119 AND SYMLINKS\fR for details.
121 File and directory creation, access, and modification timestamps. These are
122 stored with Windows' native timestamp resolution of 100 nanoseconds.
124 Security descriptors, if supported by the source filesystem and \fB--no-acls\fR
125 is not specified. Note: when not running as an Administrator, security
126 descriptors may be only partially captured (see \fB--strict-acls\fR).
128 File attributes, including hidden, sparse, compressed, encrypted, etc.
129 Encrypted files will be stored in encrypted form rather than in plain text.
130 Transparently compressed files will be read as uncompressed and stored subject
131 to the WIM's own compression. There is no special handling for storing sparse
132 files, but they are likely to compress to a small size.
134 DOS names (8.3) names of files; however, the failure to read them is not
135 considered an error condition.
137 Hard links, if supported by the source filesystem.
139 Object IDs, if supported by the source filesystem.
141 There is no support yet for capturing NTFS extended attributes.
142 .SH REPARSE POINTS AND SYMLINKS
143 A "symbolic link" (or "symlink") is a special file which "points to" some other
144 file or directory. On Windows, a "reparse point" is a generalization of a
145 symlink which allows access to a file or directory to be redirected in a more
146 complex way. Windows uses reparse points to implement symlinks and sometimes
147 uses them for various other features as well. Normally, applications can choose
148 whether they want to "dereference" reparse points and symlinks or not.
150 The default behavior of \fBwimcapture\fR is that reparse points and symlinks are
151 \fInot\fR dereferenced, meaning that the reparse points or symlinks themselves
152 are stored in the archive rather than the files or data they point to. There is
153 a \fB--dereference\fR option, but it is currently only supported by the UNIX
154 version of \fBwimcapture\fR on UNIX filesystems (it's not yet implemented for
155 Windows filesystems).
157 Windows also treats certain types of reparse points specially. For example,
158 Windows applications reading from deduplicated, WIM-backed, or system-compressed
159 files always see the dereferenced data, even if they ask not to. Therefore,
160 \fBwimcapture\fR on Windows will store these files dereferenced, not as reparse
161 points. But \fBwimcapture\fR on UNIX in NTFS-3G mode cannot dereference these
162 files and will store them as reparse points instead. This difference can be
163 significant in certain situations, e.g. when capturing deduplicated files which,
164 to be readable after extraction, require that the chunk store also be present.
168 Mark the new image as the "bootable" image of the WIM. The "bootable" image is
169 the image which the Windows bootloader will use when loading Windows PE from the
173 Include extra integrity information in the resulting WIM. With \fBwimappend\fR,
174 also check the integrity of the WIM before appending to it.
176 \fB--compress\fR=\fITYPE\fR[:\fILEVEL\fR]
177 With \fBwimcapture\fR, use the specified compression format in the new WIM file.
178 \fITYPE\fR may be "none", "XPRESS" (alias: "fast"), "LZX" (alias: "maximum"), or
179 "LZMS" (alias: "recovery"). \fITYPE\fR is matched case-insensitively. The
182 You can optionally also specify an integer compression \fILEVEL\fR. The
183 compression level specifies how hard the compression algorithm for the specified
184 compression \fITYPE\fR will work to compress the data. The values are scaled so
185 that 20 is quick compression, 50 is medium compression, and 100 is high
186 compression. However, you can choose any value and not just these particular
187 values. The default is 50.
189 This option only affects the compression type used in non-solid WIM resources.
190 If you are creating a solid WIM (using the \fB--solid\fR option), then you
191 probably want \fB--solid-compress\fR instead.
193 Be careful if you choose LZMS compression. It is not compatible with wimlib
194 before v1.6.0, WIMGAPI before Windows 8, DISM before Windows 8.1, and 7-Zip
195 before v15.12. Also note that choosing LZMS compression does not automatically
196 imply solid-mode compression, as it does with DISM. Use \fB--solid\fR if you
197 want to create a solid WIM, or "ESD file".
199 \fB--chunk-size\fR=\fISIZE\fR
200 With \fBwimcapture\fR, use a compression chunk size of \fISIZE\fR bytes. A
201 larger compression chunk size results in a better compression ratio. wimlib
202 supports different chunk sizes depending on the compression type:
205 XPRESS: 4K, 8K, 16K, 32K, 64K
207 LZX: 32K, 64K, 128K, 256K, 512K, 1M, 2M
209 LZMS: 32K, 64K, 128K, 256K, 512K, 1M, 2M, 4M, 8M, 16M, 32M, 64M, 128M, 256M, 512M, 1G
212 You can provide the full number (e.g. 32768), or you can use one of the K, M, or
213 G suffixes. KiB, MiB, and GiB are also accepted.
215 This option only affects the chunk size used in non-solid WIM resources. If you
216 are creating a solid WIM (using the \fB--solid\fR option), then you probably
217 want \fB--solid-chunk-size\fR instead.
219 Use this option with caution if compatibility with Microsoft's WIM software is
220 desired, since their software has limited support for non-default chunk sizes.
223 With \fBwimcapture\fR, create a "solid" WIM file that compresses files together
224 rather than independently. This results in a significantly better compression
225 ratio, but it comes at the cost of slow compression with very high memory usage,
226 reduced compatibility, and slow random access to the resulting WIM file.
228 By default this enables solid LZMS compression, thereby creating a file
229 equivalent to one created with DISM's \fB/compress\fR:\fIrecovery\fR option.
230 Such files are also called "ESD files" and were first supported by WIMGAPI in
231 Windows 8, by DISM in Windows 8.1, and by 7-Zip 15.12.
233 \fB--solid-compress\fR=\fITYPE\fR[:\fILEVEL\fR]
234 Like \fB--compress\fR, but set the compression type used in solid resources.
235 The default is LZMS compression. This option only has an effect when
236 \fB--solid\fR is also specified.
238 \fB--solid-chunk-size\fR=\fISIZE\fR
239 Like \fB--chunk-size\fR, but set the chunk size used in solid resources. The
240 default, assuming LZMS compression, is 64MiB (67108864); this requires about
241 640MiB of memory per thread. This option only has an effect when \fB--solid\fR
242 is also specified. Note: Microsoft's WIM software is not compatible with LZMS
243 chunk sizes larger than 64MiB.
245 \fB--threads\fR=\fINUM_THREADS\fR
246 Number of threads to use for compressing data. Default: autodetect (number of
250 With \fBwimappend\fR, rebuild the entire WIM rather than appending the new data
251 to the end of it. Rebuilding the WIM is slower, but will save some space that
252 would otherwise be left as a hole in the WIM. Also see \fBwimoptimize\fR(1).
254 \fB--flags\fR=\fIEDITIONID\fR
255 Specify a string to use in the <FLAGS> element of the XML data for the new
258 \fB--image-property\fR \fINAME\fR=\fIVALUE\fR
259 Assign an arbitrary property to the new image in the XML document of the WIM.
260 \fIVALUE\fR is the string to set as the property value. \fINAME\fR is the name
261 of the image property, for example "NAME", "DESCRIPTION", or "TOTALBYTES". The
262 name can contain forward slashes to indicate a nested XML element; for example,
263 "WINDOWS/VERSION/BUILD" indicates the BUILD element nested within the VERSION
264 element nested within the WINDOWS element. A bracketed number can be used to
265 indicate one of several identically-named elements; for example,
266 "WINDOWS/LANGUAGES/LANGUAGE[2]" indicates the second "LANGUAGE" element nested
267 within the "WINDOWS/LANGUAGES" element. When adding a list of elements in this
268 way, they must be specified in sequential order. Note that element names are
269 case-sensitive. This option may be specified multiple times.
272 (UNIX-like systems only) Follow symbolic links and archive the files they point
273 to, rather than archiving the links themselves.
275 \fB--config\fR=\fIFILE\fR
276 Specifies a configuration file (UTF-8 or UTF-16LE encoded; plain ASCII also
277 works) for capturing the new image. The configuration file specifies files that
278 are to be treated specially during the image capture.
280 The format of the configuration file is INI-style; that is, it is arranged in
281 bracketed sections. Currently, the following sections are recognized:
284 [ExclusionList] --- contains a list of path globs to exclude from capture. If
285 a directory is matched, both the directory and its contents are excluded.
287 [ExclusionException] --- contains a list of path globs to include in the
288 capture, even when the file or directory also matches a glob in [ExclusionList].
290 [PrepopulateList] --- this does not affect capture, but if the image is applied
291 later with \fB--wimboot\fR, these are globs of files that shall be extracted
292 normally, not as WIMBoot "pointer files". If a directory is matched, all files
293 and subdirectories are also matched recursively.
296 Path globs may contain the '*' and '?' meta-characters. Relative globs (e.g.
297 *.mp3) match against a filename in any directory. Absolute globs (e.g.
298 /dir/file), are treated as paths starting at the main directory being captured,
299 or the root of the NTFS volume for NTFS volume capture mode. Do not use drive
300 letters in the paths; they will be ignored. Path separators may be either
301 forwards slashes or backwards slashes.
303 Lines beginning with the '#' or ';' characters are treated as comments and
304 ignored. Globs with whitespace in them need not be quoted; however, if they
305 are, both double and single quotes are accepted.
307 If this option is not specified the following default configuration file is
318 \\System Volume Information
327 However, special behavior applies if \fB--wimboot\fR is also specified. By
328 default, with \fB--wimboot\fR specified, the file
329 Windows/System32/WimBootCompress.ini in the directory being captured will be
330 used as the configuration file. However, this can be overridden using
331 \fB--config\fR; and this also causes the specified configuration file to be
332 saved in the WIM image as Windows/System32/WimBootCompress.ini, overriding any
333 that may be present on the filesystem.
336 (UNIX-like systems only) Store UNIX-specific metadata and special files. This
337 includes: standard UNIX file permissions (owner, group, and mode); device nodes,
338 named pipes, and sockets; and extended attributes (Linux only). This
339 information can later be restored by \fBwimapply\fR with the \fB--unix-data\fR
342 UNIX-specific information is ignored by Microsoft's WIM software and by the
343 Windows version of wimlib.
346 Do not capture files' security descriptors.
349 Fail immediately if the full security descriptor of any file cannot be read. On
350 Windows, the default behavior without this option is to first try omitting the
351 SACL from the security descriptor, then to try omitting the security descriptor
352 entirely. The purpose of this is to capture as much data as possible without
353 always requiring Administrator privileges. However, if you desire that all
354 security descriptors be captured exactly, you may wish to provide this option,
355 although the Administrator should have permission to read everything anyway.
357 \fB--rpfix\fR, \fB--norpfix\fR
358 Set whether to fix targets of absolute symbolic links (reparse points in Windows
359 terminology) or not. When enabled (\fB--rpfix\fR), absolute symbolic links that
360 point inside the directory tree being captured will be adjusted to be absolute
361 relative to the root of the directory tree being captured. When disabled
362 (\fB--norpfix\fR), absolute symbolic links will be captured exactly as is.
364 The default behavior of \fBwimcapture\fR is equivalent to \fB--rpfix\fR. The
365 default behavior of \fBwimappend\fR is equivalent to \fB--rpfix\fR if reparse
366 point fixups have previously been done on \fIWIMFILE\fR, otherwise
369 In the case of a multi-source capture, (\fB--source-list\fR specified), passing
370 \fB--norpfix\fR is recommended. Otherwise, reparse point fixups will be
371 disabled on all capture sources destined for non-root locations in the WIM
372 image, while capture sources destined for the WIM root will get the default
373 behavior from the previous paragraph.
376 \fBwimcapture\fR and \fBwimappend\fR support creating a WIM image from multiple
377 separate files or directories. When \fB--source-list\fR is specified, the
378 \fISOURCE\fR argument specifies the name of a text file, each line of which is
379 either 1 or 2 whitespace separated file paths. The first file path, the source,
380 specifies the path to a file or directory to capture into the WIM image. It may
381 be either absolute or relative to the current working directory. The second
382 file path, if provided, is the target and specifies the path in the WIM image
383 that this file or directory will be saved as. Leading and trailing slashes in
384 the target are ignored, except if it consists entirely of slashes (e.g. "/"),
385 which indicates that the directory is to become the root of the WIM image. If
386 omitted, the target string defaults to the same as the source string.
388 An example source list file is as follows:
393 # Make the WIM image from the 'winpe' directory
396 # Send the 'overlay' directory to '/overlay' in the WIM image
399 # Overlay a separate directory directly on the root of the WIM image.
405 Subdirectories in the WIM are created as needed. Multiple source directories
406 may share the same target, which implies an overlay. In the event that this
407 results a nondirectory file being added to the WIM image multiple times, the
408 last version (as listed in the source list file) overrides any earlier version.
410 File paths containing whitespace may be quoted with either single quotes or
411 double quotes. Quotes may not be escaped.
413 Lines consisting only of whitespace and lines beginning with '#' preceded by
414 optional whitespace are ignored.
416 As a special case, if \fISOURCE\fR is "-", the source list is read from standard
417 input rather than an external file.
419 The NTFS volume capture mode on UNIX-like systems cannot be used with
420 \fB--source-list\fR, as only capturing a full NTFS volume is supported.
423 With \fBwimcapture\fR, create a wimlib-specific "pipable" WIM which can be
424 captured and applied fully sequentially. If \fIWIMFILE\fR is specified as "-",
425 then the pipable WIM is written directly to standard output; otherwise, it is
426 written to disk as usual. The image in the pipable WIM can be later be applied
427 with \fBwimapply\fR, either from disk or from standard input. A typical use of
428 pipable WIMs might involve streaming the WIM image to a remote server when
429 capturing it and/or streaming the WIM image from a remote server when applying
432 Generally, all the \fBwimlib-imagex\fR commands work on both pipable and
433 non-pipable WIMs. \fBwimoptimize\fR and \fBwimexport\fR may also be used to
434 convert between pipable WIMs and non-pipable WIMs. However, there are a few
435 limitations of pipable WIMs:
438 Pipable WIMs are a wimlib extension which are \fInot\fR compatible with
439 Microsoft's WIM software or with other programs such as 7-Zip.
441 Using \fBwimappend\fR, multiple images may be added to a pipable WIM. This is
442 supported, though it is less efficient than doing so with non-pipable WIMs
443 because a pipable WIM is fully rebuilt each time it is appended to; and when
444 piping such a WIM to \fBwimapply\fR to extract an image, some unneeded data will
445 be sent over the pipe.
447 Although a pipable WIM image may be updated using \fBwimupdate\fR, it requires a
448 full rebuild of the WIM file, making it less efficient than updating a
451 Solid pipable WIMs are not yet supported.
455 With \fBwimappend\fR, rebuild the WIM file in the non-pipable (regular) format.
456 This option is only useful if you happen to be adding an image to a pipable WIM
457 (see \fB--pipable\fR) which you want in non-pipable format instead. Note that
458 \fBwimoptimize\fR(1) can also be used to convert between non-pipable and pipable
461 \fB--update-of\fR=[\fIWIMFILE\fR:]\fIIMAGE\fR
462 Hint that the image being captured or appended from \fISOURCE\fR is mostly the
463 same as the existing image \fIIMAGE\fR in \fIWIMFILE\fR, but captured at a later
464 point in time, possibly with some modifications in the intervening time. This
465 is designed to be used in incremental backups of the same filesystem or
466 directory tree. \fIIMAGE\fR can be a 1-based index or name of an existing image
467 in \fIWIMFILE\fR. It can also be a negative integer to index backwards into the
468 images (e.g. -1 means the last existing image in \fIWIMFILE\fR).
470 When this option is provided, the capture or append of the new image will be
471 optimized by not reading files that, based on metadata such as timestamps,
472 appear not to have been modified since they were archived in the existing
473 \fIIMAGE\fR. Barring manipulation of timestamps, this option only affects
474 performance and does not change the resulting WIM image (but see note below).
476 As shown, the full syntax for the argument to this option is to specify the WIM
477 file, a colon, and the image; for example, "--update-of mywim.wim:1". However,
478 the WIM file and colon may be omitted if \fB--delta-from\fR is specified exactly
479 once, in which case the WIM defaults to that specified in \fB--delta-from\fR, or
480 if the operation is \fBwimappend\fR rather \fBwimcapture\fR, in which case the
481 WIM defaults to the one being appended to.
483 Note: in the Windows version of wimlib, it has been observed that
484 \fB--update-of\fR mode is not completely reliable at detecting changes in file
485 contents, sometimes causing the old contents of a few files to be archived
486 rather than the current contents. The cause of this problem is that Windows
487 does not immediately update a file's last modification timestamp after every
488 write to that file. Unfortunately, there is no known way for applications like
489 wimlib to automatically work around this bug. Manual workarounds are possible;
490 theoretically, taking any action that causes the problematic files to be closed,
491 such as restarting applications or the computer itself, should cause the files'
492 last modification timestamps to be updated. Also note that wimlib compares file
493 sizes as well as timestamps in determining whether a file has changed, which
494 helps make the problem less likely to occur; and the problem does not occur on
495 other operating systems such as Linux which maintain files' last modification
496 timestamps correctly.
498 \fB--delta-from\fR=\fIWIMFILE\fR
499 Capture or append the new image as a "delta" from \fIWIMFILE\fR. Any file data
500 that would ordinarily need to be archived in the new or updated WIM is omitted
501 if it is already present in the \fIWIMFILE\fR on which the delta is being based.
502 The resulting WIM will still contain a full copy of the image metadata, but this
503 is typically only a small fraction of a WIM's total size.
505 This option can be specified multiple times, in which case the resulting delta
506 WIM will only contain file data not present in any of the specified base WIMs.
508 To operate on the resulting delta WIM using other commands such as
509 \fBwimapply\fR, you must specify the delta WIM as the WIM file to operate on,
510 but also reference the base WIM(s) using the \fB--ref\fR option. Beware: to
511 retain the proper functioning of the delta WIM, you can only add, not delete,
512 files and images to the base WIM(s) following the capture of a delta from it.
514 \fB--delta-from\fR may be combined with \fB--update-of\fR to increase the
515 speed of capturing a delta WIM.
517 As an example, consider the following backup and restore sequence:
523 $ wimcapture /some/directory bkup-base.wim
525 (some days later, create second backup as delta from first)
527 $ wimcapture /some/directory bkup-2013-08-20.dwm \\
528 --update-of bkup-base.wim:-1 --delta-from bkup-base.wim
530 (restoring the second backup)
532 $ wimapply bkup-2013-08-20.dwm --ref=bkup-base.wim 1 \\
537 However, note that as an alternative to the above sequence that used a delta
538 WIM, the second backup could have simply been appended to the WIM as new image
539 using \fBwimappend\fR. Delta WIMs should be used only if it's desired to base
540 the backups or images on a separate, large file that is rarely modified.
542 \fB--delta-from\fR is supported by both \fBwimcapture\fR and \fBwimappend\fR.
544 Delta WIMs are compatible with Microsoft's WIM software. For example, you can
545 use the /ref option of ImageX to reference the base WIM(s), similar to above.
547 Additional note: wimlib is generalized enough that you can in fact combine
548 \fB--pipable\fR and \fB--delta-from\fR to create pipable delta WIMs. In such
549 cases, the base WIM(s) must be captured as pipable as well as the delta WIM, and
550 when applying an image, the base WIM(s) must be sent over the pipe after the
554 Mark the image as WIMBoot-compatible. See Microsoft's documentation for more
555 information about WIMBoot. With \fBwimcapture\fR this option will set the
556 compression type to XPRESS and the chunk size to 4096 bytes; these can, however,
557 still be overridden through the \fB--compress\fR and \fB--chunk-size\fR
558 parameters, respectively. In addition, this option will set the configuration
559 file to \fISOURCE\fR\\Windows\\System32\\WimBootCompress.ini if present and
560 accessible; however, this may still be overridden through the \fB--config\fR
563 \fB--unsafe-compact\fR
564 With \fBwimappend\fR, compact the WIM archive in-place and append any new data,
565 eliminating "holes". This is efficient, but in general this option should
566 \fInot\fR be used because a failed or interrupted compaction will corrupt the
567 WIM archive. For more information, see the documentation for this option to
568 \fBwimoptimize\fR(1).
571 Create a temporary filesystem snapshot of the source directory and capture the
572 files from it. Currently, this option is only supported on Windows, where it
573 uses the Volume Shadow Copy Service (VSS). Using this option, you can create a
574 consistent backup of the system volume of a running Windows system without
575 running into problems with locked files. For the VSS snapshot to be
576 successfully created, \fBwimlib-imagex\fR must be run as an Administrator, and
577 it cannot be run in WoW64 mode (i.e. if Windows is 64-bit, then
578 \fBwimlib-imagex\fR must be 64-bit as well).
580 \fBwimappend\fR does not support appending an image to a split WIM.
582 Except when using \fB--unsafe-compact\fR, it is safe to abort a \fBwimappend\fR
583 command partway through; however, after doing this, it is recommended to run
584 \fBwimoptimize\fR to remove any data that was appended to the physical WIM file
585 but not yet incorporated into the structure of the WIM, unless the WIM was being
586 fully rebuilt (e.g. with \fB--rebuild\fR), in which case you should delete the
587 temporary file left over.
589 \fBwimlib-imagex\fR creates WIMs compatible with Microsoft's software (WIMGAPI,
590 ImageX, DISM), with some caveats:
592 With \fBwimlib-imagex\fR on UNIX-like systems, it is possible to create a WIM
593 image containing files with names differing only in case, or files with names
594 containing the characters ':', '*', '?', '"', '<', '>', '|', or '\\', which are
595 valid on POSIX-compliant filesystems but not Windows. Be warned that such files
596 will not be extracted by default by the Windows version of \fBwimlib-imagex\fR,
597 and (even worse) Microsoft's ImageX can be confused by such names and quit
598 extracting the image partway through.
600 Pipable WIMs are incompatible with Microsoft's software. Pipable WIMs are
601 created only if \fIWIMFILE\fR was specified as "-" (standard output) or if
602 the \fB--pipable\fR flag was specified.
604 WIMs captured with a non-default chunk size (with the \fB--chunk-size\fR option)
605 or as solid archives (with the \fB--solid\fR option) or with LZMS compression
606 (with \fB--compress\fR=LZMS or \fB--compress\fR=recovery) have varying levels of
607 compatibility with Microsoft's software. Generally, more recent versions of
608 Microsoft's software are more compatible.
610 First example: Create a new WIM 'mywim.wim' with LZX ("maximum") compression
611 that will contain a captured image of the directory tree 'somedir'. Note that
612 the image name need not be specified and will default to 'somedir':
615 wimcapture somedir mywim.wim
618 Next, append the image of a different directory tree to the WIM created above:
621 wimappend anotherdir mywim.wim
624 Easy enough, and the above examples of imaging directory trees work on both
625 UNIX-like systems and Windows. Next, capture a WIM with several non-default
626 options, including XPRESS ("fast") compression, extra integrity information, no
627 messing with absolute symbolic links, and an image name and description:
630 wimcapture somedir mywim.wim --compress=fast \\
632 --check --norpfix "Some Name" "Some Description"
636 On a UNIX-like system, capture a full NTFS volume into a new WIM using the
637 \fBNTFS VOLUME CAPTURE (UNIX)\fR mode, and name the image "Windows 7":
640 wimcapture /dev/sda2 windows7.wim "Windows 7"
643 or, on Windows, to capture a full NTFS volume you instead need to specify the
644 root directory of the mounted volume, for example:
647 wimcapture E:\\ windows7.wim "Windows 7"
650 Same as UNIX example above, but capture the WIM in the wimlib-specific "pipable"
651 format that can be piped to \fBwimapply\fR:
654 wimcapture /dev/sda2 windows7.wim "Windows 7" --pipable
657 Same as above, but instead of writing the pipable WIM to the file
658 "windows7.wim", write it directly to standard output through a pipe into some
659 other program "someprog", which could, for example, be a program or script that
660 streams the data to a server:
663 wimcapture /dev/sda2 - "Windows 7" | someprog
666 .BR wimlib-imagex (1),
git://wimlib.net / wimlib / blob