 _____ _   _  ____ ____  ____  ____  ____      /(        )`
|  ___| | | |/ ___/ ___||  _ \| __ )|  _ \     \ \___   / |
| |_  | | | | |  _\___ \| |_) |  _ \| |_) |    /- _  `-/  '
|  _| | |_| | |_| |___) |  __/| |_) |  _ <    (/\/ \ \   /\
|_|    \___/ \____|____/|_|   |____/|_| \_\   / /   | `    \
                                              O O   ) /    |
-------------------------------------------   `-^--'`<     '
                                             (_.)  _  )   /
                                              `.___/`    /
 Brazilian Group of FreeBSD Users               `-----' /
      http://www.fugspbr.org       <----.     __ / __   \
          FreeBSD LiveCD           <----|====O)))==) \) /====
            24/june/2002             <----'    `--' `.__,' \


Disclaimer
==========

This software is offered to you "as is", and it is your responsibility to deal
with its results. The authors do not take any responsibility for any loss, 
problems or any other kind of misfortunes that might come from its use.

This is a work in progress and some features described below may not be 
present yet. Also, some functionality may be present and not yet documented.

Always check the main website (http://livecd.sourceforge.net/) to 
an up to date status of the developments.

Using this tool in the wrong way may cause data loss ! Make sure you read 
the instructions carefully !

Objective
=========

The FreeBSD LiveCD Toolkit has the objective of allowing the generation of 
custom bootable CDs based on a working FreeBSD system. The project itself 
was born due to a necessity of the Brazilian FreeBSD User Group, whose goal 
was to have a diagnostic and recovery tool for emergency situations like a 
disk crash and others.


What is it after all ?
======================

In short, the FreeBSD LiveCD itself is a set of scripts that will prepare 
an ISO image of a working FreeBSD system, based on some questions asked to 
the user. A custom made kernel will allow this ISO to be bootable and to 
have iteration with other partitions that might exist on the original or 
other hard disk(s).

Some of the uses for the FreeBSD LiveCD include: live operating system for 
system recovery, implement firewalls (packet filtering), NAT, bridges, 
installing the system on another machine, among other applications. Most of 
those NOT NEEDING a hard disk !!!!

Requirements
============

* To use the FreeBSD LiveCD system:


- Run it as ROOT ! You must have write permission on several places.
- A working FreeBSD machine running version 4.5-stable or higher (not 
tested with 5.x yet. Please let us know if you do it)
- your sources (/usr/src mandatory !) synchronized with the above version.
- 2 GB of free disk space under /usr/local
- mkisofs

Of course you need a CD Recorder to burn the CD image, but it does not need 
to be in the FreeBSD system.

* To recover/install the system based on a FreeBSD LiveCD

A computer with a equivalent configuration of the original machine (pay 
special attention to disk controllers and network cards, not to mention 
disk space, in case you are recovering/installing the system on a hard drive)


How to use it
=============

Using the FreeBSD LiveCD is very simple. It consists basically of running 3 
scripts:

-       LiveCD/livecd.sh
-       LiveCD/scripts/create_vnodes.sh
-       LiveCD/scripts/install_freebsd.sh

The livecd.sh script is the main tool, used to generate the ISO image, 
while the other two scripts will only be used when you are running the 
FreeBSD system from your newly generated CD.

Livecd.sh usage
===============

Before using the livecd.sh script you should edit the config file and set 
some basic variables in there. Those variables will define paths, places 
and files that will be used and/or generated during the operation. 
When  running the livecd.sh script those parameters will be displayed to 
you so that you can review them. To accept, press enter. To abort the 
process press Ctrl-C and change the file as needed.

There are 8 steps to create the LiveCD, and for each of those, there is one 
entry on the main menu. Options "F" (burn CD) and "C" (install applications)
are optional.

The process can be interrupted at any time, and can be resumed by executing 
the next step right after the last concluded step.

Usage of create_vnodes.sh
=========================

This script - found under /scripts on your FreeBSD LiveCD - will extend the 
usage of you FreeBSD LiveCD. During the boot phase, this script will try to 
detect and mount all of the FAT/NTFS/EXT2FS/UFS partitions found on your 
local hard disks. Once those partitions are identified and mounted, you 
will be able to create "virtual nodes" on that partition and use them to 
install applications on your LiveCD, permanently save your configurations,
among other tasks.

By using the virtual nodes you will be able to use a 100% working FreeBSD 
system without having to repartition your hard disk or to install it at 
all. This is ideal for those that are willing to try out the system without 
installing it.

The FreeBSD LiveCD system uses a .flp file to boot up the system. The 
creation of the .flp file and its path (mounting point) are defined when 
running the create_vnodes.sh script. By selecting the .flp file to be used 
you will also be prompted for the size  in MB  to be used.

Usage on the install_freeebsd.sh
================================

This script  also available under /scripts on you newly created FreeBSD 
LiveCD  will obviously install the FreeBSD system on you hard disk, in a 
permanent way.

This installation is slightly different from a regular FreeBSD installation 
for it will use ALL the space on you hard disk REGARDLESS OF ANY 
PREEXISTING INFORMATION ! The hard drive will be initialized, erasing ALL 
and ANY previous information. All disk space will be allocated and used.

You will be prompted for which disk to install the system (it defaults to 
the first disk). Next you will be prompted for the sizes in MB of the root, 
swap and /var partitions, respectively. The /usr will use the remaining of 
the disk.

The system will be installed in a matter of minutes (some or several, 
depending on you computer configuration) . Simply remove the CD and 
reboot your system after the installation is complete.

You may choose to use the install_freebsd.sh script in the non-interactive 
way, by informing the needed parameters on the command line, as follows:

/scripts/install_freebsd.sh ad0 300 256 1000

This means that the system will be installed using disk ad0, allocation 
300 MB to the root partition, 256 MB to be used as swap, 1000 MB (approx. 1 GB) 
for /var and the remaining of the disk for /usr.

Notice that in batch mode NO CONFIRMATION WILL BE REQUIRED !

Usage of the FreeBSD LiveCD as a crash recovery disk.
=====================================================

One of the most popular and important uses of the FreeBSD LiveCD is 
recovering one server EXACTLY the way it was before a crash.

This is accomplished by customizing the installation script so that it 
creates all of the needed partitions, and also including the installation 
of the originally existing ports/packages (but not those applications 
installed by hand ! e.g. squid when compiled to use diskd or Apache with 
thousand of customizations !). All of this in batch mode, without user 
intervention.

To generate a FreeBSD LiveCD that will automatically boot up and start the 
recovery of your system, you simply have to create a /etc/rc.local file 
referring to the /scripts/install_freebsd.sh script. Of course that, to 
make the installation absolutely user-free you will have to include the 
parameters for disk unity, and partition sizes. This is very helpful for 
server recovery/replication without user intervention.

Notes:
======

The FreeBSD LiveCD is highly customizable. You will be able to create 
several scripts of you own to perform the most different tasks from the 
generated bootable CD.

Due to the nature of the CDROM-based system, you RAM memory is widely used 
and demanded. This means that if, for some reason your system's hardware is 
not properly tuned or has bad quality memory, you may experience several 
problems like core dumps (with signals 10 and 11), computer freezing up, 
etc. Remember. Most of the system will be running under MFS (memory file 
system) therefore, bad memory behavior also means corrupted files.

Comments:
=========

All comments and suggestions are VERY welcome.
Please, feel free to email the FreeBSD LiveCD Development team at

livecd@fugspbr.org

just making sure that the term "LiveCD" (caps does not matter) is within the
subject line, or the message will be rejected.

