hdiutil(1) BSD General Commands Manual hdiutil(1)
NAME
hdiutil - manipulate disk images
SYNOPSIS
hdiutil verb [options]
DESCRIPTION
hdiutil uses the DiskImages framework to manipulate disk images. Common
verbs include attach, detach, verify, create, convert, and burn.
The rest of the verbs are: help, info, load, checksum, chpass, eject
(historical synonym for detach), flatten, unflatten, imageinfo, mount
(historical synonym for attach), mountvol, unmount, plugins,
internet-enable, resize, segment, compact, makehybrid, and pmap.
COMMON OPTIONS
All hdiutil verbs accept the following options:
-verbose be verbose; default is less output. This option can help the
user decipher why a particular operation failed. At a minimum,
the probing of any specified images will be detailed.
-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. -debug and -verbose generate almost entirely
independent outputs.
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 recognition sys-
tem. (-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 CEncryptedEncoding. CEncryptedEncoding
utilizes the AES cipher with a 128 bit key.
-stdinpass cause hdiutil to read a null-terminated passphrase from its
standard input. ^@ can be typed to explicitly insert the
terminator. -stdinpass is primarily for automation and does
not currently suppress the terminal's current echo state
when used interactively. -stdinpass replaces -passphrase
though the latter is still supported for compatibility.
-recover keychain_file
specify a keychain containing a certificate (generated with
-certificate) to unlock the image.
-certificate certificate_file
specify a secondary access certificate for the image being
created.
-cacert cert specify a certificate authority certificate. cert can be
either a PEM file or a directory of certificates processed
by c_rehash(1). See also --capath and --cacert in curl(1).
-insecurehttp ignore SSL host validation failure. Useful for self-signed
servers for which the appropriate certificates are unavail-
able or if access to a server is desired when the server
name doesn't match what is in the certificate.
-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 attached read/write. When
blocks are being read from the image, blocks present in the
shadow file override blocks in the base image. All data
written to the attached device will be redirected to the
shadow file. If not specified, -shadow defaults to
image.shadow. If the shadow file does not exist, it is cre-
ated. Verbs accepting -shadow also accept -cacert and
-insecurehttp.
Verbs that create images automatically append the correct extension to
any filenames if the extension is not already 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 .spar-
seimage 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 any order. A sector is 512 bytes.
help display minimal usage information for each verb. hdiutil verb
-help will provide full usage information for that verb.
attach image [options]
attach a disk image to the system as a device. attach, like
hdid(8), will return information about an already-attached
image as if it had attached it. mount is a synonym for
attach.
Beware that an image you have created and attached is a con-
sidered a new removable device. See hdid(8) and the EXAMPLES
section below for more details.
Common options: -encryption, -stdinpass, -recover, -imagekey,
-shadow, and -plist.
Options:
-readonly force the resulting device to be read-only
-readwrite attempt to override the DiskImages frame-
work's decision to attach a particular image
read-only. For example, -readwrite can be
used to modify the HFS filesystem on a
HFS/ISO hybrid CD image.
-nokernel attach with a helper process.
-kernel attempt to attach this image without a
helper process; fail if not possible.
-notremovable prevent this image from being detached.
Only root can use this option.
-mount required|optional|suppressed
indicate whether filesystems in the image
should be mounted or not. OS X 10.2.x and
earlier defaulted to optional behavior; the
default is now required.
-nomount identical to -mount suppressed.
-mountroot path mount volumes in path instead of in /Volumes
-mountpoint path assuming only one volume, mount it at path
instead of in /Volumes
-union perform a union mount
-private suppress mount notifications to the rest of
the system.
-nobrowse mark the volumes non-browsable in applica-
tions such as the Finder.
-owners on|off enable or disable owners for HFS+ volumes,
potentially overriding the system's default
value for the volume.
-drivekey key=value
specify a key/value pair to be attached to
the device in the IOKit registry.
The following options have corresponding elements in the
com.apple.frameworks.diskimages preferences domain and thus
can be rendered in both the positive and the negative:
-[no]verify do [not] suppress verification of the image.
By default hdiutil attach verifies all
images containing checksums before attaching
them. To maintain backwards compatibility,
hdid(8) does not attempt to verify images
before attaching them.
-[no]ignorebadchecksums
specify whether bad checksums should be
ignored. The default is to abort when a bad
checksum is detected.
-[no]idme do [not] perform IDME actions on IDME
images. IDME actions are normally only per-
formed when a browser downloads and attaches
an image.
-[no]idmereveal do [not] reveal (in the Finder) the results
of IDME processing.
-[no]idmetrash do [not] put IDME images in the trash after
processing.
-[no]autoopen do [not] auto-open volumes (in the Finder)
after attaching an image. By default, read-
only volumes are auto-opened in the Finder.
-[no]autoopenro do [not] auto-open read-only volumes.
-[no]autoopenrw do [not] auto-open read/write volumes.
-[no]autofsck do [not] force automatic file system check-
ing before mounting a disk image. The
default is to perform these checks.
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, detach will attempt to
unmount any filesystems and detach the image directly (using
the `eject' ioctl). If Disk Arbitration is not running, it
may be necessary to unmount the filesystems with umount(8)
before detaching the image. eject is a synonym for detach.
Options:
-force Similar to umount -f. Unmounts any filesystems and
detaches the image, regardless of any open files on
the image.
verify image [options]
compute the checksum of a read-only (or compressed) image, and
verify it against the value stored in the image. verify
accepts the common options -encryption, -stdinpass,
-srcimagekey, and -plist.
create size_spec image
create a new image of the given size. If image already
exists, -ov must be specified or create will fail. If image
is attached, it must be detached before it can be overwritten,
even if -ov is specified.
The size specified is the size of the image file. Filesystem
and partition layout overhead (64 sectors for the default SPUD
layout) will be deducted before space is made for user data in
any volume on the image.
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 (note that 'b' specifies a number
of sectors, not bytes). The larger sizes are occa-
sionally useful when creating large sparse images.
-sectors sector_count
Specify the size of the image file in 512 byte sec-
tors.
-megabytes size
Specify the size of the image file in megabytes
(1024*1024 bytes).
-srcfolder directory
specifies the image size based on the contents of
directory. -srcfolder also specifies that the con-
tents of directory should populate the resulting
image. -srcfolder copies file by file, creating an
optimized filesystem on the destination image
(which then could be restored by asr(8)). -srcdir
is a synonym for -srcfolder.
Common options: -encryption, -stdinpass,
-plist, -imagekey, -tgtimagekey, and -plist.
-imagekey di-sparse-puma-compatible=TRUE and -imagekey
di-shadow-puma-compatible=TRUE will create, respectively,
sparse and shadow images that can be attached on OS X 10.1.
-imagekey encrypted-encoding-version can select between ver-
sion 1 and version 2 of the encrypted encoding. The framework
preferences have a corresponding key to change the default for
all images. Version 2 is not compatible with OS X 10.2 but is
more robust for SPARSE images. Version 1 is the default.
General 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 UDSP: a
read/write image which expands as is is filled
with data. 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 resize can resize an HFS+ filesys-
tem within predefined stretch limits. See
USING PERSISTENT SPARSE IMAGES below for more
information.
-fs filesystem
where filesystem is one of HFS+, HFS+J, HFSX,
HFS, MS-DOS, or UFS. -fs may also change the
default layout if that particular filesystem is
not native to an Apple Partition Map.
-volname volname
The newly-created filesystem will be named
volname. The default name is `untitled'.
-uid uid the root of the newly-created volume will be
owned by the given numeric user id. 99 maps to
the magic `unknown' user (see hdid(8)).
-gid gid the root of the newly-created volume will be
owned by the given numeric group id. 99 maps
to `unknown'.
-mode mode the root of the newly-created volume will have
mode mode.
-nouuid suppress addiing a UUID to the volume. Such a
volume will behave more like a volume which was
formatted with OS 9 or earlier.
-[no]autostretch do [not] suppress automatically making
stretchable volumes when the volume size
crosses the auto-stretch-size threshhold
(default: 50 MB). See also asr(8).
-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_args
additional arguments to pass to whatever newfs
program is implied by -fs.
-layout layout
Specify the partition layout of the image.
layout can be anything specified in Medi-
aKit.framework's MKDrivers.bundle. NONE cre-
ates an image with no partition map. When such
an image is attached, a single /dev entry will
be created (e.g. /dev/disk1). SPUD is an
acronym for Single Partition UDIF. SPUD cre-
ates an image with a DDM and an Apple Partition
Scheme partition map with a single entry for an
Apple_HFS partition. When attached, multiple
/dev entries will be created and the 2nd parti-
tion 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. OS 9 drivers are not
used by OS X nor by its Classic environment.
-partitionType partition_type
Change the type of partition in a SPUD. The
default is Apple_HFS. The principal alterna-
tive is Apple_UFS, though the appropriate par-
tition type will be automatically chosen
depending on the argument to -fs.
-ov overwrite an existing file. The default is not
to overwrite existing files. See the note with
create about not being allowed to overwrite
attached images.
-attach attach the image after creating it. Note that
if no filesystem is specified via -fs, the
attach will fail per the default attach -mount
required behavior.
Image from directory options (for -srcfolder):
-format format Specify the final image format. The default is
UDZO. format can be any of the format parame-
ters used by create.
-[no]crossdev do [not] cross device boundaries when copying
from the source.
-[no]scrub do [not] skip temporary files when imaging vol-
umes. Scrubbing is only the default when the
argument to -srcfolder is a the root of a vol-
ume. Such files include trashes, temporary
folders, swap files, etc.
-[no]anyowners do [not] require that the user invoking hdiutil
own all of the files being copied. create nor-
mally prompts for authentication if it detects
a file owned by someone other than the user
creating the image so that the ownership of the
files will be maintained in the image.
convert image -format format -o outfile
convert image 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
UDRO - UDIF read-only image
UDCO - UDIF ADC-compressed image
UDZO - UDIF zlib-compressed image
UFBI - UDIF entire image with MD5 checksum
UDRo - UDIF read-only (obsolete format)
UDCo - UDIF compressed (obsolete format)
UDTO - DVD/CD-R master for export
UDxx - UDIF stub image
UDSP - SPARSE (growable with content)
RdWr - NDIF read/write image (deprecated)
Rdxx - NDIF read-only image (Disk Copy 6.3.3 format)
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: -encryption, -stdinpass, -certificate,
-srcimagekey, -tgtimagekey, -shadow with friends, and -plist.
Other options:
-align alignment
The default is 4 (2K).
-pmap add partition map.
When converting a NDIF to a any variety of UDIF,
or when converting an unpartitioned UDIF, the
default is true.
-segmentSize [sector_count]
Specify segmentation into sector_count-sized seg-
ments as outfile is being written. The default
sector_count when -segmentSize is specified alone
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 create's -size
flag.
-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 image
Burn image to optical media in an attached burning device. In
all cases, a prompt for media will be printed once an appro-
priate drive has been found. Common options are: -shadow with
friends, -srcimagekey, -encryption, and -stdinpass.
Other options:
-device specify a device to use for burning. See
-list.
-testburn don't turn on laser (laser defaults to on).
-anydevice allow burning to devices not qualified by
Apple.
-[no]eject do [not] eject disc after burning. The
default is to eject the disc.
-[no]verifyburn do [not] verify disc contents after burn.
The default is to verify.
-[no]addpmap do [not] 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.
The default is to add the partition map if
needed.
-[no]skipfinalfree do [not] skip final free partition. If
there is a partition map on the image speci-
fying 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. The default
is to skip burning a final free partition.
-[no]optimizeimage do [not] optimize filesystem for burning.
Optimization 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 dif-
ferent checksum than the image it came from.
The default is to burn all blocks of the disk
image (minus any trailing Apple_Free).
-nounderrun turn off buffer underrun protection.
-[no]forceclose do [not] force the disc to be closed after
burning. Further burns to the disc will be
impossible. The default is not to close the
disc.
-speed x_factor 1, 2, 4, 6, ... `max'
The desired "x-factor". e.g. 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. Slower speeds can produce
more reliable burns.
-sizequery calculate the size of disc required (the size
returned is in sectors) without burning any-
thing.
-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).
-list list all burning devices, with OpenFirmware
paths suitable for -device.
makehybrid -o image source
Generate a disk image image using source with the DiscRecord-
ing framework's content creation system. source can either be
a directory or a disk image. The generated image can later be
burned using hdiutil burn, or converted to a read-only disk
image with hdiutil convert. The generated filesystem is not
designed to be used read/write, but can safely have its files
copied to a read/write filesystem by ditto(8) or asr(8).
Filesystem options:
-hfs Generate an HFS+ filesystem. This filesystem can be
present on an image simultaneously with an ISO9660 or
Joliet filesystem. On operating systems that under-
stand HFS+ as well as ISO9660, like Mac OS 9 or Mac OS
X, it is usually the preferred filesystem.
-iso Generate an ISO9660 Level 2 filesystem with Rock Ridge
extensions. This filesystem can be present on an
image simultaneously with an HFS+ or Joliet filesys-
tem. ISO9660 is the standard cross-platform inter-
change format for CDs and some DVDs, and is understood
by virtually all operating systems. If an ISO9660
Joliet filesystem is present on a disk image or CD,
but not HFS+, Mac OS X will use the ISO9660 (or
Joliet) filesystem.
-joliet Generate Joliet extensions to ISO9660. This view of
the filesystem can be present on an image simultane-
ously with HFS+, and requires the presence of an
ISO9660 filesystem. Joliet supports Unicode file-
names, but is only supported on some operating sys-
tems. If both an ISO9660 and Joliet filesystem are
present on a disk image or CD, but not HFS+, Mac OS X
will prefer the Joliet filesystem.
By default, if no filesystem is specified, the image will be
created with all three filesystems as a hybrid image. When
multiple filesystems are selected, the data area of the image
is shared between all filesystems, and only directory informa-
tion and volume metadata are unique to each filesystem. This
means that creating a cross-platform ISO9660/HFS+ hybrid has a
minimal overhead when compared to a single filesystem image.
Other options (most take a single argument):
-hfs-blessed-directory Path to folder which should be
"blessed" for Mac OS X booting on the
generated filesystem. This assumes the
folder has been otherwise prepared, for
example with bless -bootinfo to create
a valid BootX file. (HFS+ only).
-hfs-openfolder Path to a folder that will be opened by
the Finder automatically. See also the
-openfolder option in bless(8) (HFS+
only).
-hfs-startupfile-size Allocated an empty HFS+ Startup File of
the specified size, in bytes (HFS+
only).
-abstract-file Path to a file in the source directory
(and thus the root of the generated
filesystem) for use as the
ISO9660/Joliet Abstract file
(ISO9660/Joliet).
-bibliography-file Path to a file in the source directory
(and thus the root of the generated
filesystem) for use as the
ISO9660/Joliet Bibliography file
(ISO9660/Joliet).
-copyright-file Path to a file in the source directory
(and thus the root of the generated
filesystem) for use as the
ISO9660/Joliet Copyright file
(ISO9660/Joliet).
-application Application string (ISO9660/Joliet).
-preparer Preparer string (ISO9660/Joliet).
-publisher Publisher string (ISO9660/Joliet).
-system-id System Identification string
(ISO9660/Joliet).
-keep-mac-specific Expose Macintosh-specific files (such
as .DS_Store) in non-HFS+ filesystems
(ISO9660/Joliet).
-default-volume-name Default volume name for all filesys-
tems, unless overridden. If not speci-
fied, defaults to the last path compo-
nent of source.
-hfs-volume-name Volume name for just the HFS+ filesys-
tem if it should be different (HFS+
only).
-iso-volume-name Volume name for just the ISO9660
filesystem if it should be different
(ISO9660 only).
-joliet-volume-name Volume name for just the Joliet
filesystem if it should be different
(Joliet only).
-hide-all A glob expression of files and directo-
ries that should not be exposed in the
generated filesystems. The string may
need to be quoted to avoid shell expan-
sion, and will be passed to glob(3) for
evaluation. Although this option can-
not be used multiple times, an arbi-
trarily complex glob expression can be
used.
-hide-hfs A glob expression of files and directo-
ries that should not be exposed via the
HFS+ filesystem, although the data may
still be present for use by other
filesystems (HFS+ only).
-hide-iso A glob expression of files and directo-
ries that should not be exposed via the
ISO filesystem, although the data may
still be present for use by other
filesystems (ISO9660 only).
-hide-joliet A glob expression of files and directo-
ries that should not be exposed via the
Joliet filesystem, although the data
may still be present for use by other
filesystems (Joliet only).
-print-size Preflight the data and calculate an
upper bound on the size of the image.
The actual size of the generated image
is guaranteed to be less than or equal
to this estimate.
-plistin Instead of using command-line parame-
ters, use a standard plist from stan-
dard input to specific the parameters
of the hybrid image generation. Each
command-line option should be a key in
the dictionary, without the leading
"-", and the value should be a string
for path and string arguments, a number
for number arguments, and a boolean for
toggle options. The source argument
should use a key of "source" and the
image should use a key of "output".
If a disk image was specified for source, the image will be
attached and paths will be evaluated relative to the mount-
point of the image. No absolute paths can be used in this
case. If source is a directory, all argument paths should
point to files or directories either via an absolute path, or
via a relative path to your current working directory.
The volume name options, just like files in the filesystems,
may need to be mapped onto the legal character set for a given
filesystem or otherwise changed to obey naming restrictions.
Use drutil(1) as drutil filename myname to see how a given
string would be remapped.
The -abstract-file, -bibliography-file, -and -copyright-file
must exist directly in the source directory, not a sub-direc-
tory, and must have an 8.3 name for compatibility with ISO9660
Level 1.
compact image
scans the bands of a SPARSE type disk image with an HFS
filesystem in it, removing those parts of the image file which
are no longer being used by the filesystem. Depending on the
layout of files in the filesystem, compact may or may not
shrink the image file. Common Options: -encryption,
-stdinpass, -srcimagekey, -shadow with friends, and -plist.
info display information about DiskImages.framework, the disk image
driver, and any images that are currently attached. hdiutil
info accepts -plist.
load manually load the disk image driver. Normally, the disk image
driver is loaded by the DiskImages framework whenever needed.
As of OS X 10.2, the driver will automatically unregister
itself after the last image is detached (it will then be
unloaded after about a minute without being used again).
checksum image -type type
Calculate the specified checksum on the image data, regardless
of image type. Common options: -shadow with friends,
-encryption, -stdinpass. -srcimagekey, and -plist,
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
chpass image
change the passphrase for an encrypted image. The default is
to change the password interactively.
Common options are: -recover and -srcimagekey. The options
-oldstinpass and -newstdinpass allow, in the order specified,
the null-terminated old and new passwords to be read from the
standard input in the same manner as with -stdinpass.
unflatten image
unflatten a read-only (or compressed) UDIF disk image, creat-
ing a dual-fork file in traditional format (resource-only; no
XML). Common options: -encryption, -stdinpass, and
-srcimagekey.
flatten image
Flatten a read-only (or compressed) UDIF disk image into a
single-fork file. If the image is UDZO format and does not
contain XML meta-data for in-kernel attachment, it will be
added. Common options are: -srcimagekey, -encryption, and
-stdinpass. flatten is only required if the UDIF has previ-
ously 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 image
Print information about an HFS/HFS+ volume. As is usually the
case, image can be a /dev entry corresponding to a physical
disk. See the NOTE ON DEV ENTRY ACCESS section.
Common options are: -encryption, -stdinpass, -srcimagekey, and
-shadow with friends.
mountvol dev_name
Attempt to mount dev_name using Disk Arbitration (similar to
diskutil mount). XML output is available from -plist. Note
that mountvol (rather than mount) will remount a volume after
it has been unmounted by unmount. mount/attach can be called
on a /dev entry, but it will treat the /dev entry as a disk
image to be attached (creating another /dev entry). This is
usually undesirable.
unmount volume [-force]
unmounts a mounted volume. volume can be a full path to a
/dev entry or the name of a mountpoint.
Options:
-force unmount filesystem regardless of open files on that
filesystem. Similar to umount -f.
imageinfo image
Print out information about a disk image. Common options are:
-encryption, -stdinpass, -srcimagekey, -shadow with friends,
and -plist.
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 (i.e. ~/Library/Plug-ins/DiskImages,
/System/Library/Plug-ins/DiskImages,
/Library/Plug-ins/DiskImages,
/Network/Library/Plug-ins/DiskImages). -plist is available.
internet-enable [-yes] | -no | -query image
Enable or disable post-processing for the image. Without
arguments, IDME will be enabled. If so enabled, upon first
encounter with Disk Copy (on OS X 10.2.3+) or a browser using
the feature for a download on OS X 10.3, the image will have
its visible contents copied into the directory containing the
image and the image will be put into the trash with IDME
turned off.
Common options are: -encryption, -stdinpass, -srcimagekey, and
-plist.
resize size_spec image
Given a read/write partitioned UDIF, if the last partition is
Apple_HFS, attempt to resize the partition to the end of the
image file, or to the last used block in the embedded HFS/HFS+
file system (depending on size_spec). resize is typically used
when working with a large device image when it is desirable to
shrink the HFS/HFS+ partition before converting to CD-R/DVD-R
format. resize can also be used to grow a filesystem within
its predefined stretch limits.
hdiutil burn does not burn Apple_Free partitions at the end of
the devices, so an image with a resized filesystem can be
burned to create a CD-R/DVD-R master that contains only the
actual data in the image filesystem (assuming minimal data
fragmentation).
Common options are: -encryption, -stdinpass, -srcimagekey,
-shadow with friends, and -plist.
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
resized to and uses that value. max automat-
ically 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 (more partitions can then be
added in the new free space).
-partitiononly only resize the partition(s) in the image
(including their embedded filesystems). This
is the default for NDIF images. For a newly-
created SPUD where the partition fills the
image, the partition can only be shrunk. If
there is an Apple_Free partition after an
existing partition, that partition can be
expanded into the space marked by the
Apple_Free. Shrinking a partition results in
a larger Apple_Free partition.
-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 restored
to a hard drive 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
sizes (in 512 byte sectors) that could be
passed given possible -imageonly or
-partitiononly flags. Does not modify the
image file.
segment
segment -o firstSegname -segmentCount #segs image [opts]
segment -o firstSegname -segmentSize size image [opts]
segment a NDIF or UDIF disk image. Segmented images work
around limitations in file size which are sometimes imposed by
filesystems, network protocols, or media. Common options are:
-encryption, -stdinpass, -srcimagekey, -tgtimagekey, and
-plist.
Options:
-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 or in the
style of mkfile(8) (here unqualified numbers are
still 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. Segmenting read/write (UDRW) images is
not supported (as of OS X 10.3).
-firstSegmentSize segment_size
Specify the first segment size in sectors in the
same form as for -segmentSize. Used for multi-CD
restores.
-restricted Make restricted segments for use in multi-CD
restores.
pmap image_source [-options optstr]
display the partition map of an image or device. image_source
is either a plain file or special file (i.e. a /dev/disk
entry). See the NOTE ON DEV ENTRY ACCESS below. Common
options are: -encryption, -stdinpass, -srcimagekey, and
-shadow with friends.
optstr 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 block number
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
Verifying:
hdiutil verify myimage.img
Verifies an image against its internal checksum.
Segmenting:
hdiutil segment -segmentSize 10m -o /tmp/aseg 30m.dmg
creates aseg.dmg, aseg.002.dmgparg, and aseg.003.dmgpart
Converting:
hdiutil convert master.dmg -format UDTO -o master
Converts master.dmg to a CD-R export image, appending
.toast to the filename.
hdiutil convert CDmaster.dmg -format UDTO -o CDmaster.cdr
Converts CDmaster.dmg to a CD-R export image named
CDmaster.cdr.
hdiutil convert /dev/disk1 -format UDRW -o devimage
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 use of the block-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 disc. Volumes will be mounted after burning.
Creating a 50 MB encrypted image:
hdiutil create -encryption -size 50m e.dmg -fs HFS+J
Creating a "1 GB" sparse image (a 1 GB filesystem in a growable file):
hdiutil create -type SPARSE -size 1g -fs HFS+ growableTo1g
Creating a new mounted volume backed by an image:
hdiutil create -volname Dick -size 1.3m -fs HFS -attach Moby.dmg
Using makehybrid. Given the files:
albumlist.txt song2.wma song4.m4a song6.mp3 song8.mp3
song1.wma song3.m4a song5.mp3 song7.mp3
Create an HFS+/ISO9660/Joliet hybrid MusicBackup.iso with some common
content between filesystems. The HFS+ filesystem, typically only visible
on Macintosh systems, will not include the .wma files, but will show the
.m4a and .mp3 files. The Joliet filesystem will not show the .m4a and
.mp3 files, but will show the .wma files. The ISO9660 filesystem, typi-
cally the default filesystem for optical media on many platforms, will
only show the .mp3 files. All three filesystems will include the "album-
list.txt" files. The -hide options take glob expressions as expanded by
glob(3).
hdiutil makehybrid -o MusicBackup.iso Music -hfs -iso -joliet \
-hide-hfs 'Music/*.wma' -hide-joliet 'Music/{*.m4a,*.mp3}' \
-hide-iso 'Music/*.{wma,m4a}'
Image from folder (new-style):
hdiutil create -srcfolder mydir mydir.dmg
Image from folder (10.1-style; of historical interest):
du -s myFolder # du(1) will count resource forks
10542
hdiutil create -sectors 10642 folder # add ~1% for filesytem
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
sudo mount -u -t hfs -o perm /dev/disk1s2 /Volumes/myFolderImage
# optionally enable owners; sudo unneeded if manually mounted
ditto -rsrcFork myFolder /Volumes/myFolderImage
hdiutil detach disk1s2 # when you are all done
hdiutil convert -format UDZO -o folder.z.dmg folder.dmg # compress
Manually changing ownership settings of a read-only disk image:
hdiutil attach myimage.dmg
...
/dev/disk1s2 Apple_HFS /Volumes/myVolume
sudo mount -ur -t hfs -o perm /dev/disk1s2 /Volumes/myVolume
# what if I prefer using /sbin/mount
disktool -p disk1s2 # try 'diskutil unmount' on Panther
mkdir /Volumes/myVolume
USING PERSISTENT SPARSE IMAGES
SPARSE images (and shadow files) were originally designed for the inter-
mediate steps in the creation other images (e.g. UDZO) when final image
sizes are unknown. As of OS X 10.3, partially-updated SPARSE images are
now properly handled such that they can be safely used for persistent
storage. SPARSE images are not recommended for persistent storage on
earlier versions of the operating system. resize can resize an HFS+
filesystem within predefined stretch limits.
If more space is needed than is referenced by the hosted filesystem,
create -stretch and resize can help to grow or shrink the filesystem in
the image. compact improves the experience of using a SPARSE image for
persistent storage by reclaiming unused space in the image. Beware that
SPARSE images can enhance the effects of any fragmentation in the
filesystem.
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 are used primarily by the kernel's filesystem code.
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 (due to EACCES) 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).
Generally, the /dev/disk node is preferred for imaging devices (e.g.
convert operations), while /dev/rdisk is usable for the quick pmap or
hfsanalyze. In particular, creating a read-only image from a mounted
journaled filesystem will prevent the volume in the image from mounting
(because the journal will be permanently dirty).
COMPATIBILITY
Several new features were introduced into the DiskImages framework with
OS X 10.1 and OS X 10.2. Sparse images, encrypted images, and zlib-com-
pressed 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. There are multiple types of
sparse, shadow, and encrypted images; various keys (documented above) can
be passed to ensure the compatibility desired is achieved (at some cost
to performance and reliability).
With OS X 10.2, in-kernel attachment became possible, image meta-data
could be stored as XML, and the default Disk Copy.app "compressed" format
became 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. SPARSE
images should not be expected to be backwards compatible (mounting on
older systems than created them).
HISTORY
Originally, disk images were invented to electronically store and trans-
mit representations of floppy disks for manufacturing replication. These
images are typically referred to as 'Disk Copy 4.2' images, in reference
to the application that created these images and restored them to floppy
disks. Disk Copy 4.2 images were block for block representations 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.
NDIF (New Disk Image Format) images were developed to replace the Disk
Copy 4.2 and DART image formats, as well as provide the ability to create
images larger than a floppy disk. Additionally, compression and the
ability to attach disk images to Mac OS 9 as mass storage devices was
introduced. NDIF images were created and manipulated by Disk Copy ver-
sion 6.
UDIF (Universal Disk Image Format) device images go beyond NDIF, allowing
the creation of device images which include data that might appear on a
given mass storage device (DDM, Apple partition scheme partition map,
disk-based drivers, etc). This format allows items such as bootable CD's
to be created from an image. UDIF is a flat file format (vs. NDIF which
is a dual fork format), and is the native image format for OS X.
Raw disk images from other operating systems (e.g. .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.
WHAT'S NEW
As of Mac OS X 10.3, most Disk Copy functionality moved to Disk Utility
and a new background application DiskImageMounter attaches images for the
Finder. hdiutil features the new verbs makehybrid, compact, and chpass.
create has undergone a number of enhancements, most notably the ability
to create an image directly from a source directory. All framework
clients now use the same diskimages-helper background process for pro-
cessing images, including applications such as Safari.
SEE ALSO
authopen(1), hdid(8), diskutil(8), ditto(8), load_hdi(8), ioreg(8),
drutil(1), ufs.util(8), msdos.util(8), hfs.util(8), diskarbitrationd(8),
/usr/sbin/disktool (run with no arguments for usage),
/System/Library/CoreServices/DiskImageMounter.app.
Mac OS X 25 Jun 2002 Mac OS X
Mac OS X 10.3 - Generated Tue Jan 29 20:43:29 CST 2008