X-Git-Url: https://wimlib.net/git/?p=wimlib;a=blobdiff_plain;f=doc%2Fimagex-capture.1.in;h=3685e8ee1d19db431a7e49c88c7928bb4306ec92;hp=6e3edd42048c378c4f543a50656a03234c09647b;hb=9aa9a387906341315fab3f097fdadb3a76fcf280;hpb=ef8f45b98b5c4db398321cd36d052ccbb9c3784a diff --git a/doc/imagex-capture.1.in b/doc/imagex-capture.1.in index 6e3edd42..3685e8ee 100644 --- a/doc/imagex-capture.1.in +++ b/doc/imagex-capture.1.in @@ -1,50 +1,353 @@ -.TH IMAGEX "1" "May 2012" "imagex (wimlib) wimlib @VERSION@" "User Commands" +.TH IMAGEX "1" "May 2013" "@IMAGEX_PROGNAME@ @VERSION@" "User Commands" .SH NAME -imagex capture \- Create a new WIM file from a directory. - +@IMAGEX_PROGNAME@-capture, @IMAGEX_PROGNAME@-append \- Create or append a WIM image .SH SYNOPSIS -\fBimagex capture\fR \fIDIRECTORY\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 +\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 - -Captures a WIM image from \fIDIRECTORY\fR and creates a new WIM archive, -\fIWIMFILE\fR, that contains it. \fIDIRECTORY\fR becomes the root directory of -the image. - -\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 \fIDIRECTORY\fR. If \fIDESCRIPTION\fR is not given, the -description is taken to be empty. - +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. 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. +.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] +File and directory creation, access, and modification timestamps to the nearest +100 nanoseconds, if supported by the underlying filesystem +.IP \[bu] +Hard links and symbolic links +.PP +However, in this mode, the following information is \fInot\fR captured from the +directory tree: +.IP \[bu] 4 +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] +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 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). +.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] +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). +.IP \[bu] +The security descriptor for each NTFS inode. +.IP \[bu] +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. +.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 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. +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 \fB@IMAGEX_PROGNAME@ append\fR. .TP -\fB--compress\fR[=\fITYPE\fR] -Specifies the compression type for the WIM file. \fITYPE\fR may be "none", -"maximum", or "fast". By default, the compression type is "none". If \fB--compress\fR -is specified but \fITYPE\fR is not, the compression type is taken to be -"maximum", which is LZX compression. "fast" compression is XPRESS compression. +\fB--compress\fR=\fITYPE\fR +Specifies the compression type for the new WIM file. This flag is only valid +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 -\fB--flags\fR \fIEDITIONID\fR -Specify a string to use in the element of the XML data for the image. +\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. +.TP +\fB--rebuild\fR +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 +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. +.TP +\fB--dereference\fR +(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. +.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 path globs to +exclude from capture, while the [ExclusionException] section specifies a list of +path globs to include in the capture even if the matched file or directory name +also appears in the [ExclusionList]. +.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. 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 +.nf +[ExclusionList] +\\$ntfs.log +\\hiberfil.sys +\\pagefile.sys +"\\System Volume Information" +\\RECYCLER +\\Windows\\CSC +.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 EXAMPLES -.IP -image capture boot boot.wim --compress=maximum --check -.LP -Create a new WIM 'boot.wim' from the directory 'boot', using LZX compression and -including an integrity table. +# Send the 'overlay' directory to '/overlay' in the WIM image +overlay /overlay +# 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 \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_PROGNAME@ capture somedir mywim.wim --compress=maximum --check +.RE +.PP +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_PROGNAME@ append /dev/sda2 mywim.wim --check "Windows 7" +.RE +.PP .SH SEE ALSO -.BR imagex (1) - +.BR @IMAGEX_PROGNAME@ (1)