hdid(8) hdid(8)
NAME
hdid - HDI driver backing store service
SYNOPSIS
hdid [ options ] image
DESCRIPTION
Historically, hdid has been the user-level process handling the loading and decompression of disk
image data for the hard disk image (HDI) driver in the Mac OS X kernel. With Mac OS X version 10.2
and later, certain read/write images and 10.2+-generated zlib-compressed (UDZO) images attach in-ker-nel in-kernel
nel without a persistent user process.
With Mac OS X version 10.3, hdid calls the DiskImages.framework and its helpers take care of any out-of-kernel outof-kernel
of-kernel image serving duties. As of Mac OS X 10.4, hdid calls through to hdiutil attach. hdid
exists primarily for backwards compatibility. Generally, hdiutil attach should be used instead of
hdid. This man page continues to document certain DiskImages features that are not tool-specific.
The DiskImages framework supports a variety of flat-file and dual-fork image formats, including
read/write, read-only, and read-only compressed formats (which it decompresses on the fly). It auto-matically automatically
matically decodes AppleSingle and MacBinary file formats and is capable of mounting most images
directly from http:// URLs.
hdiutil detach or diskutil eject should be used to detach (aka "eject") images attached to the system
via hdid.
Beware that an image you have created and attached is considered an unknown removable device. For
HFS filesystems on such a device, being unknown to the system means that the on-disk ownership of
files and directories are initially ignored. On 10.2, the owner values were dynamically replaced
with the owner of /dev/console and the group unknown (gid 99). On 10.3, the group remains unknown,
but the owner is whoever is currently accessing the file (joe sees that he owns files when he looks
at the volume; mary sees that she owns files when she looks). Owners can be enabled for a particular
volume permanently (see disktool/"get info" in the Finder) or temporarily (see EXAMPLES section of
hdiutil(1)). Aside from whether owners are enabled, being removable means that disk arbitration will
mount any volumes with special options such as nosuid.
The error "no mountable filesystems" generally means that there is no filesystem in the image or that
any filesystem is corrupt. Unfortunately, read-only device images made from mounted journaled vol-
umes will not mount because the journal can't be replayed. It should be noted, however, that the
error was common on older systems when remotely logged in to a machine with no one logged in on con-
sole. Disk arbitration wouldn't mount removable media until the SystemUIServer process was running.
On 10.2 systems, 'disktool -c `id -u`' would allow image-based volumes to mount in such situations.
With 10.3, volumes automatically mount on non-managed systems regardless of whether anyone is logged
in on console. Image-based filesystems can also be manually mounted after attaching the image with
-nomount.
Please see the section below on setting up HTTP image servers if you plan to regularly mount images
from web servers or are wondering why a particular image isn't mounting over HTTP.
ARGUMENTS
-help show available options
-shadow [ <shadowfile> ]
Use a shadow file in conjunction with the data in the image. This 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. 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.
-readonly
Attach the image read only. Has no effect on read-only images.
-readwrite
Attach the image read/write. Has no effect on read-only (or compressed) images. Used in some
cases where a read/write image might default to being attached read-only.
-nomount
Suppress automatic mounting of any filesystems in the image. This will result in /dev entries
being created and (for non-kernel-attached images) a process in the background, but no volumes
will be mounted.
-notremovable
Make the image appear to the system as a fixed disk. A reboot will be required to cleanly
detach the image, though filesystems can be unmounted and remounted. This option requires
root access, e.g. via sudo(8).
-encryption [ <crypto method> ]
This option specifies a particular encrypted encoding. The default CEncryptedEncoding auto-
matically recognizes its images so this option should rarely be needed. Be careful what you
are asking for if the argument to -encryption comes directly before the image name on the com-
mand line.
-stdinpass
causes hdid to read a null-terminated passphrase from its standard input. ^@ (control-@) can
be typed to explicitly insert the terminator. This option is designed for automation in which
standard input would be attached to a file or pipe. -passphrase <passphrase> This option is
provided for automation purposes but is very insecure as the passphrase value will be visible
in the output of ps(1) (and thus to other users). -passphrase has been deprecated.
-imagekey <key>=<value>
Specify a key/value pair for the disk image recognition and creation system. See hdiutil(1)
for more information.
-drivekey <keyname>=<value>
Specify a key/value pair for the IOHDIXHDDrive object created (shows up in the IOKit registry
of devices which is viewable with ioreg(8)).
-section subspec
Attach a subset of the disk image. subspec is any of <offset>, <first-last>, or
<start,count>. All sector numbers are zero-based and ranges are inclusive.
-kernel
hand the image directly to the IOHDIXController module in the kernel even if this image would
not normally be sent "in-kernel." If the image cannot be attached, no attempt will be made to
attach it with a user process.
-nokernel
attach the image with a persistent process instead of attaching in-kernel, even if the default
for this type of image is to attach in-kernel. Use hdiutil(1)'s imageinfo verb to determine
if an image will default to mounting in-kernel.
-plist output a plist describing the image and system entities (dev entries, mount points, etc) that
were created as a result of attaching the given image.
-verbose
verbose output when attaching an image
-debug diagnostic output when attaching an image
-quiet Don't print out resulting /dev entries and filesystems. Also do not print any errors. hdid's
exit status will indicate whether the attach was successful.
EXAMPLES
$ hdid funstuff.img
Present funstuff.img as a device so that its filesystems can be mounted.
$ hdid master.dmg -shadow
Present master.dmg to the filesystems for potential mounting, redirecting all write operations to the
shadow file master.dmg.shadow.
$ hdid http://my.webserver.com/master.img -shadow /tmp/mastershadowfile
Present master.img to the filesystems for potential mounting, redirecting all write operations to the
shadow file mastershadowfile in /tmp. The shadow file can be on any mounted read/write filesystem --
keep in mind the consequences of using a remote filesystems (NFS, AFP) for such shadow files.
hdid -nomount ram://<sectors>
will attach a ram disk that can be mounted and used after being formatted with a newfs utility or
Disk Utility.app. A sector is 512 bytes.
A small shell script to create and mount a ram disk:
#!/bin/sh
NUMSECTORS=128000
mydev=`hdid -nomount ram://$NUMSECTORS`
newfs_hfs $mydev
mkdir /tmp/mymount
mount -t hfs $mydev /tmp/mymount
OUTPUT
Unless -plist is specified, hdid returns one line of output per /dev entry created. Each line con-
tains up to three tab-delimited columns. The first column always contains the full path to the /dev
entry created. The second column will contain the partition type if the image contained a partition
map. The third column will contain the mountpoint if the particular /dev entry was mounted.
If hdid is asked to attach an image that is already attached, it will attempt to return the usual
information for the attached image, as if it had just been attached. However, if there are unmounted
partitions on the attached image, they will not be remounted.
Mounting Images via HTTP
In addition to mounting images from local or remote mounted filesystems, one can also mount images
from HTTP servers without downloading the entire image. For flat images (UDIF images, or AppleSin-
gle/MacBinary encoded NDIF image files) mounting an image is a matter of passing the http:// URL to
hdid:
hdid http://server.company.com/Images/stuff.dmg
It should be noted that some web servers (Apache in particular) do not support byte-range requests
beyond 2 (Apache 1.x) or 4 GB (Apache 2.x) and thus image files larger than those sizes will not be
accessible over HTTP. Read/write images may attach, but will not be fully accessible. Segmented
images do work correctly over HTTP (assuming they are named properly) and can be used to work around
the file size limitation.
Browsing images via HTTP is much more pleasant if the server settings are modified to be more
friendly to highly-persistent clients. In particular for Apache, MaxKeepAliveRequests should be
increased significantly beyond 100 or set to 0 (unlimited) and KeepAliveTimeout should be boosted to
at least 30 (seconds). Increasing the number of simultaneous clients may also be desirable because
of the increased delay before clients are forcibly disconnected.
If the image to be served via HTTP is a dual fork NDIF image that is not encoded into a flat-file
format such as AppleSingle and the HTTP server is running on Mac OS X, dual fork files may be
detected and supported. Such dual-fork files must be moved or copied using the Finder, or some other
resource-fork-aware tool. Properly copied dual-fork files on a UFS volume have a ._filename file in
addition to the filename you see in the Finder (i.e. stuff.img would also have ._stuff.img in the
same directory).
In either case, one would specify the URL to the data fork, and DiskImages will determine if it is
necessary to access the secondary file.
Accessing dual fork images on HFS+ filesystems via HTTP is only supported if the HTTP server is on a
Mac OS X system. It is possible that the web server's configuration could prevent access to the
resource fork. For example, Mac OS X 10.3 security updates have disabled access to the /..namedfork/
paths necessary to access resource forks on HFS. Thus it may be necessary to tweak web server set-
tings to successfully serve dual-fork images.
While it is not directly related to mounting via hdid(1), informing your web server that '.dmg' (and
others) are extensions associated with the MIME type application/octet-stream will allow web browsers
to download the files rather than try to display them. For apache, you add the extensions to the
appropriate line in /etc/httpd/mime.types.
SEE ALSO
hdiutil(1), load_hdi(8), ditto(8), diskutil(8), diskarbitrationd(8), ioreg(8)
25 June 2002 hdid(8)
|