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

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