The Linux Kernel contains both generic USB interface drivers and higher level USB device drivers for some devices like USB mice or USB thumb drivers. The generic interface drivers can be used from user space applications to connect to USB devices not specifically supported by the kernel itself. Any application using libgphoto2 is an example of such a user space application.

Unfortunately, for some devices there are drivers both in the kernel and in libgphoto2, creating a conflict situation. If that happens with your device and you want to use libgphoto2 instead of the kernel driver, you may have a problem. In later kernels and current libusb versions , libgphoto2 will try to unload the kernel driver for the interface as soon as libgphoto2 wants to claim the device. On older kernels, you need to prevent the kernel from loading its kernel space driver in some fashion.

Hotplugging of devices is a central feature of USB, and thus the Linux Kernel's USB system must also handle the addition of new devices at run-time. Over the course of time, multiple solutions for this have been invented: linux-hotplug (kernels 2.4), udev (kernel 2.6), and nowadays HAL (which provides complete desktop integration). The basic mechanism is the same: When the Kernel notices that a new USB device has been plugged in (or switched on), it runs a program. That program can then walk through its configured set of rules and apply them to the new device.

This section describes how to set up USB device permissions using HAL. Due to this article's author's cluelessness about HAL, it just describes the HAL setup provided by the Fedora Core 6 (FC6) gphoto2 RPM package.

The libgphoto2 specific part of the HAL configuration consists of two parts: The device list and a policy. Each is stored in its own file.

The device list file contains a list of all devices supported by libgphoto2 in any fashion and giving HAL information as to the device's capabilities. You can generate this file using the print-camera-list utility shipped with libgphoto2:

host:~# /usr/lib/libgphoto2/print-camera-list hal-fdi > libgphoto2.fdi

The FC6 gphoto2 package stores this file as /usr/share/hal/fdi/information/20thirdparty/10-camera-libgphoto2.fdi. Its content looks like:

<?xml version="1.0" encoding="ISO-8859-1"?> <!-- -*- SGML -*- -->
<!-- This file was generated by libgphoto2 print-camera-list - - fdi -->
<deviceinfo version="0.2">
 <device>
  <match key="info.bus" string="usb">
   <match key="usb.vendor_id" int="1363">
    <match key="usb.product_id" int="514">
     <merge key="info.category" type="string">camera</merge>
     <append key="info.capabilities" type="strlist">camera</append>
     <merge key="camera.access_method" type="string">proprietary</merge>
     <merge key="camera.libgphoto2.name" type="string">AEG Snap 300</merge>
     <merge key="camera.libgphoto2.support" type="bool">true</merge>
    </match>
   </match>
     ...
   <match key="usb.vendor_id" int="10096">
    <match key="usb.product_id" int="36956">
     <merge key="info.category" type="string">camera</merge>
     <append key="info.capabilities" type="strlist">camera</append>
     <merge key="camera.access_method" type="string">proprietary</merge>
     <merge key="camera.libgphoto2.name" type="string">Vivitar Vivicam35</merge>
     <merge key="camera.libgphoto2.support" type="bool">true</merge>
    </match>
   </match>
  </match>
 </device>
</deviceinfo>

Note that FC6's hal RPM already ships the following /usr/share/hal/fdi/information/10freedesktop/10-camera-ptp.fdi file which matches all PTP class cameras, so their being missing in the device list file generated by print-camera-list does not matter:

<?xml version="1.0" encoding="UTF-8"?>
<deviceinfo version="0.2">
  <device>
    <match key="info.bus" string="usb">
      <match key="usb.interface.class" int="0x06">
        <match key="usb.interface.subclass" int="0x01">
          <match key="usb.interface.protocol" int="0x01">
            <merge key="info.category" type="string">camera</merge>
	    <append key="info.capabilities" type="strlist">camera</append>
            <merge key="camera.access_method" type="string">ptp</merge>
          </match>
        </match>
      </match>
    </match>
  </device>
</deviceinfo>

The policy file defines what HAL is to do with devices which have a "camera" capability. The FC6 gphoto2 package stores the policy file as /usr/share/hal/fdi/policy/20thirdparty/90-gphoto-camera-policy.fdi. It just calls a script, as the content shows:

<?xml version="1.0" encoding="UTF-8"?> <!-- -*- SGML -*- --> 
<deviceinfo version="0.2">
  <device>
    <match key="info.capabilities" contains="camera">
      <match key="camera.access_method" string="proprietary">
        <append key="info.callouts.add" type="strlist">/usr/libexec/gphoto-set-procperm</append>
      </match>
      <match key="camera.access_method" string="ptp">
        <append key="info.callouts.add" type="strlist">/usr/libexec/gphoto-set-procperm</append>
      </match>
    </match>
  </device>
</deviceinfo>

The FC6 gphoto2 package stores the permission setup script as /usr/libexec/gphoto-set-procperm. It uses printf(1) to construct the name of the device file from USB bus and device numbers given by HAL, waits a few seconds to make sure the device file actually exists, and then finally hands ownership of the device file to the pam_console user:

#!/bin/bash

console_user=`cat /var/run/console/console.lock` 

if [ -z "$console_user" ] ; then
  exit 1 
fi

if [ -z "$HAL_PROP_USB_BUS_NUMBER" -o -z "$HAL_PROP_USB_LINUX_DEVICE_NUMBER" ] ; then
  exit 2 
fi

if [ $HAL_PROP_USB_BUS_NUMBER -lt 0 -o  $HAL_PROP_USB_LINUX_DEVICE_NUMBER -lt 0 ] ; then
  exit 3 
fi

bus_num=`printf %.3u $HAL_PROP_USB_BUS_NUMBER`
dev_num=`printf %.3u $HAL_PROP_USB_LINUX_DEVICE_NUMBER`

NUM_TRIES_LEFT=5
while [ $NUM_TRIES_LEFT -ge 0 ] && [ ! -c /dev/bus/usb/$bus_num/$dev_num ]; do
        sleep 1
        NUM_TRIES_LEFT=$(($NUM_TRIES_LEFT - 1))
done
[ -c /dev/bus/usb/$bus_num/$dev_num ] || exit 4

chown $console_user /dev/bus/usb/$bus_num/$dev_num 

NUM_TRIES_LEFT=5
while [ $NUM_TRIES_LEFT -ge 0 ] && [ ! -f /proc/bus/usb/$bus_num/$dev_num ]; do
        sleep 1
        NUM_TRIES_LEFT=$(($NUM_TRIES_LEFT - 1))
done
[ -f /proc/bus/usb/$bus_num/$dev_num ] || exit 5

chown $console_user /proc/bus/usb/$bus_num/$dev_num

udev is the mechanism called by Linux Kernel 2.6 to add and remove device files in /dev. udev is an integral part of the system, and thus installed directly in /, not in /usr/. This means that helper programs and scripts are installed in /lib/udev/, and the udev rules are stored in /etc/udev/rules.d/.

There are multiple versions of udev around with slightly different rule formats, so libgphoto2's /usr/lib/libgphoto2/print-camera supports a version argument.

# call script /lib/udev/foobar
host:~# /usr/lib/libgphoto2/print-camera-list \
    udev-rules version 0.98 script foobar \
    > /etc/udev/rules.d/90-libgphoto2.rules

# call script /path/to/foobar
host:~# /usr/lib/libgphoto2/print-camera-list \
    udev-rules version 0.98 script /path/to/foobar \
    > /etc/udev/rules.d/90-libgphoto2.rules

# set up permissions with "chmod 0660 $device; chgrp plugdev $device"
host:~# /usr/lib/libgphoto2/print-camera-list \
    udev-rules version 0.98 group plugdev mode 0660 \
    > /etc/udev/rules.d/90-libgphoto2.rules
	

These udev rule files contain two sorts of matches: Lots of listings by USB VendorID/ProductID, and one special case each for matching PTP and MTP devices. These two special cases run special scripts/programs, which should also be installed in /lib/udev/.

#!/bin/sh
# UNTESTED SCRIPT (but you get the idea)

test "x$ACTION" != "xadd" || exit 0
test "x$SUBSYSTEM" != "xusb_device" || exit 0

if test -e "$DEVNAME"
then
  user="photoripper"
  chown "$user" "$DEVNAME"
  chmod 0600 "$DEVNAME"

  # SUBSYSTEM == "usb_device" implies that DEVNAME == "/dev/bus/usb/123/456"
  # Determine device ID and bus ID.
  dev="$(basename "$DEVNAME")"
  bus="$(basename "$(dirname "$DEVNAME")")"

  # Download all files from that camera to incoming directory with
  # lowercase filenames
  command="/usr/bin/gphoto2 --port usb:${bus},${dev} --get-all-files"
  command="$command --filename /var/local/photodump/incoming/%:"
  echo "Executing command: $command"
  su "$photoripper" -c "$command"
else
  echo "photoripper: Given device named $DEVNAME not found."
  exit 1
fi

linux-hotplug was the first solution for hooks to run when hotplugging devices, introduced with the 2.4 kernel's USB code.

linux-hotplug stores its files in pairs: One file /etc/hotplug/usb/usbcam.usermap is a list of device descriptions, and the other /etc/hotplug/usb/usbcam is a script to call in case a newly added device matches that description.

libgphoto2 supports linux-hotplug via a device list generated using print-camera-list and a few example scripts shipped in packaging/linux-hotplug/.

host:~# /usr/lib/libgphoto2/print-camera-list usb-usermap \
    > /etc/hotplug/usb/usbcam.usermap

In ancient times, before the arrival of udev, one usually needed to mount the "usbdevfs" or later "usbfs" to /proc/bus/usb. One particular mount option allowed the whole usb filesystem (i.e. all mice, card readers, and all other USB devices) to be made group or world writeable.

Obviously, this kind of “security” is no security and should thus be avoided. Additionally, since udev exists now, just use udev. You can look up how to shoot yourself in the foot with usbdevfs... where? Well, just use udev. After all, this is almost the year 2007, not 1997.

libgphoto2 provides a user space driver for cameras, which conflicts with having a kernel driver for the camera. So in order to use libgphoto2, you have to disable all kernel drivers which want to handle the camera themselves (e.g. the Linux dc2xx or stv680 drivers). You can check whether these modules are loaded by executing lsmod.

We will not cover basic USB setup in detail here. For more information on how to get USB working on your hardware and your system at all, we'd like to refer you to http://www.linux-usb.org/USB-guide/ and especially http://www.linux-usb.org/USB-guide/c122.html . These pages explains the USB basics in a better way than we could do.

Now that you've got your basic USB system working, you have basically two options to allow user access to USB devices on your Linux system:

Solution b has a huge advantage over solution a: It doesn't allow the user/group to interfere with or eavesdrop on any other USB devices which might be attached, such as USB keyboards, fingerprint reader or similar. The following section thus describe setting up b.

On Linux systems, from the 2.4 kernel series on, the kernel supports hotplugging. You may have to compile a kernel with hotplug support if you're not already running one. You may have to install the hotplug package (http://linux-hotplug.sourceforge.net/) if you don't have it installed already.

Note (TODO).  print-usb-usermap is deprecated as of 2.1.99.1. Use print-camera-list instead. Description of udev rules and HAL setup missing here.

To find out whether your kernel has hotplug support, look for the file /proc/sys/kernel/hotplug. If it exists, your kernel is hotplug enabled. If

alice@host:~$ cat /proc/sys/kernel/hotplug
          

prints the path to your hotplug binary (usually /sbin/hotplug) and this binary exists, you are ready to rock.

Also note that the following solution does not provide absolute security and that you should definitely know the security implications of the respective usbcam script you are going to use.

FreeBSD uses a dynamically created devices filesystem (devfs). In order to use the camera as non-root user, you need to tell the devfs framework what permissions it is to use when it dynamically creates these USB devices.

Follow the following steps as the root user to grant write access for the group usb to USB devices.

Your system should be all set up now. Now you can test it as your normal non-root user:

FIXME for the FreeBSD instructions:

FIXME: This chapter still is to be written. If you know about USB on these systems and/or are willing to contribute text or hints, please contact the developers at [ gphoto minus devel at lists dot sourceforge dot net ].