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

   1 .TH WIMLIB-IMAGEX 1 "December 2021" "wimlib 1.13.5" "User Commands"
   2 .SH NAME
   3 wimlib-imagex \- Extract, create, modify, or mount a WIM archive
   4 .SH SYNOPSIS
   5 \fBwimlib-imagex append\fR \fIarguments...\fR (or \fBwimappend\fR \fIarguments...\fR)
   6 .br
   7 \fBwimlib-imagex apply\fR \fIarguments...\fR (or \fBwimapply\fR \fIarguments...\fR)
   8 .br
   9 \fBwimlib-imagex capture\fR \fIarguments...\fR (or \fBwimcapture\fR \fIarguments...\fR)
  10 .br
  11 \fBwimlib-imagex delete\fR \fIarguments...\fR (or \fBwimdelete\fR \fIarguments...\fR)
  12 .br
  13 \fBwimlib-imagex dir\fR \fIarguments...\fR (or \fBwimdir\fR \fIarguments...\fR)
  14 .br
  15 \fBwimlib-imagex export\fR \fIarguments...\fR (or \fBwimexport\fR \fIarguments...\fR)
  16 .br
  17 \fBwimlib-imagex extract\fR \fIarguments...\fR (or \fBwimextract\fR \fIarguments...\fR)
  18 .br
  19 \fBwimlib-imagex info\fR \fIarguments...\fR (or \fBwiminfo\fR \fIarguments...\fR)
  20 .br
  21 \fBwimlib-imagex join\fR \fIarguments...\fR (or \fBwimjoin\fR \fIarguments...\fR)
  22 .br
  23 \fBwimlib-imagex mount\fR \fIarguments...\fR (or \fBwimmount\fR \fIarguments...\fR)
  24 .br
  25 \fBwimlib-imagex mountrw\fR \fIarguments...\fR (or \fBwimmountrw\fR \fIarguments...\fR)
  26 .br
  27 \fBwimlib-imagex optimize\fR \fIarguments...\fR (or \fBwimoptimize\fR \fIarguments...\fR)
  28 .br
  29 \fBwimlib-imagex split\fR \fIarguments...\fR (or \fBwimsplit\fR \fIarguments...\fR)
  30 .br
  31 \fBwimlib-imagex unmount\fR \fIarguments...\fR (or \fBwimunmount\fR \fIarguments...\fR)
  32 .br
  33 \fBwimlib-imagex update\fR \fIarguments...\fR (or \fBwimupdate\fR \fIarguments...\fR)
  34 .br
  35 \fBwimlib-imagex verify\fR \fIarguments...\fR (or \fBwimverify\fR \fIarguments...\fR)
  36 .SH DESCRIPTION
  37 \fBwimlib-imagex\fR deals with archive files in the Windows Imaging (WIM)
  38 format.  Its interface is similar to Microsoft's ImageX, but \fBwimlib-imagex\fR
  39 is 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 (WIM) format 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 which Microsoft released with Windows 8 uses
  57 solid-mode LZMS compression to achieve a better compression ratio.  Such files
  58 are also called "ESD files" and may have the \.esd extension instead of .wim.
  59 wimlib fully supports these files except when 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: if appropriate hard links or batch files have been installed, a command
  68 \fBwimlib-imagex \fICOMMAND\fR can also be accessed as simply
  69 \fBwim\fICOMMAND\fR; for example, \fBwimapply\fR for \fBwimlib-imagex apply\fR.
  70 For brevity the documentation uses the shorter names.
  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 (\fBwiminfo\fR)
  76 .IP \[bu]
  77 List the files in a WIM image (\fBwimdir\fR)
  78 .IP \[bu]
  79 Extract, or "apply", a full WIM image (\fBwimapply\fR)
  80 .IP \[bu]
  81 Extract files or directories from a WIM image (\fBwimextract\fR)
  82 .IP \[bu] 4
  83 Capture a WIM image and save it to a new WIM file (\fBwimcapture\fR)
  84 .IP \[bu]
  85 Capture a WIM image and append it to an existing WIM file (\fBwimappend\fR)
  86 .IP \[bu]
  87 Modify a WIM image by adding, deleting, or renaming files (\fBwimupdate\fR)
  88 .IP \[bu]
  89 (Linux only) Mount a WIM image read-only (\fBwimmount\fR)
  90 .IP \[bu]
  91 (Linux only) Mount a WIM image read-write (\fBwimmountrw\fR)
  92 .IP \[bu]
  93 Delete an image from a WIM file (\fBwimdelete\fR)
  94 .IP \[bu]
  95 Export image(s) from a WIM file (\fBwimexport\fR)
  96 .IP \[bu]
  97 Change the name or description of a WIM image (\fBwiminfo\fR)
  98 .IP \[bu]
  99 Change the bootable image index of a WIM file (\fBwiminfo\fR)
 100 .IP \[bu]
 101 Rebuild, and optionally recompress, a WIM file (\fBwimoptimize\fR)
 102 .IP \[bu]
 103 Split a WIM file into multiple parts (\fBwimsplit\fR)
 104 .IP \[bu]
 105 Join a split WIM (\fBwimjoin\fR)
 106 .IP \[bu]
 107 Verify the validity and integrity of a WIM file (\fBwimverify\fR)
 108 .SH DETAILED FEATURES
 109 This section presents some of the interesting features of
 110 \fBwimlib-imagex\fR in more detail.
 111 .IP \[bu] 4
 112 Multi-platform support.  \fBwimlib-imagex\fR is supported on both UNIX-like
 113 systems (mainly Linux, but also FreeBSD, Mac OS X, etc.) and Windows.  Most code
 114 is shared among all platforms, but platform-specific features are still
 115 supported when possible.
 116 .IP \[bu]
 117 XPRESS, LZX, and LZMS compression and decompression.  wimlib contains advanced
 118 implementations of all these compression algorithms.  These have been improved
 119 over time and now usually outperform and outcompress their Microsoft
 120 equivalents, while remaining fully compatible.
 121 .IP \[bu]
 122 Solid-mode compression, or "ESD file", support. "ESD files" are an updated WIM
 123 format that uses solid LZMS compression to achieve a better compression ratio.
 124 .IP \[bu]
 125 Multithreaded compression.  By default, wimlib's data compression is
 126 multithreaded and will use all available processors.
 127 .IP \[bu]
 128 On UNIX-like systems, integration with libntfs-3g allows capturing a WIM image
 129 directly from an NTFS volume, or applying a WIM image directly to an NTFS
 130 volume.  This allows saving and restoring NTFS-specific data and metadata, such
 131 as security descriptors and named data streams, which would otherwise only be
 132 supported on Windows.
 133 .IP \[bu]
 134 On UNIX-like systems, optional support for saving and restoring standard UNIX
 135 file permissions (owner/group/mode), UNIX special files, and extended
 136 attributes.  (This is a wimlib extension; Microsoft's WIM software ignores this
 137 extra information.)
 138 .IP \[bu]
 139 On Linux, support for mounting WIM images with FUSE (Filesystem in UserSpacE),
 140 both readonly and read-write.
 141 .IP \[bu]
 142 Split WIMs.  A split WIM is a WIM archive split into multiple parts.
 143 \fBwimsplit\fR can create a split WIM from a standalone WIM, and \fBwimjoin\fR
 144 can create a standalone WIM from a split WIM.
 145 .IP \[bu]
 146 Delta WIMs.  A delta WIM contains image metadata but excludes file data already
 147 present in another WIM file.  A delta WIM can be created using \fBwimcapture\fR
 148 with the \fB--delta-from\fR option.
 149 .IP \[bu]
 150 "Pipable" WIMs.  As a wimlib extension (not compatible with the Microsoft
 151 implementation), \fBwimcapture\fR supports capturing a WIM file to standard
 152 output in a special "pipable" format which can later be applied by sending it to
 153 \fBwimapply\fR on standard input.  Among other things, this can be used to pipe
 154 images to or from a server over the network to implement fast filesystem imaging
 155 and restore.
 156 .IP \[bu]
 157 Support for WIM integrity tables.  Although file data in WIM archives is always
 158 checksummed, there can also be an extra set of checksums (an "integrity table")
 159 associated with the WIM file itself to provide extra integrity assurance.  The
 160 \fB--check\fR option to several \fBwimlib-imagex\fR commands can be used to
 161 verify or add these extra checksums.
 162 .IP \[bu]
 163 Fast incremental backups.  Because WIM archives use content-addressible file
 164 data, the contents of files are automatically deduplicated.  In addition, using
 165 the \fB--update-of\fR option of \fBwimcapture\fR or \fBwimappend\fR, you can
 166 optimize an image capture so that files that are unmodified based on timestamps
 167 are not even read from disk.
 168 .IP \[bu]
 169 Windows-specific image metadata support.  When capturing an image of a Windows
 170 operating system, wimlib will automatically populate XML metadata fields such as
 171 the Windows OS version details by scanning well-known system files.
 172 .IP \[bu]
 173 WIMBoot support.  On Windows 8.1 and later, files can be "externally backed" by
 174 a WIM archive with the help of Microsoft's Windows Overlay Filesystem (WOF)
 175 filter driver.  With the \fB--wimboot\fR option, \fBwimapply\fR will extract
 176 "pointer files" to the WIM archive rather than the files themselves.
 177 .IP \[bu]
 178 VSS snapshot support.  On Windows, \fBwimcapture\fR or \fBwimappend\fR with the
 179 \fB--snapshot\fR option will automatically create a temporary VSS snapshot and
 180 capture the image from it.  This can be used to image a "live" Windows system.
 181 .IP \[bu]
 182 Long path support on Windows.  \fBwimlib-imagex\fR can capture and apply files
 183 with paths exceeding the MAX_PATH (260 character) limitation of the Win32
 184 subsystem.
 185 .IP \[bu]
 186 Non-Administrator support on Windows.  You can run \fBwimlib-imagex\fR without
 187 Administrator rights, subject to some limitations.
 188 .SH COMMON OPTIONS
 189 The following options work for all \fBwimlib-imagex\fR commands:
 190 .TP 6
 191 \fB--help\fR
 192 Display the help, then exit.
 193 .TP
 194 \fB--version\fR
 195 Display the version and legal information, then exit.
 196 .TP
 197 \fB--quiet\fR
 198 Suppress informational and progress messages.
 199 .SH CASE SENSITIVITY
 200 By default, the case sensitivity of \fBwimlib-imagex\fR differs somewhat between
 201 UNIX-like systems and Windows.  WIM images may (but usually do not) have
 202 multiple files with the same case-insensitive name.  Internally, wimlib stores
 203 filenames as case-sensitive, but on Windows paths actually provided by the user
 204 for use in a WIM image (e.g. for extracting, adding, renaming, or deleting
 205 files) will by default be treated as case-insensitive in order to get the
 206 "expected" behavior. This differs from the default behavior on UNIX-like
 207 systems, where such paths will be treated as case-sensitive.
 208 .PP
 209 Note that with case insensitivity, a path component may in general be ambiguous
 210 due to multiple files or directories having the same case-insensitive name.  In
 211 such cases, if there is a file or directory with an exactly matching name, it is
 212 chosen; otherwise, one of the case-insensitively matching file or directories is
 213 chosen arbitrarily.
 214 .PP
 215 The default case sensitivity of \fBwimlib-imagex\fR can be overridden by
 216 explicitly setting the environmental variable \fBWIMLIB_IMAGEX_IGNORE_CASE\fR to
 217 1, in which case such paths will be treated case insensitively, or 0, in which
 218 such paths will be treated case sensitively.
 219 .PP
 220 Regardless of these settings, options and non-path arguments must be specified
 221 in lower case.
 222 .SH LICENSE
 223 wimlib-imagex may be redistributed and/or modified under the terms of the GNU
 224 General Public License; either version 3 of the License, or (at your option) any
 225 later version.  There is NO WARRANTY, to the extent permitted by law.
 226 .SH REPORTING BUGS
 227 Report bugs to \fIhttps://wimlib.net/forums/\fR.
 228 Feedback and suggestions are also welcome.
 229 .SH SEE ALSO
 230 .BR wimappend (1),
 231 .BR wimapply (1),
 232 .BR wimcapture (1),
 233 .BR wimdelete (1),
 234 .BR wimdir (1),
 235 .BR wimexport (1),
 236 .BR wimextract (1),
 237 .BR wiminfo (1),
 238 .BR wimjoin (1),
 239 .BR wimmount (1),
 240 .BR wimmountrw (1),
 241 .BR wimoptimize (1),
 242 .BR wimsplit (1),
 243 .BR wimunmount (1),
 244 .BR wimupdate (1),
 245 .BR wimverify (1),