
Installation instructions for Aladdin key driver and daemon
==============================================================

In order for the hardware key access to work, a kernel mode driver
(aksparlnx.o) and a daemon (aksusbd) have to be loaded.

All described actions should be executed as root.


Driver Installation (aksparlnx.o)
---------------------------------

Generating the Device Node

For the driver to be accessible, a /dev/Hardlock device node has to be
generated. It should use the same major number as is used when loading
the driver (major=xxx command line to insmod, or 42 default).

The device node is generated with the following command:

	mknod /dev/Hardlock c 42 0

Allow everyone to access the node:

	chmod 666 /dev/Hardlock

Alternatively, if the access to Aladdin keys should be restricted to a
special group of users (e.g. group aladdin): 

	chgrp aladdin /dev/Hardlock
	chmod 660 /dev/Hardlock


Initializing the Parport System

The aksparlnx driver uses the Linux parport driver in order to get
access to the parallel port in a manner which does not disturb other
users of the parallel port (e.g. printer, zip drive).

So before loading the aksparlnx driver the parport system must be
initialized:

	modprobe parport_pc

The parport driver will report in the system log the parallel ports it
has found in the system. aksparlnx will by default be able to access
keys on any of these ports.


Loading the Driver

Then the aksparlnx driver should be loaded with the command:

	insmod <path_to_driver>/aksparlnx.o

If the driver successfully loaded, a system log message is generated:

	Feb  2 12:16:01 panther kernel: aksparlnx: EYE/HASP driver v1.01/API v3.77/major 42 loaded (ppi) 

If the driver fails to load, an error message is generated in the
system log.

The loading of the driver (modprobe and insmod) should be incorporated
into a startup script, so that on subsequent system boots the driver
is readily available.


Aladdin daemon (aksusbd)
------------------------

In order for the daemon to access USB keys, the so-called usbdevfs
must be mounted on /proc/bus/usb.
On newer distributions it is mounted automatically (e.g SuSe 7.0). It
can be manually mounted with the command

	mount -t usbdevfs none /proc/bus/usb

In order for the daemon to access parallel port keys, the kernel
driver aksparlnx must be installed before starting aksusbd. 

Load the daemon by starting it:

	<path>/aksusbd

The daemon will fork and put itself into the background. Successful
installation can be verified in the syslog:

	Feb  2 12:42:43 panther aksusbd:[21772]: loaded, daemon version: 1.00, key API (USB) version: 3.77, key API (parallel) version: 3.77 

It reports its version, the version of the API used for USB, and the
version of the API inside the kernel driver (for parallel port keys).

If the kernel driver happens to be unavailable when aksusbd is
launched, parallel port keys cannot be accessed, but USB keys are
still accessible. The system log reflects this status:  

	Feb  2 12:46:11 panther aksusbd:[21789]: loaded, daemon version: 1.00, key API (USB) version: 3.77 (parallel driver not available)

If /proc/bus/usb is not mounted when launching aksusbd, the daemon
does not load:

	Feb  2 12:52:05 panther aksusbd:[21804]: cannot open /proc/bus/usb/devices: No such file or directory

Preferably the daemon should be started at system boot up time with
some script located in /etc/rc.d/init.d or /etc/init.d (depending on
Linux distribution).


Options for aksparlnx.o
-----------------------

    Types of diagnostic messages: 
    -----------------------------
    You can use the switch loglevel to select which types of diagnostic 
    will be issued by the driver. Possible values are:
	 
	 0 - nothing, only errors
	 1 - normal (default)
	 2 - verbose
	 3 - ultra verbose
    
    The messages are logged in syslog with priority kern.info 
    (and kern.debug). Refer to /etc/syslog.conf to see where the messages 
    will be put, usally it is the file /var/log/messages.

    e.g.
		insmod aksparlnx.o loglevel=2
 
    
    Change device major number:
    ---------------------------
    The driver uses device major number 42 by default. You can 
    change this by giving an argument to the insmod command:
    
		insmod aksparlnx.o major=123
    
    You have to change the driver special file also:
    
		mknod /dev/Hardlock c 123 0

    
    Port addresses:
    ---------------
    If you have a parallel port in the system which by chance isn't
    detected by the Linux parport driver (and therefore not seen by
    aksparlnx.o), you can tell aksparlnx.o of the existence of this
    port:

		insmod aksparlnx.o hlportaddress=0x278

    BEWARE: You should know what you do! Giving an illegal port
    address here may reliably crash the system!

    
    Timeout:
    --------
    You can specify the maximum amount of time the driver waits when 
    requesting exclusive port access from the parport driver. The value
    used is 1/100 of a second. The default value is 100 (= 1 second).
    
		insmod aksparlnx.o timeout=200
    
    After this time (in this example 2 seconds) the request will be 
    aborted with a PORT_BUSY error. 



Options for aksusbd
-------------------

    Types of diagnostic messages: 
    -----------------------------
    You can use the switch loglevel to select which types of diagnostic 
    will be issued by the daemon. Possible values are:
	 
	 0 - nothing, only errors
	 1 - normal (default)
	 2 - verbose
	 3 - ultra verbose
    
    The messages are logged in syslog with priority kern.info 
    (and kern.debug). Refer to /etc/syslog.conf to see where the messages 
    will be put, usally it is the file /var/log/messages.

    e.g.
		aksusbd -l 2
 

    Permissions:
    ------------
    The Unix domain socket /tmp/.aksusb is used by the applications to
    access aksusbd. This is created with permissions 666 by
    default. You can tell aksusbd to use different permissions:

		aksusbd -u 660


