-.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
-\fBwimlib-imagex capture\fR \fISOURCE\fR \fIWIMFILE\fR [\fIIMAGE_NAME\fR \
-[\fIIMAGE_DESCRIPTION\fR]] [\fIOPTION\fR...]
-.br
-\fBwimlib-imagex append\fR \fISOURCE\fR \fIWIMFILE\fR [\fIIMAGE_NAME\fR \
-[\fIIMAGE_DESCRIPTION\fR]] [\fIOPTION\fR...]
-.SH DESCRIPTION
-The \fBwimlib-imagex capture\fR and \fBwimlib-imagex append\fR commands
-create a Windows Imaging (WIM) image from a directory tree. The
-\fBwimlib-imagex capture\fR command creates a new WIM file containing the
-captured image, while the \fBwimlib-imagex append\fR command appends the
-captured image to an existing WIM file.
-These commands are also available as simply \fBwimcapture\fR and \fBwimappend\fR
-if the appropriate hard links or batch files are installed.
-.PP
-Background information: A WIM image is an independent directory tree in a WIM
-file. A WIM file may contain any number of separate images. WIM files are
-single-instancing with regards to file data, so a file is stored only one time
-in the entire WIM, regardless of how many images the file appears in.
-.PP
-\fISOURCE\fR specifies the location of the files to create the new WIM image
-from. If \fISOURCE\fR is a directory, the WIM image is captured from that
-directory (see \fBDIRECTORY CAPTURE (UNIX)\fR or \fBDIRECTORY CAPTURE
-(WINDOWS)\fR). Alternatively, if the \fB--source-list\fR option is specified,
-\fISOURCE\fR is interpreted as a file that itself provides a list of
-files and directories to include in the new WIM image. Still
-alternatively, only on UNIX-like systems, if \fISOURCE\fR is a
-regular file or block device, it is interpreted as an NTFS volume from
-which a WIM image is to be captured using libntfs-3g (see \fBNTFS VOLUME CAPTURE
-(UNIX)\fR).
-.PP
-\fIIMAGE_NAME\fR and \fIIMAGE_DESCRIPTION\fR specify the name and description to
-give the new WIM image. If \fIIMAGE_NAME\fR is not specified, it defaults to
-the base name (excluding path to parent directory) of \fISOURCE\fR, but if this
-name already exists in \fIWIMFILE\fR, a unique suffix is added. Otherwise,
-\fIIMAGE_NAME\fR must be either a name that does not already exist as an image in
-\fIWIMFILE\fR, or the empty string to create an image with no name. If
-\fIIMAGE_DESCRIPTION\fR is not specified, no description is given to the new
-image.
-.PP
-As a special case, if \fIWIMFILE\fR is "-", the \fB--pipable\fR option is
-assumed and the WIM file is written to standard output in a special pipable
-format. See the documentation for \fB--pipable\fR for more details.
-.SH DIRECTORY CAPTURE (UNIX)
-This section documents how \fBwimlib-imagex\fR captures files from a
-directory tree on UNIX-like systems. See \fBDIRECTORY CAPTURE (WINDOWS)\fR for
-the corresponding documentation for Windows.
-.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
-mountpoints are followed recursively. In this mode, wimlib will store the
-following types of information:
-.IP \[bu] 4
-Directories and regular files, and the contents of regular files
-.IP \[bu]
-Hard links
-.IP \[bu]
-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: standard UNIX file permissions (owner, group, and mode)
-.IP \[bu]
-With \fB--unix-data\fR: device nodes, named pipes, and sockets
-.IP \[bu]
-With \fB--unix-data\fR: extended attributes (Linux only)
-.PP
-There is no support for storing 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.
-.PP
-On UNIX-like systems, a special image capture mode is entered when \fISOURCE\fR
-is a regular file or block device. In this mode, \fISOURCE\fR is assumed to be
-an NTFS volume or volume image, and \fBwimlib-imagex\fR will capture a WIM
-image containing the full contents of the NTFS volume, including NTFS-specific
-data. This is done using libntfs-3g.
-.PP
-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:
-.IP \[bu] 4
-All data streams of all unencrypted files, including the unnamed data stream as
-well as all named data streams.
-.IP \[bu]
-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]
-Windows security descriptors, including all components (owner, group, DACL, and
-SACL).
-.IP \[bu]
-DOS/Windows file attribute flags.
-.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
-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,
-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
-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
-\fBwimlib-imagex\fR should be run with Administrator privileges; however,
-non-NTFS filesystems and running without Administrator privileges are also
-supported.
-.PP
-On Windows, \fBwimlib-imagex capture\fR and \fBwimlib-imagex append\fR
-try to archive as much data and metadata as possible, including:
-.IP \[bu] 4
-All data streams of all files.
-.IP \[bu]
-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.
-.IP \[bu]
-Security descriptors, if supported by the source filesystem and \fB--no-acls\fR
-is not specified. However, beware that unless \fB--strict-acls\fR is specified,
-the security descriptors for individual files or directories may be omitted or
-only partially captured if the user does not have permission to read them, which
-can be a problem if \fBwimlib-imagex\fR is run as a non-Administrator.
-.IP \[bu]
-File attributes, including hidden, sparse, compressed, encrypted, etc.
-Encrypted files will be stored in encrypted form rather than in plain text.
-Transparently compressed files will be read as uncompressed and stored subject
-to the WIM's own compression. There is no special handling for storing sparse
-files, but they are likely to compress to a small size.
-.IP \[bu]
-DOS names (8.3) names of files; however, the failure to read them is not
-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.
-.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
-NTFS filesystem but are inaccessible to the Windows API, for example two files
-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
-Specifies that the new image is to be made the bootable image of the WIM archive.
-.TP
-\fB--check\fR
-For \fBwimlib-imagex append\fR, before performing the append operation,
-check the integrity of \fIWIMFILE\fR if an integrity table is present.
-Furthermore, include an integrity table in the new WIM file
-(\fBwimlib-imagex capture\fR) or the modified WIM file (\fBwimlib-imagex
-append\fR). If this option is not specified, no integrity table is included in
-a WIM file created with \fBwimlib-imagex capture\fR, while a WIM file
-updated with \fBwimlib-imagex append\fR will be written with an integrity
-table if and only if one was present before.
-.TP
-\fB--compress\fR=\fITYPE\fR[:\fILEVEL\fR]
-Specifies the compression format for the new WIM file. \fITYPE\fR may be
-"none", "XPRESS" (alias: "fast"), "LZX" (alias: "maximum"), or "LZMS" (alias:
-"recovery"). \fITYPE\fR is matched case-insensitively. The default is "LZX".
-.IP ""
-You can optionally also specify an integer compression \fILEVEL\fR. The
-compression level specifies how hard the compression algorithm for the specified
-compression \fITYPE\fR will work to compress the data. The values are scaled so
-that 20 is quick compression, 50 is medium compression, and 100 is high
-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 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
-solid WIM, or "ESD file".
-.TP
-\fB--chunk-size\fR=\fISIZE\fR
-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" 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 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 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
-available CPUs).
-.TP
-\fB--rebuild\fR
-For \fBwimlib-imagex append\fR: rebuild the entire WIM rather than appending the new
-data to the end of it. Rebuilding the WIM is slower, but will save a little bit
-of space that would otherwise be left as a hole in the WIM. Also see \fBwimlib-imagex
-optimize\fR(1).
-.TP
-\fB--flags\fR=\fIEDITIONID\fR
-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--config\fR=\fIFILE\fR
-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, 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 ""
-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:
-.IP ""
-.RS
-.RS
-.nf
-[ExclusionList]
-\\$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 UNIX-specific metadata and special files. This
-includes: standard UNIX file permissions (owner, group, and mode); device nodes,
-named pipes, and sockets; and extended attributes (Linux only). This
-information can later be restored by \fBwimlib-imagex apply\fR with the
-\fB--unix-data\fR option.
-.IP
-UNIX-specific information is ignored by Microsoft's WIM software and by the
-Windows version of wimlib.
-.TP
-\fB--no-acls\fR
-Do not capture files' security descriptors.
-.TP
-\fB--strict-acls\fR
-Fail immediately if the full security descriptor of any file cannot be read. On
-Windows, the default behavior without this option is to first try omitting the
-SACL from the security descriptor, then to try omitting the security descriptor
-entirely. The purpose of this is to capture as much data as possible without
-always requiring Administrator privileges. However, if you desire that all
-security descriptors be captured exactly, you may wish to provide this option,
-although the Administrator should have permission to read everything anyway.
-.TP
-\fB--rpfix\fR, \fB--norpfix\fR
-Set whether to fix targets of absolute symbolic links (reparse points in Windows
-terminology) or not. When enabled (\fB--rpfix\fR), absolute symbolic links that
-point inside the directory tree being captured will be adjusted to be absolute
-relative to the root of the directory tree being captured. When disabled
-(\fB--norpfix\fR), absolute symbolic links will be captured exactly as is.
-.IP ""
-The default behavior for \fBwimlib-imagex capture\fR is equivalent to
-\fB--rpfix\fR. The default behavior for \fBwimlib-imagex append\fR will be
-\fB--rpfix\fR if reparse point fixups have previously been done on
-\fIWIMFILE\fR, otherwise \fB--norpfix\fR.
-.IP ""
-In the case of a multi-source capture, (\fB--source-list\fR specified), passing
-\fB--norpfix\fR is recommended. Otherwise, reparse point fixups will be
-disabled on all capture sources destined for non-root locations in the WIM
-image, while capture sources destined for the WIM root will get the default
-behavior from the previous paragraph.
-.TP
-\fB--source-list\fR
-\fBwimlib-imagex capture\fR and \fBwimlib-imagex append\fR support
-creating a WIM image from multiple separate files or directories. When
-\fB--source-list\fR is specified, the \fISOURCE\fR argument specifies the name
-of a text file, each line of which is either 1 or 2 whitespace separated file
-paths. The first file path, the source, specifies the path to a file or
-directory to capture into the WIM image. It may be either absolute or relative
-to the current working directory. The second file path, if provided, is the
-target and specifies the path in the WIM image that this file or directory will
-be saved as. Leading and trailing slashes in the target are ignored, except if
-it consists entirely of slashes (e.g. "/"), which indicates that the directory
-is to become the root of the WIM image. If omitted, the target string defaults
-to the same as the source string.
-.IP ""
-An example source list file is as follows:
-.IP ""
-.RS
-.RS
-.nf
-# Make the WIM image from the 'winpe' directory
-winpe /
-
-# Send the 'overlay' directory to '/overlay' in the WIM image
-overlay /overlay
-
-# Overlay a separate directory directly on the root of the WIM image.
-/data/stuff /
-.RE
-.RE
-.fi
-.IP ""
-Subdirectories in the WIM are created as needed. Multiple source directories
-may share the same target, which implies an overlay. In the event that this
-results a nondirectory file being added to the WIM image multiple times, the
-last version (as listed in the source list file) overrides any earlier version.
-.IP ""
-File paths containing whitespace may be quoted with either single quotes or
-double quotes. Quotes may not be escaped.
-.IP ""
-Lines consisting only of whitespace and lines beginning with '#' preceded by
-optional whitespace are ignored.
-.IP ""
-As a special case, if \fISOURCE\fR is "-", the source list is read from standard
-input rather than an external file.
-.IP ""
-The NTFS volume capture mode on UNIX-like systems cannot be used with
-\fB--source-list\fR, as only capturing a full NTFS volume is supported.
-.TP
-\fB--pipable\fR
-Create a "pipable" WIM, which can be applied fully sequentially, including from
-a pipe. An image in the resulting WIM can be applied with \fBwimlib-imagex
-apply\fR, either normally by specifying the WIM file name, or with
-\fBwimlib-imagex apply -\fR to read the WIM from standard input. See
-\fBwimlib-imagex apply\fR(1) for more details.
-.IP ""
-For append operations, this option will result in a full rebuild of the WIM to
-make it pipable. For capture operations, the captured WIM is simply created as
-pipable. Beware that the more images you add to a pipable WIM, the less
-efficient piping it will be, since more unneeded data will be sent through the
-pipe.
-.IP ""
-When wimlib creates a pipable WIM, it carefully re-arranges the components of
-the WIM so that they can be read sequentially and also makes several other
-modifications. As a result, these "pipable" WIMs are \fInot compatible with
-Microsoft's software\fR, so keep this in mind if you're going to use them. If
-desired, you can use \fBwimlib-imagex optimize --not-pipable\fR to re-write
-a pipable WIM as a regular WIM. (\fBwimlib-imagex export\fR also provides
-the capability to export images from a pipable WIM into a non-pipable WIM, or
-vice versa.)
-.IP ""
-For the most part, wimlib operates on pipable WIMs transparently. You can
-modify them, add or delete images, export images, and even create split pipable
-WIMs. The main disadvantages are that appending is (currently) less efficient
-(\fB--rebuild\fR is always implied), and also they aren't compatible with
-Microsoft's software.
-.IP ""
-\fBwimlib-imagex capture\fR and \fBwimlib-imagex append\fR can both
-write a pipable WIM directly to standard output; this is done automatically if
-\fIWIMFILE\fR is specified as "-". (In that case, \fB--pipable\fR is assumed.)
-.TP
-\fB--not-pipable\fR
-Ensure the resulting WIM is in the normal, non-pipable WIM format. This is the
-default for \fBwimlib-imagex capture\fR, except when writing to standard
-output (\fIWIMFILE\fR specified as "-"), and also for \fBwimlib-imagex
-append\fR, except when appending to a WIM that is already pipable.
-.TP
-\fB--update-of\fR=[\fIWIMFILE\fR:]\fIIMAGE\fR
-Declares that the image being captured or appended from \fISOURCE\fR is mostly the same as
-the existing image \fIIMAGE\fR in \fIWIMFILE\fR, but captured at a later point
-in time, possibly with some modifications in the intervening time. This is
-designed to be used in incremental backups of the same filesystem or directory
-tree. \fIIMAGE\fR can be a 1-based index or name of an existing image in
-\fIWIMFILE\fR. It can also be a negative integer to index backwards into the
-images (e.g. -1 means the last existing image in \fIWIMFILE\fR).
-.IP ""
-When this option is provided, the capture or append of the new image will be
-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 (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,
-the WIM file and colon may be omitted, in which case the WIM file will default
-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
-\fIWIMFILE\fR. Any streams that would ordinarily need to be archived in the new
-WIM are omitted if they are already present in the \fIWIMFILE\fR on which the
-delta is being based. The new WIM will still contain a full copy of the image
-metadata, but this is typically only a small fraction of a WIM's total size.
-.IP ""
-This option can be specified multiple times, in which case the resulting delta
-WIM will only contain streams not present in any of the specified base WIMs.
-.IP ""
-To operate on the resulting delta WIM using other commands such as
-\fBwimlib-imagex apply\fR, you must specify the delta WIM as the WIM file to
-operate on, but also reference the base WIM(s) using the \fB--ref\fR option.
-Beware: to retain the proper functioning of the delta WIM, you can only add, not
-delete, files and images to the base WIM(s) following the capture of a delta
-from it.
-.IP ""
-\fB--delta-from\fR may be combined with \fB--update-of\fR to increase the
-speed of capturing a delta WIM.
-.IP ""
-As an example, consider the following backup and restore sequence:
-.IP ""
-.RS
-.nf
-(initial backup)
-
-$ wimcapture /some/directory bkup-base.wim
-
-(some days later, create second backup as delta from first)
-
-$ wimcapture /some/directory bkup-2013-08-20.dwm \\
- --update-of bkup-base.wim:-1 --delta-from bkup-base.wim
-
-(restoring the second backup)
-
-$ wimapply bkup-2013-08-20.dwm --ref=bkup-base.wim 1 \\
- /some/directory
-.RE
-.fi
-.IP ""
-However, note that as an alternative to the above sequence that used a delta
-WIM, the second backup could have simply been appended to the WIM as new image
-using \fBwimlib-imagex append\fR. Delta WIMs should be used only if it's
-desired to base the backups or images on a separate, large file that is rarely
-modified.
-.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. For example, you can use the /ref option of ImageX to
-reference the base WIM(s), similar to above.
-.IP ""
-Additional note: \fBwimlib-imagex\fR is generalized enough that you can in
-fact combine \fB--pipable\fR and \fB--delta-from\fR to create pipable delta
-WIMs. In such cases, the base WIM(s) must be captured as pipable as well as the
-delta WIM, and when applying an image, the base WIM(s) must be sent over the
-pipe after the delta WIM.
-.TP
-\fB--wimboot\fR
-Mark the image as WIMBoot-compatible. See Microsoft's
-documentation for more information about WIMBoot. This option will, by default,
-set the compression type to XPRESS and the chunk size to 4096 bytes; these
-can, however, still be overridden through the \fB--compress\fR and
-\fB--chunk-size\fR parameters, respectively. In addition, this option will, by
-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
-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
-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:
-.IP \[bu] 4
-With \fBwimlib-imagex\fR on UNIX-like systems, it is possible to create a
-WIM image containing files with names differing only in case, or files with
-names containing the characters ':', '*', '?', '"', '<', '>', '|', or '\\',
-which are valid on POSIX-compliant filesystems but not Windows. Be warned that
-such files will not be extracted by default by the Windows version of
-\fBwimlib-imagex\fR, and (even worse) Microsoft's ImageX can be confused by
-such names and quit extracting the image partway through. (It perhaps is worth
-pointing out that Windows' own default filesystem, NTFS, supports these
-characters, although Windows does not!)
-.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.
-.IP \[bu]
-WIMs captured with a non-default chunk size (with the \fB--chunk-size\fR option)
-or as solid archives (with the \fB--solid\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. Generally, more
-recent versions of Microsoft's software are more compatible.
-.SH EXAMPLES
-First example: Create a new WIM 'mywim.wim' with LZX ("maximum") compression
-that will contain a captured image of the directory tree 'somedir'. Note that
-the image name need not be specified and will default to 'somedir':
-.RS
-.PP
-wimlib-imagex capture somedir mywim.wim
-.RE
-.PP
-or, if the \fBwimcapture\fR hard link or batch file has been installed, the
-abbreviated form can be used:
-.RS
-.PP
-wimcapture somedir mywim.wim
-.RE
-.PP
-The remaining examples will use the long form, however. Next, append the image
-of a different directory tree to the WIM created above:
-.RS
-.PP
-wimlib-imagex append anotherdir mywim.wim
-.RE
-.PP
-Easy enough, and the above examples of imaging directory trees work on both
-UNIX-like systems and Windows. Next, capture a WIM with several non-default
-options, including XPRESS ("fast") compression, an integrity table, no messing
-with absolute symbolic links, and an image name and description:
-.RS
-.PP
-wimlib-imagex capture somedir mywim.wim --compress=fast \\
-.RS
---check --norpfix "Some Name" "Some Description"
-.RE
-.RE
-.PP
-Capture an entire NTFS volume into a new WIM file and name the image "Windows
-7". On UNIX-like systems, this requires using the special mode described in
-\fBNTFS VOLUME CAPTURE (UNIX)\fR where \fISOURCE\fR is a file or block device
-containing an NTFS filesystem:
-.RS
-.PP
-wimlib-imagex capture /dev/sda2 windows7.wim "Windows 7"
-.RE
-.PP
-or, on Windows, to capture a full NTFS volume you instead need to specify the
-root directory of the mounted volume, for example:
-.RS
-.PP
-wimlib-imagex capture E:\\ windows7.wim "Windows 7"
-.RE
-.PP
-Same as above example with capturing an NTFS volume from \fBwimlib-imagex\fR
-running on a UNIX-like system, but capture the WIM in the wimlib-specific
-"pipable" format that can be piped to \fBwimlib-imagex apply\fR:
-.RS
-.PP
-wimlib-imagex capture /dev/sda2 windows7.wim "Windows 7" \\
-.br
-.RS
---pipable
-.RE
-.RE
-.PP
-Same as above, but instead of writing the pipable WIM to the file
-"windows7.wim", write it directly to standard output through a pipe into some
-other program "someprog", which could, for example, be a program or script that
-streams the data to a server. Note that \fB--pipable\fR need not be explicitly
-specified when using standard output as the WIM "file":
-.RS
-.PP
-wimlib-imagex capture /dev/sda2 - "Windows 7" | someprog
-.RE
-.SH SEE ALSO
-.BR wimlib-imagex (1),
-.BR wimlib-imagex-apply (1)
git://wimlib.net / wimlib / commitdiff