CatRescue  is   a package for  creating   custom emergency boot  floppies with
utilities to help you bring your system back to good  health. It uses existing
kernel and programs on your hard drive, so that  you can always keep your boot
floppy  up-to-date  with  the  main    system. It  also  supports  easy-to-use
configuration files to specify which programs to include.

			       CatRescue 1.01E

This is an   ELF-only upgrade of CatRescue.  In  the process  I  also did some
cleanup and added a few new features. If you  used CatRescue 1.00 before, here
are the most important changes:

^oo^ CatRescue now uses an extended 1743K  floppy format.  This means that you
need to use a  new program, superformat from fdutil-4.1  or later,  to prepare
floppies. You also need to mount /dev/fd0H1743  instead of /dev/fd0. I wrote a
custom  boot sector  for Lilo  to   boot extended  formats;  The binary  is on
standard rescue image as /boot/boot.x and source code is in "lilo" directory.

This is because ELF binaries don't compress as well as QMAGIC ones :)

^oo^ e2defrag is now on a separate tools floppy, along with some new stuff.

^oo^ This floppy  will now  work on 4M   machine if you  don't enable multiple
virtual terminals.

This  distribution is unusable on systems  without ELF libc 5.x installed. Use
CatRescue 1.00 instead. Note  that there is a  bug in 1.00  canned image - you
need to add libext2.so.* to /mnt/usr/lib.

As Linux ELF support is still on development stage, some wrinkles are expected.
Please let me know of any.


			    Getting More Software

I included bits and pieces of other packages in this  distribution so that you
don't have to  install all of them just  to run  CatRescue. Full distributions
are   available from the following    locations  (download the latest  version
available and compile it for ELF):

sunsite.unc.edu:/pub/Linux/utils/compress/tzx100.tgz - executable  compression
utilities, like gzexe or tcx but less  buggy (I think).  It doesn't maintain a
cache of decompressed executables though.

sunsite.unc.edu:/pub/Linux/utils/file/perforate100.tgz - programs   and  shell
scripts that attempt to   save some disk  space  with benigh methods,  such as
making holes in files, linking together duplicates and so on.

sunsite.unc.edu:/pub/Linux/system/Misc/fdutils-4.1.src.tar.gz   - Programs  to
make and access extended floppy formats.

gd.cs.csufresno.edu:/pub/sun4bin/src/term-2.3.5Elf.tgz - ELF version of term.

In addition,  gd.cs.CSUFresno.EDU:/pub/sun4bin/src  has all Linux  programs  I
wrote myself, including  CatRescue. However it's a slow  machine and has small
login limit, so please get stuff from sunsite whenever you can.

###############################################################################

			Using CatRescue - Canned Image

The simpliest way to make  a floppy is to use  the default image included with
this distribution. First, you  need to make  a floppy device for 1743K format.
If you didn't already install fdutil 4.1 or later, type as root:

# mknod /dev/fd0H1743 b 2 76
# chown root.floppy /dev/fd0H1743
# chmod 660 /dev/fd0H1743

To generate a floppy, do as a member of group floppy or root:

   ./superformat 
   zcat image.gz | dd bs=1024 of=/dev/fd0H1743

You should write-protect the floppy, because it might otherwize get damaged if
kernel fails to load it to RAM disk. You can now test  the floppy by rebooting
your system.

When asked to insert a RAM disk  floppy, don't do  anything, just press Enter.
Enable multi-vt mode  unless you have  <8M of RAM;  if so  keep reading.  With
multi-vt mode you can use Alt-F{1,2,3,4,5,6} to switch terminals, as usual. 

You'll see  a  lot  of warnings  about  bdflush  not running and   ld.so.cache
missing.  It's  safe to ignore them  as  this only happens at  startup, before
init unpacks tar files that contain both bdflush and ld.so.cache :)

CatRescue floppies will  get you logged in  automagically as  root.  I thought
getty and login are waste of space, so /sbin/init  is just a shell script that
runs root shell. In fact you can't logout.


			       What's Included?

A lot :)

ext2fs utils version 0.5b
vi (=elvis), less
lilo
gzip, tar
mount, umount, mkswap, swap{on, off}, fdisk
ifconfig, route
Assorted utilities from /sbin and /bin. 
Manual pages for complicated commands.


			   Solving Common Problems

a) Lilo   on  HD is  defunct: The  boot  floppy  includes lilo   and  a sample
/etc/lilo.conf from your hard drive (or mine if  you are using default image).
Although I included some links on the floppy  to make lilo.conf files that use
{/,/boot/}{vmlinuz,vmlinuz.old}  work, it may need  some manual editing. After
everything is fixed, type: "lilo -v -v -v".


If you made a custom floppy on  the same system, you
can just do "lilo -v -v -v",  as lilo.conf was copied to  the floppy from your
hard drive. Otherwize, vi /etc/lilo.conf first.

b) Same or kernel  on  HD went bad;  also  if DOS install hosed  your parition
table: You can also boot from the floppy but mount your  HD as root. Just type
some options at lilo prompt:

LILO: CatRescue root=/dev/hda2 ramdisk=0

c) Your root filesystem is ill: Run fsck first (which  is a link to e2fsck. If
you use xiafs or umsdos, you'll have to customize the floppy). After that, you
can mount it with:

      mount -t ext2 /dev/hda2 (or whatever) /rootfs

This will make most libraries and binaries  on your root filesystem accessible
from rescue floppy. You can even run a.out programs. echo $LD_LIBRARY_PATH and
echo $PATH to get an idea. Also, man will be  able to access manual pages from
/usr/man/preformat on your HD. You may want to  also mount /rootfs/usr if it's
a separate filesystem.

If you  would rather not  have  this happen, choose  a  mount point other than
/rootfs, for example /mnt.

For more complete environment, you can use chroot, for example:

# cd /rootfs
# chroot /rootfs /bin/zsh -l

If you have suitable swap space  enabled, you can  even run X windows. To make
ps work, mount /proc. Don't forget to umount /proc,  exit chroot()ed shell and
umount /rootfs for clean reboot.

The floppy includes vi and less, so you can  modify system files as needed. If
your system can't  boot because of bad kernel  or shared library, you can just
copy them from the boot floppy. /vmlinuz is not on the  RAM disk, because init
deletes it to save space during boot process. But you can always do:

      mkdir /floppy 
      mount -t ext2 /dev/fd0H1743 /floppy

And then copy /floppy/vmlinuz. You can also mount other floppies to copy files
from another computer  or restore your backups.  Boot floppy does include gzip
and tar if you want to extract an archive to your hard drive.

d) Your root filesystem  is terminally ill: Huh oh!  You have a backup,  don't
you?  First see  if  you can  salvage  at least   some files, like  your  home
directory.  Once you  copied  them elsewhere   (you can temporarily   use swap
partition if you have 8M RAM and didn't enable swap), do:

# mke2fs /dev/hd_your_root

If you have another HD with healthy filesystem, you can mount it and tar files
over. However if you  have tape backups, distribution  CD-ROM or no  backup at
all except getting  files back  from  Internet, you'll need  to customize your
CatRescue floppy  to include programs   that   can recover files  from   those
sources.

		Using CatRescue on Systems with Limited Memory

If  you have a  system with  only  4M RAM, you  have to  answer 'n' to "Enable
mutliple vt's?" prompt at boot time  or the system will  hang. This will cause
/sbin/init to exec ash directly instead of  spawning subprocesses, so that the
only processes running on the system will be login shell and update. 

Still you should enable swap space as  soon as possible.  Only utilities to do
so (fdisk, mount, mkswap, swapon, dd) are tested to work without  swap on a 4M
system.

Once swap is on,  you may want to enable  multi-vt mode by typing "multvt". It
can take several minutes to initialize on a system with slow HD, but once it's
done, the performance it tolerable.

			   Customizing Canned Image

CatRescue boot floppies  use standard ext2 filesystem, so  you can mount it at
any time with:

	 mount -t ext2 /dev/fd0H1743 /mnt

At this point you can do anything you want with directory tree under /mnt.

Naturally I packed image.gz as tightly as possible, so there is nearly no free
space left. You'll have to delete something you don't  need before you can add
new stuff.  Consider getting rid   of manual pages in  /mnt/usr/man/preformat.
/mnt/bin/{xargs,tar,find}  are not   normally  essential for   recovering data
either.  And yeah,  don't  forget to  start pathnames  with /mnt or  you might
accidently delete data on your own hard drive!

The following program shouldn't be deleted or the floppy won't boot:

gzip and untzx.gz  - needed to run compressed executables
ash, update, mount - Guess what?
tail		   - used in /etc/profile to fake "cat"

Some  trivial  programs  can  be  implemented using  shell functions.  Look at
/etc/profile in /mnt/etc.tgz for interesting examples.

If you copy new executables on the  floppy, it's a  good idea to compress them
using  tzx, which is an improved version of gzexe:

cp /dir/program /tmp
tzx /tmp/program
cp /tmp/program /mnt/usr/local/bin
rm /tmp/program~ (backup)

When  you run programs on  a floppy, they'll  be transparently uncompressed on
the  fly by  /usr/local/bin/untzx, run,  and then uncompressed   image will be
deleted. You can copy and uncompress /mnt/usr/local/bin/untzx.gz and use it on
your hard drive as well.  However it's better to get  tzx100.tgz from the same
ftp site where you got CatRescue. 

Programs that will run all the time, like shells, daemons,  cu, term and so on
should  NOT be  compressed  with tzx,  because  their uncompressed  image will
occupy disk space all the time anyway.

If you copy a data file, you can compress it with  gzip -9 and have /sbin/init
uncompress  it. init deletes  kernel and other stuff  that is not needed after
boot from RAM disk, so there is more space available than on the floppy itself.
Just add more filenames to "gunzip" line.

zum is  another way to save space.  It takes filenames  as either it's command
line arguments, or,  if none given, standard  input and scans them  for holes,
runs of zero bytes that UNIX can store without allocating any disk blocks. You
should run it on uncompressed executables and  libraries AFTER you copied them
to the floppy. For example:  zum /mnt/lib/mylib.so.1.0). It's not as effective
with ELF libraries as it used to be with DLL ones, but a couple  of K here and
there never hurts.

Finally,  replacing  kernel is a   bit more complicated.   First  of all, most
kernels from ready-to-run Linux distributions have much  more drivers then you
need ON A BOOT FLOPPY. You should make a minimal version to spare RAM and disk
space that is better used for additional user programs. For example, you don't
need math emulation if you have a 486DX and you  don't need IDE support if you
only use a SCSI HD for Linux. Also, quota, accounting and SysV IPC are useless
on a rescue floppy.

Linux versions 1.2.10 .. 1.3.2 are unable to run ELF binaries. 1.2.9, which is
used in default image, works fine and 1.3 series will be probably fixed soon.

It's possible  to  install kernel  on  a separate  floppy and   delete it from
CatRescue disk by playing with lilo.CatRescue

At some points there may be just no way to squeeze  in any more files. In this
case you'll have to use  a second floppy to  hold additional programs. Read on
to find out how.

		 BUILDING A CUSTOM IMAGE WITH A SHELL SCRIPT

It may  be inconvinient to keep replacing  files on boot  floppy by hand every
time you upgrade the system.  There is a shell script  to do some work for you
automagically.  Note  that you can't  use a.out executables on CatRescue 1.01E
floppy,  so you can   only build custom   floppies  on systems  where standard
programs in {/,/usr}/{sbin,bin} are mostly upgraded to ELF.

You are likely to need dynamically linked e2fsck, because static executable is
around     200K.    It   can  be     compiled     by  deleting  -static   from
e2fsprogs-0.5b/e2fsck/Makefile. However, e2fsprogs 0.5b also need an ELF patch
and current patch doesn't create several subdirectories needed for compile. :(
Therefore you  may want to  just copy  and  use the  binary from default image
until the next version of ext2fs is out.

The script will  become   much more  useful   when a standard    all-ELF Linux
distribution is out. But if  you already completely  upgraded your own system,
type:

       CatRescue /dev/<floppy_device> /dir_where_to_mount_it /your_kernel.

For example:

       ./CatRescue /dev/fd0H1743 /mnt /usr/src/linux/arch/i386/boot/zImage

You can choose a different floppy format/device, but you'll have to format the
floppy yourself to different density first and adjust the size  of RAM disk in
lilo.template. 2.88M   format should leave a  pleanty  of space for additional
software, but won't work on systems with 4M RAM.

Also you have to mknod /dev/fd0H1743 or install fdutil-4.1.

CatRescue script will prompt you before doing each of the steps, so you can do
some manual processing  if you  want. For example,   you can just run  lilo to
reinstall it for new kernel.

If you just run it without changing configuration files, you'll build the same
floppy I provided in image.gz, but with version of system utilities and kernel
that  is currently on  your hard  drive. Of  course it's  more  interesting to
change it's behaviour. Here is how:

 * files.copy is a list of files that get copied to the floppy without any
   modification.  For  example, /usr/man/preformat/cat1/mv.1.gz will be copied
   to /mnt/usr/man/preformat/cat1/mv.1.gz

 * files.tzx is a list of executables to compress and copy. For example, you
   can specify /usr/games/tetris.

Note  that   for CatRescue  to  work,  destination directories  should already
exist.  If you  want  to specify directory  structure,  make soft links or add
programs that are NOT normally on your hard drive, uncompess skeletion.tgz:

mkdir t; cd t
zcat ../skeletion.tgz | tar --same-owner --preserve -xvf -

You can then modify the directory structure under t. This is also the place to
modify /sbin/init and /etc/profile. 

Once you are satisfied with modifications, compress the directory tree again:

tar -cvf - . | gzip -9 > ../skeletion.tgz

Finally,  CatRescue runs  a script  called "special"  after it's  done copying
files.   You can  put additional  actions,   such as   making  more links  and
directories, in this script as well.

Some  actions, in paritular copying kernel  and shared  libraries, are done in
CatRescue script itself.

		       Building and Using Tools Floppy

CatRescue supports using  a second floppy with  additional tools. This  is the
place to add  programs you need to  connect to the   network and restore  your
backups if you can't squeeze them to  CatRescue floppy itself.  Here is how it
works:

^oo^ You mount the tools floppy with:
	mount -r -t ext2 /dev/fd0H1743 /tools

There is also a shell function, "mntools" in /etc/profile that does just that,
unless you want to use a format other than 1743K for tools floppy.

^oo^ Environment is set up so that  CatRescue finds executables in /tools/bin,
shared libraries in /tools/lib and manual pages in /tools/man/cat?.

^oo^ There are  some soft    links on  CatRescue  floppy  (look  at /etc   and
/root/.term) that  reference files under   /tools. You add  your  own links as
needed.

I included a tar file, tools.tgz, that has programs that are most useful in my
setup. They include:

modules-1.8.5 ELF patch 5
strace
file
mtools
superformat
term-2.3.5E
sz,rz
zip, lha, unarj, zoo
cu
e2defrag - because it must be run with unmounted root partition

The plan is to  use 'cu -l /dev/ttyS1', connect  to an Internet host, run term
and than download anything I need from ftp sites.  Also think about taking the
two floppies with  you to travel and  use  them to run  term  on your friend's
computer.  If you convince  your   friend to  run  Linux,  you can later   use
CatRescue  to make ext2  partition on her Hard Drive   and download a standard
distribution from sunsite :)

To make a tools floppy, run:

./CatTools /dev/fd0H1743 /mnt /your_termrc_file.

If you don't specify /your_termrc_file, default  one in tools.tgz will be used
and you'll need  to edit /tools/.term/termrc before you   can connect to  your
host.

After the  built is complete, you  can mount the  floppy again  under /mnt and
copy any additional  programs you need.  This  may include modules you need in
addition  to small  kernel on CatRescue  floppy (like  ftape, ppp  or ethernet
drivers) and networking programs (like ifconfig, route and ftp). Unlike floppy
built  by CatRescue, tools floppy  has a pleanty of  free space for additional
programs.

If you must use a.out programs, you'll need to copy ld.so and libc.so.4.x.x in
/tools/lib and change the soft link to ld.so in CatRescue /lib directory.

If I were  you, I would make  tools floppy read-only  and make any directories
that need to be writable on CatRescue disk. In this way you can avoid trashing
the  filesystem  if you forget to  unmount  it  before reboot  and also floppy
writes are much slower than RAM disk.

No configuration files are  provided at this time  because I suspect  that few
people have ELF versions  of all these programs.  This may change in  the next
release.

			    Undocumented Features

Ctrl-Alt-Del doesn't work. The problem is that  non-interactive ash started as
/sbin/init interpreter appears to  block some signals by  default, so I  can't
trap them from the shell script to do shutdown.

I think  using real init, agetty  and login would  be a waste of space. Anyone
knows  of a better solution?  At  the meantime, use  "reboot" or if /rootfs is
not mounted just press reset button.


				 Todo

Add support for 5 1/2 inch and 2.88M floppies. Anyone wants to donate a 2.88M
drive for development? :)

Add an option to use an editor other than vi.

--

Happy hacking!

     Snow ^oo^ Cat <snowcat@gd.cs.CSUFresno.EDU>
      _  ->  <-    aka Oleg Kibirev <oleg@gd.cs.CSUFresno.EDU>
  ___(_)  _ _)_
 /            _)
 \_.-._
       |___/	Purr!


PS: This distribution includes binaries for many Linux utilities. Their source
code and  use  licenses are available via   anonymous ftp  from,  for example,
sunsite.unc.edu:/pub/Linux.

My own code in this distribution is under GPL, but ask if you need any change.
