There are two ways to install frandom:
(1) Patch the kernel, so it includes frandom, and recompile the kernel
(2) Compile the module only, and plant it in /lib/modules/{something}

If you need the sysctl interface, your only choice is (1). The sysctl interface
works only if frandom is compiled into the kernel itself (see "Kernel Patching"
below).

If all you want is to enable the /dev/frandom and /dev/erandom device files,
option (2) is a quick and painless solution. In this case, you should refer
to "Kernel Module Installation" below.


K E R N E L   M O D U L E   I N S T A L L A T I O N
===================================================

There is nothing special about these instructions. They are intended as a
step-by-step guide for whoever isn't used to install kernel modules.

IF YOU'RE A KERNEL HACKER, you may not like my Makefile. It's only one
file to compile, so you can defenitely use your own.

It may *look* complicated, but the whole thing should take no more than 10
minutes.

NOTES: (1) By default, the module is compiled for the kernel currently running.
       (2) Subscribing to the frandom-critical is HIGHLY recommended. This
           is an ultra-low traffic list, with me only allowed to post.
           It will contain only critical messages such as (unlikely (-; )
           bugs that require immediate action.

The installations consists of the following steps:

1. Choose Makefile (and possibly edit it)
2. Compilation
3. Move frandom.o or frandom.ko to /lib/modules/{something}
4. Create /dev/frandom
5. Set up /etc/modules.conf, so that modprobe will load the module when needed.
6. Make frandom load at bootup
7. Test (and possibly sending me the results)
8. Subscribe to frandom-critical (and possibly frandom-users)

In detail:
=========

1. Choose Makefile
==================

If you're running on a 2.2 or 2.4 kernel, and want to compile for the kernel
currenly running, skip to the next item.

If you're compiling for a 2.6 kernel (or alike), change the symlink of
Makefile, so it points to Makefile-2.6. Since 2.6-alike kernels are under
development when writing these lines, it's hard to guarantee that this will
work right away.

If you want to compile for another kernel than the currently running, edit
the relevant Makefile, so that LINUXSRCDIR is the directory of the source
of the kernel that you want to compile for (for example,
LINUXSRCDIR := /usr/src/linux-2.4.18-mysrc)

2. Compile
==========

Simply type "make" at shell prompt. On 2.2/2.4 kernels, a single file should
be compiled with no warnings. On 2.6 kernels, the build system takes over
for a while...

3. Copy module binary to some /lib/modules/
===========================================

In short (for 2.2/2.4 kernels), as root:

install -m 644 frandom.o /lib/modules/`uname -r`/misc
depmod -a

This is good if the module was compiled for the currently running kernel.
Otherwise, go for /lib/modules/x.x.xx-xxx/misc instead.

On 2.6 kernels, you want to do the same with frandom.ko instead.

If you get an error message on the "depmod -a", on which frandom.o is
*directly mentioned*, you probably compiled the module for the wrong kernel, or
installed it in the wrong module tree. Other errors have nothing to do with
frandom.

At this stage, "insmod frandom" (as root) should work. If the module is found,
but fails on a "Device or resource busy" error, it may be because the
character-MAJOR 235 is occupied by some other device. In any case of failure,
check /var/log/messages for a reason for it.

See the README file about changing the MAJOR.

4. Create /dev/frandom
======================

In short: (as root)

mknod /dev/frandom c 235 11
chmod 444 /dev/frandom
mknod /dev/erandom c 235 12
chmod 444 /dev/erandom

The /dev/frandom is set to read-only permission for everyone. There is no
write operation for /dev/frandom, so the device file might as well reflect
that. Same goes for /dev/erandom.

5. Set up /etc/modules.conf
===========================

This step is essential, so that the kernel module is loaded every time
/dev/frandom is accessed. Without completing this step, trying to read
from /dev/frandom will result in a "No such device" error if the module
wasn't previously loaded manually. 

If you don't complete this step, /dev/frandom will work for you *now*,
but not after a reboot that may take place two months from now.

The following line should be added somewhere to /etc/modules.conf:

alias char-major-235 frandom

NOTE: On some systems (such as Debian), /etc/module.conf is automatically
      generated, and changes to it are temporary. If this is the case, a
      huge warning is expected to appear at the beginning of the file.

After doing this, verify that the magic works. Remove the frandom module
with "rmmod frandom" (if it's loaded). Verify with "lsmod" that it's indeed
not loaded. Now try (possibly as a non-root user):

head --bytes=1k /dev/frandom > /dev/null

This should apparently do nothing. But check with "lsmod" that frandom was
indeed loaded.

6. Make frandom load at bootup
==============================

Despite the automatic load of the module, it's advisabe to explicitly load
it at bootup. The reason is that some applications (such as dd) will fail to
trigger this mechanism unless executed as root.

"head" should work as a non-root user even if the module isn't preloaded,
if step 5 above was done right.

This can be done by adding the following line (or alike) to /etc/rc.local:

/sbin/modprobe frandom

This is a matter of your taste in system administration.

7. Test
=======

The test.sh bash script runs a simple speed test. It can be executed as regular
user. It generates a file, frandom-res.txt. I need this data! Please
send the file to the e-mail address given below.

8. Subscribe to frandom-critical
================================

It's highly recommended to subscribe to the zero-traffic list frandom-critical.
If something is wrong with the module, this is how you'll know about it.
Please visit http://lists.sourceforge.net/lists/listinfo/frandom-critical
and add yourself.



K E R N E L   P A T C H I N G
=============================

The installations consists of the following steps:

1. Patch the kernel (and make possible manual fixes)
2. Configure the kernel to support frandom.
3. Compile & install kernel
4. Fix include file in /usr/include
5. Check for sysctl interface
6. Set up device files

1. Patch the kernel
===================

The patch given in the tarball was done against kernel version 2.4.22. The
critical parts are random.c and frandom.c, which will most probably go smooth
on other kernel versions as well.

The patching is done by changing directory to *within* the source directory
(as in "cd /usr/src/linux-xx.xx.xx") and type (note the -p1 !):

patch -p1 -E < /path/to/patch/frandom-patch

If this went smooth, you may proceed to step 2. The information coming just
below is for manual patching, in case some part failed.

Except for frandom.c and the patch in random.c, we have patches regarding
the configuration environment, which can be done by hand. They consist of the
following items:

(1) drivers/char/Makefile modified to include frandom.o: frandom.o appended to
    export-objs, and the following line added:

    obj-$(CONFIG_FRANDOM) += frandom.o

(2) RANDOM_ERANDOM=7 is added to the /proc/sys/kernel/random enumerator in
    include/linux/sysctl.h, so that the RANDOM_ERANDOM is recognized in
    sysctl calls.

(3) A line in drivers/char/Config.in, so that "make xconfig" and friends
    recognize frandom:

    tristate 'Fast random data generator suite (/dev/frandom and /dev/erandom)' CONFIG_FRANDOM

(4) An entry in Documentation/Configure.help, so that some help is given on
    interactive configuration (as in make xconfig)

2. Configure the kernel to support frandom
==========================================

Using your favourite configuration tool (make xconfig?), enter "character
devices" and enable "Fast random data generator suite" either as "y" or "m".

NOTE: If you choose "m" (frandom as module, and not compiled in), the sysctl
====  interface will not be available.

3. Compile & install kernel
===========================

Follow the common practice of compiling and installing the kernel. Refer to
any Kernel-HOWTO for information about this.

4. Fix include file in /usr/include 
===================================

This step (and the step 5) are necessary only for sysctl interface.

If compiled into the kernel, the frandom suite supports an interface via sysctl
calls. But alas, the include file used by gcc will not recognize the magic
number for erandom sysctl calls, even though the version in the kernel is
patched correctly.

In order to fix this, do something like (as root):
cp /path/to/linux-source/include/linux/sysctl.h /usr/include/linux/

or use a symlink.

5. Check for sysctl interface
=============================

When running on a kernel that has frandom *compiled in*, you should find
a /proc/sys/kernel/random/erandom file. The existence of this file is a
confident indication that the sysctl interface is active on the running
kernel. Its absence is a likewise confident indication for the opposite.
Reading from this file generates 16 bytes of random data, in hex
representation.

For C interface testing, compile and run the test_sysctl.c application, which
came with the tarball. If you get an "`RANDOM_ERANDOM' undeclared" error on
compilation, step 4 above wasn't effective for some reason.

Just to have it spelled out:

> gcc test_sysctl.c -o test_sysctl
> ./test_sysctl

6. Set up device files
======================
Proceed from step 4 in "Kernel Module Installation" above.
   

Good luck & skill,

  Eli Billauer, 1 Oct 2003 (updated Apr 2004)
  Email: eli_billauer _at_ users.sourceforge.net 
