-.TH WIMLIB-IMAGEX "1" "January 2015" "wimlib 1.7.4" "User Commands"
+.TH WIMLIB-IMAGEX "1" "November 2015" "wimlib 1.8.3" "User Commands"
.SH NAME
wimlib-imagex-capture, wimlib-imagex-append \- Create or append a WIM image
.SH SYNOPSIS
.PP
On UNIX-like systems, when \fISOURCE\fR specifies a directory or a symbolic link
to a directory, the WIM image will be captured from the directory tree rooted at
-this directory. This directory can be on any type of filesystem, and mount
-points are followed recursively. However, it is important to keep in mind that
-the WIM format was designed for Windows, so it cannot store all possible
-metadata from filesystems used on UNIX-like systems. The main information that
-will \fInot\fR be stored is:
+this directory. This directory can be on any type of filesystem, and
+mountpoints are followed recursively. In this mode, wimlib will store the
+following types of information:
.IP \[bu] 4
-UNIX file owners, groups, modes, and device IDs (major and minor numbers),
-unless the \fB--unix-data\fR option is specified. By default (without
-\fB--unix-data\fR), files that are neither regular files, directories, nor
-symbolic links, such as device nodes and FIFOs, will be excluded.
+Directories and regular files, and the contents of regular files
.IP \[bu]
-Extended attributes. This mainly includes extensions to the traditional UNIX
-security model, such as SELinux security labels, POSIX ACLs, and capabilities
-labels.
+Hard links
.IP \[bu]
-Linux file attributes, as can be changed using the \fBchattr\fR (1) utility.
+Symbolic links (translated losslessly to Windows reparse points)
+.IP \[bu]
+Last modification times (mtime) and last access times (atime) with 100
+nanosecond granularity
+.IP \[bu]
+With \fB--unix-data\fR: UNIX owners, groups, and modes
+.IP \[bu]
+With \fB--unix-data\fR: device nodes, FIFOs, and UNIX domain sockets
.PP
-Notes: Timestamps are stored with 100 nanosecond granularity and include last
-modification time (mtime) and last access time (atime), but not last status
-change time (ctime). Hard links and symbolic links are supported by the WIM
-format and \fIare\fR stored. Symbolic links are turned into "native" Windows
-symbolic links, or "reparse points"; this process is fully reversible, e.g.
-automatically by \fBwimlib-imagex apply\fR, unless the symbolic link target
-contains backslash characters.
+There is no support for storing extended attributes (e.g. SELinux security
+labels and POSIX ACLs). Also note that last status change times (ctime) are not
+stored.
.PP
Pedantic note: A limitation of the WIM format prevents the unusual case where a
single symbolic link file itself has multiple names (hard links); in this
image containing the full contents of the NTFS volume, including NTFS-specific
data. This is done using libntfs-3g.
.PP
-Please note that the NTFS volume capture mode is \fInot\fR entered if
-\fISOURCE\fR is a directory, even if an NTFS filesystem is mounted on
-\fISOURCE\fR using ntfs-3g. You must specify the NTFS volume itself (and it
-must be unmounted, and you must have permission to read from it).
+Note that the NTFS volume capture mode is \fInot\fR entered if \fISOURCE\fR is a
+directory, even if an NTFS filesystem is mounted on \fISOURCE\fR using ntfs-3g.
+You must specify the NTFS volume itself (and it must be unmounted, and you must
+have permission to read from it).
.PP
The NTFS volume capture mode attempts to capture as much data and metadata as
possible, including:
.PP
However, the main limitations of this NTFS volume capture mode are:
.IP \[bu] 4
-Encrypted files are excluded by default. Although ntfs-3g can read their data,
-they need to be stored in the WIM file in a special format that wimlib does not
-yet support (except on Windows, where wimlib can treat the data as opaque and
-hand it off to the appropriate API function).
+Encrypted files are excluded by default. Although libntfs-3g can read their
+data, they need to be stored in the WIM file in a special format that wimlib
+does not yet support (except on Windows, where wimlib can treat the data as
+opaque and hand it off to the appropriate API function).
.IP \[bu]
The sparse attribute on sparse files will be saved, but the data stored will be
the full data of the file rather than the "sparse" data. (The data is, however,
.IP \[bu]
Hard links, if supported by the source filesystem.
.PP
-Note: the capture process is reversible, since when \fBwimlib-imagex
-apply\fR (on Windows) extracts the captured WIM image, it will extract all of
-the above information, at least to the extent supported by the destination
-filesystem. One exception is that since encrypted files are stored as
-encrypted, their data will not be available if restored on a Windows system
-that does not have the decryption key.
+There is no support for storing NTFS extended attributes and object IDs.
+.PP
+The capture process is reversible, since when \fBwimlib-imagex apply\fR (on
+Windows) extracts the captured WIM image, it will extract all of the above
+information, at least to the extent supported by the destination filesystem.
.PP
Pedantic note: since Windows is not fully compatible with its own filesystem
(NTFS), on Windows wimlib cannot archive certain files that may exist on a valid
compression. However, you can choose any value, and not just these particular
values. The default is 50.
.IP ""
+This option only affects the compression type used in non-solid WIM resources.
+If you are creating a solid WIM (using the \fB--solid\fR option), then you
+probably want \fB--solid-compress\fR instead.
+.IP ""
Be careful if you choose LZMS compression. It is not compatible with wimlib
-before v1.6.0, WIMGAPI before Windows 8, DISM before Windows 8.1, and 7-Zip.
+before v1.6.0, WIMGAPI before Windows 8, DISM before Windows 8.1, and 7-Zip
+before v15.12.
.IP ""
Also note that choosing LZMS compression does not automatically imply solid-mode
compression, as it does with DISM. Use \fB--solid\fR if you want to create a
You can provide the full number (e.g. 32768), or you can use one of the K, M, or
G suffixes. KiB, MiB, and GiB are also accepted.
.IP ""
-This option only affects the chunk size used for non-solid WIM resources. If
-you are creating a solid WIM (using the \fB--solid\fR option), then you probably
+This option only affects the chunk size used in non-solid WIM resources. If you
+are creating a solid WIM (using the \fB--solid\fR option), then you probably
want \fB--solid-chunk-size\fR instead.
.IP ""
Use this option with caution if compatibility with Microsoft's implementation is
WIM files was released with Windows 8, and the first version of DISM to do so
was released with Windows 8.1.
.IP ""
-If you want to create an "ESD" file, then use this option. An (unencrypted)
-"ESD" file is a solid WIM file.
+If you want to create an "ESD file", then use this option. An (unencrypted)
+"ESD file" is a solid WIM file.
.IP ""
By default, this option has an effect equivalent to DISM's option
\fB/compress:recovery\fR. The options for wimlib-imagex are different because
Like \fB--chunk-size\fR, but set the chunk size used in solid resources. The
default, assuming LZMS compression, is 64MiB (67108864); this requires about
640MiB of memory per thread. This option only has an effect when \fB--solid\fR
-is also specified. For maximum compatibility with the Microsoft implementation,
-do not use this option.
+is also specified. Note: Microsoft's implementation is not compatible with LZMS
+chunk sizes larger than 64MiB.
.TP
\fB--solid-compress\fR=\fITYPE\fR[:\fILEVEL\fR]
Like \fB--compress\fR, but set the compression type used in solid resources.
The default is LZMS compression. This option only has an effect when
-\fB--solid\fR is also specified. For maximum compatibility with the Microsoft
-implementation, do not use this option.
+\fB--solid\fR is also specified.
.TP
\fB--threads\fR=\fINUM_THREADS\fR
Number of threads to use for compressing data. Default: autodetect (number of
Specify a string to use in the <FLAGS> element of the XML data for the new
image.
.TP
+\fB--image-property\fR \fINAME\fR=\fIVALUE\fR
+Specify an arbitrary per-image property to set in the XML document of the WIM
+file. \fIVALUE\fR is the string to set as the property value. \fINAME\fR is
+the name of the image property, for example "NAME", "DESCRIPTION", or
+"TOTALBYTES". The name can contain forward slashes to indicate a nested XML
+element; for example, "WINDOWS/VERSION/BUILD" indicates the BUILD element nested
+within the VERSION element nested within the WINDOWS element. A bracketed
+number can be used to indicate one of several identically-named elements; for
+example, "WINDOWS/LANGUAGES/LANGUAGE[2]" indicates the second "LANGUAGE" element
+nested within the "WINDOWS/LANGUAGES" element. When adding a list of elements
+in this way, they must be specified in sequential order. Note that element
+names are case-sensitive. This option may be specified multiple times.
+.TP
\fB--dereference\fR
(UNIX-like systems only) Follow symbolic links and archive the files they point
to, rather than archiving the links themselves.
are to be treated specially during the image capture.
.IP ""
The format of the configuration file is INI-style; that is, it is arranged in
-bracketed sections. Currently, only the following sections are recognized:
+bracketed sections. Currently, the following sections are recognized:
.RS
.IP \[bu] 4
[ExclusionList] --- contains a list of path globs to exclude from capture. If
and subdirectories are also matched recursively.
.RE
.IP ""
-Any unrecognized sections will be ignored, with a warning printed. Sections
-dealing with compression (e.g. [CompressionExclusion]) are not particularly
-important.
-.IP ""
Path globs may contain the '*' and '?' meta-characters. Relative globs (e.g.
*.mp3) match against a filename in any directory. Absolute globs (e.g.
/dir/file), are treated as paths starting at the main directory being captured,
default, set the configuration file to
\fISOURCE\fR\\Windows\\System32\\WimBootCompress.ini if present and accessible;
however, this may still be overridden through the \fB--config\fR parameter.
+.TP
+\fB--unsafe-compact\fR
+See the documentation for this option in \fBwimlib-imagex-optimize\fR (1).
+.TP
+\fB--snapshot\fR
+EXPERIMENTAL: create a temporary filesystem snapshot of the source directory and
+capture the files from it. Currently, this option is only supported on Windows,
+where it uses the Volume Shadow Copy Service (VSS). Using this option, you can
+create a consistent backup of the system volume of a running Windows system
+without running into problems with locked files. For the VSS snapshot to be
+successfully created, \fBwimlib-imagex\fR must be run as an Administrator, and
+it cannot be run in WoW64 mode (i.e. if Windows is 64-bit, then
+\fBwimlib-imagex\fR must be 64-bit as well).
.SH NOTES
\fBwimlib-imagex append\fR does not support appending an image to a split WIM.
.PP
-It is safe to abort an \fBwimlib-imagex append\fR command partway through;
-however, after doing this, it is recommended to run \fBwimlib-imagex
-optimize\fR to remove any data that was appended to the physical WIM file but
-not yet incorporated into the structure of the WIM, unless the WIM was being
-fully rebuilt (e.g. with \fB--rebuild\fR), in which case you should delete the
-temporary file left over.
+Except when using \fB--unsafe-compact\fR, it is safe to abort a \fBwimlib-imagex
+append\fR command partway through; however, after doing this, it is recommended
+to run \fBwimlib-imagex optimize\fR to remove any data that was appended to the
+physical WIM file but not yet incorporated into the structure of the WIM, unless
+the WIM was being fully rebuilt (e.g. with \fB--rebuild\fR), in which case you
+should delete the temporary file left over.
.PP
\fBwimlib-imagex\fR creates WIMs compatible with Microsoft's software
(WIMGAPI, ImageX, DISM), with some caveats:
git://wimlib.net / wimlib / blobdiff