-.TH WIMLIB-IMAGEX "1" "March 2014" "@IMAGEX_PROGNAME@ @VERSION@" "User Commands"
+.TH WIMLIB-IMAGEX "1" "May 2014" "@IMAGEX_PROGNAME@ @VERSION@" "User Commands"
.SH NAME
@IMAGEX_PROGNAME@-capture, @IMAGEX_PROGNAME@-append \- Create or append a WIM image
.SH SYNOPSIS
.SH DIRECTORY CAPTURE (WINDOWS)
On Windows, \fB@IMAGEX_PROGNAME@ capture\fR and \fB@IMAGEX_PROGNAME@ append\fR
natively support Windows-specific and NTFS-specific data. They therefore act
-similarly to the corresponding commands of Microsoft's ImageX. For best
+similarly to the corresponding commands of Microsoft's ImageX or DISM. For best
results, the directory being captured should be on an NTFS volume and
\fB@IMAGEX_PROGNAME@\fR should be run with Administrator privileges; however,
non-NTFS filesystems and running without Administrator privileges are also
.IP ""
As of wimlib v1.6.0, a third compression type, "recovery" or "LZMS", is also
available. Its use is generally not recommended because other than wimlib
-itself, as of Windows 8 it is only compatible with WIMGAPI and Windows Setup
-(not even ImageX or Dism). However, LZMS is the compression algorithm used in
+itself, it is only compatible with WIMGAPI Windows 8 and later, and DISM Windows
+8.1 and later. However, LZMS is the compression algorithm used by default in
packed resources created if the \fB--pack-streams\fR option is specified.
.TP
\fB--compress-slow\fR
default) and LZMS ("recovery") compression.
.TP
\fB--chunk-size\fR=\fISIZE\fR
-Set the WIM compression chunk size to \fISIZE\fR. Larger chunks mean larger
+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 a
-power of 2 greater than or equal to 2^15 (32768) up to a maximum determined by
-the compression format. For LZX ("maximum") compression, the maximum allowed
-chunk size is 2^21 (2097152), and for XPRESS ("fast") and LZMS ("recovery")
-compression, the maximum allowed chunk size is 2^30 (1073741824).
-.IP ""
-For XPRESS and LZX compression, Microsoft's implementation (as of Windows 8)
-does not appear to support alternate chunk sizes; although it will still open
-such files, it will crash, extract the data incorrectly, or report that the data
-is invalid. For LZMS compression, Microsoft's implementation (as of Windows 8)
-appears to only support chunk sizes that are powers of 2 between 2^15 (32768)
-and 2^20 (1048576) inclusively. In addition, wimlib versions before 1.6.0 do
-not support alternate chunk sizes.
+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^26 (67108864), 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.
.TP
\fB--pack-streams\fR, \fB--solid\fR
Create a "solid" archive that compresses multiple unique streams ("files")
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 \fB@IMAGEX_PROGNAME@ mount\fR. Also, WIMs created using this
-option use a different version number in their header and as of Windows 8 are
-only compatible with Windows Setup and WIMGAPI, not even ImageX and Dism.
-.IP ""
-Packed resources use a compression type and chunk size that is independent of
-the WIM's "default compression type" and "default chunk size" (which may be
-adjusted by the \fB--compress\fR and \fB--chunk-size\fR options, respectively).
-For compatibility reasons, \fB@IMAGEX_PROGNAME@ capture\fR currently has no
-option to change the compression type used in packed resources; however, the
-\fB--pack-chunk-size\fR option may be used to set the chunk size.
+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 packed resources is LZMS with
+2^25 (33554432) byte chunks. This is independent of the WIM's main compression
+type and chunk size.
.TP
\fB--pack-chunk-size\fR=\fISIZE\fR, \fB--solid-chunk-size\fR=\fISIZE\fR
Like \fB--chunk-size\fR, but set the chunk size used in packed resources. The
-compression format is LZMS, so the chunk size can be any power of 2 between 2^15
-and 2^30, inclusively. WIMGAPI (Windows 8) appears to be compatible with these
-sizes up to 2^26 inclusively, despite not being compatible with sizes greater
-than 2^20 in non-packed resources. The default is currently 2^25 (33554432).
-Note: currently, the LZMS compression algorithm uses about 15 times the chunk
-size in memory per thread, which is about 500 MB per thread for the default pack
-chunk size of 2^25 or 1 GB per thread if you change it to 2^26 (67108864).
+default is LZMS compression with 2^25 (33554432) byte chunks. This option only
+has an effect when \fB--pack-streams\fR is also specified. For maximum
+compatibility with the Microsoft implementation, do not use either of these
+options.
+.TP
+\fB--pack-compress\fR=\fITYPE\fR, \fB--solid-compress\fR=\fITYPE\fR
+Like \fB--compress\fR, but set the compression format used in packed resources.
+The default is LZMS compression with 2^25 (33554432) byte chunks. This option
+only has an effect when \fB--pack-streams\fR is also specified. For maximum
+compatibility with the Microsoft implementation, do not use either of these
+options.
.TP
\fB--threads\fR=\fINUM_THREADS\fR
Number of threads to use for compressing data. Default: autodetect (number of
to, rather than archiving the links themselves.
.TP
\fB--config\fR=\fIFILE\fR
-Specifies a configuration file for capturing the new image. The configuration
-file specifies files that are to be treated specially during the image capture.
-.IP ""
-The format of the configuration file is a number of sections containing path
-globs one per line, where each section begins with the tag [ExclusionList],
-[ExclusionException], [CompressionExclusionList], or [AlignmentList].
-Currently, only the [ExclusionList] and [ExclusionException] sections are
-implemented. The [ExclusionList] section specifies a list of path globs to
-exclude from capture, while the [ExclusionException] section specifies a list of
-path globs to include in the capture even if the matched file or directory name
-also appears in the [ExclusionList].
-.IP ""
-Relative globs with only one path component (e.g. *.mp3) match against a
-filename in any directory. Relative globs with multiple path components (e.g.
-dir/file), as well as absolute globs (e.g. /dir/file), are treated as paths
-starting at the root directory of capture, or the root of the NTFS volume for
-NTFS volume capture mode. If a directory is matched by a glob in the
-[ExclusionList], the entire directory tree rooted at that directory is excluded
-from the capture, unless \fB--dereference\fR is specified and there is another
-path into that directory through a symbolic link.
-.IP ""
-For compatibility with Windows, the path separators in the globs may be either
-forward slashes or backslashes, and the line separators may be either UNIX-style
-or DOS-style. Globs with spaces in them must be quoted, and leading and
-trailing whitespace is not significant. Empty lines and lines beginning with
-\'#' or whitespace followed by '#' are ignored.
-.IP ""
-Paths may not have drive letters in them, as they are all relative to the root
-of capture and not absolute external paths.
+Specifies a configuration file (UTF-8 or UTF-16LE encoded; plain ASCII also
+works) for capturing the new image. The configuration file specifies files that
+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:
+.RS
+.IP \[bu] 4
+[ExclusionList] --- contains a list of path globs to exclude from capture. If
+a directory is matched, both the directory and its contents are excluded.
+.IP \[bu]
+[ExclusionException] --- contains a list of path globs to include in the
+capture, even when the file or directory also matches a glob in [ExclusionList].
+.IP \[bu]
+[PrepopulateList] --- this does not affect capture, but if the image is applied
+later with \fB--wimboot\fR, these are globs of files that shall be extracted
+normally, not as WIMBoot "pointer files". If a directory is matched, all files
+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,
+or the root of the NTFS volume for NTFS volume capture mode. Do not use drive
+letters in the paths; they will be ignored. Path separators may be either
+forwards slashes or backwards slashes.
+.IP ""
+Lines beginning with the '#' or ';' characters are treated as comments and
+ignored. Globs with whitespace in them need not be quoted; however, if they
+are, both double and single quotes are accepted.
.IP ""
If this option is not specified the following default configuration file is
used:
\\$ntfs.log
\\hiberfil.sys
\\pagefile.sys
-"\\System Volume Information"
+\\swapfile.sys
+\\System Volume Information
\\RECYCLER
\\Windows\\CSC
.RE
.RE
.fi
+.IP ""
+However, special behavior applies if \fB--wimboot\fR is also specified. By
+default, with \fB--wimboot\fR specified, the file
+Windows/System32/WimBootCompress.ini in the directory being captured will be
+used as the configuration file. However, this can be overridden using
+\fB--config\fR; and this also causes the specified configuration file to be
+saved in the WIM image as Windows/System32/WimBootCompress.ini, overriding any
+that may be present on the filesystem.
.TP
\fB--unix-data\fR
(UNIX-like systems only) Store the UNIX owner, group, and mode of all captured
-files. This is done by adding a special alternate data stream to each directory
-entry that contains this information. Please note that this flag is for
-convenience only, in case you want to use \fB@IMAGEX_PROGNAME@\fR to archive
-files on UNIX. Microsoft's software will not understand this special
-information. You also may run into problems when applying an image with UNIX
-data from a pipable WIM.
+files. This is done by adding a special tagged metadata item to each directory
+entry that contains this information. This information should be ignored by the
+Microsoft implementation. (Note: the way that UNIX data is stored was changed
+in wimlib v1.7.0 and is not backwards or forward compatible.)
.TP
\fB--no-acls\fR
Do not capture files' security descriptors.
.IP ""
Note: unlike "pipable" WIMs (created with the \fB--pipable\fR option), "delta"
WIMs (created with the \fB--delta-from\fR option) are compatible with
-Microsoft's software. You can use the /ref option of imagex.exe to reference
-the base WIM(s), similar to above.
+Microsoft's software. For example, you can use the /ref option of ImageX to
+reference the base WIM(s), similar to above.
.IP ""
Additional note: \fB@IMAGEX_PROGNAME@\fR is generalized enough that you can in
fact combine \fB--pipable\fR and \fB--delta-from\fR to create pipable delta
pipe after the delta WIM.
.TP
\fB--wimboot\fR
-Windows only: mark the image as WIMBoot-compatible. See Microsoft's
+Mark the image as WIMBoot-compatible. See Microsoft's
documentation for more information about WIMBoot. This option will, by default,
change the compression type to XPRESS and the chunk size to 4096 bytes; these
can, however, still be overridden through the \fB--compress\fR and
temporary file left over.
.PP
\fB@IMAGEX_PROGNAME@\fR creates WIMs compatible with Microsoft's software
-(imagex.exe, Dism.exe, wimgapi.dll), with some caveats:
+(WIMGAPI, ImageX, DISM), with some caveats:
.IP \[bu] 4
With \fB@IMAGEX_PROGNAME@\fR on UNIX-like systems, it is possible to create a
WIM image containing files with names differing only in case, or files with
pointing out that Windows' own default filesystem, NTFS, supports these
characters, although Windows does not!)
.IP \[bu]
-WIMs captured with \fB--unix-data\fR should be assumed to be incompatible with
-Microsoft's software.
-.IP \[bu]
Pipable WIMs are incompatible with Microsoft's software. Pipable WIMs are
created only if \fIWIMFILE\fR was specified as "-" (standard output) or if
the \fB--pipable\fR flag was specified.
WIMs captured with a non-default chunk size (with the \fB--chunk-size\fR option)
or as solid archives (with the \fB--pack-streams\fR option) or with LZMS
compression (with \fB--compress\fR=LZMS or \fB--compress\fR=recovery) have
-varying levels of compatibility with Microsoft's software. The best
-compatibility is achieved with WIMGAPI itself (not ImageX or Dism) on Windows 8
-or later.
+varying levels of compatibility with Microsoft's software. Generally, more
+recent versions of Microsoft's software are more compatible.
.SH EXAMPLES
First example: Create a new WIM 'mywim.wim' with "maximum" (LZX) compression
that will contain a captured image of the directory tree 'somedir'. Note that
git://wimlib.net / wimlib / blobdiff