X-Git-Url: https://wimlib.net/git/?p=wimlib;a=blobdiff_plain;f=doc%2Fimagex-capture.1.in;h=3685e8ee1d19db431a7e49c88c7928bb4306ec92;hp=1647f7a1c2ceb4b9a5d18a58651c6d50775b1d35;hb=9aa9a387906341315fab3f097fdadb3a76fcf280;hpb=a6c413a13da72aac44b0a522c2650d5e54e16a72 diff --git a/doc/imagex-capture.1.in b/doc/imagex-capture.1.in index 1647f7a1..3685e8ee 100644 --- a/doc/imagex-capture.1.in +++ b/doc/imagex-capture.1.in @@ -1,45 +1,46 @@ -.TH IMAGEX "1" "November 2012" "imagex (wimlib) wimlib @VERSION@" "User Commands" +.TH IMAGEX "1" "May 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. .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 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 +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. - -In this normal image capture mode, we capture the following information from the -directory tree: - +.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] @@ -47,36 +48,32 @@ 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 the normal image capture mode, we do \fInot\fR capture the following -information from the directory tree: - +However, in this mode, the following information is \fInot\fR captured 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. +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] -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. - +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 a NTFS filesystem is mounted on +\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). - -More specifically, in this mode, we capture the following types of information +.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. @@ -93,7 +90,41 @@ 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 @@ -102,14 +133,14 @@ 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 -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. +\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 @@ -120,9 +151,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 @@ -130,103 +161,193 @@ 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 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 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 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 NOTES - -\fBimage append\fR does not support appending an image to a split WIM. +# Send the 'overlay' directory to '/overlay' in the WIM image +overlay /overlay -The two different capture modes only specify the data that is captured and don't +# 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 \fBimagex\fR always enforces this. - -\fBimagex\fR writes WIMs having the version number 0x10d00 and a compressed +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. - -Unless --rebuild 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. - +.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 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 -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. +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 append /dev/sda2 mywim.wim --check "Windows 7" "Warning: This operating -system has been approved by Bill Gates" +@IMAGEX_PROGNAME@ append /dev/sda2 mywim.wim --check "Windows 7" .RE .PP - .SH SEE ALSO -.BR imagex (1) - +.BR @IMAGEX_PROGNAME@ (1)