X-Git-Url: https://wimlib.net/git/?p=wimlib;a=blobdiff_plain;f=doc%2Fimagex-capture.1.in;h=a3c0ac653333396f4a921efcfb679eadf6d319c9;hp=38c462aa1460f7f2c84cb4c9fa336e1327a3555c;hb=bc0480e80627467ff64818235fbd164ed179f64c;hpb=a381a9e10a60c7790fe33255c949bf55b5872a8d diff --git a/doc/imagex-capture.1.in b/doc/imagex-capture.1.in index 38c462aa..a3c0ac65 100644 --- a/doc/imagex-capture.1.in +++ b/doc/imagex-capture.1.in @@ -1,20 +1,20 @@ -.TH IMAGEX "1" "March 2013" "imagex (wimlib) wimlib @VERSION@" "User Commands" +.TH IMAGEX "1" "April 2013" "@IMAGEX_PROGNAME@ @VERSION@" "User Commands" .SH NAME -imagex-capture, imagex-append \- Create or append a WIM image +@IMAGEX_PROGNAME@-capture, @IMAGEX_PROGNAME@-append \- Create or append a WIM image .SH SYNOPSIS -\fBimagex capture\fR \fISOURCE\fR \fIWIMFILE\fR [\fIIMAGE_NAME\fR] \ +\fB@IMAGEX_PROGNAME@ capture\fR \fISOURCE\fR \fIWIMFILE\fR [\fIIMAGE_NAME\fR] \ [\fIDESCRIPTION\fR] [\fIOPTION\fR]... .br -\fBimagex append\fR \fISOURCE\fR \fIWIMFILE\fR [\fIIMAGE_NAME\fR] \ +\fB@IMAGEX_PROGNAME@ append\fR \fISOURCE\fR \fIWIMFILE\fR [\fIIMAGE_NAME\fR] \ [\fIDESCRIPTION\fR] [\fIOPTION\fR]... .SH DESCRIPTION .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 +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. Note: this man page primarily documents the UNIX behavior. See \fBWINDOWS @@ -106,31 +106,31 @@ Win32+DOS namespace, and POSIX namespace. This includes hard links. Yet another capture mode is entered when the \fB--source-list\fR option is given. It is essentially an extension of the \fBNORMAL MODE\fR that allows multiple files or directories to be incorporated into a WIM image using a single -\fBimagex capture\fR or \fBimagex append\fR command. See the documentation for +\fB@IMAGEX_PROGNAME@ capture\fR or \fB@IMAGEX_PROGNAME@ append\fR command. See the documentation for \fB--source-list\fR below. .SH WINDOWS VERSION -This section documents the differences between \fBimagex capture\fR and -\fBimagex append\fR in the Windows builds of wimlib versus the rest of this man -page, which is written to document UNIX version. +This section documents the differences between \fB@IMAGEX_PROGNAME@ capture\fR and +\fB@IMAGEX_PROGNAME@ append\fR in the Windows builds of wimlib versus the rest of this man +page, which is written to document UNIX build. -\fBimagex capture\fR and \fBimagex append\fR do not have separate "normal" and +\fB@IMAGEX_PROGNAME@ capture\fR and \fB@IMAGEX_PROGNAME@ append\fR do not have separate "normal" and "NTFS" modes on Windows. There is simply one mode, and it uses the Windows API to capture NTFS-specific information, including alternate data streams, reparse points, hard links, and file attributes. So, you essentially get the advantages of the "NTFS mode" documented above, but you can capture a WIM image from any -directory, not just an entire NTFS volume. This is mostly the same behavior as -Microsoft's ImageX. +directory, not just an entire NTFS volume. This is essentially the same +behavior as Microsoft's ImageX. The \fB--source-list\fR option is supported on Windows, but the \fB--dereference\fR option is not. -Other than the differences documented in this section, the Windows version -should be essentially equivalent to the UNIX version. However, one additional -thing to note is that wimlib's Windows version of ImageX is NOT written to be -command-line compatible with Microsoft's version of ImageX, although they are -very similar. +Except for the differences documented in this section, the Windows build of +\fB@IMAGEX_PROGNAME@ capture\fR and \fB@IMAGEX_PROGNAME@ append\fR should be essentially equivalent to +the UNIX build. However, one additional thing to note is that wimlib's Windows +ImageX is NOT written to be command-line compatible with Microsoft's ImageX, +although they are very similar. .SH OPTIONS .TP 6 @@ -140,11 +140,11 @@ Specifies that the new image is to be made the bootable image of the WIM archive \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 +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". @@ -158,9 +158,9 @@ threads will not be used, regardless of this parameter, since no compression needs to be done in this case. .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 +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 @@ -180,27 +180,32 @@ capture mode. 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 +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. +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. 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. + +Paths may not have drive letters in them, as they are all relative to the root +of capture and not absolute external paths. If this option is not specified the following default configuration file is used: @@ -213,15 +218,9 @@ used: \\$ntfs.log \\hiberfil.sys \\pagefile.sys -\\System Volume Information +"\\System Volume Information" \\RECYCLER \\Windows\\CSC - -[CompressionExclusionList] -*.mp3 -*.zip -*.cab -\\WINDOWS\\inf\\*.pnf .RE .RE @@ -230,12 +229,44 @@ used: Store the UNIX owner, group, and mode of regular files, symbolic links, and directories. 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 \fBimagex\fR to archive files on +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 +In the NTFS capture mode, do not capture security descriptors. This flag is +also available in the native Win32 build of wimlib. +.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. + +The default behavior for \fBimagex capture\fR is equivalent to \fB--rpfix\fR. +The default behavior for \fBimagex append\fR will be \fB--rpfix\fR if reparse +point fixups have previously been done on \fIWIMFILE\fR, otherwise +\fB--norpfix\fR. + +Links are fixed up on a per-source basis in the case of a multi-source capture +(\fB--source-list\fR specified), so you may wish to set \fB--norpfix\fR in that +case. +.TP +\fB--strict-acls\fR +In the Win32 native build of wimlib, fail immediately if the full security +descriptor of any file or directory 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 with to provide this option, although the +Administrator should have permission to read everything anyway. +.TP \fB--source-list\fR -\fBimagex capture\fR and \fBimagex append\fR, as of wimlib 1.2.7, support a new +\fB@IMAGEX_PROGNAME@ capture\fR and \fB@IMAGEX_PROGNAME@ append\fR, as of wimlib 1.3.0, support a new option to create 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 @@ -266,7 +297,7 @@ overlay /overlay 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. +if the same file appears in different overlays to the same directory. Filenames containing whitespace may be quoted with either single quotes or double quotes. Quotes may not be escaped. @@ -287,30 +318,19 @@ a full NTFS volume is supported. 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. +type, and \fB@IMAGEX_PROGNAME@\fR always enforces this. -\fBimagex\fR writes WIMs having the version number 0x10d00 and a compressed +\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. -Unless \fB--rebuild\fR is specified, aborting an \fBimagex append\fR command +Unless \fB--rebuild\fR is specified, aborting an \fB@IMAGEX_PROGNAME@ 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 +of an aborted \fB@IMAGEX_PROGNAME@ append\fR, \fB@IMAGEX_PROGNAME@ 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. -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. - \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 @@ -322,7 +342,7 @@ Create a new WIM 'mywim.wim' from the directory 'somedir', using LZX compression 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 @@ -332,10 +352,10 @@ 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" +@IMAGEX_PROGNAME@ append /dev/sda2 mywim.wim --check "Windows 7" .RE .PP .SH SEE ALSO -.BR imagex (1) +.BR @IMAGEX_PROGNAME@ (1)