-.TH WIMLIB-IMAGEX "1" "August 2015" "wimlib 1.8.2" "User Commands"
+.TH WIMLIB-IMAGEX "1" "August 2016" "wimlib 1.10.0" "User Commands"
.SH NAME
wimlib-imagex-capture, wimlib-imagex-append \- Create or append a WIM image
.SH SYNOPSIS
With \fB--unix-data\fR: device nodes, FIFOs, and UNIX domain sockets
.PP
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
-unlikely case, each symbolic link is stored as an independent file.
+labels and POSIX ACLs), last status change times (ctimes), or hard link
+information for symbolic link files (each symbolic link will be stored as an
+independent file). In addition, filenames and symbolic link targets on UNIX
+filesystems which are not valid UTF-8 with the addition of surrogate codepoints
+are unsupported. Note: if you have a filesystem containing filenames in another
+multibyte encoding, such as ISO-8859-1, and you wish to archive it with wimlib,
+you may be able to mount it with an option which causes its filenames to be
+presented as UTF-8.
.SH NTFS VOLUME CAPTURE (UNIX)
This section documents how \fBwimlib-imagex\fR captures files directly from
an NTFS volume image on UNIX-like systems.
All data streams of all unencrypted files, including the unnamed data stream as
well as all named data streams.
.IP \[bu]
-Reparse points, including symbolic links, junction points, and other reparse
-points.
+Reparse points. See \fBREPARSE POINTS AND SYMLINKS\fR for details.
.IP \[bu]
File and directory creation, access, and modification timestamps, using the
native NTFS resolution of 100 nanoseconds.
.IP \[bu]
All names of all files, including names in the Win32 namespace, DOS namespace,
Win32+DOS namespace, and POSIX namespace. This includes hard links.
+.IP \[bu]
+Object IDs.
.PP
However, the main limitations of this NTFS volume capture mode are:
.IP \[bu] 4
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,
subject to the WIM format's compression.)
+.IP \[bu]
+Some types of reparse points are transparently dereferenced by Windows but not
+by NTFS-3G. See \fBREPARSE POINTS AND SYMLINKS\fR.
.SH DIRECTORY CAPTURE (WINDOWS)
On Windows, \fBwimlib-imagex capture\fR and \fBwimlib-imagex append\fR
natively support Windows-specific and NTFS-specific data. They therefore act
.IP \[bu] 4
All data streams of all files.
.IP \[bu]
-Reparse points, including symbolic links, junction points, and other reparse
-points, if supported by the source filesystem. (Note: see \fB--rpfix\fR and
-\fB--norpfix\fR for documentation on exactly how absolute symbolic links and
-junctions are captured.)
+Reparse points, if supported by the source filesystem. See \fBREPARSE POINTS
+AND SYMLINKS\fR for details.
.IP \[bu]
File and directory creation, access, and modification timestamps. These are
stored with Windows NT's native timestamp resolution of 100 nanoseconds.
considered an error condition.
.IP \[bu]
Hard links, if supported by the source filesystem.
+.IP \[bu]
+Object IDs, if supported by the source filesystem.
.PP
-There is no support for storing NTFS extended attributes and object IDs.
+There is no support for storing NTFS extended attributes.
.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
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
NTFS filesystem but are inaccessible to the Windows API, for example two files
-with names differing only in case in the same directory, or a file whose name
-contains certain characters considered invalid by Windows. If you run into
+with names differing only in case in the same directory (unless
+ObCaseInsensitive has been set to 0 in the Windows registry), or a file whose
+name contains certain characters considered invalid by Windows. If you run into
problems archiving such files consider using the \fBNTFS VOLUME CAPTURE
(UNIX)\fR mode from Linux.
+.SH REPARSE POINTS AND SYMLINKS
+A "symbolic link" (or "symlink") is a special file which "points to" some other
+file or directory. On Windows, a "reparse point" is a generalization of a
+symlink which allows access to a file or directory to be redirected in a more
+complex way. Windows uses reparse points to support symlinks, and sometimes
+uses them for various other features as well. Normally, applications can choose
+whether they want to "dereference" reparse points and symlinks or not.
+.PP
+The default behavior of \fBwimcapture\fR is that reparse points and symlinks are
+\fInot\fR dereferenced, meaning that the reparse points or symlinks themselves
+are stored in the archive rather than the files or data they point to. There is
+a \fB--dereference\fR option, but it is currently only supported by the UNIX
+version of \fBwimcapture\fR on UNIX filesystems (it's not yet implemented for
+Windows filesystems).
+.PP
+Windows also treats certain types of reparse points specially. For example,
+Windows applications reading from deduplicated, WIM-backed, or system-compressed
+files always see the dereferenced data, even if they ask not to. Therefore,
+\fBwimcapture\fR on Windows will store these files dereferenced, not as reparse
+points. But \fBwimcapture\fR on UNIX in NTFS-3G mode cannot dereference these
+files and will store them as reparse points instead. This difference can be
+significant in certain situations, e.g. when capturing deduplicated files which,
+to be readable after extraction, require that the chunk store also be present.
.SH OPTIONS
.TP 6
\fB--boot\fR
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
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.
.TP
\fB--unix-data\fR
(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 minor number) of each captured file. Since 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.
optimized by not reading files that, based on metadata such as timestamps,
appear not to have been modified since they were archived in the existing
\fIIMAGE\fR. Barring manipulation of timestamps, this option only affects
-performance and does not change the resulting WIM image.
+performance and does not change the resulting WIM image (but see note below).
.IP ""
As shown, the full syntax for the argument to this option is to specify the WIM
file, a colon, and the image; for example, "--update-of mywim.wim:1". However,
to the WIM file being appended to for append operations, or the WIM file from
which a delta is being taken (only if \fB--delta-from\fR is specified exactly
once) for capture operations.
+.IP ""
+Note: in the Windows version of wimlib, it has been observed that
+\fB--update-of\fR mode is not completely reliable at detecting changes in file
+contents, sometimes causing the old contents of a few files to be archived
+rather than the current contents. The cause of this problem is that Windows
+does not immediately update a file's last modification timestamp after every
+write to that file. Unfortunately, there is no known way for applications like
+wimlib to automatically work around this bug. Manual workarounds are possible;
+theoretically, taking any action that causes the problematic files to be closed,
+such as restarting applications or the computer itself, should cause the files'
+last modification timestamps to be updated. Also note that wimlib compares file
+sizes as well as timestamps in determining whether a file has changed, which
+helps make the problem less likely to occur; and the problem does not occur on
+other operating systems such as Linux which maintain files' last modification
+timestamps correctly.
.TP
\fB--delta-from\fR=\fIWIMFILE\fR
For \fBwimlib-imagex capture\fR only: capture the new WIM as a "delta" from
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).
+For \fBwimlib-imagex append\fR: compact the WIM archive in-place and append any
+new data, eliminating "holes". In general, this option should \fInot\fR be used
+because a failed or interrupted compaction will corrupt the WIM archive. For
+more information, see the documentation for this option in
+\fBwimlib-imagex-optimize\fR (1).
+.TP
+\fB--snapshot\fR
+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