Linux Installation Bootdisk Hacking
===================================

Written on April 7, 2002

Here is an outline of a procedure for adapting the RedHat (or similar)
installation boot disk so that BRLTTY can be used during the installation
process.

History:
-Initial draft from Stphane Doyon <s.doyon@videotron.ca>
-Additions from Nicolas Pitre <nico@cam.org>
-April 7, 2002: Mostly rewritten by Stphane Doyon to take into account
   the INIT_PATH hack

TODO:
-Figure out how to use shared libraries from a statically linked
   executable, when the lib references symbols from the main
   program. With that we could do generic bootdisk with dynamic selection
   of braille driver.
-Give working instructions on how to make higher sized floppies for a
   one-floppy solution.

You need an already working Linux station to perform this. A certain
level of Linux/UNIX expertise is also required. Please read to the end
before doing anything. You'll probably end up asking for sighted help at
some point (such as to know why it won't boot, or to help install BRLTTY
on the new machine), but if you can get this to work then you'll be free
to spend an hour on your own choosing which packages you want installed.

This was last tried with RedHat 7.2.

First step is compiling BRLTTY. The bootdisk will use one and only one
BRLTTY driver, so you must choose wich. Do:

make clean
make BRL_TARGET=<driver> TEXTTRANS=<table> INIT_HACK=1 LINKSTATIC=1

where <driver> is the driver to build into BRLTTY (one of the possible
BRL_TARGET values listed in the Makefile) and <table> is the translation
table to use (such as text.french.tbl, text.german.tbl, ...) (see the
BrailleTables/ directory).

This will build BRLTTY with the chosen display driver built-in, and will
link the BRLTTY executable statically so that it doesn't depend on any
shared libraries.

Alternatively you may edit the Makefile, make appropriate selections in
there, and then do "make". You must uncomment one BRL_TARGET line, as
well as the lines INIT_HACK=1 and LINKSTATIC=1.

If your display is on the second serial port instead of the first,
you will need to add "BRLDEV=/dev/ttyS1".

You should get an executable called "brltty" whose size is around 570K,
depending on the driver you chose.
If you do:

	file brltty

it should say, among other things, "statically linked".

The Red Hat installation boot disk is a DOS disk that contains a boot
loader (called syslinux), a kernel, and an initial ramdisk
(initrd.img). That initial ramdisk is the initial root filesystem
containing a bootstrap installation program: /sbin/init. We'll just put
brltty on that ramdisk image and make sure it is started before anything
else. However, because the statically linked BRLTTY executable is so
large, we will have to put the ramdisk image on a second floppy, because
it won't fit on the original single boot floppy (with the kernel).

So now we must hack floppies. Make a temporary work directory. We will
call it ".../work", could be "~/work".

mkdir .../work
mkdir .../work/etcbrltty

Now copy relevant files from your BRLTTY build. Copy the executable, the
translation table and the help file(s) to your work directory.

cp brltty .../work
cp help/* .../work/etcbrltty

(You can also copy alternative translation tables from BrailleTables/
to .../work/etcbrltty. These CAN be loaded dynamically.)

Now change to the work directory:

cd .../work

Next step is to select a installation boot floppy image from your
distribution. This could be images/boot.img or images/bootnet.img from an
RH CDROM. Consider checking the updates site for your distribution in
case they have updated installation disk images. If what you have is an
actual floppy, use "dd if=/dev/fd0 of=boot.img bs=512" to make an image
file from it.

Copy the chosen image to your work directory and if necessary rename it
to boot.img.

So now the current directory should contain boot.img, brltty, and
etcbrltty.

Now run the mkbd script. It will copy boot.img to myboot.img, and it will
modify the syslinux.cfg: it will add a new boot entry called
"brltty". That entry will have options to cause syslinux to load a
ramdisk from a second floppy, instead of using the initrd.img on the
first floppy. The BRLTTY entry has the "text" keyword parameter to
trigger the text-mode install. mkbd also makes this new entry the default
boot entry.

Now run the mkinit script. It will get initrd.img (the initial ramdisk)
from boot.img and call it initrd.gz. It will modify that image:
-Rename /sbin/init to /sbin/init_real,
-Copy brltty to /sbin/brltty,
-Link /sbin/init to /sbin/brltty
-Copy files from etcbrltty to /etc/brltty,
-Try to make sure necessary devices such as vcsa, serial ports and
   console device exist in /dev. (vcsa is usually missing.)

Assuming there are no errors, the next step is to actually write the
floppies.

So get two formatted floppies. One will be the boot floppy, the other the
ramdisk floppy. To write the boot floppy do:

dd if=myboot.img of=/dev/fd0 bs=512

To write the ramdisk floppy do:

dd if=initrd.gz of=/dev/fd0 bs=512

That's it!

So now boot the boot floppy on the machine you want to install. At the
prompt you can press ENTER to choose the brltty entry. 

If you want to specify boot parameters, remember to use the label
"brltty" instead of "linux".

You can pass options to BRLTTY from the boot prompt by using the same
option names as in the brltty.conf file.

When you press ENTER, syslinux will load the kernel. When the floppy
stops spinning the kernel will start to run and will prompt you for the
ramdisk floppy. Put the second floppy in and press ENTER. The kernel will
load the ramdisk. When the floppy stops spinning, BRLTTY SHOULD
(hopefullY) come on and the installation program should start.

One of the problems you may have during the installation process, is that
some autoconfiguration programs may play around with the serial ports to
try to autodetect hardware, thereby upsetting them and causing BRLTTY to
stop working. This can also occur when the system itself boots. More
recent RedHat versions are less aggressive though. Two tricks if you have
problems:
-If kudzu runs when your system boots and upsets BRLTTY, either disable
that service (using chkconfig or ntsysv) or modify /etc/sysconfig/kudzu
or the script that uses kudzu to make it use the --safe option.
-To get the installation program to let a serial port alone, you might
try to modify the ramdisk to change /dev/ttyS0 to say /dev/ttySmyown, and
tell BRLTTY to use that as it's serial port. This might have the effect
of hiding the serial port from bad applications.

Note that you must also install BRLTTY on your new machine. When it will
boot Linux after the installation, BRLTTY will not be installed and the
machine will be inaccessible. One way to simplify things is to use the
statically linked brltty you compiled for the installation disk, as it is
fairly self-contained. Once it's running, then you can build yourself a
shared version and modify your boot scripts or inittab to have BRLTTY
start automatically. A nice way to get the brltty onto your new machine
is this: during the installation process, after your target partition has
been formatted, it is (at least with the current RH installation program)
mounted under /mnt/sysimage. You can temporarily put aside the
installation program and get a shell by going to the second virtual
console (alt-F2). There you can do

cp /sbin/brltty /mnt/sysimage/sbin

I am not sure if at that point it is possible to edit inittab or startup
scripts. Otherwise on your first boot, you just have to log in as root
(without braile support) and type "/sbin/brltty" and if all went well
BRLTTY should come on.

Good luck
