wimlib-imagex: Support being invoked as wimCOMMAND
[wimlib] / doc / imagex-capture.1.in
1 .TH IMAGEX "1" "August 2013" "@IMAGEX_PROGNAME@ @VERSION@" "User Commands"
3 @IMAGEX_PROGNAME@-capture, @IMAGEX_PROGNAME@-append \- Create or append a WIM image
7 .br
11 The \fB@IMAGEX_PROGNAME@ capture\fR and \fB@IMAGEX_PROGNAME@ append\fR commands
12 create a Windows Imaging (WIM) image from a directory tree.  The
13 \fB@IMAGEX_PROGNAME@ capture\fR command creates a new WIM file containing the
14 captured image, while the \fB@IMAGEX_PROGNAME@ append\fR command appends the
15 captured image to an existing WIM file.
16 These commands are also available as simply \fBwimcapture\fR and \fBwimappend\fR
17 if the appropriate hard links or batch files are installed.
18 .PP
19 Background information: A WIM image is an independent directory tree in a WIM
20 file.  A WIM file may contain any number of separate images.  WIM files are
21 single-instancing with regards to file data, so a file is stored only one time
22 in the entire WIM, regardless of how many images the file appears in.
23 .PP
24 \fISOURCE\fR specifies the location of the files to create the new WIM image
25 from.  If \fISOURCE\fR is a directory, the WIM image is captured from that
27 (WINDOWS)\fR.   Alternatively, if the \fB--source-list\fR option is specified,
28 \fISOURCE\fR is interpreted as a file that itself provides a list of
29 files and directories to include in the new WIM image.  Still
30 alternatively, only on UNIX-like systems, if \fISOURCE\fR is a
31 regular file or block device, it is interpreted as an NTFS volume from
32 which a WIM image is to be captured using libntfs-3g (see \fBNTFS VOLUME CAPTURE
33 (UNIX)\fR.
34 .PP
35 \fIIMAGE_NAME\fR and \fIIMAGE_DESCRIPTION\fR specify the name and description to
36 give the new WIM image.  If \fIIMAGE_NAME\fR is not specified, it defaults to
37 the base name (excluding path to parent directory) of \fISOURCE\fR, but if this
38 name already exists in \fIWIMFILE\fR, a unique suffix is added.  Otherwise,
39 \fIIMAGE_NAME\fR must be either a name that does not already exist as an image in
40 \fIWIMFILE\fR, or the empty string to create an image with no name.  If
41 \fIIMAGE_DESCRIPTION\fR is not specified, no description is given to the new
42 image.
43 .PP
44 As a special case, if \fIWIMFILE\fR is "-", the \fB--pipable\fR option is
45 assumed and the WIM file is written to standard output in a special pipable
46 format.   See the documentation for \fB--pipable\fR for more details.
48 This section documents how \fB@IMAGEX_PROGNAME@\fR captures files from a
49 directory tree on UNIX-like systems.  See \fBDIRECTORY CAPTURE (WINDOWS)\fR for
50 the corresponding documentation for Windows.
51 .PP
52 On UNIX-like systems, when \fISOURCE\fR specifies a directory or a symbolic link
53 to a directory, the WIM image will be captured from the directory tree rooted at
54 this directory.  This directory can be on any type of filesystem, and mount
55 points are followed recursively.  However, it is important to keep in mind that
56 the WIM format was designed for Windows, so it cannot store all possible
57 metadata from filesystems used on UNIX-like systems.  The main information that
58 will \fInot\fR be stored is:
59 .IP \[bu] 4
60 UNIX file owners, groups, and modes.  (Exception: see the \fB--unix-data\fR
61 option.)  As a result, file permissions will not be stored, and files that are
62 neither regular files, directories, nor symbolic links, such as device files and
63 FIFOs, cannot be captured.
64 .IP \[bu]
65 Extended attributes.  This mainly includes extensions to the traditional UNIX
66 security model, such as SELinux security labels, POSIX ACLs, and capabilities
67 labels.
68 .PP
69 Notes: hard links and symbolic links are supported by the WIM format and
70 \fIare\fR stored.  (Symbolic links are turned into "native" Windows symbolic
71 links via reparse points; this process is reversible, e.g. automatically by
72 \fB@IMAGEX_PROGNAME@ apply\fR.)  Timestamps are stored with 100 nanosecond
73 granularity and include last modification time (mtime) and last access time
74 (atime), but not last status change time (ctime).
76 This section documents how \fB@IMAGEX_PROGNAME@\fR captures files from an NTFS
77 volume image on UNIX-like systems.  See \fBDIRECTORY CAPTURE (WINDOWS)\fR for
78 the corresponding documentation for Windows.
79 .PP
80 On UNIX-like systems, a special image capture mode is entered when \fISOURCE\fR
81 is a regular file or block device.  In this mode, \fISOURCE\fR is assumed to be
82 a NTFS volume or volume image, and wimlib will capture a WIM image containing a
83 full contents of the NTFS volume, including NTFS-specific data.  This is done
84 using libntfs-3g.
85 .PP
86 Please note that the NTFS volume capture mode is \fInot\fR entered if
87 \fISOURCE\fR is a directory, even if an NTFS filesystem is mounted on
88 \fISOURCE\fR using ntfs-3g.  You must specify the NTFS volume itself (and it
89 must be unmounted, and you must have permission to read from it).
90 .PP
91 The NTFS volume capture mode attempts to capture as much data as
92 possible, including:
93 .IP \[bu] 4
94 All data streams of all files, including the unnamed data stream as well as all
95 named data streams.
96 .IP \[bu]
97 Reparse points, including symbolic links, junction points, and other reparse
98 points.
99 .IP \[bu]
100 File and directory creation, access, and modification timestamps, using the
101 native NTFS resolution of 100 nanoseconds.
102 .IP \[bu]
103 Windows security descriptors, including all components (owner, group, DACL, and
104 SACL).
105 .IP \[bu]
106 DOS/Windows file attribute flags.
107 .IP \[bu]
108 All names of all files, including names in the Win32 namespace, DOS namespace,
109 Win32+DOS namespace, and POSIX namespace.  This includes hard links.
111 On Windows, \fB@IMAGEX_PROGNAME@ capture\fR and \fB@IMAGEX_PROGNAME@ append\fR
112 natively support Windows-specific and NTFS-specific data.  They therefore act
113 similarly to the corresponding commands of Microsoft's ImageX.  For best
114 results, the directory being captured should be on an NTFS volume and you should
115 be running with Administrator privileges; however, non-NTFS filesystems and
116 running without Administrator privileges are also supported.
117 .PP
118 On Windows, \fB@IMAGEX_PROGNAME@ capture\fR and \fB@IMAGEX_PROGNAME@ append\fR
119 try to archive as much data as possible, including:
120 .IP \[bu] 4
121 All data streams of all files, unless running on a version of Windows prior to
122 Vista, in which case named data streams (if supported by the source filesystem)
123 will not be captured.
124 .IP \[bu]
125 Reparse points, including symbolic links, junction points, and other reparse
126 points, if supported by the source filesystem.  (Note: see \fB--rpfix\fR and
127 \fB--norpfix\fR for documentation on exactly how absolute symbolic links and
128 junctions are captured.)
129 .IP \[bu]
130 File and directory creation, access, and modification timestamps.  These are
131 stored with Windows NT's native timestamp resolution of 100 nanoseconds.
132 .IP \[bu]
133 Security descriptors, if supported by the source filesystem and \fB--no-acls\fR
134 is not specified.  However, beware that unless \fB--strict-acls\fR is specified,
135 the security descriptor for individual files or directories may be omitted or
136 only partially captured if the user does not have permission to read it, which
137 is mainly a problem if \fB@IMAGEX_PROGNAME@\fR is run as a non-Administrator.
138 .IP \[bu]
139 File attributes, including hidden, sparse, compressed, encrypted, etc.
140 Encrypted files will be stored in encrypted form rather than in plain text.
141 Transparently compressed files will be read as uncompressed and stored subject
142 to the WIM's own compression.  There is no special handling for storing sparse
143 files, but they are likely to compress to a small size.
144 .IP \[bu]
145 DOS names (8.3) names of files; however, the failure to read them is not
146 considered an error condition.
147 .IP \[bu]
148 Hard links, if supported by the source filesystem.
149 .PP
150 Note: the capture process is reversible, since when \fB@IMAGEX_PROGNAME@
151 apply\fR (on Windows) extracts the captured WIM image, it will extract all of
152 the above information, at least to the extent supported by the destination
153 filesystem.  One exception is that since encrypted files are stored as
154 unencrypted, their data will not be available if restored on a Windows system
155 that does not have the decryption key.
157 .TP 6
158 \fB--boot\fR
159 Specifies that the new image is to be made the bootable image of the WIM archive.
160 .TP
161 \fB--check\fR
162 For \fB@IMAGEX_PROGNAME@ append\fR, before performing the append operation,
163 check the integrity of \fIWIMFILE\fR if an integrity table is present.
164 Furthermore, include an integrity table in the new WIM file
165 (\fB@IMAGEX_PROGNAME@ capture\fR) or the modified WIM file (\fB@IMAGEX_PROGNAME@
166 append\fR).  If this option is not specified, no integrity table is included in
167 a WIM file created with \fB@IMAGEX_PROGNAME@ capture\fR, while a WIM file
168 updated with \fB@IMAGEX_PROGNAME@ append\fR will be written with an integrity
169 table if and only if one was present before.
170 .TP
171 \fB--compress\fR=\fITYPE\fR
172 Specifies the compression type for the new WIM file.  This flag is only valid
173 for \fB@IMAGEX_PROGNAME@ capture\fR, since the compression mode for
174 \fB@IMAGEX_PROGNAME@ append\fR must be the same as that of the existing WIM (and
175 is automatically set as such).
176 \fITYPE\fR may be "none", "fast", or "maximum".  By default, it is "maximum".
177 This default behavior is different from Microsoft's ImageX, where the default is
178 "fast". \fB@IMAGEX_PROGNAME@ capture\fR instead gives you the best compression
179 ratio by default and makes up for the slightly slower compression by being
180 faster than Microsoft's software in the first place and using multiple CPUs when
181 available.
182 .IP ""
183 You may also specify the actual names of the compression algorithms, "XPRESS"
184 and "LZX", instead of "fast" and "maximum", respectively.
185 .TP
186 \fB--threads\fR=\fINUM_THREADS\fR
187 Number of threads to use for compressing data.  Default: autodetect (number of
188 available CPUs).
189 .TP
190 \fB--rebuild\fR
191 For \fB@IMAGEX_PROGNAME@ append\fR: rebuild the entire WIM rather than appending the new
192 data to the end of it.  Rebuilding the WIM is slower, but will save a little bit
193 of space that would otherwise be left as a hole in the WIM.  Also see \fB@IMAGEX_PROGNAME@
194 optimize\fR(1).
195 .TP
196 \fB--flags\fR=\fIEDITIONID\fR
197 Specify a string to use in the <FLAGS> element of the XML data for the new
198 image.
199 .TP
200 \fB--verbose\fR
201 Print the names of files and directories as they are captured.
202 .TP
203 \fB--dereference\fR
204 (UNIX-like systems only) Follow symbolic links and archive the files they point
205 to, rather than archiving the links themselves.
206 .TP
207 \fB--config\fR=\fIFILE\fR
208 Specifies a configuration file for capturing the new image.  The configuration
209 file specifies files that are to be treated specially during the image capture.
210 .IP ""
211 The format of the configuration file is a number of sections containing path
212 globs one per line, where each section begins with the tag [ExclusionList],
213 [ExclusionException], [CompressionExclusionList], or [AlignmentList].
214 Currently, only the [ExclusionList] and [ExclusionException] sections are
215 implemented.  The [ExclusionList] section specifies a list of path globs to
216 exclude from capture, while the [ExclusionException] section specifies a list of
217 path globs to include in the capture even if the matched file or directory name
218 also appears in the [ExclusionList].
219 .IP ""
220 Relative globs with only one path component (e.g. *.mp3) match against a
221 filename in any directory.  Relative globs with multiple path components (e.g.
222 dir/file), as well as absolute globs (e.g. /dir/file), are treated as paths
223 starting at the root directory of capture, or the root of the NTFS volume for
224 NTFS volume capture mode.  If a directory is matched by a glob in the
225 [ExclusionList], the entire directory tree rooted at that directory is excluded
226 from the capture, unless \fB--dereference\fR is specified and there is another
227 path into that directory through a symbolic link.
228 .IP ""
229 For compatibility with Windows, the path separators in the globs may be either
230 forward slashes or backslashes, and the line separators may be either UNIX-style
231 or DOS-style.  Globs with spaces in them must be quoted, and leading and
232 trailing whitespace is not significant.  Empty lines and lines beginning with
233 \'#' or whitespace followed by '#' are ignored.
234 .IP ""
235 Paths may not have drive letters in them, as they are all relative to the root
236 of capture and not absolute external paths.
237 .IP ""
238 If this option is not specified the following default configuration file is
239 used:
240 .IP ""
241 .RS
242 .RS
243 .nf
244 [ExclusionList]
245 \\$ntfs.log
246 \\hiberfil.sys
247 \\pagefile.sys
248 "\\System Volume Information"
250 \\Windows\\CSC
251 .RE
252 .RE
253 .fi
254 .TP
255 \fB--unix-data\fR
256 (UNIX-like systems only) Store the UNIX owner, group, and mode of all captured
257 files.  This is done by adding a special alternate data stream to each directory
258 entry that contains this information.  Please note that this flag is for
259 convenience only, in case you want to use \fB@IMAGEX_PROGNAME@\fR to archive
260 files on UNIX.  Microsoft's software will not understand this special
261 information.  You also may run into problems when applying an image with UNIX
262 data from a pipable WIM.
263 .TP
264 \fB--no-acls\fR
265 Do not capture files' security descriptors.
266 .TP
267 \fB--strict-acls\fR
268 Fail immediately if the full security descriptor of any file cannot be read.  On
269 Windows, the default behavior without this option is to first try omitting the
270 SACL from the security descriptor, then to try omitting the security descriptor
271 entirely.  The purpose of this is to capture as much data as possible without
272 always requiring Administrator privileges.  However, if you desire that all
273 security descriptors be captured exactly, you may wish to provide this option,
274 although the Administrator should have permission to read everything anyway.
275 .TP
276 \fB--rpfix\fR, \fB--norpfix\fR
277 Set whether to fix targets of absolute symbolic links (reparse points in Windows
278 terminology) or not.  When enabled (\fB--rpfix\fR), absolute symbolic links that
279 point inside the directory tree being captured will be adjusted to be absolute
280 relative to the root of the directory tree being captured.  In addition,
281 absolute symbolic links that point outside the directory tree being captured
282 will be ignored and not be captured at all.  When disabled (\fB--norpfix\fR),
283 absolute symbolic links will be captured exactly as is.
284 .IP ""
285 The default behavior for \fB@IMAGEX_PROGNAME@ capture\fR is equivalent to
286 \fB--rpfix\fR.  The default behavior for \fB@IMAGEX_PROGNAME@ append\fR will be
287 \fB--rpfix\fR if reparse point fixups have previously been done on
288 \fIWIMFILE\fR, otherwise \fB--norpfix\fR.
289 .IP ""
290 In the case of a multi-source capture, (\fB--source-list\fR specified), passing
291 \fB--norpfix\fR is recommended.  Otherwise, reparse point fixups will be
292 disabled on all capture sources destined for non-root locations in the WIM
293 image, while capture sources destined for the WIM root will get the default
294 behavior from the previous paragraph.
295 .TP
296 \fB--source-list\fR
297 \fB@IMAGEX_PROGNAME@ capture\fR and \fB@IMAGEX_PROGNAME@ append\fR support
298 creating a WIM image from multiple separate files or directories.  When
299 \fB--source-list\fR is specified, the \fISOURCE\fR argument specifies the name
300 of a text file, each line of which is either 1 or 2 whitespace separated file
301 paths.  The first file path, the source, specifies the path to a file or
302 directory to capture into the WIM image.  It may be either absolute or relative
303 to the current working directory.  The second file path, if provided, is the
304 target and specifies the path  in the WIM image that this file or directory will
305 be saved as.  Leading and trailing slashes in the target are ignored, except if
306 it consists entirely of slashes (e.g. "/"), which indicates that the directory
307 is to become the root of the WIM image.  If omitted, the target string defaults
308 to the same as the source string.
309 .IP ""
310 An example source list file is as follows:
311 .IP ""
312 .RS
313 .RS
314 .nf
315 # Make the WIM image from the 'winpe' directory
316 winpe   /
318 # Send the 'overlay' directory to '/overlay' in the WIM image
319 overlay /overlay
321 # Overlay a separate directory directly on the root of the WIM image.
322 # This is only legal if there are no conflicting files.
323 /data/stuff     /
324 .RE
325 .RE
326 .fi
327 .IP ""
328 Subdirectories in the WIM are created as needed.  Multiple source directories
329 may share the same target, which implies an overlay; however, an error is issued
330 if the same file appears in different overlays to the same directory.
331 .IP ""
332 File paths containing whitespace may be quoted with either single quotes or
333 double quotes.  Quotes may not be escaped.
334 .IP ""
335 Lines consisting only of whitespace and lines beginning with '#' preceded by
336 optional whitespace are ignored.
337 .IP ""
338 As a special case, if \fISOURCE\fR is "-", the source list is read from standard
339 input rather than an external file.
340 .IP ""
341 The NTFS volume capture mode on UNIX-like systems cannot be used with
342 \fB--source-list\fR, as only capturing a full NTFS volume is supported.
343 .TP
344 \fB--pipable\fR
345 Create a "pipable" WIM, which can be applied fully sequentially, including from
346 a pipe.  An image in the resulting WIM can be applied with \fB@IMAGEX_PROGNAME@
347 apply\fR, either normally by specifying the WIM file name, or with
348 \fB@IMAGEX_PROGNAME@ apply -\fR to read the WIM from standard input.  See
349 \fB@IMAGEX_PROGNAME@ apply\fR(1) for more details.
350 .IP ""
351 For append operations, this option will result in a full rebuild of the WIM to
352 make it pipable.  For capture operations, the captured WIM is simply created as
353 pipable.  Beware that the more images you add to a pipable WIM, the less
354 efficient piping it will be, since more unneeded data will be sent through the
355 pipe.
356 .IP ""
357 When wimlib creates a pipable WIM, it carefully re-arranges the components of
358 the WIM so that they can be read sequentially and also makes several other
359 modifications.  As a result, these "pipable" WIMs are \fInot compatible with
360 Microsoft's software\fR, so keep this in mind if you're going to use them.  If
361 desired, you can use \fB@IMAGEX_PROGNAME@ optimize --not-pipable\fR to re-write
362 a pipable WIM as a regular WIM.  (\fB@IMAGEX_PROGNAME@ export\fR also provides
363 the capability to export images from a pipable WIM into a non-pipable WIM, or
364 vice versa.)
365 .IP ""
366 For the most part, wimlib operates on pipable WIMs transparently.  You can
367 modify them, add or delete images, export images, and even create split pipable
368 WIMs.  The main disadvantages are that appending is (currently) less efficient
369 (\fB--rebuild\fR is always implied), and also they aren't compatible with
370 Microsoft's software.
371 .IP ""
372 \fB@IMAGEX_PROGNAME@ capture\fR and \fB@IMAGEX_PROGNAME@ append\fR can both
373 write a pipable WIM directly to standard output; this is done automatically if
374 \fIWIMFILE\fR is specified as "-".  (In that case, \fB--pipable\fR is assumed.)
375 .TP
376 \fB--not-pipable\fR
377 Ensure the resulting WIM is in the normal, non-pipable WIM format.  This is the
378 default for \fB@IMAGEX_PROGNAME@ capture\fR, except when writing to standard
379 output (\fIWIMFILE\fR specified as "-"), and also for \fB@IMAGEX_PROGNAME@
380 append\fR, except when appending to a WIM that is already pipable.
382 \fB@IMAGEX_PROGNAME@ append\fR does not support appending an image to a split WIM.
383 .PP
384 It is safe to abort an \fB@IMAGEX_PROGNAME@ append\fR command partway through;
385 however, after doing this, it is recommended to run \fB@IMAGEX_PROGNAME@
386 optimize\fR to remove any data that was appended to the physical WIM file but
387 not yet incorporated into the structure of the WIM, unless the WIM was being
388 fully rebuilt (e.g. with \fB--rebuild\fR), in which case you should delete the
389 temporary file left over.
390 .PP
391 \fB@IMAGEX_PROGNAME@\fR creates WIMs compatible with Microsoft's software
392 (imagex.exe, Dism.exe, wimgapi.dll), with some caveats:
393 .IP \[bu] 4
394 With \fB@IMAGEX_PROGNAME@\fR on UNIX-like systems, it is possible to create a
395 WIM image containing files with names differing only in case, or files with
396 names containing the characters ':', '*', '?', '"', '<', '>', '|', or '\\',
397 which are valid on POSIX-compliant filesystems but not Windows.  Be warned that
398 such files will not be extracted by default by the Windows version of
399 \fB@IMAGEX_PROGNAME@\fR, and (even worse) Microsoft's ImageX can be confused by
400 such names and quit extracting the image partway through.  (It perhaps is worth
401 pointing out that Windows' own default filesystem, NTFS, supports these
402 characters, although Windows does not!)
403 .IP \[bu]
404 WIMs captured with \fB--unix-data\fR should be assumed to be incompatible with
405 Microsoft's software.
406 .IP \[bu]
407 Pipable WIMs are incompatible with Microsoft's software.  Pipable WIMs are
408 created only if \fIWIMFILE\fR was specified as "-" (standard output) or if
409 the \fB--pipable\fR flag was specified.
411 First example:  Create a new WIM 'mywim.wim' with "maximum" (LZX) compression
412 that will contain a captured image of the directory tree 'somedir'.  Note that
413 \fB@IMAGEX_PROGNAME@\fR uses "maximum" (LZX) compression by default, so
414 \fB--compress\fR does \fInot\fR need to be specified; furthermore, the image
415 name need not be specified and will default to 'somedir':
416 .RS
417 .PP
418 @IMAGEX_PROGNAME@ capture somedir mywim.wim
419 .RE
420 .PP
421 or, if the \fBwimcapture\fR hard link or batch file is installed, the
422 abbreviated form can be used:
423 .RS
424 .PP
425 wimcapture somedir mywim.wim
426 .RE
427 .PP
428 The remaining examples will use the long form, however.  Next, append the image
429 of a different directory tree to the WIM created above:
430 .RS
431 .PP
432 @IMAGEX_PROGNAME@ append anotherdir mywim.wim
433 .RE
434 .PP
435 Easy enough, and the above examples of imaging directory trees work on both
436 UNIX-like systems and Windows.  Next, capture a WIM with several non-default
437 options, including "fast" (XPRESS) compression, an integrity table, no messing
438 with absolute symbolic links, and an image name and description:
439 .RS
440 .PP
441 @IMAGEX_PROGNAME@ capture somedir mywim.wim --compress=fast \\
442 .RS
443 --check --norpfix "Some Name" "Some Description"
444 .RE
445 .RE
446 .PP
447 Capture an entire NTFS volume into a new WIM file and name the image "Windows
448 7".  On UNIX-like systems, this requires using the special mode described in
449 \fBNTFS VOLUME CAPTURE (UNIX)\fR where \fISOURCE\fR is a file or block device
450 containing a NTFS filesystem:
451 .RS
452 .PP
453 @IMAGEX_PROGNAME@ capture /dev/sda2 windows7.wim "Windows 7"
454 .RE
455 .PP
456 or, on Windows, to capture a full NTFS volume you instead need to specify the
457 root directory of the mounted volume, for example:
458 .RS
459 .PP
460 @IMAGEX_PROGNAME@ capture E:\\ windows7.wim "Windows 7"
461 .RE
462 .PP
463 Same as above example with capturing a NTFS volume from \fB@IMAGEX_PROGNAME@\fR
464 running on a UNIX-like system, but capture the WIM in the wimlib-specific
465 "pipable" format that can be piped to \fB@IMAGEX_PROGNAME@ apply\fR:
466 .RS
467 .PP
468 @IMAGEX_PROGNAME@ capture /dev/sda2 windows7.wim "Windows 7" \\
469 .br
470 .RS
471 --pipable
472 .RE
473 .RE
474 .PP
475 Same as above, but instead of writing the pipable WIM to the file
476 "windows7.wim", write it directly to standard output through a pipe into some
477 other program "someprog", which could, for example, be a program or script that
478 streams the data to a server.  Note that \fB--pipable\fR need not be explicitly
479 specified when using standard output as the WIM "file":
480 .RS
481 .PP
482 @IMAGEX_PROGNAME@ capture /dev/sda2 - "Windows 7" | someprog
483 .RE
486 .BR @IMAGEX_PROGNAME@-apply (1)