-.TH IMAGEX "1" "November 2012" "imagex (wimlib) wimlib @VERSION@" "User Commands"
+.TH IMAGEX "1" "May 2013" "@IMAGEX_PROGNAME@ @VERSION@" "User Commands"
.SH NAME
-imagex-capture, imagex-append \- Capture a WIM image from a directory tree
-
+@IMAGEX_PROGNAME@-capture, @IMAGEX_PROGNAME@-append \- Create or append a WIM image
.SH SYNOPSIS
-\fBimagex capture\fR \fISOURCE\fR \fIWIMFILE\fR [\fIIMAGE_NAME\fR] \
-[\fIDESCRIPTION\fR] [\fIOPTION\fR]...
+\fB@IMAGEX_PROGNAME@ capture\fR \fISOURCE\fR \fIWIMFILE\fR [\fIIMAGE_NAME\fR \
+[\fIIMAGE_DESCRIPTION\fR]] [\fIOPTION\fR...]
.br
-\fBimagex append\fR \fISOURCE\fR \fIWIMFILE\fR [\fIIMAGE_NAME\fR] \
-[\fIDESCRIPTION\fR] [\fIOPTION\fR]...
-
+\fB@IMAGEX_PROGNAME@ append\fR \fISOURCE\fR \fIWIMFILE\fR [\fIIMAGE_NAME\fR \
+[\fIIMAGE_DESCRIPTION\fR]] [\fIOPTION\fR...]
.SH DESCRIPTION
+The \fB@IMAGEX_PROGNAME@ capture\fR and \fB@IMAGEX_PROGNAME@ append\fR commands
+create a Windows Imaging (WIM) image from a directory tree. The
+\fB@IMAGEX_PROGNAME@ capture\fR command creates a new WIM file containing the
+captured image, while the \fB@IMAGEX_PROGNAME@ append\fR command appends the
+captured image to an existing WIM file.
.PP
-
-The \fBimagex capture\fR and \fBimagex append\fR commands create a Windows
-Imaging (WIM) image from a directory tree. The \fBimagex capture\fR command
-creates a new WIM file containing the captured image, while the \fBimagex
-append\fR command appends the captured image to an existing WIM file.
-
A WIM image is an independent directory tree in the WIM file. A WIM file may
contain any number of separate images. However, files are 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. If \fISOURCE\fR is a regular file or block device, it is interpreted
-as a NTFS volume from which a WIM image is to be captured.
-
-\fIIMAGE_NAME\fR and \fIDESCRIPTION\fR specify the name and description of the
-new image. If \fIIMAGE_NAME\fR is not given, it is taken to be the same as the
-base name of \fISOURCE\fR. If \fIDESCRIPTION\fR is not given, no description is
-given to the new image.
-
-.SH NORMAL MODE
-
-The normal image capture mode is entered when \fISOURCE\fR specifies a
-directory. The WIM image will be captured from the directory tree rooted at
+directory. Alternatively, if the \fB--source-list\fR option is given,
+\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 builds of wimlib, 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.
+.PP
+\fIIMAGE_NAME\fR and \fIIMAGE_DESCRIPTION\fR specify the name and description of
+the new image. If \fIIMAGE_NAME\fR is not given, it is taken to be the same as
+the base name of \fISOURCE\fR. If \fIIMAGE_DESCRIPTION\fR is not given, no
+description is given to the new image.
+.SH NORMAL MODE (UNIX)
+This section documents how files are captured from a directory on UNIX. See
+\fBWINDOWS VERSION\fR for the corresponding documentation for the Windows
+version.
+.PP
+On UNIX, the "normal" image capture mode is entered when \fISOURCE\fR specifies
+a directory. The WIM image will be captured from the directory tree rooted at
this directory. The directory may be on any type of filesystem.
-
-In this normal image capture mode, we capture the following information from the
-directory tree:
-
+.PP
+In this mode, the following information is captured from the directory tree:
.IP \[bu] 4
The "normal" name and contents of each file and directory
.IP \[bu]
100 nanoseconds, if supported by the underlying filesystem
.IP \[bu]
Hard links and symbolic links
-
.PP
-
-However, in the normal image capture mode, we do \fInot\fR capture the following
-information from the directory tree:
-
+However, in this mode, the following information is \fInot\fR captured from the
+directory tree:
.IP \[bu] 4
-File permissions. The resulting WIM image will not contain any security
-descriptors because the format of the security descriptors is Windows-specific,
-and they cannot contain UNIX file modes.
+UNIX file owners, groups, and modes. The resulting WIM image will contain no
+security information (file permissions). (Exception: see the \fB--unix-data\fR
+option.)
.IP \[bu]
-No alternate data streams will be captured, since these do not exist on
-POSIX-compliant filesystems. The resulting WIM image will not contain any
-alternate data streams.
-
-.SH NTFS MODE
-
-A special image capture mode is entered when \fISOURCE\fR is a regular file or
-block device. \fISOURCE\fR is interpreted as an NTFS volume and opened using
-libntfs-3g. If successful, a WIM image is captured containing the contents of
-the NTFS volume, including NTFS-specific data.
-
+Extended attributes.
+.SH NTFS MODE (UNIX)
+This section documents how files are captured from an NTFS volume image on UNIX.
+See \fBWINDOWS VERSION\fR for the corresponding documentation for the Windows
+version.
+.PP
+On UNIX, a special image capture mode is entered when \fISOURCE\fR is a regular
+file or block device. \fISOURCE\fR is interpreted as an NTFS volume and opened
+using libntfs-3g. If successful, a WIM image is captured containing the
+contents of the NTFS volume, including NTFS-specific data.
+.PP
Please note that the NTFS image capture mode is \fInot\fR entered if
-\fISOURCE\fR is a directory, even if a NTFS filesystem is mounted on
+\fISOURCE\fR is a directory, even if an NTFS filesystem is mounted on
\fISOURCE\fR. You must specify the NTFS volume itself (and it must be
unmounted, and you must have permission to read from it).
-
-More specifically, in this mode, we capture the following types of information
+.PP
+More specifically, in this mode, the following types of information are captured
from the NTFS volume:
-
.IP \[bu] 4
All data streams of all files, including the un-named data stream as well as all
named data streams.
.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.
-
+.SH WINDOWS VERSION
+The Windows versions of \fB@IMAGEX_PROGNAME@ capture\fR and \fB@IMAGEX_PROGNAME@
+append\fR act similarly to the corresponding commands of Microsoft's ImageX.
+For best results, the directory being captured should be on an NTFS volume and
+you should be running with Administrator privileges; however, non-NTFS
+filesystems and running without Administrator privileges are also supported.
+.PP
+On Windows, \fB@IMAGEX_PROGNAME@ capture\fR and \fB@IMAGEX_PROGNAME@ append\fR
+try to archive as much data as possible. This includes:
+.IP \[bu] 4
+All data streams of all files. This includes the default file contents, as well
+as named data streams if supported by the filesystem and if the version of
+Windows is Vista or later.
+.IP \[bu]
+Reparse points, including symbolic links, junction points, and other reparse
+points, if supported by the underlying filesystem. (Note: see
+\fB--rpfix\fR and \fB--norpfix\fR for documentation on how absolute symbolic
+links and junctions are captured.)
+.IP \[bu]
+File and directory creation, access, and modification timestamps to the nearest
+100 nanoseconds.
+.IP \[bu]
+Security descriptors, if supported by the filesystem and \fB--no-acls\fR is not
+specified. Furthermore, unless \fB--strict-acls\fR is specified, the security
+descriptor for individual files or directories may be omitted or only partially
+captured if the user does not have permission to read them.
+.IP \[bu]
+File attributes, including hidden, sparse, compressed, encrypted, etc.
+Encrypted files will be stored in encrypted form rather than in plain text.
+.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, excluding directory hard links (which aren't supposed to exist
+anyway).
.SH OPTIONS
.TP 6
\fB--boot\fR
\fB--check\fR
Include an integrity table in the new WIM file or the modified WIM file. If
this option is not specified, no integrity table is included in \fIWIMFILE\fR,
-even if there was one before in the case of \fBimagex append\fR.
+even if there was one before in the case of \fB@IMAGEX_PROGNAME@ append\fR.
.TP
\fB--compress\fR=\fITYPE\fR
Specifies the compression type for the new WIM file. This flag is only valid
-for \fBimagex capture\fR, since the compression mode for \fBimagex append\fR
-must be the same as that of the existing WIM. \fITYPE\fR may be "none",
-"maximum", or "fast". By default, it is "fast".
-
+for \fB@IMAGEX_PROGNAME@ capture\fR, since the compression mode for
+\fB@IMAGEX_PROGNAME@ append\fR must be the same as that of the existing WIM.
+\fITYPE\fR may be "none", "maximum", or "fast". By default, it is "fast".
+.IP ""
You may also specify the actual names of the compression algorithms, "XPRESS"
and "LZX", instead of "fast" and "maximum", respectively.
.TP
needs to be done in this case.
.TP
\fB--rebuild\fR
-For \fBimagex append\fR: rebuild the entire WIM rather than appending an image
-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 \fBimagex
+For \fB@IMAGEX_PROGNAME@ 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 \fB@IMAGEX_PROGNAME@
optimize\fR.
.TP
\fB--flags\fR=\fIEDITIONID\fR
image.
.TP
\fB--verbose\fR
-Print the names of files and directories as they are captured, as well as a few
-other informational messages.
+Print the names of files and directories as they are captured.
.TP
\fB--dereference\fR
-Follow symlinks; archive and dump the files they point to. (The default is to
-archive the symlinks themselves.) This flag is only valid in the normal image
-capture mode.
+(UNIX 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 for capturing the new image. The configuration
file specifies files that are to be treated specially during the image capture.
-
-The format of the configuration file is a number of sections containing file
+.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 file globs to
+implemented. The [ExclusionList] section specifies a list of path globs to
exclude from capture, while the [ExclusionException] section specifies a list of
-file globs to include in the capture even if the matched file or directory name
+path globs to include in the capture even if the matched file or directory name
also appears in the [ExclusionList].
-
-Relative globs with only one path component match against a filename in any
-directory. Relative globs with multiple path components, as well as absolute
-globs, are treated as paths starting at the root directory of capture, or the
-root of the NTFS volume for NTFS 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 ""
+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 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. However, globs with spaces in them currently must not be quoted.
-Empty lines are ignored.
-
+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.
+.IP ""
If this option is not specified the following default configuration file is
used:
-
+.IP ""
.RS
.RS
-.PP
.nf
[ExclusionList]
\\$ntfs.log
\\hiberfil.sys
\\pagefile.sys
-\\System Volume Information
+"\\System Volume Information"
\\RECYCLER
\\Windows\\CSC
-
-[CompressionExclusionList]
-*.mp3
-*.zip
-*.cab
-\\WINDOWS\\inf\\*.pnf
.RE
.RE
+.fi
+.TP
+\fB--unix-data\fR
+(UNIX 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.
+.TP
+\fB--no-acls\fR
+Do not capture files' security descriptors. This option is available in the
+Windows version, as well as on UNIX in NTFS capture mode.
+.TP
+\fB--strict-acls\fR
+(Windows only) Fail immediately if the full security descriptor of any file
+cannot be read. 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. In addition,
+absolute symbolic links that point outside the directory tree being captured
+will be ignored and not be captured at all. When disabled (\fB--norpfix\fR),
+absolute symbolic links will be captured exactly as is.
+.IP ""
+The default behavior for \fB@IMAGEX_PROGNAME@ capture\fR is equivalent to
+\fB--rpfix\fR. The default behavior for \fB@IMAGEX_PROGNAME@ 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
+\fB@IMAGEX_PROGNAME@ capture\fR and \fB@IMAGEX_PROGNAME@ append\fR support
+creating a WIM image from multiple 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 are ignored. "/" indicates that the
+directory is to become the root of the WIM image. If not specified, the target
+string defaults to the same as the source string.
+.IP ""
+An example source list file is as follows:
+.IP ""
+.RS
+.nf
+# Make the WIM image from the 'winpe' directory
+winpe /
-.SH NOTES
-
-\fBimage append\fR does not support appending an image to a split WIM.
+# Send the 'overlay' directory to '/overlay' in the WIM image
+overlay /overlay
-The two different capture modes only specify the data that is captured and don't
+# Overlay a separate directory directly on the root of the WIM image.
+# This is only legal if there are no conflicting files.
+/data/stuff /
+.RE
+.fi
+.IP ""
+Subdirectories in the WIM are created as needed. Multiple source directories
+may share the same target, which implies an overlay; however, an error is issued
+if the same file appears in different overlays to the same directory.
+.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 capture mode cannot be used with \fB--source-list\fR, as only capturing
+a full NTFS volume is supported.
+.SH NOTES
+\fB@IMAGEX_PROGNAME@ append\fR does not support appending an image to a split WIM.
+.PP
+The different capture modes only specify the data that is captured and don't
specify a special WIM format. A WIM file can contain images captured using
different modes. However, all images in a WIM must have the same compression
-type, and \fBimagex\fR always enforces this.
-
-\fBimagex\fR writes WIMs having the version number 0x10d00 and a compressed
+type, and \fB@IMAGEX_PROGNAME@\fR always enforces this.
+.PP
+\fB@IMAGEX_PROGNAME@\fR writes WIMs having the version number 0x10d00 and a compressed
stream chunk size of 32768. The only WIMs I've seen that are different from
this are some pre-Vista WIMs that had a different version number.
-
+.PP
+It is safe to abort an \fB@IMAGEX_PROGNAME@ append\fR command partway through;
+however, after doing this, it is recommended to run \fB@IMAGEX_PROGNAME@
+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 \fB--rebuild\fR was
+specified, in which case you should delete the temporary file left over.
+.PP
+\fISOURCE\fR may be a symbolic link to a directory rather than a directory
+itself. However, additional symbolic links in subdirectories, or in additional
+source directories not destined for the WIM image root (with
+\fB--source-list\fR), are not dereferenced unless \fB--dereference\fR is
+specified.
+.PP
+With the UNIX version of \fB@IMAGEX_PROGNAME@\fR, 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
+\fB@IMAGEX_PROGNAME@\fR, and Microsoft's ImageX might get confused by such
+names.
.SH EXAMPLES
Create a new WIM 'mywim.wim' from the directory 'somedir', using LZX compression and
including an integrity table:
.RS
.PP
-imagex capture somedir mywim.wim --compress=maximum --check
+@IMAGEX_PROGNAME@ capture somedir mywim.wim --compress=maximum --check
.RE
.PP
-Append an image to the WIM we just captured, but do it from a NTFS volume on the
-partition /dev/sda2, and name the image "Windows 7" and give it a description.
-You do not need to specify the compression type, because the WIM already is
-using LZX compression and this cannot be changed. You need to specify --check
-if you don't want the integrity table to be discarded.
+Append an image to the WIM we just captured, but do it from an NTFS volume on the
+partition /dev/sda2 and name the image "Windows 7". You do not need to specify
+the compression type, because the WIM already is using LZX compression and this
+cannot be changed. You need to specify \fB--check\fR if you don't want the
+integrity table to be discarded.
.RS
.PP
-imagex append /dev/sda2 mywim.wim --check "Windows 7" "Warning: This operating
-system has been approved by Bill Gates"
+@IMAGEX_PROGNAME@ append /dev/sda2 mywim.wim --check "Windows 7"
.RE
.PP
-
.SH SEE ALSO
-.BR imagex (1)
-
+.BR @IMAGEX_PROGNAME@ (1)
git://wimlib.net / wimlib / blobdiff