-.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
metadata from filesystems used on UNIX-like systems. The main information that
will \fInot\fR be stored is:
.IP \[bu] 4
-UNIX file owners, groups, and modes. (Exception: see the \fB--unix-data\fR
-option.) As a result, file permissions will not be stored, and files that are
-neither regular files, directories, nor symbolic links, such as device files and
-FIFOs, cannot be captured and will be excluded by default.
+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.
.IP \[bu]
Extended attributes. This mainly includes extensions to the traditional UNIX
security model, such as SELinux security labels, POSIX ACLs, and capabilities
.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
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.
+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
to, rather than archiving the links themselves.
.TP
\fB--config\fR=\fIFILE\fR
-Specifies a configuration file (UTF-8 or UTF-16LE encoded) 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. Trailing and leading whitespace is ignored. Lines beginning with
-the '#' or ';' characters are treated as comments and ignored. Globs with
-whitespace in them need not be quoted, unless the whitespace is leading or
-trailing. Both double and single quotes are accepted.
-.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
+\\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.
+(UNIX-like systems only) Store the UNIX owner, group, mode, and device ID (major
+and minor number) of each captured file. As of wimlib v1.7.0, you can backup
+and restore not only the standard UNIX file permission information, but also
+character device nodes, block device nodes, named pipes (FIFOs), and UNIX domain
+sockets.
+.IP
+wimlib stores UNIX data by adding a special tagged metadata item to each
+directory entry of each file that contains this information. This extra
+information is ignored by the Microsoft implementation. Note: UNIX data stored
+by wimlib before v1.7.0 used a different format that is no longer supported. If
+you have old WIM files with UNIX data, apply them with v1.6.2 and recapture them
+with v1.7.0 or later.
.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
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