
	===============================
	== Installation instructions ==
	===============================

Contents:
	* FAQ
	  * SCSI support
	  * PCMCIA support

	* Tiny manual


	===============================
	==            FAQ            ==
	===============================


	====== Q. How to leave howto ======

Program you're using to read this howto is e3 trying to imitate vi.
So to leave it press <ESC>, <:>, <q>, <Enter>.


	====== Q. How to install _on_ SCSI disk(s) ======

You must load proper SCSI hostadapter modules.
They can be specified in 'scsi_hostadapters' variable in
/etc/installer.conf, e.g.:

  scsi_hostadapters="aic7xxx"

you may specify more than one:

  scsi_hostadapters="aic7xxx advansys"

or if you have all adapters on PCI bus, let installer scan for them:

  scsi_hostadapters="auto"


	====== Q. How to install _from_ SCSI disk/cdrom ======

You must also specify scsi_hostadapter as above

	====== Q. How to install _from_ PCMCIA device ======

Must specify pcmcia_controller variable:

  pcmcia_controller="auto"

or specify your controller:
  
  pcmcia_controller="i82365"

	====== Q. How to install _to_ hardware RAID device ======
	
At the very moment just three hardware RAID controllers are supported:
  * cpqarray, with devices in /dev/ida
  * DAC960, with devices in /dev/rd
  * cciss, with devices in /dev/cciss
cpqarray/EISA is not supported, as there is currently no way to pass it arguments.
(if you *really* need it, please contact me (malekith@pld.org.pl))
  * ataraid (hptraid or pdcraid), with devices in /dev/ataraid

In order to install on these raid devices one need to list /dev/ida/c0d0 or whatever
in dest_devices, (same as /dev/hda or /dev/sda), and then in dest_partX_device
(either /dev/rd/c0d0 or /dev/rd/c1d7p3). /dev/(ida|rd|cciss)/c\dd\d+ and
/dev/ataraid/d\d+ are treated equally the same as /dev/[hs]d[a-z]. 

Devices in /dev/ida|rd|cciss|ataraid are created during installation.

You do NOT need to set scsi_hostadapters.

	====== Q. How to install _to_ software RAID device ======

It is somewhate more tricky then hardware RAID.

First we might need to create partitions to make RAID on them.
If you already have partitions use 'use_existing' action for given
device. You mark partitions that are going to be used for RAID, with
bogus 'md' filesystem and mountpoint. You set them proper size.
format_partion, format_options and fstab_options are ignored.

Second you need to tell the installer from which devices to make given
RAID array. You tell all that in dest_partN_device variable. Example
entry might look like this:

dest_part5_device=/dev/md0:raid5,/dev/sda2,/dev/sdb1,/dev/sdc1,/dev/sdd1:spare,chunk_size=256

this means to make /dev/md0 device, using RAID level 5 (see Software-RAID HOWTO),
from 4 SCSI disks, using sdd1 as a spare disk. Also strip size is set up
to 256 instead of default 128.

We first have /dev/mdX, then a colon (:), RAID level description (use raidl 
for linear raid, raid0, raid1, raid4 and raid5 are all allowed), and
then comma separated devices and options. You can make one RAID over another,
like this:

dest_part12_device=/dev/md4:raidl,/dev/md0,/dev/md1,/dev/md2,/dev/md3

however note, that raids are created in order, first /dev/md0, then /dev/md1
and so on, so this is invalid:

dest_part12_device=/dev/md0:raidl,/dev/md1,/dev/md2

(installer would try to make /dev/md0, from non-yet-existing /dev/md1
and /dev/md2)

Allowed options:
  * parity_algorithm={left,right}-{,a}symmethric, default=left-symmethric, this
    can only be given for raid5
  * chunk_size=N, in kB, default: 32, expect raid5, where 128 is the default.
  * persistent_superblock=0, default 1
  * just_start=1, default to 0, just do raidstart, no mkraid.

Notes:
  * stride option for mke2fs is automagicly computed, unless explictly given

Following RAID levels are supported:
  * raidl -- linear
    - disks doesn't have to be of the same size
    - disks are filled in order
  * raid0 -- stripe 
    - disks doesn't have to be of the same size
    - writes in parallel (faster)
  * raid1 -- mirroring
    - disks have to be of the same size
    - 0 or more spare disks
  * raid4
    - 3 or more disks of the same size
    - parity is stored on just one drive, so it's slow (unless disk to store 
      parity is veeeery fast compared to other)
    - 0 or more spare disks
  * raid5
    - 3 or more disks
    - parity information is distributed over all disks
    - 0 or more spare disks

Example part of installer.conf about RAID:

#v+
dest_devices="/dev/hda /dev/hdc"
dest_devices_actions="use_existing make_new"

dest_part1_device="/dev/hda1"
dest_part1_size="0"
dest_part1_filesystem="ext2"
dest_part1_format_partition="yes"
dest_part1_mnt_point="/boot"
dest_part1_options="defaults"
dest_part1_format_options=""

dest_part2_device="/dev/hda2"
dest_part2_size="0"
dest_part2_filesystem="swap"
dest_part2_format_partition="yes"
dest_part2_mnt_point="swap"
dest_part2_options="defaults"
dest_part2_format_options=""

dest_part3_device="/dev/hda3"
dest_part3_size="0"
dest_part3_filesystem="md"
dest_part3_format_partition="yes"
dest_part3_mnt_point="md"
dest_part3_options=""
dest_part3_format_options=""

dest_part4_device="/dev/hdc"
dest_part4_size="10000"
dest_part4_filesystem="md"
dest_part4_format_partition="yes"
dest_part4_mnt_point="md"
dest_part4_options=""
dest_part4_format_options=""

dest_part5_device="/dev/md0:raid0,/dev/hda3,/dev/hdc1"
dest_part5_size="0"
dest_part5_filesystem="ext2"
dest_part5_format_partition="yes"
dest_part5_mnt_point="/"
dest_part5_options="defaults"
dest_part5_format_options=""
#v-



	===============================
	==           Manual          ==
	===============================
	
	======== How to use the installer ========

This is batch-installer. You can read more about it here:
http://team.pld.org.pl/~klakier/doc/pld-installer/en/

Basically, installation process is driven by following config files:

  /etc/installer.conf
  /etc/installer.pkgs
  /etc/installer.sysconf

You can edit these files in two ways:
  1) edit them manually with text editor
  2) use 'setup' utility that provides simple UI

If you choose 1), several simplified version of popular editors are
available, you may use one of 'vi', 'emacs', 'pico', 'ne'.

For 2), 'setup' is run automagicly on 1st console. What setup actually does
is editing these three config files.

For your convenience, several virtual consoles are available. Use
Alt-F1, Alt-F2 ... to switch between them - e.g. you may leave this howto
on current console and switch to another to run editor or 'setup' or 
whatever else on it.



	======== Features ========

What installer does:

  1) Create partitions
  2) Install rpm software packages
  3) Install bootloader
  4) Preconfigure installed system

  Note: The preconfiguration of installed system is very limited.
        Do not expect everything to work out-of-the-box.

The step 1) is driven by /etc/installer.conf 

The list of packages to install in step 2) is given in
/etc/installer.pkgs 

Bootloader is specified in /etc/installer.conf 

The preconfiguration of installed system is given in
/etc/installer.sysconf


	======== Types of installation ========

In order to be able to accomplish mission, installer must get to
source of installation. Various types of installation sources are
supported. The type of installation is determined by 'source' variable
in /etc/installer.conf

Here some examples will be given

* cdrom --- The simplest one: if you have popular ide (ATAPI) cdrom,
  you do not need to configure anything to get to source. If you have
  SCSI cdrom, you must specify SCSI adapter.

* net --- In order to install from net you must be using bootdisk_net*img
  For net installation, some additional information must be given to 
  installer. See example fragment of /etc/installer.conf:

  source=net
  source_device="ftp://ftp.pld.org.pl"
  source_filesystem=net
  source_dir="PLD-1.0/i686"

  net_device=eth0
  net_device_module=auto
  net_ipaddr=192.168.0.3
  net_prefix=24
  net_gateway=192.168.0.1
  net_dns="192.168.1.1 195.116.199.146"
	

* nfs --- It is similar to net installation (the same bootdisk_net*img may be used). 
  You must give correct  nfs share and directory. E.g. if you have local mirror of PLD 
  resources in directories 
  /exports/linux/PLD-1.0/i686/PLD/{installer,RPMS} on the nfs server
  server exports /exports/linux/PLD-1.0 directory, you may use the following
  setup:
  
  source_device="server.my.net:/exports/linux/PLD-1.0"
  source_dir="i686"

  Note that source_dir must point to the directory containing structure
  PLD/{installer,RPMS}.


* disk --- installation from disk is supported by bootdisk_{ide,scsi}.img
  Installation from disk involves some setup first: you need to specify
  location od PLD resources. Example:

  source=disk
  source_device=/dev/sdb
  source_filesystem=ext2
  source_dir="/home/users/joe/mirrors/PLD-1.0"
  scsi_hostadapter=auto

  In case you install from SCSI disk, you may be asked for additional
  diskette containing proper scsi_hostadapter module.


	======== Configuring destination disk ========

By default the installer is configured to install on standard ide disk.
(dest_devices="/dev/hda"). In that case installer will automatically
load all necessary modules needed.
If you want to install on scsi disk, installer must configure scsi adapter(s)
first. Read 'SCSI support' later.


	======== Validating /etc/installer.conf ========

In order to catch simple errors	in config file, some special
script named 'installer-validate' exists. 
It is invoked  by 'installer' at the baginning, It is also used 
by 'setup' each time you change any option.

If you edit installer.conf by hand, you can also run installer-validate
command manually.

	======== Installation process ========

Installation process is driven by 'installer' script.
Normally you should invoke this script and it should do
everything and finally display success message.

What this script actually does is invoking several other scripts 
(after validating config with installer-validate):

  installer-prep - prepare installer (load some modules, configure 
                   network if necessary)
  installer-dest - create partitions
  installer-pkgs - install rpm packages
  installer-boot - install bootloader
  installer-conf - do initial config

