This is quick guide for those who never read the full documentation.
See the "how-to" for more details.

Warnings

This is release 2.x

It is file compatible with version 1.2 which was the last version and
is very stable and has remained unchanged for a long time. It worked
with Linux 2.0 and 2.2 series kernels.

Release 2.x of ppdd works only with Linux 2.4 series although the
modifications should allow it to work with future series too.

If you are using Linux 2.0 or 2.2 series you need ppdd version 1.2.

Release 2.x of ppdd builds on the crypto api and the cryptoloop
module. 

The backing file or partition used for ppdd MUST be a multiple of 512 bytes 
and SHOULD be a mutiple of 4096 bytes.  Most of the time ppdd functions
perfectly well even if the size is not a multiple of 4096 bytes but there is
an obscure bug in Linux (as at 2.4.17) which causes a read/write error
because the size of the device is not always calculated correctly.
Partitions which are an exact multiple of 4096 bytes do not suffer from this
problem and in view of the importance you attach to your data it is safer to
avoid even the smallest chance of this.


Pre-Requisites

You need the kernel source. The latest at the time this work was done
was 2.4.17. Get a standard version. Many distributions have patched
versions of the kernel source and this may conflict with this package.

You need the "international" patch. The patch for 2.4.17 is included
but you should try to get the correct version for your kernel.

You need a patch for loop.c which overcomes several problems, one of
which is critical to ppdd. Hopefully these changes will find there way
into the official kernel. The patch "loop-jari-2.4.16.0.patch" is 
included (it works OK on 2.4.17) but you should get the latest version.

You need the sources for "util-linux". This package includes the mount
and setup utilities which need patching for ppdd.

If you want to make use of ext2 disc labels on ppdd/loop devices you need
to get the latest e2fsprogs sources.


Installation

You can short cut some of this by applying all the patches (in the right
order) and then compiling everything. However if you are doing this for the
first time I urge you to go step by step and to test at each stage. That
way if something is slightly wrong you will know where to start looking!

Install the kernel source.
Configure it and compile it.
Run lilo and reboot this kernel - make sure it works!

go into the ppdd directory (e.g. /usr/src/ppdd-2.0)

Edit the file "Makefile.config" for your needs.

Apply the "international" patch as follows:

make trial_patch_intl

If you are happy with the result do it for real:

make apply_patch_intl

Apply the Jari "loop.c" patch as follows:

make trial_patch_jari

If you are happy with the result do it for real: 

make apply_patch_jari

Now go back to the Linux source directory.

Configure the kernel to include the loop device and the crytoloop
feature and blowfish. Compile the kernel. I prefer to do a "make dep"
again before the "make bzImage" and "make modules".
Run lilo and reboot this kernel - make sure it works!

Now build the util-linux package. DO NOT install it!

cd /usr/src/util-linux-xxxx
make

You should not install everything and there is a real chance you will
cause problems if you do - the package contains such things as
"login" and if there's anything wrong you may never get anything
working again! We need three programs which are in the "mount" directory
in this package - "losetup", "mount" and "umount". Rename your existing
versions of these (you may not have losetup) so that you can get them
back if you need to rescue things later. Then copy the three programs from
the package to wherever your versions were.

Test the loop device without encryption.

Apply the cryptoloop patch to util-linux

go into the ppdd directory (e.g. /usr/src/ppdd-2.0)

make trial_patch_util

If you are happy with the result do it for real 

make apply_patch_util

Rebuild the util-linux package. Again we just want only the three
programs as above.

Now we can test the loop device using blowfish encryption via the
cryptoloop feature.

If you've compiled the cryptoloop as a module you'll need to do:

modprobe cryptoloop

at this stage.

If you've got this far then we are ready to begin work on ppdd proper!

Go to the ppdd source directory.
Do "make check_linux" to see if you have everything in place.
Do "make trial_patch_ppdd" to see if there will be any patch problems.
Do "make apply_patch_ppdd".

Go to the kernel source.
Make menuconfig and select the ppdd option under crypto.
If you wish you can deselect blowfish - it was for testing purposes in
a previous step.
You will need ram disc support and initrd support for building a root fs
on ppdd - include it at this stage.

make dep
make clean
make bzImage
make modules
make modules_install

install the bzImage and run lilo as usual

You can now reboot and run the ppdd kernel.

Go to the ppdd source directory.
Do "make"
Do "make install"

Apply the ppdd patch to util-linux

make trial_patch_mount

If you are happy with the result do it for real:

make apply_patch_mount

Rebuild util-linux. Again only install "losetup", "mount" and "umount".

Go to the ppdd source directory.
Do "make test"

All the programs provide a little help if you run them with no arguments.

Initrd support (encrypted root filesystem) is available.
Read the how-to; it's too complex to fit it here.

If you use ext2 labels you can patch the appropriate utilities:

make trial_patch_looplabels

If you are happy with the result do it for real:

make apply_patch_looplabels

You then need to recompile and install util-linux and e2fsprogs.
Remember only to install "losetup", "mount" and "umount" from util-linux. 

Useful examples are in the examples directory.

The modified or new files which belong in the Linux source tree are in
the linux directories - may help you if the patch doesn't work first time.

Please provide feedback - good or bad. (Bad I will try to fix, good makes
me feel it was a worthwhile effort.)

Allan Latham <alatham@flexsys-group.com> January 2002

Rev 2.0 version - Beta.

