--- /dev/null
+.TH WIMMOUNT "1" "August 2016" "wimlib 1.10.0" "User Commands"
+.SH NAME
+wimmount, wimmountrw, wimunmount \- Mount or unmount a WIM image
+.SH SYNOPSIS
+\fBwimmount\fR \fIWIMFILE\fR [\fIIMAGE\fR] \fIDIRECTORY\fR [\fIOPTION\fR...]
+.br
+\fBwimmountrw\fR \fIWIMFILE\fR [\fIIMAGE\fR] \fIDIRECTORY\fR [\fIOPTION\fR...]
+.br
+\fBwimunmount\fR \fIDIRECTORY\fR [\fIOPTION\fR...]
+.SH DESCRIPTION
+On Linux-based systems, the \fBwimmount\fR and \fBwimmountrw\fR commands will
+mount the specified \fIIMAGE\fR in the Windows Imaging (WIM) archive
+\fIWIMFILE\fR on the directory \fIDIRECTORY\fR using FUSE (Filesystem in
+Userspace). \fBwimmount\fR will mount the image read-only, while
+\fBwimmountrw\fR will mount the image read-write.
+.PP
+\fIIMAGE\fR specifies the image in \fIWIMFILE\fR to mount. It may be the
+1-based index of an image or the name of an image. It may be omitted if
+\fIWIMFILE\fR contains only one image. You can use \fBwiminfo\fR(1) to list the
+images contained in \fIWIMFILE\fR.
+.PP
+The WIM image can be unmounted using the \fBwimunmount\fR command. Changes made
+to an image mounted read-write will be discarded unless the \fB--commit\fR flag
+is provided to \fBwimunmount\fR.
+.SH DATA AND METADATA SUPPORT
+WIM images can contain a variety of types of files and file metadata, some of
+which is Windows-specific. Currently, the mount feature can translate some, but
+not all, Windows concepts to Linux equivalents. Briefly, the following features
+are \fIsupported\fR (read/write):
+.IP \[bu] 4
+Hard links
+.IP \[bu]
+Symbolic links. Native Windows symbolic links and junctions in a
+mounted WIM image will automatically be translated into UNIX symbolic links,
+potentially with their targets fixed to be valid given the actual mountpoint
+directory. UNIX symbolic links created in a read-write mounted WIM image will
+automatically be translated into native Windows symbolic links.
+.IP \[bu]
+Named data streams (mostly). See the \fB--streams-interface\fR option.
+.PP
+In addition, standard UNIX file permissions (owner, group, and mode) and special
+files are supported if the \fB--unix-data\fR option is used.
+.PP
+However, the following features are \fIunsupported\fR and not exposed in mounted
+images:
+.IP \[bu] 4
+Windows security descriptors. New files are not given security descriptors.
+.IP \[bu]
+DOS names (8.3 names) (short names). New files are not given DOS names.
+.IP \[bu]
+Windows file attributes. New files are assigned default attributes based on the
+UNIX file mode bits.
+.IP \[bu]
+Object IDs. New files are not given object IDs.
+.IP \[bu]
+EFS-encrypted files. The files themselves will be visible in mounted WIM images
+but their data will not be available.
+.IP \[bu]
+Extended attributes. Although wimlib now supports creating a WIM image
+containing Linux-style extended attributes, these are not yet exposed in mounted
+WIM images. (This may be implemented in the future, though it would conflict
+with the use of extended attributes to expose Windows concepts like named data
+streams.)
+.SH SPLIT WIMS
+You may use \fBwimmount\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
+mywim3.swm
+mywim4.swm
+mywim5.swm
+.RE
+.PP
+To mount the first image of this split WIM to the directory "dir", run:
+.PP
+.RS
+wimmount mywim.swm 1 dir --ref="mywim*.swm"
+.RE
+.PP
+.SH NOTES
+\fIAvailability\fR: Mounting WIM images is only supported on Linux-based systems.
+These commands will not work on other platforms. Furthermore, the library
+cannot have been configured \fB--without-fuse\fR.
+.PP
+\fIMultiple mounts\fR: You are free to mount many WIM images at the same time,
+provided that there are not two images mounted read-write from the same file at
+the same time.
+.PP
+\fIAppends vs. rebuilds\fR: 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 \fBwimunmount\fR
+to force the WIM to be rebuilt, or else run \fBwimoptimize\fR afterwards.
+.PP
+\fIESD files (solid WIMs)\fR: You can mount version 3584 WIMs, which usually
+contain LZMS-compressed solid resources 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 6
+\fB--check\fR
+Before mounting the WIM image, verify the integrity of the WIM if it contains
+extra integrity information.
+.TP
+\fB--streams-interface\fR=\fIINTERFACE\fR
+This option is inspired by the \fBntfs-3g\fR(8) filesystem driver. It controls
+how named data streams (also called "alternate 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). 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".
+.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 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 \fBwimlib-imagex\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.
+Only valid for \fBwimmountrw\fR.
+.TP
+\fB--unix-data\fR
+Honor UNIX-specific metadata that was captured by \fBwimcapture\fR with the
+\fB--unix-data option\fR. By default, \fBwimmount\fR (and \fBwimmountrw\fR)
+will ignore both Windows-style security descriptors and UNIX-specific metadata.
+In this default mode, all files will simply be owned by the user running
+\fBwimmount\fR and will have mode 0777. (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 option, these default permissions will be
+overridden on a per-file basis with the UNIX-specific metadata from the WIM
+image when available, and in the case of \fBwimmountrw\fR it will also be
+possible to change the UNIX permissions on files in the mounted image using the
+standard UNIX tools and functions, and (if appropriately privileged) create UNIX
+special files such as device nodes.
+.TP
+\fB--allow-other\fR
+Pass the \fBallow_other\fR option to the FUSE mount. See \fBmount.fuse\fR (8).
+Note: to do this as a non-root user, \fBuser_allow_other\fR needs to be
+specified in /etc/fuse.conf.
+.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--force\fR
+In combination with \fB--commit\fR, force the WIM image to be committed even if
+there are open file descriptors to the WIM image. Any such file descriptors
+will be immediately closed, and the WIM image will be committed and unmounted.
+.TP
+\fB--check\fR
+If committing changes to the WIM, include extra integrity information, even if
+it was not 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
+.TP
+\fB--new-image\fR
+In combination with \fB--commit\fR for a read-write mounted image, causes the
+modified image to be committed as a new, unnamed image appended to the WIM
+archive. The original image will be unmodified.
+.SH IMPLEMENTATION DETAILS
+Since a WIM is an archive and not a filesystem per se, \fBwimmountrw\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
+rebuilt completely with \fB--rebuild\fR), merging in the staging files as
+needed. Then, the temporary staging directory is deleted.
+.PP
+\fBwimunmount\fR runs in a separate process from the process that previously ran
+\fBwimmount\fR. When unmounting a read-write mounted WIM image with
+\fB--commit\fR, these two processes communicate using a POSIX message queue so
+that the unmount process can track the progress of the mount process. See
+\fIsrc/mount_image.c\fR in the source code for details.
+.SH SEE ALSO
+.BR wimlib-imagex (1)
git://wimlib.net / wimlib / blobdiff