<sect1 id="removable-media">

  <sect1info>

    <authorgroup>

      <author>

        <firstname>Dan</firstname>

	<surname>Pelleg</surname>

	<contrib>Contributed by </contrib>

      </author>

      <!-- daniel+handbook@pelleg.org -->

    </authorgroup>

    <!-- 26 September 2003 -->

  </sect1info>

    <title>Using Removable Memory Devices</title>

      <para>Many consumer electronic devices now support removable memory

        cards.  They provide a fast and easy way to transfer information to

        and from a PC.  Here we explore the ways to use those cards under

        &os;.  Our goal is to minimize the administrative overhead for the

        user - eliminating the need for <username>root</username> access or

        manual mounts.  For simple tasks such as uploading files from the

        card we can even come up with a completely hands-off operation -

        the user doesn't have to do anything but insert the card in, wait

        for a while, and then pop it back out.</para>

      <sect2 id="cf-intro">

        <title>Introduction</title>

        <para>The discussion refers to Compact Flash (CF) cards. However,

          most of the instructions also apply, with slight modifications,

          to other types of 'flash' media (SmartMedia, MMC, MemoryStick and

          all their variations), as well as cameras, MP3 players, and other

          devices supported by the &man.umass.4 device driver.  </para>

        <para>Compact Flash cards typically interface to a PC in one of

          two ways: an external USB card-reader, or through the PC-CARD

          (also known as "PCMCIA") slot.  For the PC-CARD case, a cheap

          adapter allows insertion of CF media to a standard PC-CARD slot.

          Some laptops have a special CF slot, eliminating the need for an

          adapter.  The way &os; accesses your device will vary, depending

          on the reader type.  PC-CARD readers will show up as ATA disks,

          while USB readers will show up as SCSI disks.</para>

        <para>Once the "disks" show up, we can mount the filesystem on

          them, and then manipulate it in the standard way - copying and

          deleting files.  We explore two approaches to doing this.  The

          first involves a script that handles the specific task of

          uploading all of the new files from the CF card to the PC,

          requiring no user intervention.  The second is more general, and

          uses the automounter to mount the filesystem as soon as it is

          accessed, letting the user directly manipulate it.  </para>

        <para>To make things easy to follow, we first detail the steps

          for USB readers, and then explain how the same procedures work

          for PC-CARD devices.</para>

        </sect2>

        <sect2 id="cf-usb">

          <title>USB-Based Compact-Flash Readers</title>

            <sect3>

              <title>Requirements</title>

                <para>Support for USB readers requires the &man.umass.4

                  driver.  As the manpage tells you, you will need the

                  following options in your kernel config: </para>

                <programlisting>device usb

device ohci (OR device uhci)

device umass

device scbus

device da

device pass</programlisting>

                <para>Note that the GENERIC kernel that comes with 4.8

                  already includes them all.  After recompiling your kernel

                  (or not, if you're using GENERIC), you should be able to

                  plug the reader into the USB slot and have it show up.

                  Usually, the media has to be already in the reader before

                  you plug in the USB connector.  So, if things don't work

                  for you, unplug the reader from the USB slot, stick the

                  memory card in, and plug it into USB again.</para>

                <para>The message log will tell you the device name for

                  the CF card.  <devicename>umass</devicename>-attached

                  devices will show up like this:</para>

                <screen>da0 at umass-sim0 bus 0 target 0 lun 0</screen>

                <para>indicating that the device name is

                  <devicename>da0</devicename>.  Note that if you already

                  have SCSI devices in the system, this might interfere

                  with whatever you have in &man.fstab.5;.  To avoid nasty

                  surprises, you should wire down all of your other SCSI

                  devices so their numbering doesn't change.</para>

                <para>If the reader is supported, at this point you

                  should be able to mount the device.  If you are using a

                  card from a standard camera or music player, the

                  following command, typed as root, will mount it under

                  <filename class="directory">/mnt</filename>:</para>

                <screen>&prompt.root; <userinput>mount -t msdos /dev/da0s1 /mnt</userinput></screen>

                <para>In theory, at this point you can become

                  <username>root</username> whenever you want and

                  <command>mount</command> the device.  However the goal

                  here is to try and avoid this step.  The following

                  section and <xref linkend="cf-automount"> describe two

                  different strategies that accomplish this.</para>

              </sect3>

              <sect3>

                <title>Using an upload script</title>

                <para>Most often, the computer is used as a backing store

                  for the small-capacity CF card.  You take a few photos on

                  your digital camera, and want to make sure you have

                  copied them to a "real" disk so you can later process

                  them.  We use a script that uploads all the new photos

                  from a CF card into the PC's disk-drive.  Once installed,

                  it will go into action as soon as the CF media is

                  attached.  It will <command>mount</command> the

                  filesystem, copy the new files over, and then unmount it.

                  The only thing the user has to do is insert the media and

                  later pull it out.</para>

                <para>You can <link linkend="cf-script">download a copy of the

                  script</link>.  We assume you have it installed at

                  <filename>/usr/local/sbin/copy-flash</filename> and

                  marked it as executable.</para>

                <para>Next, you will need the USB daemon, &man.usbd.8;.

                  Add this line to <filename>/etc/rc.conf</filename>,

                  unless it's already there:</para>

                <programlisting>usbd_enable="YES"</programlisting>

                <para>To make the script run when a USB reader is

                  attached, add an entry to

                  <filename>/etc/usbd.conf</filename>.  It will look like

                  this:</para>

                <programlisting>device "CF card"

devname "umass[0-9]+"

attach "/usr/local/sbin/copy-flash da0 /tmp/cf <replaceable>CFOWNER</replaceable>"</programlisting>

                <para>where <devicename>da0</devicename> should be

                  substituted by whatever device you see in the message

                  log.  Before you use this hook, replace the string

                  CFOWNER.  It should be a user name, and the copied files

                  will be owned by that user.  This is normally you or the

                  primary user of the machine.  Also, create the target

                  directory into which the files will be copied.  In this

                  example it is <filename

                  class="directory">/tmp/cf</filename>.  Make sure you

                  choose a partition that is big enough to contain all the

                  files you plan on using.  Finally, don't forget to kill

                  and restart <command>usbd</command>.</para>

                <para>The provided script will also sound a short melody

                  once the copying is done.  This lets you know it is safe

                  to pull out the CF card.  If you don't hear it, add the

                  &man.spkr.4 psuedo-device to your kernel.</para>

              </sect3>

            </sect2>

            <sect2 id="cf-pccard">

              <title>PC-CARD readers</title>

                <para>This section repeats the previous one, this time

                  explaining how to make a PC-CARD slot (or a dedicated CF

                  slot) work.</para>

              <sect3>

                <title>Requirements</title>

                  <para>Compared to USB readers, PC-CARD readers are

                    simpler.  They only require the &man.pccardd.8 daemon

                    to run.  In all likelihood, you already have it.  If

                    not, add the following line to

                    <filename>/etc/rc.conf</filename>:</para>

                  <programlisting>pccard_enable="YES"</programlisting>

                  <para>Again, the message log will tell us the name of

                    the device.  For example, one

                    <command>pccardd</command>-attached device shows up

                    as:</para>

                    <screen>ad8: 124MB &lt;SAMSUNG CF/ATA&gt; [496/16/32] at ata4-master BIOSPIO</screen>

                    <para>indicating that the device is <devicename>ad8</devicename>.</para>

              </sect3>

              <sect3>

                <title>Using an upload script</title>

                  <para>The <link linkend="cf-script">same script as

                    above</link> can be used for PC-CARD readers.  The only

                    difference is what runs it - in this case, it is

                    <command>pccardd</command> instead of

                    <command>usbd</command>.  Add this entry to

                    <filename>/etc/pccardd.conf</filename> (create the file

                    if it doesn't exist on your system):</para>

                    <programlisting># GENERIC Flash ATA / ATA HDD

	generic fixed_disk

		config  0x1 "ata" ?

		insert /usr/local/sbin/copy-flash $device /tmp/cf <replaceable>CFOWNER</replaceable>

		logstr  "GENERIC Flash ATA / ATA HDD"</programlisting>

                  <para>Again, change CFOWNER to the name of the user you

                    want to have access to the files.</para>

              </sect3>

            </sect2>

            <sect2 id="cf-automount">

              <title>Using the automounter</title>

                <para>Much of the information in this section is from a

                  <ulink url="http://www.daemonnews.org/200202/automounting.html">

                  Dæmon News article by Renaud Waldura </ulink>.  The

                  automounter can mount filesystems automatically whenever

                  they are accessed.  That is, you simply

                  <command>ls</command> or <command>cd</command> to a

                  directory that represents a filesystem, and the

                  automounter intercepts the operation, and makes sure the

                  underlying filesystem is mounted.  It is typically used

                  for managing NFS mounts, but here we use it for local

                  mounts.</para>

                <para>Add these lines to <filename>/etc/amd.map</filename>:</para>

                <programlisting>localhost		type:=auto;fs:=${map};pref:=${key}/

localhost/cf            type:=program;fs:=/mnt/cf;\

    mount:="/sbin/mount mount /mnt/cf";\

    unmount:="/sbin/umount umount /mnt/cf"</programlisting>

                <para>Next, add a line for the filesystem in

                  <filename>/etc/fstab</filename>.  It will look like this,

                  assuming that in your system the reader appears as the

                  device <filename>/dev/ad8</filename>:</para>

<programlisting>/dev/ad8s1  /mnt/cf  msdos  rw,noauto  0  0</programlisting>

                <para>Note that we specify the first slice on the disk,

                  and the <option>msdos</option> filesystem.  Many digital

                  cameras expect their CF cards to be configured in this

                  way.  We also need to create the mount point:</para>

                  <screen>&prompt.root; <userinput>mkdir -p /mnt/cf</userinput></screen>

                <para>To enable the automounter, add this line to

                  <filename>/etc/rc.conf</filename>:</para>

                <programlisting>portmap_enable=YES

amd_enable="YES"

amd_flags="-a /.amd_mnt -l syslog /host /etc/amd.map"</programlisting>

                <para>Once you start <command>amd</command> (or reboot),

                  any user should be able to access the CF card, simply by

                  doing a <command>ls</command> or <command>cd</command> on

                  the directory <filename

                  class="directory">/host/localhost/cf</filename></para>

                <para>Remember that <command>amd</command> only unmounts

                  the filesystem after it has been idle for some time.

                  This means that before you take the CF card out of the

                  slot, you need to stop using it (remembering to

                  <command>cd</command> out of any directories on it), and

                  wait.  Pulling out a mounted device can cause all kinds

                  of trouble, including data loss and system crashes.  So

                  you want to make sure you unmount first.  If you're in a

                  hurry and can't wait for <command>amd</command> to time

                  out, you can ask it to unmount the filesystem immediately

                  by doing:</para>

<screen>&prompt.user; <userinput>amq -u /host/localhost/cf</userinput></screen>

                <para>This, again, is not a privileged operation and does

                  not require <username>root</username> access.</para>

            </sect2>

            <sect2 id="cf-summary">

              <title>Summary</title>

                <para>We eliminated the need for root access to read and

                  write files stored on CF media.  We can let the

                  automounter do the mounting for us, or have a script that

                  does all the copying as well.  In fact, both of these

                  solutions can co-exist: whenever media is inserted, new

                  files are immediately copied over.  If the user later

                  wants to access the card and, say, delete some files,

                  they can do that and <command>amd</command> will take

                  care of mounting.</para>

                <para>Once you start using the file-copy script, you will

                  probably discover that managing multiple copies of the

                  same data is hard.  The original photo is kept on the CF

                  card, the script makes another one on your local disk,

                  and you will also probably make a final copy in your

                  electronic album.  To make room and reduce clutter, you

                  will want to delete redundant copies.  It is often

                  easiest to do this on the PC where you can easily view

                  the photos on a big screen.  The problem is, the files

                  will re-appear the next time you pop the CF card in.  One

                  solution is to wipe the CF card clean every time you

                  insert it.  But it is wiser to give the good photos

                  another chance, just in case they get lost.  A trick I

                  find useful is to create a text file in the directory

                  which stores the files from the CF card, and in that file

                  I record the name of each file that I delete from the PC

                  copy.  This way, I can also quickly delete the same files

                  from the CF card whenever it fills up.</para>

            </sect2>

            <sect2>

              <title>Acknowledgments</title>

              <para>Scott Mitchell provided greatly valuable help for

                this article.  Thanks to Joshua Schachter and Nadav

                Eiron.</para>

            </sect2>

            <sect2 id="cf-script">

              <title>Helper Script for Copying Files from CF Card</title>

                <programlisting>#!/bin/sh

# Dan Pelleg, March 2003

#

# copy-flash: mount a compact-flash card, copy the contents over, unmount

# usage: copy-flash [flash-device] [target-dir] [user]

dev=${1:-da6}

tgt=${2:-/tmp/foo}

user=${3:-root}

[ -e "$tgt" ] || mkdir -p $tgt && chown $user $tgt

[ -e /mnt/cf ] || mkdir -p /mnt/cf

# figure out if we were called with a device like ad8 or ata4. If it's

# the latter, figure out the usable device name

case ${dev} in

    ata* )

        channel=${dev##ata}

        if [ -n ${channel} ]; then

            realdev=$(atacontrol info $channel | grep ^Master | cut -d " " -f 3)

        fi

    ;;

    ad* | da* )

        realdev=${dev}

    ;;

esac

if [ -n "${realdev}" ]; then

    # on -CURRENT we might need to wait a bit before the device node appears

    if [ ! -e /dev/${realdev} ]; then

        sleep 5

    fi

    # if the slice doesn't yet exist, try to nudge

    # things so it does. Might be necessary for some devices

    # on -CURRENT

    # This mount is not supposed to succeed, but it does

    # sometime cause the device node to be created.

    if [ ! -e /dev/${realdev}s1 ]; then

        mount -t msdos /dev/${realdev} /mnt/cf && umount /mnt/cf

    fi

    mount -t msdos /dev/${realdev}s1 /mnt/cf && \

    su ${user} -c "cp -nRp /mnt/cf/ ${tgt}" ; \

    # play a tune to let the user know it's all over

    umount /mnt/cf && echo "MLT250o3fc" > /dev/speaker

fi</programlisting>

            </sect2>

  </sect1>