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-kernel 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 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 DiskIm-
       ages 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 com-
       pressed formats (which it decompresses on the fly).   It  automatically
       decodes AppleSingle and MacBinary file formats and is capable of mount-
       ing 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.   Unfortu-
       nately,  read-only  device  images  made from mounted journaled volumes
       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 console.  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, vol-
       umes 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 [  ]
              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  writ-
              ten,  the  writes will be redirected to the shadow file.  If not
              specified,  -shadow  defaults  to  .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-ker-
              nel-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  [    ]
              This option specifies  a  particular  encrypted  encoding.   The
              default  CEncryptedEncoding  automatically 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 command line.

       -stdinpass
              causes hdid to read a null-terminated passphrase from its  stan-
              dard  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
               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 =
              Specify a key/value pair for the disk image recognition and cre-
              ation system.  See hdiutil(1) for more information.

       -drivekey =
              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  ,
              ,  or  .   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-ker-
              nel."  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, redirect-
       ing all write operations to the shadow file master.dmg.shadow.
              $ hdid http://my.webserver.com/master.img  -shadow  /tmp/master-
              shadowfile

       Present master.img to the filesystems for potential mounting, redirect-
       ing 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://

       will attach a ram disk that can be mounted and used after being format-
       ted 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 contains up to three tab-delimited columns.
       The first column always contains the full path to the /dev  entry  cre-
       ated.   The  second column will contain the partition type if the image
       contained a partition map.  The third column will  contain  the  mount-
       point 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  filesys-
       tems,  one  can also mount images from HTTP servers without downloading
       the entire image.  For flat images (UDIF images, or  AppleSingle/MacBi-
       nary 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 acces-
       sible.  Segmented images do work correctly over HTTP (assuming they are
       named  properly)  and  can be used to work around the file size limita-
       tion.

       Browsing images via HTTP is much more pleasant if the  server  settings
       are modified to be more friendly to highly-persistent clients.  In par-
       ticular for Apache, MaxKeepAliveRequests should be  increased  signifi-
       cantly  beyond  100 or set to 0 (unlimited) and KeepAliveTimeout should
       be boosted to at least 30 (seconds).  Increasing the number of simulta-
       neous  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 sup-
       ported.  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 file-
       name 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 DiskIm-
       ages will determine if it is necessary to access the secondary file.

       Accessing dual fork images on HFS+ filesystems via HTTP  is  only  sup-
       ported 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 settings 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 down-
       load  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)