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