X-Git-Url: https://wimlib.net/git/?p=wimlib;a=blobdiff_plain;f=doc%2Fimagex-mount.1.in;h=da3e97fbfeb45dd0d71f163ba531b860e279432e;hp=6d04c7f952b7c07ae6e52e0fc83b03aead43edf6;hb=e510d33bc53ca66de7737d49b8086532bac2e4f7;hpb=370533dcb819ad11d6424e7e0284915eb501812b diff --git a/doc/imagex-mount.1.in b/doc/imagex-mount.1.in index 6d04c7f9..da3e97fb 100644 --- a/doc/imagex-mount.1.in +++ b/doc/imagex-mount.1.in @@ -1,25 +1,168 @@ -.TH IMAGEX "1" "May 2012" "imagex (wimlib) wimlib @VERSION@" "User Commands" +.TH IMAGEX "1" "May 2013" "@IMAGEX_PROGNAME@ @VERSION@" "User Commands" .SH NAME -imagex mount \- Mount an image from a WIM archive readonly - +@IMAGEX_PROGNAME@-mount, @IMAGEX_PROGNAME@-mountrw, @IMAGEX_PROGNAME@-unmount \- Mount and unmount an image from a WIM archive .SH SYNOPSIS -\fBimagex mount\fR \fIWIMFILE\fR (\fIIMAGE_NUM\fR | \fIIMAGE_NAME\fR) \ -\fIDIRECTORY\fR [--check] - +\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...] +.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. .PP -\fBimagex mount\fR mounts the image specified by \fIIMAGE_NUM\fR or -\fIIMAGE_NAME\fR on the directory \fIDIRECTORY\fR using FUSE (Filesystem in -UserSpace). It is mounted read-only. - -It is permissible to omit the \fIIMAGE_NUM\fR or \fIIMAGE_NAME\fR only if +\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. \fIIMAGE\fR may be omitted if \fIWIMFILE\fR contains only one image. - -.SH OPTIONS +.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. +.PP +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). +.PP +Here's an example. The names for the split WIMs usually go something like: +.RS +.PP +.nf +mywim.swm +mywim2.swm +mywim3.swm +mywim4.swm +mywim5.swm +.RE +.PP +To mount the first image of this split WIM to the directory "dir", we would do: +.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. +.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 +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. +.SH MOUNT OPTIONS .TP 6 \fB--check\fR -When reading \fIWIMFILE\fR, verify its integrity if the integrity table is -present. +When reading the WIM, verify its integrity if it contains an integrity table. +.TP +\fB--streams-interface\fR=\fIINTERFACE\fR +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). +.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 +stream. +.TP +\fB--debug\fR +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. +.TP +\fB--staging-dir\fR=\fIDIR\fR +Store temporary staging files in a subdirectory of the directory \fIDIR\fR. +Only valid for \fB@IMAGEX_PROGNAME@ mountrw\fR. +.TP +\fB--unix-data\fR +By default, \fB@IMAGEX_PROGNAME@ mount\fR and \fB@IMAGEX_PROGNAME@ mountrw\fR will ignore both +Windows-style security descriptors (which may have been set either from Windows or by +\fB@IMAGEX_PROGNAME@ capture\fR from a NTFS-volume) and UNIX-specific data (which is from using +\fB@IMAGEX_PROGNAME@ capture\fR with the \fB--unix-data\fR flag). In this default mode, +all files will simply be owned by the user running \fB@IMAGEX_PROGNAME@\fR and will have mode 0777. +(Note: they will still not be accessible to other users unless you also specify +\fB--allow-other\fR.) If you instead provide the \fB--unix-data\fR flag, these +default permissions will be overridden on a per-file basis with the +UNIX-specific data when available, and in the case of \fB@IMAGEX_PROGNAME@ mountrw\fR it +will be possible to change the UNIX permissions using the standard UNIX +tools and functions. +.TP +\fB--allow-other\fR +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 +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. +.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. +.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 +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. .SH SEE ALSO -.BR imagex (1) - +.BR @IMAGEX_PROGNAME@ (1)