HDIUTIL(1) System General Commands Manual HDIUTIL(1)
NAME
hdiutil - manipulate disk images
SYNOPSIS
hdiutil verb [options]
DESCRIPTION
hdiutil uses the DiskImages framework to manipulate disk image files.
Common verbs include attach, detach, verify, create, convert, and burn.
The rest of the verbs are: help, info, load, checksum, eject (historical
synonym for detach), flatten, unflatten, imageinfo, mount (historical
synonym for attach), mountvol, unmount, plugins, resize, segment, and
pmap.
COMMON OPTIONS
All hdiutil verbs accept the following options:
-verbose be verbose; default is less output. This option is good if it
is unclear why a particular operation failed. At a minimum, the
probing for each image type of any given files will be shown.
-quiet minimize output in most cases.
-debug be very verbose. This option is good if a large amount of
information about what hdiutil and the DiskImages framework are
doing is needed.
Many hdiutil verbs understand the following options:
-plist display output in plist format
-srcimagekey <key>=<value>
specify a key/value pair for the disk image recognizer.
(-imagekey is normally a synonym)
-tgtimagekey <key>=<value>
specify a key/value pair for any image created. (-imagekey
is only a synonym if there is no input image).
-encryption [crypto_method]
specify a particular type of encryption or, if not speci-
fied, the default CEncrypedEncoding.
-passphrase passphrase
provide a passphrase for an encrypted image. -passphrase is
very insecure since the passphrase will be visible to anyone
who can run ps(1).
-shadow [shadowfile]
Use a shadow file in conjunction with the data in the image.
This option prevents modification of the original image and
allows read-only images to be used as read/write images.
When blocks are being read from the image, blocks present in
the shadow file override blocks in the base image. When
blocks are being written, the writes will be redirected to
the shadow file. If not specified, -shadow defaults to
<imagename>.shadow. If the shadow file does not exist, it
is created.
For the verbs that create images, it should be noted that the correct
extension will be added to the filenames if the extension is not present.
The creation engine also examines the filename extension of the provided
filename and changes its behavior accordingly. For example, a sparse
image can be created without specifying -type SPARSE simply by appending
the .sparseimage extension to the provided filename.
VERBS
Each verb is listed with its description and individual arguments. Argu-
ments to the verbs can be passed in almost any order. A sector is 512
bytes.
help display the usage information for each verb.
attach imagename [options]
attach calls hdid with its arguments. See hdid(1) for options
that you can pass to attach. attach, like hdid, will return
information about an already-attached image as if it had
attached it. mount is a synonym for attach.
detach dev_name [-force]
detach a disk image and terminate any associated hdid process.
dev_name is a partial /dev node path (e.g. "disk1"). If Disk
Arbitration is running, detach will use it to unmount any par-
titions and detach the image. If not, the partition will need
to be manually unmounted (by the user who mounted them or by
root -- if Disk Arbitration made the mount, only root can do a
clean umount) using umount(8). Only then will hdiutil detach
be able to detach the image. eject is a synonym for detach.
-force Similar to umount -f. Unmounts any filesystems and
detaches the image file, regardless of any open files
on the image.
verify imagename [options]
compute the checksum of a read-only (or compressed) image
file, and verify it against the value stored in the image.
verify accepts the common options -encryption, -srcimagekey,
-tgtimagekey, -passphrase, and -shadow.
create imagename size_spec [options]
create a new blank image. If imagename already exists, -ov
must be specified or create will fail.
Size specifiers:
-size <??b|??k|??m|??g|??t??p|??e>
-size specifies the size of the image in the style
of mkfile(8) with the addition of tera-, peta-, and
exa-bytes sizes. The larger sizes are occasionally
useful when creating large sparse images.
-sectors sector_count
Specify the size of the image file in 512 byte sec-
tors. Note that this quantity includes the space
that might be used for a partition map or other
utility partitions. The overhead for a SPUD (the
default single-partition layout) is 64 sectors.
The overhead for layout NONE is 0 sectors.
-megabytes size
Specify the size of the image file in megabytes
(1024*1024 bytes). Note that this quantity
includes the space that might be used for a parti-
tion map or other utility partitions.
Common options: -plist, -tgtimagekey, -encryption, and
-passphrase. -imagekey di-sparse-puma-compatible=TRUE and
-imagekey di-shadow-puma-compatible=TRUE will create, respec-
tively, sparse and shadow image files that can be attached on
OS X 10.1.
Other options:
-align alignment
specifies a size to which the final data parti-
tion will be aligned. The default is 4K.
-type <UDIF|SPARSE>
UDIF is the default disk image format. If
specified, a UDRW of the specified size will be
created. Specifying SPARSE creates a
read/write image which starts small and grows
as more data is written to it. The default is
to grow one megabyte at a time, but the key
sparse-band-size can be used (with -imagekey)
to specify the number of sectors that will be
added each time the image grows. The maximum
size of a SPARSE image is bounded by the
filesystem in the image. Keep in mind that an
HFS+ filesystem can be resized within ini-
tially-defined stretch limits.
SPARSE images (and shadow files) are designed
to be used during intermediate steps in the
process of creating other images (eg. UDZO)
when final image sizes are unknown. Such grow-
able files should not be used for persistent
storage because their internal structure exac-
erbates any fragmentation introduced by the
filesystem.
-fs filesystem
where filesystem is one of HFS+, HFS, MS-DOS,
or UFS. -fs causes the image to be attached,
formatted with the specified filesystem and
then detached. -fs may also change the default
layout if that particular filesystem does not
natively come in an Apple Partition Map.
-volname volname
specify the volume name (default is "untitled")
of the newly-created filesystem.
-stretch max_stretch
-stretch initializes HFS+ filesystem data such
that it can later be stretched using hdiutil
resize. max_stretch is specified like -size.
-fsargs newfs_options
additional options to pass to whatever newfs
program is being called.
-layout layout
Specify the partition map layout of the image.
layout can be anything specified in Medi-
aKit.framework's MKDrivers.bundle. NONE cre-
ates an image file with no partition map. When
such an image is attached, a single /dev entry
will be created (e.g. /dev/disk1). SPUD speci-
fies a Single Partition UDIF. This creates an
image file with a DDM and an Apple Partition
Scheme partition map, with a single entry for
an Apple_HFS partition. When attached, multi-
ple /dev entries will be created and the 2nd
partition will be the data partition (e.g.
/dev/disk1, /dev/disk1s1, /dev/disk1s2; the
second partition is disk1s2). Unless changed
by -fs, the default is SPUD. Other layouts
include "UNIVERSAL HD" and "UNIVERSAL CD" which
add appropriate OS 9 driver partitions for
those types of media.
-partitionType partition_type
Change the single partition type in a SPUD.
The default is Apple_HFS. The principal alter-
native is Apple_UFS, though the appropriate
partition map will be generated depending on
what is passed to -fs.
-ov overwrite an existing file. The default is not
to overwrite existing files.
convert imagefile -format format -o outfile [options]
convert imagefile to type format and write the result to
outfile.
As mentioned above, the correct filename extension will be
added only if it isn't part of the provided name. Format is
one of:
UDRW UDIF read/write image
UFBI UDIF entire image with MD5 checksum
UDRO UDIF read/only image
UDCO UDIF ADC-compressed image
UDRo UDIF read/only (obsolete format)
UDCo UDIF compressed (obsolete format)
UDTO DVD/CD-R export image
UDxx UDIF stub image
UDZO UDIF zlib-compressed image
RdWr NDIF read/write image (deprecated)
Rdxx NDIF read/only image (deprecated, but still
usable on OS 9 and OS X)
ROCo NDIF compressed image (deprecated)
Rken NDIF compressed (obsolete format)
DC42 Disk Copy 4.2 image
In addition to the compression offered by some formats, the
UDIF and NDIF non-read/write image formats completely remove
unused space in HFS and UFS filesystems. For UDZO, -imagekey
zlib-level=value allows you to set the zlib compression level
ala gzip(1). The default compression level is 1 (fastest).
options are any of:
Common options: -shadow, -srcimagekey, -tgtimagekey,
-encryption, and -passphrase.
Other options:
-align sector_alignment
default is 4 (2K) [does this really make sense on
a convert?]
-pmap add partition map.
When converting a NDIF to a any variety of UDIF,
or when converting a partition-less UDIF to UDIF,
the default is true.
-segmentSize [sector_count]
Specify segmentation of imagename into
sector_count- sized segments. The default
sector_count when -segmentSize is specified is
2*1024*1024 (1 GB segments) for UDTO images and
4*1024*1024 (2 GB segments) for all other image
types. sector_count can also be specified
<??b|??k|??m|??g|??t??p|??e> like mkfile(8).
-tasks task_count
When converting an image into a compressed for-
mat, specify the number of threads to use for the
compression operation. The default is the number
of processors active in the current system.
burn imagename [options]
Burn imagename to optical media in an attached drive. In all
cases, a prompt for media will be printed once an appropriate
drive has been found. options are any of:
Common options: -shadow, -srcimagekey, -encryption, and
-passphrase.
Other options:
-testburn don't turn on laser (laser defaults to on).
-noeject don't eject disc after burning.
-eject eject disc after burning (default).
-verifyburn verify disc contents after burn (default).
-noverifyburn don't verify disc contents after burn.
-addpmap add partition map if necessary. Some
filesystem types will not be recognized when
stored on optical media unless they are
enclosed in a partition map. This option
will add a partition map to any bare filesys-
tem which needs a partition map in order to
be recognized when burned to optical media.
This is the default behavior.
-noaddpmap don't add partition map.
-skipfinalfree skip final free partition. If there is a
partition map on the image specifying an
Apple_Free partition as the last partition,
that Apple_Free partition will not be burned.
The burned partition map will still reference
the empty space. This is the default behav-
ior.
-noskipfinalfree don't skip any trailing Apple_Free partition.
-optimizeimage optimize filesystem for burning. Optimiza-
tion can reduce the size of an HFS or HFS+
volume to the size of the data contained on
the volume. This option will change what is
burned such that the disc will have a differ-
ent checksum than the image it came from.
-nooptimizeimage don't optimize. Burn all blocks of the image
(minus any blocks in trailing Apple_Free par-
titions unless -noskipfinalfree is speci-
fied). This is the default behavior.
-forceclose force the disc to be closed after burning.
Further burns to the disc will be impossible.
-noforceclose don't force disc to be closed (default)
-speed x_factor 1, 2, 4, 6, ... `max'
The desired "x-factor". eg. 8 means the
drive will be instructed burn at "8x speed".
`max' will cause the burn to proceed at the
maximum speed of the drive. `max' is the
default speed.
-sizequery just calculate the size of disc required (the
size returned is in sectors).
-erase prompt for optical media (DVD-RW/CD-RW) and
then, if the hardware supports it, quickly
erase the media.
-fullerase erase all sectors of the disc (this usually
takes quit a bit longer than -erase).
info display information about the disk image driver and any image
files that are currently attached. hdiutil info accepts
-plist.
load manually load the disk image driver. The disk image driver
will be loaded automatically by the Disk Copy application or
hdid(8) if an image file is being attached and the driver is
not currently loaded. As of OS X 10.2, the driver will auto-
matically detach itself after use and then be unloaded after a
minute or so, making hdiutil load something of a no-op.
checksum imagename [options] -type type
Calculate the specified checksum on the image data, regardless
of image source or type. Common options: -plist, -shadow,
-srcimagekey, -encryption, and -passphrase.
type is one of:
UDIF-CRC32 - CRC-32 image checksum
UDIF-MD5 - MD5 image checksum
DC42 - Disk Copy 4.2
CRC28 - CRC-32 (NDIF)
CRC32 - CRC-32
MD5 - MD5
unflatten imagename
unflatten a read-only (or compressed) UDIF disk image, creat-
ing a dual-fork file in traditional format (resource-only; no
XML). Common options: -srcimagekey, -encryption, and
-passphrase.
flatten imagename
Flatten a read-only (or compressed) UDIF disk image into a
single-fork file. If the image is UDZO and does not contain
XML meta-data for in-kernel attachment, add it. Common
options are: -srcimagekey, -encryption, and -passphrase.
flatten is only required if the UDIF has previously been
unflatten'd.
Other options:
-noxml don't embed XML data for in-kernel attachment.
The image will never attach in-kernel.
-norsrcfork don't embed resource fork data. The image will
not attach on OS X versions prior to OS X 10.2.
hfsanalyze imagename
Print information about an HFS/HFS+ volume. As is often the
case, imagename can be a /dev entry. See the NOTE ON DEV
ENTRY ACCESS section.
Common options are: -shadow, -srcimagekey, -encryption, and
-passphrase.
mountvol devnode
Attempt to mount the given /dev node through Disk Arbitration
(similar to disktool -m). XML output is available from
-plist. Note that mountvol and unmount are a pair. mount/
attach can be called on a /dev entry, but it will treat the
/dev entry as a disk image file to be attach (through another
/dev entry). This is usually undesirable.
unmount volume
unmounts a mounted volume. volume can be a full path to a
/dev entry or the name of a mountpoint.
imageinfo imagename [options]
Print out information about a disk image. Common options are:
-plist, -srcimagekey, -encryption, and -passphrase. options
are any of:
-format just print out the image format
-checksum just print out the image checksum
plugins print information about DiskImages framework plugins. The
user, system, local, and network domains are searched for plu-
gins (ie. ~/Library/Plug-ins/DiskImages,
/System/Library/Plug-ins/DiskImages,
/Library/Plug-ins/DiskImages,
/Network/Library/Plug-ins/DiskImages). -plist is available.
resize size_spec imagename [options]
For a read/write partitioned UDIF device image, if the last
partition is Apple_HFS (either HFS or HFS+), attempt to resize
the partition to the end of the device file, or to the last
used block in the embedded HFS/HFS+ file system. This is typ-
ically used when working with a large device image file, when
it is desirable to shrink the HFS/HFS+ partition before con-
verting to CD-R/DVD-R format. Images converted to CD-R/DVD-R
do not include the Apple_Free partition at the end of the
device, so such conversions result in a CD-R/DVD-R master that
would only write the actual data.
Common options are: -srcimagekey, -encryption, and
-passphrase. Size specifiers:
-size <??b|??k|??m|??g|??t??p|??e>
-sectors sector_count | min | max
Specify the number of 512 byte sectors to
which the partition should be resized. If
this falls outside the min/max values, an
error will be returned and the partition will
not be resized. min automatically determines
the smallest size the partition can be short-
ened to and uses that value. max automati-
cally determines the largest size to which
the partition can be grown and then uses that
value.
Other options:
-imageonly only resize the image file, not the parti-
tion(s) inside of it. This is the default
for UDIF images.
-partitiononly only resize the partition(s) in the image.
This is the default for NDIF images. It only
works when shrinking a partition and results
in a larger Apple_Free partition.
-addPart partType sizespec add a partition of type partType
and size sizespec after the partition being
resized.
-partitionNumber partitionNumber
specifies which partition to resize (UDIF
only -- see HISTORY below). partitionNumber
is 0-based, but, per hdiutil pmap, partition
0 is the partition map itself.
-growonly only allow the image to grow
-shrinkonly only allow the image to shrink
-nofinalgap allow resize to entirely eliminate the trail-
ing free partition. Such an image will not
boot OS 9 nor will it allow OS X to boot on
old-world (beige) machines.
-limits Displays the minimum, current, and maximum
values for the size of the given volume in
512 byte sectors. Does not modify the image
file.
segment
segment -o firstSegname -segmentCount <#segs> imagename [opts]
segment -o firstSegname -segmentSize <size> imagename [opts]
segment a NDIF or UDIF disk image. Common options are:
-srcimagekey, -tgtimagekey, -encryption, and -passphrase.
options include:
-segmentCount segment_count
Specify the number of segments. Only one of
-segmentCount or -segmentSize will be honored.
-segmentSize segment_size
Specify the segment size in sectors. If the
original image size is not an exact multiple of
the segment size, the last segment will be
shorter than the others. Only one of
-segmentCount or -segmentSize will be honored.
-firstSegmentSize segment_size
Specify the first segment size in sectors. Used
for multi-CD restores.
-restricted Make restricted segments for use in multi-CD
restores. This option is ignored for NDIF
images.
pmap image_source [options]
display partition map from image or device. image_source is
either a plain file or special file (ie. a /dev/disk entry).
See the NOTE ON DEV ENTRY ACCESS below. Common options are:
-shadow, -srcimagekey, -encryption, and -passphrase.
options defaults to "xsSgcvk" and can be any combination of
the following:
r raw - process all without modification
x extended - process 2K & 512 entries and merge
s sectorize - return all quantities in Sectors
S sort - sort all entries By Blockno
g genfree - account for all unmapped space
c combfree - combine adjacent freespace entries
f fixfinal - extend last partition to device end
v volume synthesize - synthesize single volumes as
a single partition entry
k skip zero-length - skip zero length entries
K skip void/free - skip all free & void partitions
m merge free space - Merge small free partitions into
a previous partition if possible
i ignore shims - Ignore small free partitions
caused by block alignment
EXAMPLES
A simple verb:
hdiutil verify myimage.img
Verifies an image file.
Segmentation:
hdiutil segment -segmentSize 10m -o /tmp/aseg 30m.dmg
aseg.dmg, aseg.002.dmgparg, and aseg.003.dmgpart are
created.
Converting:
hdiutil convert master.dmg -format UDTO -o master
Converts master.dmg to a CD-R export image file, appending
.toast to the filename.
hdiutil convert CDmaster.dmg -format UDTO -o CDmaster.cdr
Converts CDmaster.dmg to a CD-R export image file named
CDmaster.cdr.
hdiutil convert /dev/rdisk1 -format UDRW -o devim
Converts the disk /dev/disk1 to a read/write device image
file. authopen(1) will be used if read access to
/dev/rdisk1 is not available. Note access via the raw
(character-special) device.
Burning:
hdiutil burn myImage.dmg
Burns the image to available optical media and verifies
the burn.
hdiutil burn myRawImage.cdr -noverifyburn -noeject
Burns the image without verifying the burn or ejecting
the disk. The disk will be attached after burning.
Creating a 50 MB encrypted image:
hdiutil create -encryption -size 50m e.dmg
Image from folder (old-style; -fs does some of this work now):
du -s myFolder # du(1) will count resource forks
10542
hdiutil create -sectors 10642 folder # add ~1% for meta-data
hdid -nomount folder.dmg
...
/dev/disk1s2 Apple_HFS
newfs_hfs -v myFolderImage /dev/rdisk1s2
hdiutil detach disk1
hdid folder.dmg
...
/dev/disk1s2 Apple_HFS /Volumes/myFolderImage
ditto -rsrcFork myFolder /Volumes/myFolderImage
hdiutil detach disk1s2 # when you are all done
hdiutil convert -format UDZO -o folder.z.dmg folder.dmg # compress
NOTE ON DEV ENTRY ACCESS
Since any /dev entry can be treated as a raw disk image, it is worth not-
ing which devices can be accessed when and how. /dev/rdisk nodes are
character-special devices, but are "raw" in the BSD sense and force
block-aligned I/O. They are closer to the physical disk than the buffer
cache. /dev/disk nodes, on the other hand are buffered block-special
devices and used primarily by the kernel's filesystem code (tools like
fsck(8) and newfs(8) prefer the raw device but work on either). It is
not possible to read from a /dev/disk node while a filesystem is mounted
from it, but anyone with read access to the appropriate /dev/rdisk node
can use hdiutil verbs such as hfsanalyze on it. The DiskImages framework
will attempt to use authopen(1) to open any device which it can't open
for reading with open(2). This may cause apparent hangs while trying to
access /dev entries while logged in remotely (an authorization panel is
waiting on console).
COMPATIBILITY
Several new features have been introduced into the DiskImages framework
with OS X 10.1 and OS X 10.2. Sparse images, encrypted images, and zlib-
compressed images all did not exist in OS X 10.0.x but came into being
with 10.1. These images will not attach (or will attach read/write
allowing for their destruction) on OS X 10.0.x.
With OS X 10.2, in-kernel attachment becomes possible, image meta-data
can now be stored as XML-only, and the default Disk Copy.app "compressed"
format is now UDZO. It is now possible to create images that won't
attach on OS X 10.1 and easy to create images that won't attach on OS X
10.0.
HISTORY
Originally, disk image files were created to electronically store and
transmit representations of floppy disks for manufacturing replication.
These image files are typically referred to as 'Disk Copy 4.2' images, in
reference to the application that created these image files and restored
them to floppy disks. Disk Copy 4.2 images were block for block repre-
sentations of a floppy disk, with no notion of compression.
DART is a variant of the Disk Copy 4.2 format that supported compression
of the floppy image file.
NDIF (New Disk Image Format) image files were developed to replace the
Disk Copy 4.2 and DART image formats, as well as provide the ability to
create image files larger than floppy-sized disks. Additionally, com-
pression and the ability to attach disk image files in the OS 9 filesys-
tem as mass storage devices was introduced. NDIF image files were cre-
ated and manipulated by Disk Copy version 6.
UDIF (Universal Disk Image Format) device image files extend NDIF to pro-
vide the ability to create device images, which include data that might
appear on a given mass storage device (DDM, Apple partition scheme parti-
tion map, disk-based drivers, etc). This format allows items such as
bootable CD's to be created from an image file. UDIF is a flat file for-
mat (vs. NDIF which is a dual fork format), and is the native image for-
mat for OS X.
Raw disk image files from other operating systems (eg. .iso files) can be
mounted if they contain data which OS X can interpret as a filesystem.
They can also be burned with hdiutil burn.
FILES
/usr/libexec/load_hdi - SUID tool used to load HDI disk image driver
SEE ALSO
authopen(1), hdid(8), ioreg(8), ufs.util(8), msdos.util(8), hfs.util(8),
autodiskmount(8), /usr/sbin/disktool (run with no args for usage).
Mac OS 25 Jun 2002 Mac OS