-.TH WIMLIB-IMAGEX "1" "November 2014" "wimlib 1.7.3" "User Commands"
+.TH WIMLIB-IMAGEX "1" "August 2015" "wimlib 1.8.2" "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.
+.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
+solid WIM, or "ESD file".
.TP
\fB--chunk-size\fR=\fISIZE\fR
-Set the WIM compression chunk size to \fISIZE\fR bytes. Larger chunks mean larger
-LZ77 dictionaries and better compression ratios on sufficiently large files, but
-slower random access. \fBUsing this option is generally not recommended because
-of the compatibility limitations detailed in the next paragraph.\fR But if you
-decide to use this option regardless, you may choose a chunk size that is
-allowed by the compression format. All formats only allow power-of-2 chunk
-sizes. For LZX ("maximum") compression the maximum allowed chunk size is 2^21
-(2097152), for XPRESS ("fast") compression the maximum allowed chunk size is
-2^16 (65536), and for LZMS ("recovery") compression the maximum allowed chunk
-size is 2^30 (1073741824).
-.IP ""
-Beware that Microsoft's implementation has limited support for non-default chunk
-sizes. Depending on the version, their software may refuse to open the WIM, or
-open it and crash, or open it and report the data is invalid, or even extract
-the data incorrectly. In addition, wimlib versions before 1.6.0 do not support
-alternate chunk sizes.
+Set the compression chunk size to \fISIZE\fR bytes. A larger compression chunk
+size results in a better compression ratio. wimlib supports different chunk
+sizes depending on the compression type:
+.RS
+.IP \[bu] 2
+XPRESS: 4K, 8K, 16K, 32K, 64K
+.IP \[bu]
+LZX: 32K, 64K, 128K, 256K, 512K, 1M, 2M
+.IP \[bu]
+LZMS: 32K, 64K, 128K, 256K, 512K, 1M, 2M, 4M, 8M, 16M, 32M, 64M, 128M, 256M, 512M, 1G
+.RE
+.IP ""
+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 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
+desired, since their implementation has limited support for non-default chunk
+sizes.
.TP
\fB--solid\fR
-Create a "solid" archive that compresses multiple unique streams ("files")
-together, rather than each unique stream ("file") independently. This can
-result in a significantly better compression ratio, but this format greatly
-decreases the performance of random access to the data, as may occur on a WIM
-mounted with \fBwimlib-imagex mount\fR. Also, WIMs created using this
-option use a different version number in their header and are only compatible
-with WIMGAPI Windows 8 and later, and DISM Windows 8.1 and later.
-.IP ""
-The default compression type and chunk size in solid blocks is LZMS with 2^25
-(33554432) byte chunks. This is independent of the WIM's main compression type
-and chunk size.
+Create a "solid" WIM file that compresses files together rather than
+independently. This results in a significantly better compression ratio, but it
+comes at the cost of various tradeoffs, including: slow compression with very
+high memory usage; slow random access to the resulting WIM file; and reduced
+compatibility.
+.IP ""
+Compatibility-wise, the first version of Microsoft's WIMGAPI to support solid
+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.
+.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
+they try not to conflate the compression type (e.g. LZX or LZMS) with solid-mode
+compression, as these are two different things.
.TP
\fB--solid-chunk-size\fR=\fISIZE\fR
-Like \fB--chunk-size\fR, but set the chunk size used in solid blocks. The
-default is LZMS compression with 2^25 (33554432) byte chunks. This option only
-has an effect when \fB--solid\fR is also specified. For maximum compatibility
-with the Microsoft implementation, do not use either of these options.
+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. 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 blocks. The
-default is LZMS compression with 2^25 (33554432) byte chunks. This option only
-has an effect when \fB--solid\fR is also specified. For maximum compatibility
-with the Microsoft implementation, do not use either of these options.
+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.
.TP
\fB--threads\fR=\fINUM_THREADS\fR
Number of threads to use for compressing data. Default: autodetect (number of
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).
.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