wimlib.net Git - wimlib/blob - doc/man1/wimlib-imagex.1

   1 .TH WIMLIB-IMAGEX 1 "May 2015" "wimlib 1.8.1" "User Commands"
   2 .SH NAME
   3 wimlib-imagex \- Extract, create, modify, or mount a WIM (Windows Imaging Format) archive
   4 .SH SYNOPSIS
   5 \fBwimlib-imagex append\fR \fIarguments...\fR
   6 .br
   7 \fBwimlib-imagex apply\fR \fIarguments...\fR
   8 .br
   9 \fBwimlib-imagex capture\fR \fIarguments...\fR
  10 .br
  11 \fBwimlib-imagex delete\fR \fIarguments...\fR
  12 .br
  13 \fBwimlib-imagex dir\fR \fIarguments...\fR
  14 .br
  15 \fBwimlib-imagex export\fR \fIarguments...\fR
  16 .br
  17 \fBwimlib-imagex extract\fR \fIarguments...\fR
  18 .br
  19 \fBwimlib-imagex info\fR \fIarguments...\fR
  20 .br
  21 \fBwimlib-imagex join\fR \fIarguments...\fR
  22 .br
  23 \fBwimlib-imagex mount\fR \fIarguments...\fR
  24 .br
  25 \fBwimlib-imagex mountrw\fR \fIarguments...\fR
  26 .br
  27 \fBwimlib-imagex optimize\fR \fIarguments...\fR
  28 .br
  29 \fBwimlib-imagex split\fR \fIarguments...\fR
  30 .br
  31 \fBwimlib-imagex unmount\fR \fIarguments...\fR
  32 .br
  33 \fBwimlib-imagex update\fR \fIarguments...\fR
  34 .br
  35 \fBwimlib-imagex verify\fR \fIarguments...\fR
  36 .SH DESCRIPTION
  37 \fBwimlib-imagex\fR deals with archives in the Windows Imaging Format (WIM).
  38 Its interface is similar to Microsoft's ImageX, but \fBwimlib-imagex\fR is
  39 cross-platform and has useful improvements and extensions.
  40 .PP
  41 To do its work, \fBwimlib-imagex\fR uses \fBwimlib\fR, an open source C
  42 library that provides interfaces for manipulating WIM archives.  wimlib is
  43 completely independent from the equivalent Microsoft implementation (WIMGAPI, or
  44 wimgapi.dll).  You can use wimlib in your own programs, although for
  45 command-line use \fBwimlib-imagex\fR already provides access to most of
  46 wimlib's functionality.
  47 .SH BACKGROUND INFORMATION
  48 The Windows Imaging Format (WIM) was designed by Microsoft primarily for
  49 archiving Windows filesystems, such as NTFS.  However, it can be used on other
  50 platforms as well, with some limitations.  A WIM archive contains one or more
  51 images, each of which is a logically independent directory tree.  Images are
  52 indexed starting from 1, and each may also have a name.  File data is stored as
  53 content-addressable "streams" that are deduplicated across the entire archive.
  54 Streams may be compressed using one of several compression algorithms, including
  55 XPRESS and LZX.
  56 .PP
  57 An update of the WIM format released with Windows 8 features solid compression
  58 using the LZMS compression algorithm.  Such files are also called "ESD files"
  59 and may carry the extension \.esd instead of .wim.  \fBwimlib-imagex\fR
  60 v1.6.0 and later supports these new files, unless they are encrypted.
  61 .SH COMMANDS
  62 \fBwimlib-imagex\fR accepts one of a number of commands (listed above in
  63 \fBSYNOPSYS\fR), and additional arguments depending on the specific command.
  64 Although \fBwimlib-imagex\fR will print usage information with \fB--help\fR
  65 or if you invoke it incorrectly, the full documentation for each
  66 \fBwimlib-imagex\fR command can be found in the appropriate manual page.
  67 .PP
  68 Note: to save typing, if appropriate hard links or batch files have been
  69 installed, a command \fBwimlib-imagex \fICOMMAND\fR can also be accessed as
  70 simply \fBwim\fICOMMAND\fR; for example, \fBwimapply\fR for \fBwimlib-imagex
  71 apply\fR.
  72 .SH GENERAL FEATURES
  73 The following are some of the general features, or use cases, currently
  74 supported by \fBwimlib-imagex\fR, and pointers to the relevant commands:
  75 .IP \[bu] 4
  76 Display information about a WIM file
  77  (\fBwimlib-imagex info\fR)
  78 .IP \[bu]
  79 List the files in a WIM image
  80  (\fBwimlib-imagex dir\fR)
  81 .IP \[bu]
  82 Extract, or "apply", a full WIM image
  83  (\fBwimlib-imagex apply\fR)
  84 .IP \[bu]
  85 Extract files or directories from a WIM image
  86  (\fBwimlib-imagex extract\fR)
  87 .IP \[bu] 4
  88 Capture a WIM image and save it to a new WIM file
  89  (\fBwimlib-imagex capture\fR)
  90 .IP \[bu]
  91 Capture a WIM image and append it to an existing WIM file
  92  (\fBwimlib-imagex append\fR)
  93 .IP \[bu]
  94 Modify a WIM image by adding, deleting, or renaming files
  95  (\fBwimlib-imagex update\fR)
  96 .IP \[bu]
  97 (Linux only) Mount a WIM image read-only
  98  (\fBwimlib-imagex mount\fR)
  99 .IP \[bu]
 100 (Linux only) Mount a WIM image read-write
 101  (\fBwimlib-imagex mountrw\fR)
 102 .IP \[bu]
 103 Delete an image from a WIM file
 104  (\fBwimlib-imagex delete\fR)
 105 .IP \[bu]
 106 Export image(s) from a WIM file
 107  (\fBwimlib-imagex export\fR)
 108 .IP \[bu]
 109 Change the name or description of a WIM image
 110  (\fBwimlib-imagex info\fR)
 111 .IP \[bu]
 112 Change the bootable image index of a WIM file
 113  (\fBwimlib-imagex info\fR)
 114 .IP \[bu]
 115 Rebuild, and optionally recompress, a WIM file
 116  (\fBwimlib-imagex optimize\fR)
 117 .IP \[bu]
 118 Split a WIM file into multiple parts
 119  (\fBwimlib-imagex split\fR)
 120 .IP \[bu]
 121 Join a split WIM
 122  (\fBwimlib-imagex join\fR)
 123 .IP \[bu]
 124 Verify a WIM file
 125  (\fBwimlib-imagex verify\fR)
 126 .SH DETAILED FEATURES
 127 This section presents some of the interesting features of
 128 \fBwimlib-imagex\fR in more detail.
 129 .IP \[bu] 4
 130 Multi-platform support.  \fBwimlib-imagex\fR is supported on both UNIX-like
 131 systems (mainly Linux, but also FreeBSD, Mac OS X, etc.) and Windows, and most
 132 code is shared among all platforms.  However, platform-specific features are
 133 supported when possible.
 134 .IP \[bu]
 135 On UNIX-like systems, integration with libntfs-3g allows capturing a WIM image
 136 directly from a block device containing an NTFS volume, or applying a WIM image
 137 directly to a block device containing an NTFS volume.  This allows saving and
 138 restoring NTFS-specific data, such as security descriptors and named data
 139 streams, which is otherwise only supported on Windows.  This feature is
 140 unavailable if wimlib was configured using --without-ntfs-3g.
 141 .IP \[bu]
 142 Long path support on Windows.  \fBwimlib-imagex\fR can capture and apply
 143 files with paths exceeding the MAX_PATH (260 character) limitation of the Win32
 144 subsystem.
 145 .IP \[bu]
 146 Non-Administrator support on Windows.  You can run \fBwimlib-imagex\fR
 147 without Administrator rights, subject to some limitations.
 148 .IP \[bu]
 149 Support for WIM integrity tables.  An integrity table is a list of SHA-1 message
 150 digests appended to the end of a WIM file which gives checksums over the WIM
 151 file itself.  The \fB--check\fR option to several \fBwimlib-imagex\fR
 152 commands can be used to verify or add integrity tables.
 153 .IP \[bu]
 154 Support for "pipable" WIMs.  This is a wimlib extension and is not compatible
 155 with the Microsoft implementation.  A pipable WIM, created with
 156 \fBwimlib-imagex capture\fR with the \fB--pipable\fR option, can be written
 157 to standard output or read from standard input.  This can be used to pipe images
 158 to or from a server over the network to implement fast filesystem imaging and
 159 restore.
 160 .IP \[bu]
 161 On UNIX-like systems, support for saving and restoring UNIX uids (user IDs),
 162 gids (group IDs), and modes to/from WIM images.  This is a wimlib extension, but
 163 the Microsoft implementation ignores this extra metadata.
 164 .IP \[bu]
 165 Multithreaded compression.  By default, data compression is multithreaded and
 166 will use all available processors.  In most cases, this can be changed by the
 167 \fB--threads\fR option.
 168 .IP \[bu]
 169 XPRESS, LZX, and LZMS decompression and compression.  wimlib contains
 170 independent implementations of all these compression algorithms.  Sometimes they
 171 can do better than the equivalent Microsoft implementations.
 172 .IP \[bu]
 173 "ESD file" support.  As mentioned in \fBBACKGROUND INFORMATION\fR, "ESD files"
 174 use a new WIM format that features solid resources and LZMS compression.  This
 175 support was first present in wimlib v1.6.0, but v1.7.0 and later have improved
 176 compatibility.
 177 .IP \[bu]
 178 Mounting WIM images.  This relies on FUSE (Filesystem in UserSpacE) and is only
 179 supported on compatible UNIX-like systems, in particular Linux.  FreeBSD may
 180 work but is untested.
 181 .IP \[bu]
 182 Split WIMs.  A split WIM is a WIM archive split into multiple parts.
 183 \fBwimlib-imagex split\fR can create a split WIM from a standalone WIM, and
 184 \fBwimlib-imagex join\fR can create a standalone WIM from a split WIM.
 185 .IP \[bu]
 186 Delta WIMs.  A delta WIM contains image metadata but excludes file data already
 187 present in another WIM file.  A delta WIM can be created using
 188 \fBwimlib-imagex capture\fR with the \fB--delta-from\fR option.
 189 .IP \[bu]
 190 WIMBoot support.  On Windows 8.1 and later, files on an NTFS volume can be
 191 externally backed by a WIM archive with the help of Microsoft's Windows Overlay
 192 FileSystem Filter Driver (WOF).  With the \fB--wimboot\fR flag,
 193 \fBwimlib-imagex apply\fR will extract "pointer files" (actually NTFS
 194 reparse points handled by the WOF driver) to the WIM archive rather than the
 195 files themselves.
 196 .IP \[bu]
 197 Fast incremental backups.  Using the \fB--update-of\fR option of
 198 \fBwimlib-imagex capture\fR or \fBwimlib-imagex append\fR, you can
 199 optimize an image capture so that files that are unmodified based on timestamps
 200 are not be read from disk.  But even without this option, since the WIM format
 201 features single-instance files, a file identical to any already present in the
 202 WIM archive (in any image) will not be written, but rather a reference to the
 203 stored file will be used.
 204 .SH LOCALES AND CHARACTER ENCODINGS
 205 WIM files themselves store file and stream names using Windows native "wide
 206 character strings", which are UTF-16.  On Windows, wimlib works using these same
 207 strings, so conversions are usually not necessary and there should be no
 208 problems with character encodings.
 209 .PP
 210 On UNIX-like systems, wimlib works primarily in the locale-dependent multibyte
 211 encoding, which you are strongly recommended to set to UTF-8 to avoid any
 212 problems.  You can alternatively set the environmental variable
 213 \fBWIMLIB_IMAGEX_USE_UTF8\fR to force \fBwimlib-imagex\fR to use UTF-8
 214 internally, even if the current locale is not UTF-8 compatible.
 215 .SH CASE SENSITIVITY
 216 By default, the case sensitivity of \fBwimlib-imagex\fR differs somewhat
 217 between UNIX-like systems and Windows.  WIM images may (but usually do not) have
 218 multiple files with the same case-insensitive name.  Internally, wimlib
 219 stores filenames as case-sensitive, but on Windows paths
 220 actually provided by the user for use in a WIM image (e.g. for extracting,
 221 adding, renaming, or deleting files) will by default be treated as
 222 case-insensitive in order to get the "expected" behavior. This differs from the
 223 default behavior on UNIX-like systems, where such paths will be treated as
 224 case-sensitive.
 225 .PP
 226 Note that with case insensitivity, a path component may in general be ambiguous
 227 due to multiple files or directories having the same case-insensitive name.  In
 228 such cases, if there is a file or directory with an exactly matching name, it is
 229 chosen; otherwise, one of the case-insensitively matching file or directories is
 230 chosen arbitrarily.
 231 .PP
 232 The default case sensitivity of \fBwimlib-imagex\fR can be overridden by
 233 explicitly setting the environmental variable \fBWIMLIB_IMAGEX_IGNORE_CASE\fR to
 234 1, in which case such paths will be treated case insensitively, or 0, in which
 235 such paths will be treated case sensitively.
 236 .PP
 237 Regardless of these settings, options and non-path arguments must be specified
 238 in lower case.
 239 .SH LICENSE
 240 wimlib-imagex is provided to you under the GNU General Public License
 241 version 3.  Be aware this means this software is provided as-is and has no
 242 warranty.
 243 .SH REPORTING BUGS
 244 Report bugs to ebiggers3@gmail.com.  Feedback and suggestions are also welcome.
 245 .SH SEE ALSO
 246 .BR wimlib-imagex-append (1),
 247 .BR wimlib-imagex-apply (1),
 248 .BR wimlib-imagex-capture (1),
 249 .BR wimlib-imagex-delete (1),
 250 .BR wimlib-imagex-dir (1),
 251 .BR wimlib-imagex-export (1),
 252 .BR wimlib-imagex-extract (1),
 253 .BR wimlib-imagex-info (1),
 254 .BR wimlib-imagex-join (1),
 255 .BR wimlib-imagex-mount (1),
 256 .BR wimlib-imagex-mountrw (1),
 257 .BR wimlib-imagex-optimize (1),
 258 .BR wimlib-imagex-split (1),
 259 .BR wimlib-imagex-unmount (1),
 260 .BR wimlib-imagex-update (1),
 261 .BR wimlib-imagex-verify (1),