X-Git-Url: https://wimlib.net/git/?a=blobdiff_plain;f=doc%2Fimagex-capture.1.in;h=0aa4a2aafdaaba607896a8572e4b9f54529332e4;hb=c52da37557b77351f702a865909582b29ed02d1c;hp=35fe06da9d9ac53736bae51a744fdb46fb727675;hpb=e7396f16433694f9b29deb1e62861ea7799a0774;p=wimlib diff --git a/doc/imagex-capture.1.in b/doc/imagex-capture.1.in index 35fe06da..0aa4a2aa 100644 --- a/doc/imagex-capture.1.in +++ b/doc/imagex-capture.1.in @@ -65,6 +65,9 @@ FIFOs, cannot be captured. Extended attributes. This mainly includes extensions to the traditional UNIX security model, such as SELinux security labels, POSIX ACLs, and capabilities labels. +.IP \[bu] +Files that are neither regular files, directories, nor symbolic links, such as +device files and FIFOs. These will be excluded by default. .PP Notes: hard links and symbolic links are supported by the WIM format and \fIare\fR stored. (Symbolic links are turned into "native" Windows symbolic @@ -88,11 +91,11 @@ Please note that the NTFS volume capture mode is \fInot\fR entered if \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 as +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 unnamed 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. @@ -107,6 +110,17 @@ 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 @@ -379,6 +393,70 @@ 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) + +$ 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=winbkup.wim:-1 --delta-from=winbkup.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 \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. .SH NOTES \fB@IMAGEX_PROGNAME@ append\fR does not support appending an image to a split WIM. .PP