X-Git-Url: https://wimlib.net/git/?p=wimlib;a=blobdiff_plain;f=doc%2Fimagex-capture.1.in;h=940bae18997468e17185dd383ed26224784f47dd;hp=d8dc92a2dd816fa809aa67658fbe61054111af03;hb=51f8edf82794f07055e3d9bcc8cd51bf0d86fae0;hpb=4a4aa00c378959fedcc4dab39d0933d36e2a1c3e diff --git a/doc/imagex-capture.1.in b/doc/imagex-capture.1.in index d8dc92a2..940bae18 100644 --- a/doc/imagex-capture.1.in +++ b/doc/imagex-capture.1.in @@ -1,243 +1,574 @@ -.TH IMAGEX "1" "January 2013" "imagex (wimlib) wimlib @VERSION@" "User Commands" +.TH WIMLIB-IMAGEX "1" "August 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. +These commands are also available as simply \fBwimcapture\fR and \fBwimappend\fR +if the appropriate hard links or batch files are installed. .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 +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. 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 -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: - +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 \fB@IMAGEX_PROGNAME@\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 mount +points are followed recursively. However, it is important to keep in mind that +the WIM format was designed for Windows, so it cannot store all possible +metadata from filesystems used on UNIX-like systems. The main information that +will \fInot\fR be stored is: .IP \[bu] 4 -The "normal" name and contents of each file and directory +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. .IP \[bu] -File and directory creation, access, and modification timestamps to the nearest -100 nanoseconds, if supported by the underlying filesystem +Extended attributes. This mainly includes extensions to the traditional UNIX +security model, such as SELinux security labels, POSIX ACLs, and capabilities +labels. .IP \[bu] -Hard links and symbolic links - +Files that are neither regular files, directories, nor symbolic links, such as +device files and FIFOs. These will be excluded by default. .PP - -However, in the normal image capture mode, we do \fInot\fR capture the following -information 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. -.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. - -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. 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 -from the NTFS volume: - +Notes: hard links and symbolic links are supported by the WIM format and +\fIare\fR stored. (Symbolic links are turned into "native" Windows symbolic +links via reparse points; this process is reversible, e.g. automatically by +\fB@IMAGEX_PROGNAME@ apply\fR.) Timestamps are stored with 100 nanosecond +granularity and include last modification time (mtime) and last access time +(atime), but not last status change time (ctime). +.SH NTFS VOLUME CAPTURE (UNIX) +This section documents how \fB@IMAGEX_PROGNAME@\fR captures files directly from +an NTFS volume image on UNIX-like systems. See \fBDIRECTORY CAPTURE +(WINDOWS)\fR for the corresponding documentation for Windows. +.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 wimlib will capture a WIM image containing a +full contents of the NTFS volume, including NTFS-specific data. This is done +using libntfs-3g. +.PP +Please 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 files, including the un-named data stream as well as all -named data streams. +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. .IP \[bu] -File and directory creation, access, and modification timestamps from NTFS -inodes (these have a resolution of 100 nanoseconds). +File and directory creation, access, and modification timestamps, using the +native NTFS resolution of 100 nanoseconds. .IP \[bu] -The security descriptor for each NTFS inode. +Windows security descriptors, including all components (owner, group, DACL, and +SACL). .IP \[bu] -File attribute flags. +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. - +.PP +However, the main limitations of this NTFS volume capture mode are: +.IP \[bu] 4 +Encrypted files are excluded by default. Although ntfs-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.) +.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 +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 +supported. +.PP +On Windows, \fB@IMAGEX_PROGNAME@ capture\fR and \fB@IMAGEX_PROGNAME@ 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, 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.) +.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 \fB@IMAGEX_PROGNAME@\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. +.PP +Note: the capture process is reversible, since when \fB@IMAGEX_PROGNAME@ +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. One exception is that since encrypted files are stored as +unencrypted, their data will not be available if restored on a Windows system +that does not have the decryption key. .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 -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. +For \fB@IMAGEX_PROGNAME@ 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 +(\fB@IMAGEX_PROGNAME@ capture\fR) or the modified WIM file (\fB@IMAGEX_PROGNAME@ +append\fR). If this option is not specified, no integrity table is included in +a WIM file created with \fB@IMAGEX_PROGNAME@ capture\fR, while a WIM file +updated with \fB@IMAGEX_PROGNAME@ append\fR will be written with an integrity +table if and only if one was present before. .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 (and +is automatically set as such). +\fITYPE\fR may be "none", "fast", or "maximum". By default, it is "maximum". +This default behavior is different from Microsoft's ImageX, where the default is +"fast". \fB@IMAGEX_PROGNAME@ capture\fR instead gives you the best compression +ratio by default and makes up for the slightly slower compression by being +faster than Microsoft's software in the first place and using multiple CPUs when +available. +.IP "" You may also specify the actual names of the compression algorithms, "XPRESS" and "LZX", instead of "fast" and "maximum", respectively. .TP \fB--threads\fR=\fINUM_THREADS\fR Number of threads to use for compressing data. Default: autodetect (number of -processors). Note: if creating or appending to an uncompressed WIM, additional -threads will not be used, regardless of this parameter, since no compression -needs to be done in this case. +available CPUs). .TP \fB--rebuild\fR -For \fBimagex append\fR: rebuild the entire WIM rather than appending the new +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 \fBimagex -optimize\fR. +of space that would otherwise be left as a hole in the WIM. Also see \fB@IMAGEX_PROGNAME@ +optimize\fR(1). .TP \fB--flags\fR=\fIEDITIONID\fR Specify a string to use in the element of the XML data for the new 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-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 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 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. 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-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. +.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. 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 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 / -.SH NOTES +# Send the 'overlay' directory to '/overlay' in the WIM image +overlay /overlay -\fBimage append\fR does not support appending an image to a split WIM. +# 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 +.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 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 \fB@IMAGEX_PROGNAME@ +apply\fR, either normally by specifying the WIM file name, or with +\fB@IMAGEX_PROGNAME@ apply -\fR to read the WIM from standard input. See +\fB@IMAGEX_PROGNAME@ 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 \fB@IMAGEX_PROGNAME@ optimize --not-pipable\fR to re-write +a pipable WIM as a regular WIM. (\fB@IMAGEX_PROGNAME@ 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 "" +\fB@IMAGEX_PROGNAME@ capture\fR and \fB@IMAGEX_PROGNAME@ 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 \fB@IMAGEX_PROGNAME@ capture\fR, except when writing to standard +output (\fIWIMFILE\fR specified as "-"), and also for \fB@IMAGEX_PROGNAME@ +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 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). +.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 file. +.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 may be omitted, in which case it will default to the WIM +file being appended to for append operations, or the WIM file from which a delta +is being taken (with \fB--delta-from\fR, if specified) for capture operations. +.TP +\fB--delta-from\fR=\fIWIMFILE\fR +For \fB@IMAGEX_PROGNAME@ 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 "" +To operate on the resulting delta WIM using other commands such as +\fB@IMAGEX_PROGNAME@ apply\fR, you must specify the delta WIM as the WIM file to +operate on, but also reference the base WIM 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 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) -The two 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. +$ wimcapture /some/directory bkup-base.wim -\fBimagex\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. +(some days later, create second backup as delta from first) -Unless \fB--rebuild\fR is specified, aborting an \fBimagex append\fR command -mid-way through has a small chance of corrupting the WIM file. However, a -precaution is taken against this, so it should be very unlikely. In the event -of an aborted \fBimagex append\fR, \fBimagex optimize\fR may be run to remove -extra data that may have been partially appended to the physical WIM file but -not yet incorporated into the structure of the WIM. +$ wimcapture /some/directory bkup-2013-08-20.dwm \\ + --update-of bkup-base.wim:-1 --delta-from bkup-base.wim -Capturing or appending an image happens in two main phases: (1) scanning the -directory or NTFS volume to checksum all the files and determine the streams to -be written, and (2) writing the new streams to the WIM file. Streams are not -stored in memory after (1), since there could easily be gigabytes of data; -instead, they are read again during step (2); however, duplicate streams in the -image, and streams already existing in any other image in the WIM, are not read -again. In the future, it may be possible to introduce the ability to capture an -image with reading each file only one time, although this mode would have some -limitations--- for example, a stream might be compressed only to be thrown away -as a duplicate once it's been checksummed. +(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 \fB@IMAGEX_PROGNAME@ 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. You can use the /ref option of imagex.exe to reference +the base WIM, 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 +WIMs. In such cases, the base WIM must be captured as pipable as well as the +delta WIM, and when applying an image, the base WIM must be sent over the pipe +after the delta WIM. +.SH NOTES +\fB@IMAGEX_PROGNAME@ append\fR does not support appending an image to a split WIM. +.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 the WIM was being +fully rebuilt (e.g. with \fB--rebuild\fR), in which case you should delete the +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: +.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 +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 (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] +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. .SH EXAMPLES -Create a new WIM 'mywim.wim' from the directory 'somedir', using LZX compression and -including an integrity table: +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 +\fB@IMAGEX_PROGNAME@\fR uses "maximum" (LZX) compression by default, so +\fB--compress\fR does \fInot\fR need to be specified; furthermore, the image +name need not be specified and will default to 'somedir': .RS .PP -imagex capture somedir mywim.wim --compress=maximum --check +@IMAGEX_PROGNAME@ capture somedir mywim.wim .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. +or, if the \fBwimcapture\fR hard link or batch file has been installed, the +abbreviated form can be used: .RS .PP -imagex append /dev/sda2 mywim.wim --check "Windows 7" "Warning: This operating -system has been approved by Bill Gates" +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 +@IMAGEX_PROGNAME@ 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 "fast" (XPRESS) compression, an integrity table, no messing +with absolute symbolic links, and an image name and description: +.RS +.PP +@IMAGEX_PROGNAME@ 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 +@IMAGEX_PROGNAME@ 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 +@IMAGEX_PROGNAME@ capture E:\\ windows7.wim "Windows 7" +.RE +.PP +Same as above example with capturing an NTFS volume from \fB@IMAGEX_PROGNAME@\fR +running on a UNIX-like system, but capture the WIM in the wimlib-specific +"pipable" format that can be piped to \fB@IMAGEX_PROGNAME@ apply\fR: +.RS +.PP +@IMAGEX_PROGNAME@ 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 +@IMAGEX_PROGNAME@ capture /dev/sda2 - "Windows 7" | someprog +.RE .SH SEE ALSO -.BR imagex (1) - +.BR @IMAGEX_PROGNAME@ (1), +.BR @IMAGEX_PROGNAME@-apply (1)