# Troubleshooting and debugging

If something doesn't work, please contact us on the opensc-users mailing lists. For details, please see MailingList?.

If you subscribe to these mailing lists you can post directly, if not a moderator will review your posting first, so we can filter spam.

So here are some step by step instructions to find your problem:

If you try to use a USB device, please try this:

- Is your /proc filesystem mounted? ls /proc will show some files and directories.
- Is your linux kernel compiled with usb support? Does it work? "lsusb" should list your usb controller and all devices.
- Is your linux kernel compiled with hotplugging support? cat /proc/sys/kernel/hotplug should output "/sbin/hotplug".
- Do you have a hotplug script? ls /sbin/hotplug will list it or print an error message?
- Did you create the directory /var/run/openct? What files are in there? What are the file permissions? ls -la /var/run/openct will tell you.

Note that recently some linux distributions changed the hotplug system:

- The kernel still needs to be compiled with CONFIG_HOTPLUG but "cat /proc/sys/kernel/hotplug" will not show anything.
- The system is no longer using the hotplug scripts. Instead it is using either udev or udev with hald.
- /proc/bus/usb might be empty. Instead the usb devices might show up in /dev/bus/usb.

In all cases:

- Did you install the openct init.d script? Did you run it?
- Does openct-tool list show your reader?

If you are using a usb smart card reader, and openct-tool does not list it: What is that readers USB vendor and product id? lsusb will tell you. Edit /etc/openct.conf and /etc/hotplug/usb/openct.usermap, check if that entry is listed, and add it if not. If the reader works after doing this, please contact opensc-devel@…, so we can add that id to OpenCT.

## USB / Linux Kernel "feature"

This has been fixed in OpenCT 0.6.7 or even earlier.

We found a problem with the linux kernel. If you plugin your usb token/reader/device and it sometimes works well, and it sometimes does not work well, and if syslog has an error message that open() failed: we were too fast, the kernel was not yet ready to allow us to use the device. Please edit /etc/hotplug/usb/openct and replace

    #!/bin/sh

    test "$ACTION" = "add" || exit 0

    if [ -e /var/run/openct/status ]
    then
            /usr/sbin/openct-control attach $DEVICE usb:$PRODUCT
    fi

with

    #!/bin/sh

    test "$ACTION" = "add" || exit 0

    if [ -e /var/run/openct/status ]
    then
            sleep 1
            /usr/sbin/openct-control attach $DEVICE usb:$PRODUCT
    fi

(i.e. add the line "sleep 1" before the "openct-control" line.)

For reference: hotplug-devel mailing list, 2005-06-14 http://sourceforge.net/mailarchive/message.php?msg_id=12059902 and the response by Kay Sievers.

## Debugging Hotplug

For many users the hotplug system on linux doesn't work as expected. Here are some tips how to debug it.

Your linux kernel needs to be compiled with CONFIG_HOTPLUG.

    cat /proc/sys/kernel/hotplug

will tell you if your kernel does hotplugging.

You can install a test script to see if it works as advertised:

    cat > /root/testplug <<EOF
    #!/bin/bash

    (echo \$0: \$*; export; echo) >> /root/testplug.log
    EOF
    chmod +x /root/testplug
    echo /root/testplug > /proc/sys/kernel/hotplug

With this change you will generate a log file for all hotplug events. A typical log file entry for adding atoken looks like this:

    /root/testplug: usb
    declare -x ACTION="add"
    declare -x DEVPATH="/devices/pci0000:00/0000:00:1d.1/usb3/3-2"
    declare -x HOME="/"
    declare -x OLDPWD
    declare -x PATH="/sbin:/bin:/usr/sbin:/usr/bin"
    declare -x PHYSDEVBUS="usb"
    declare -x PHYSDEVDRIVER="usb"
    declare -x PWD="/"
    declare -x SEQNUM="2398"
    declare -x SHLVL="1"
    declare -x SUBSYSTEM="usb"

    /root/testplug: usb
    declare -x ACTION="add"
    declare -x DEVICE="/proc/bus/usb/003/063"
    declare -x DEVPATH="/devices/pci0000:00/0000:00:1d.1/usb3/3-2/3-2:1.0"
    declare -x HOME="/"
    declare -x OLDPWD
    declare -x PATH="/sbin:/bin:/usr/sbin:/usr/bin"
    declare -x PHYSDEVBUS="usb"
    declare -x PRODUCT="973/1/100"
    declare -x PWD="/"
    declare -x SEQNUM="2399"
    declare -x SHLVL="1"
    declare -x SUBSYSTEM="usb"
    declare -x TYPE="255/0/0"

You can ignore the first entry, only those of subsystem "usb" and ACTION="add" are important.

You can test the hotplug scripts on your system like this:

    /root/testplug: usb
    export ACTION="add"
    export DEVICE="/proc/bus/usb/003/063"
    export DEVPATH="/devices/pci0000:00/0000:00:1d.1/usb3/3-2/3-2:1.0"
    export PHYSDEVBUS="usb"
    export PRODUCT="973/1/100"
    export SUBSYSTEM="usb"
    export TYPE="255/0/0"
    sh -x /sbin/hotplug add 2>&1 |tee hotplug.log

You only need those environment settings, but please change DEVICE and DEVPATH and PRODUCT to match your last log file entry. Not that if you remove and add a usb device, the DEVICE entry will change. This will start the hotplug scripts as usual, but using "sh -x" you can see what the shell script does.

If no other software needs hotplugging, here is the fastest way to make sure it works with openct:

    echo /etc/hotplug/usb/openct > /proc/sys/kernel/hotplug

## Debugging OpenCT

But if you are writing a new driver or you have some device and you are not sure whether it works, you might want to debug openct directly.

First you need to start the init script and make sure that /var/run/opensc/status does exist.

Second add your device. If hotplug does not work or the ifdhandler dies that is ok. Use lsbusb to find out which controller your usb device is attached to and what the device number is. Also you need to check if you have usb devices in /dev/bus/usb/ or in /proc/bus/usb/.

Third start ifdhandler yourself as root. Here is an example for usb controller 002 and device 005 and the ccid driver:

    ifdhandler -FHddddd ccid /dev/bus/usb/002/005

In this example:

- "-F" tells ifdhandler to stay in foreground and write errors to stdout/stderror.
- "-H" tells ifdhandler this is a hotplug device, it could vanish any second.
- "-d" increases the debug level. 5 or 6 is usualy nice for debugging usb transactions.
- "ccid" is the name of the driver. Make sure you use the right one, in doubt ask on the list.
- "/dev/bus/usb/002/005" is the device file. Ifdhandler will open it and use ioctl() on it for sending and receiving usb packets.

If you have any trouble, please contact us via our mailing lists (see MailingLists).