X-Git-Url: https://wimlib.net/git/?p=wimlib;a=blobdiff_plain;f=doc%2Fimagex-mount.1.in;h=4875b162367f60c5baf099b8c0ace23aee1f0431;hp=f4c0673baca7b0fd45f7a222527d69bc2b48e2f2;hb=da8fe9993a0ece30bd57596081e778364ba72ec5;hpb=6aad3bee18ef52fc81d6df36080aa53bf8aa1d82 diff --git a/doc/imagex-mount.1.in b/doc/imagex-mount.1.in index f4c0673b..4875b162 100644 --- a/doc/imagex-mount.1.in +++ b/doc/imagex-mount.1.in @@ -1,49 +1,40 @@ -.TH IMAGEX "1" "April 2013" "@IMAGEX_PROGNAME@ @VERSION@" "User Commands" +.TH WIMLIB-IMAGEX "1" "December 2013" "@IMAGEX_PROGNAME@ @VERSION@" "User Commands" .SH NAME @IMAGEX_PROGNAME@-mount, @IMAGEX_PROGNAME@-mountrw, @IMAGEX_PROGNAME@-unmount \- Mount and unmount an image from a WIM archive - .SH SYNOPSIS -\fB@IMAGEX_PROGNAME@ mount\fR \fIWIMFILE\fR \fIIMAGE\fR \fIDIRECTORY\fR [\fIOPTION\fR]... +\fB@IMAGEX_PROGNAME@ mount\fR \fIWIMFILE\fR [\fIIMAGE\fR] \fIDIRECTORY\fR [\fIOPTION\fR...] .br -\fB@IMAGEX_PROGNAME@ mountrw\fR \fIWIMFILE\fR \fIIMAGE\fR \fIDIRECTORY\fR [\fIOPTION\fR]... +\fB@IMAGEX_PROGNAME@ mountrw\fR \fIWIMFILE\fR [\fIIMAGE\fR] \fIDIRECTORY\fR [\fIOPTION\fR...] .br \fB@IMAGEX_PROGNAME@ unmount\fR \fIDIRECTORY\fR [--commit] [--check] [--rebuild] - .SH DESCRIPTION +The \fB@IMAGEX_PROGNAME@ mount\fR and \fB@IMAGEX_PROGNAME@ mountrw\fR commands +will mount the image in the Windows Imaging (WIM) file \fIWIMFILE\fR specified +by \fIIMAGE\fR on the directory \fIDIRECTORY\fR using FUSE (Filesystem in +Userspace). \fB@IMAGEX_PROGNAME@ mount\fR will mount the image read-only, while +\fB@IMAGEX_PROGNAME@ mountrw\fR will mount the image read-write. +These commands are also available as simply \fBwimmount\fR, \fBwimmountrw\fR, +and \fBwimunmount\fR if the appropriate hard links or batch files are installed. .PP -The \fB@IMAGEX_PROGNAME@ mount\fR and \fB@IMAGEX_PROGNAME@ mountrw\fR commands will mount the image in -the Windows Imaging (WIM) file \fIWIMFILE\fR specified by \fIIMAGE\fR on the -directory \fIDIRECTORY\fR using FUSE (Filesystem in Userspace). \fB@IMAGEX_PROGNAME@ -mount\fR will mount the image read-only, while \fB@IMAGEX_PROGNAME@ mountrw\fR will mount -the image read-write. - \fIIMAGE\fR may be a 1-based index of the image in the WIM to mount, or it may -be the name of an image in the WIM. Use the \fB@IMAGEX_PROGNAME@ info\fR (1) command to -see the available images in the WIM. It is possible to omit \fIIMAGE\fR, but -only if the WIM contains only one image. - +be the name of an image in the WIM. Use the \fB@IMAGEX_PROGNAME@ info\fR (1) +command to see the available images in the WIM. \fIIMAGE\fR may be omitted if +\fIWIMFILE\fR contains only one image. +.PP The WIM image can be unmounted using the \fB@IMAGEX_PROGNAME@ unmount\fR command. Changes made to a WIM mounted read-write will be discarded unless the \fB--commit\fR flag is provided to \fB@IMAGEX_PROGNAME@ unmount\fR. - .SH SPLIT WIMS - -You may use \fB@IMAGEX_PROGNAME@ mount\fR to mount an image from a split WIM read-only. -However, you may not mount an image from a split WIM read-write. - -The \fIWIMFILE\fR argument is used to specify the first part of the split WIM, and -the \fB--refs\fR="\fIGLOB\fR" option is used to provide a shell-style file glob -that specifies the additional parts of the split WIM. \fIGLOB\fR is expected to -be a single string on the command line, so \fIGLOB\fR must be quoted so that it -is protected against shell expansion. \fIGLOB\fR must expand to all parts of -the split WIM, except optionally the first part which may either omitted or -included in the glob (but the first part MUST be specified as \fIWIMFILE\fR as -well). - -Here's an example. The names for the split WIMs usually go something like: - -.RS +You may use \fB@IMAGEX_PROGNAME@ mount\fR to mount an image from a split WIM +read-only. However, you may not mount an image from a split WIM read-write. +.PP +The \fIWIMFILE\fR argument must specify the first part of the split WIM, while +the additional parts of the split WIM must be specified in one or more +\fB--ref\fR="\fIGLOB\fR" options. Since globbing is built into the \fB--ref\fR +option, typically only one \fB--ref\fR option is necessary. For example, the +names for the split WIM parts usually go something like: .PP +.RS .nf mywim.swm mywim2.swm @@ -51,23 +42,22 @@ mywim3.swm mywim4.swm mywim5.swm .RE - -To mount the first image of this split WIM to the directory "dir", we would do: +.PP +To mount the first image of this split WIM to the directory "dir", run: .PP .RS @IMAGEX_PROGNAME@ mount mywim.swm 1 dir --ref="mywim*.swm" .RE .PP - .SH NOTES - -If wimlib was configured using the \fB--without-fuse\fR flag, then the \fB@IMAGEX_PROGNAME@ -mount\fR, \fB@IMAGEX_PROGNAME@ mountrw\fR, and \fB@IMAGEX_PROGNAME@ unmount\fR commands will not work. -Also, these commands are not available in the Windows builds of wimlib. - +If wimlib was configured using the \fB--without-fuse\fR flag, then the +\fB@IMAGEX_PROGNAME@ mount\fR, \fB@IMAGEX_PROGNAME@ mountrw\fR, and +\fB@IMAGEX_PROGNAME@ unmount\fR commands will not work. Also, these commands +are not available in the Windows builds of \fB@IMAGEX_PROGNAME@\fR. +.PP You can mount multiple images from a WIM file read-only at the same time, but you can only mount one image at a time from a WIM read-write. - +.PP All files in the mounted WIM will be accessible regardless of whether there is a security descriptor in the WIM associated with the file or not. New files or directories created in a read-write mounted WIM will be created with no security @@ -75,17 +65,22 @@ descriptor. Although there is support for accessing named data streams (see the \fB--streams-interface\fR option), it is currently not possible to set or get DOS names, file attributes, or security descriptors in a mounted WIM. - +.PP By default, changes to a read-write WIM are made in-place by appending to the WIM. This is nice for big WIM files, since the entire file doesn't have to be rebuilt to make a small change. But, if you are making many changes to a read-write mounted WIM, especially deleting large files, it is suggested to provide the \fB--rebuild\fR option to \fB@IMAGEX_PROGNAME@ unmount\fR to force the WIM to be rebuilt, or else run \fB@IMAGEX_PROGNAME@ optimize\fR on the WIM afterwards. - +.PP +wimlib v1.6.0 and later can mount version 3584 WIMs, which usually use packed, +LZMS-compressed streams and may carry the \fI.esd\fR file extension rather than +\fI.wim\fR. However, such files are not designed for random access, so reading +data from them when mounted may be very slow. In addition, \fI.esd\fR files +downloaded directly by the Windows 8 web downloader have encrypted segments, and +wimlib cannot mount such files until they are first decrypted. .SH MOUNT OPTIONS - -.TP +.TP 6 \fB--check\fR When reading the WIM, verify its integrity if it contains an integrity table. .TP @@ -93,19 +88,20 @@ When reading the WIM, verify its integrity if it contains an integrity table. This option is inspired by the ntfs-3g filesystem driver (see \fBntfs-3g\fR (8)). It controls how alternate data streams, or named data streams, in WIM files are made available. - +.IP "" If "none", it will be impossible to read or write the named data streams. - +.IP "" If "xattr" (default), named data streams will be accessible through extended file attributes, unless this support was disabled when compiling wimlib. The named data streams may be accessed through extended attributes named "user.*", where the * is the name of the named data stream. See \fBsetfattr\fR (1) and -\fBgetfattr\fR (1). - +\fBgetfattr\fR (1). Note that this is not an ideal interface, since named data +streams may be larger than the maximum allowed extended attribute size. +.IP "" If "windows", the named data streams will be accessible by specifying the filename, then a colon, then the name of the named data stream; for example, "myfile:mystream". - +.IP "" Please note that named data streams are a somewhat obscure NTFS feature that aren't actually used much, even though they complicate the WIM file format considerably. Normally, all you care about is the default or "unnamed" data @@ -116,9 +112,11 @@ Turn on debugging information printed by the FUSE library, and do not fork into the background. .TP \fB--ref\fR="\fIGLOB\fR" -File glob of additional split WIM parts that are part of the split WIM being -mounted. This option is valid for \fB@IMAGEX_PROGNAME@ mount\fR but not \fB@IMAGEX_PROGNAME@ -mountrw\fR. See \fBSPLIT_WIMS\fR. +File glob of additional WIMs or split WIM parts to reference resources from. +See \fBSPLIT_WIMS\fR. This option can be specified multiple times. Note: +\fIGLOB\fR is listed in quotes because it is interpreted by +\fB@IMAGEX_PROGNAME@\fR and may need to be quoted to protect against shell +expansion. .TP \fB--staging-dir\fR=\fIDIR\fR Store temporary staging files in a subdirectory of the directory \fIDIR\fR. @@ -141,9 +139,7 @@ tools and functions. Pass the \fBallow_other\fR option to the FUSE mount. See \fBmount.fuse\fR (8). Note: to do this is a non-root user, \fBuser_allow_other\fR needs to be specified in /etc/fuse.conf (with the FUSE implementation on Linux, at least). - .SH UNMOUNT OPTIONS - .TP \fB--commit\fR Update the WIM file with the changes that have been made. Has no effect if the @@ -151,18 +147,22 @@ mount is read-only. .TP \fB--check\fR When writing \fIWIMFILE\fR, include an integrity table. Has no effect if the -mount is read-only or if \fB--commit\fR was not specified. +mount is read-only or if \fB--commit\fR was not specified. The default behavior +is to include an integrity table if and only if there was one present before. .TP \fB--rebuild\fR Rebuild the entire WIM rather than appending any 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. Even more space will be saved if the read-write mount resulted in streams being deleted from the WIM. Also see -\fB@IMAGEX_PROGNAME@ optimize\fR. Has no effect if the mount is read-only or if -\fB--commit\fR was not specified. - +.TP +\fB--lazy\fR +Pass the \fB-z\fR option to \fBfusermount\fR, which performs a "lazy" unmount +where the filesystem is detached immediately even if it is still busy. However, +even with this option, \fB@IMAGEX_PROGNAME@ unmount\fR still waits for the +filesystem to become unbusy; \fB--lazy\fR will only stop the unmount from +immediately failing. .SH IMPLEMENTATION DETAILS - Since a WIM is an archive and not a filesystem, \fB@IMAGEX_PROGNAME@ mountrw\fR creates a temporary staging directory to contain files that are created or modified. This directory is located in the same directory as \fIWIMFILE\fR by default, but the @@ -170,14 +170,9 @@ location can be set using the \fB--staging-dir\fR option. When the filesystem is unmounted with \fB--commit\fR, the WIM is modified in-place (or rebuild completely with \fB--rebuild\fR), merging in the staging files as needed. Then, the temporary staging directory is deleted. - +.PP \fB@IMAGEX_PROGNAME@ unmount\fR runs in a separate process from the process that previously ran \fB@IMAGEX_PROGNAME@ mount\fR, and these two processes communicate using POSIX message -queues. See \fIsrc/mount_image.c\fR in the sources for details. Note: As of -wimlib v1.2.1, \fB@IMAGEX_PROGNAME@ unmount\fR correctly fails with an error within a -reasonable amount of time (1 second) if the filesystem daemon is abnormally -terminated. - +queues. See \fIsrc/mount_image.c\fR in the sources for details. .SH SEE ALSO .BR @IMAGEX_PROGNAME@ (1) -