Rafal Kleger-Rudomin

It is worth to realize that installation process is nothing really special. It consists of three steps, basically: Preparing filesystem (create partitions on disk/disks, format them etc.) Installation of rpm packages Setting up bootloader Can the installation be dangerous? Talking about real dangers I mean damaging hardware. Can the broken software damage a hardware? Hmm...: Too high frequency of video input signal could damage old monitors. Probably it is possible to make hard disks useless with some strange formatting (??) All dangers related to data are not really a dangers: it is obvious that responsible admin/user does not install new operating system in presence of disks that contain precious data, without backing them up first! If you want to use this installer you would better assume that all data on all disks in your system will be lost! Therefore make a backup first and prepare rescue disks...

Most existing installers for various operating systems are designed to be used interactively. They role is to assist user (possibly newbie user) during whole installation process. They usually also allows some configuration of newly installed system. However, interactive installers have some disadvantages: they absorb user attention during all installation time they do not (usually) allow repeating the same installation process they do not allow to perform installation automatically Noninteractive installers (e.g kickstart from RH) do not have those disadvantages (they have others ;) ). PLD installer will be basically noninteractive, but will also offer some additional interactive features. Nevertheless it is crucial to be able to duplicate installation noninteractively. run from single boot diskette or bootable cdrom installation from net (ftp/http), nfs, cdrom, disk installation on more than one disks/partitions

There is a bunch of concepts I follow in installer design: Batch mode installation process Idea is simple: The installation process itself should be performed automatically, without any user intervention. Batch installer reads special file that user prepared before. User can create this file in arbitrary way although some facility is provided - it is text mode UI. Before the real installation starts, installer validates the input file with validator. Reusability of install specifications File installer.conf may be saved and used to install system on the same machine again or used to perform batch installation on similar machines (nice feature e.g for computer sets vendors, admins of school computer laboratories, etc). Separation of install / configure UI+batch-installer are responsible for installation. Configuration of newly installed box (either before or after first boot) is another piece of cake. Separation of installer setup / installed box configuration There are three kind of configuration data: Installer system configuration (what modules to load, path to source of distribution, sometimes also basic net config). It is stored in installer.conf Installation specification (where to install, what partitions create), stored also in installer.conf Newly installed linux box configuration - handled by metaconfigurator To be able to perform installation we have to setup installer first: depending on source of installation, it may require loading some kernel modules, and optionally some network configuration. That is point 1) above. Note that in most installations the we would expect that 3) inherits the data from 1) (e.g we want network config in linux box to be set based on that used during installation), but it not necessarily need to be the case (e.g we want to assign static ip address during installation, but we want linux box use dhcp). Of course UI should help to share these settings by default. Note that in general case the installed system could be run on machine other than that used during installation process - it is possible to install system onto the disk(s) that will be then put into another machine. Of course in that case any autodetection e.g. for devices, would not have sense. Pre-setup of installer/box and one step batch installation As regards specifying configuration, as much as possible should be done before batch-installer is launched. Things like partitioning scheme and set of packages to install should be possibly specified before running batch installer. Batch installer should be run once and do job with no user intervention and without any questions. Only exception is an error: in that case, after fixing installer.conf, batch-installer should be invoked once again and be able to start working with the beginning - no reparation in the middle of work should be performed. This is generally true as long as you use make_new or use_existing options that will be discussed later

UI - text mode user interface. This is the interactive part used to prepare "batch installation driver file" (saved in /etc/installer.conf on bootdisk filesystem). It is responsible for assisting user to create good installer.conf, possibly checking and validating as much as possible to increase the probability of successful batch installation. Batch installer - this is main installer, it reads installer.conf and does the following: check as much as possible to prevent from future problems, prepare destination disks, install packages, install bootloader Metaconfigurator - it is rather a separate module, not part of installer itself and will not be discussed here Apart the above elements, installer usually needs some medium - either bootable diskette or cdrom (maybe some day click this address to install PLD from running system will be also possible ;)) ).

What are things installer must do? This section is a general summary. distribution Set of rpm packages to install. source Source of distribution - a place where installer can find distribution and some special .tar.gz packages used by installer. Depending of the type of installation, source can be a cdrom, disk partition, nfs volume or ftp/http location. dest Destination filesystem that the distribution will be installed onto. Dest is composed of destination partitions. User specifies what partitions on what disks will be used. Partitions can be created by installer from scratch, or the existing ones may be used. initrd Installer filesystem. After booting from bootkette/cdrom the installer system does not use any disk device - it is loaded into initial ramdisk (initrd) - 4MB virtual disk. The whole installation process consists of several steps. The general list is here, divided into stages, related to availability of certain resources: Stage 1 (have initrd only) configure installer system: hardware modules, networking (if necessary) get to the source (mount cdrom/disk/nfs_share or enable fetching files via net) Stage 2 (have source) fetch some additional tools needed to prepare dest from source create partitions on disks prepare filesystems on partitions mount entire dest Stage 3 (have dest) fetch rpm packages manager (now it can be placed on dest to save initrd space) install rpm packages The next step would be configuring linux box (not covered yet)

Bootdisk is a medium for installer. After booting from boot diskette or cdrom you get the minimal system, with root filesystem on initrd. I will call it bootdisk. Tools available on bootdisk include: Simplified versions od popular editors (provided by e3 package): vi, emacs, pico, ne, ws Berkeley ash shell Lot of basic unix tools provided by busybox (like test, ps, tar, mount). Type busybox to get a list. Set of necessary kernel modules stored in /lib/modules/ On the net-oriented bootdisks there are also: ip utility (from iproute2 package), and snarf - simple net fetcher. The rest of tools that are needed to complete the installation are copied/downloaded from <source>/inst directory - they are packaged into .tar.gz packages, e.g. parted-pkg.tar.gz, ext2-pkg.tar.gz. Note that getting them it is possible in Stage 2 and 3 only.

File /etc/installer.conf is the main file controlling installation process. It resides on installer system (initrd). The file can be edited by hand from installer system, using simple editors (vi, emacs, pico), created by UI, or created in any other way. It is also possible to prepare /etc/installer.conf on another machine (see unattended version). Config file has simple syntax. It consists of variable=value lines. Spaces around = are not allowed. Value can be surrounded by single or double quotes (if the value is a space-separated list, the quotes are mandatory) As you might guess, it is shell syntax. Keeping config file in that form allows shell scripts to include the file directly. The file consists of four main sections, related to particular parts of installation: Info about source (variables starting with source_) Network configuration - only if source is net or nfs (variables starting with net_) Dest setup (variables starting with dest_) Installation of RPM packages (variables starting with pkgs_) Detailed specification of the file may be found in .

See batch-installer/installer.conf* files for examples. Example config for installing from ide cdrom, on first ide had disk: source=cdrom source_device=auto source_filesystem=iso9660 source_dir=auto dest_devices="/dev/hda" dest_devices_actions="make_new" dest_devices_modules="" # First partition: dest_part1_device="/dev/hda" dest_part1_size="100% of free" dest_part1_filesystem="ext2" dest_part1_format_partition="yes" dest_part1_mnt_point="/" dest_part1_options="defaults" dest_part1_format_options="" # Second partition: dest_part2_device="/dev/hda" dest_part2_size="30" dest_part2_filesystem="swap" dest_part2_format_partition="yes" dest_part2_mnt_point="swap" dest_part2_options="defaults" dest_part2_format_options="" pkgs_installer="poldek"

Installation process is driven by several scripts, launched subsequently by main installer script. Particular scripts are discussed in next sections in the order they are normally invoked.

This is simple validator of /etc/installer.conf. If the file is incorrect, validator tells what's wrong, and returns non-zero exit status. This script is invoked by installer, but it is also used by general setup UI (ui-main) to assist you during general setup process.

This script prepares installer system to be able to get o source, and to be able to run installer-dest: it loads kernel modules needed to get to source media, sets up the network (if necessary), and finally loads modules and programs needed by installer-dest (like reiserfs.o or mke2fs). After successful running, the installation is in Stage 2 (we have source, and can fetch additional packages from it). To save initrd space, all modules that was on bootdisk initial are deleted from initrd after script successfully get to the source you requested. Therefore it is not possible to change source after you successfully attach to the one selected.

This is responsible for preparing destination filesystem. First it deletes existing partitions on destination disks (if make_new action given). Then it creates new ones (unless use_existing given) and makes filesystems on them. Finally, it mounts whole filesystem in /dest directory. If you do not use make_new_using_free_space for any disk, you may run installer-dest repeatedly - it checks and unmounts all /dest partitions before and then prepares /dest once again.

As you might expect this does RPM package installation. The script loads/fetches proper .tar.gz packages containing RPM installer of you choice (poldek or wuch), and then tells installer to install set of packages listed in /etc/installer.pkgs.

This is script responsible for installing bootloader. It is temporary. Will be obsoleted by rc-boot support in kernel package!!!!!!

source Type of source. Allowed values: net (ftp, http), nfs, cdrom, disk. Example: source="nfs" source_device Depending on the value of source it should be: cdrom: valid cdrom device, e.g. /dev/hdc or auto (detect first IDE cdrom) disk: valid disk partition, e.g. /dev/hdb2 net: address of ftp/http server, example: ftp://ftp.pld-linux.org/PLD-1.0/i686/. (must be numerical if no dns given in net section) nfs: volume name, e.g. my.nfs:/pub/PLD-1.0 (must be numerical if no dns given in net section) source_filesystem If source=disk it should contain filesystem type of source_device (e.g. ext2, vfat). For cdrom it should be iso9660, for net - net, for nfs - nfs. source_dir Path to the source on source_device (should point on directory containing RPMS and inst). If source=net, source_device and source_dir are concatenated therefore you may leave source_dir empty and specify full path in source_device. For disk or cdrom the value auto may be specified - tells installer to find the proper PLD/{RPMS,installer} structure.

If the source is net or nfs one must have at least one network device to get to source. The device will be configured by installer (particularly installer-dest script). Therefore some additional info is necessary: net_device Name of net device to use. In most cases (single ethernet adapter) it will be eth0. If you have more than one device it may be necessary to let the bootdisk kernel find it first (e.g. type pld ether=0,0,eth1 on bootdisk boot prompt) net_device_module The kernel module that supports your net device. For example: 3c509 is a 3Com 509 Ethernet adapter. If you have some no-name card and do not know its type, it is very likely it is compatible with NE2000 ISA (ne2000) or NE2000 PCI (ne2k-pci). Special value auto tells installer to try to detect card type and load appropriate value (works for PCI cards) net_device_module_options List of extra options to be given to modprobe program, when loading module, like irq=xx io=yy, etc. net_ipaddr Address of machine. May be static, like 192.168.0.3 or dhcp. net_prefix Net prefix (replacement for netmask). Most common one is: 24 (netmask 255.255.255.0). You may also set auto, and let the installer-prep to guess it if you have typical network. net_gateway Address of local gateway. May be empty if you are going to connect to nfs or net server in local net only. net_dns List of dns servers e.g. "192.168.1.1 195.116.199.146". May be left empty (in that case all addresses must be specified in numerical form)

Dest configuration consist of two parts: one is short, general part, second consist of series of per-partition configurations. General part include: dest_devices A list of all devices (disks) that will take part in creating dest filesystem. E.g. /dev/hda /dev/hdc means that this two disks will be involved. In common cases, I suppose, this list will be limited to one disk only. e.g. /dev/hda In order to install on hardware RAID device, you should pass its name as name or regular disk. For example to install on COMPAQ Smart RAID (supported by cpqarray.o module) pass /dev/ida/c0d0 here, and to install on Mylex DAC960 (supported by DAC960.o module) pass /dev/rd/c0d0. Other hardware RAIDs are not supported. cpqarray/EISA is not supported, as there is currently no way to pass it arguments. Devices in /dev/ida|rd are created during installation. No special devices have to be passed in order to install on software RAID (beside ones that RAID partitions resides on). dest_devices_actions The list of actions that should be performed for partitions on each disk specified in dest_devices. Possible actions include: make_new Create new partitions on given disk, existing partitions (if any) are deleted make_new_using_free_space Create new partitions on given disk, trying to use free space at bottom of disk (if any). No existing partitions are deleted. Installation will fail if existing partitions occupy entire disk space. use_existing Use existing partitions, do not create or delete anything. You may choose to prepare disk "by hand" and then run installer, or you may have disk already partitioned correctly, then this option would be useful. Example: dest_devices="/dev/hda /dev/hdc" dest_devices_actions="make_new use_existing" scsi_hostadapters Extra kernel modules needed to support dest_devices (or to source if you are installing from SCSI cdrom or disk). It is space decimated list of modules to load. It can be also single word auto which instructs the installer to automagicaly detect it. If you want to install from SCSI, you need to make specialized bootdisk using mkinstaller command. See appropriate section in this documentation. Installation to SCSI is supported out of the box. The second part of dest specification is per-partition config. Each partition config starts with dest_partX_ where X is number (1,2,3...). When specifying multiple partitions, be sure you did not missed any number (e.g 1,3,4), because installer starts with 1 and processes subsequent numbers until no variables are found for given number. The X numbers are used only within installer to distinguish configs. They are not related to partition numbers within disks (e.g. /dev/hda2). Partition numbers that will be created by installer are assigned automatically. Options are: dest_partX_mnt_point Mount point. The name of partition. At least one partition must be specified: / Another partition examples: swap, /home, /usr, /var/spool dest_partX_device Disk to put partition onto, e.g. /dev/hda. The disk must be already specified in dist_devices list. If the action for given disk is use_existing, proper partition number must be specified too, e.g. /dev/hda1. This entry is crucial for installation over software RAID. You need to tell the installer from which devices to make given RAID array. 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, defaults to 0, just do raidstart, no mkraid. dest_partX_size Size of partition that will be created. Size can be specified in three ways: absolute value in megabytes, e.g. 500 part of all available space (in percents), e.g. 20% of all part of rest - space that left (in percents), e.g. 100% of free If this partition will not be created (existing one is used) this variable is not recognized, and should be empty. dest_partX_filesystem The filesystem that will be created on given partition (or existing filesystem if partition already exists, and you do not want to format it). Possible values include ext2, swap, reiserfs and special entry for RAID md. dest_partX_format_partition Create filesystem on given partition? In most cases should be yes. Only exception is when you use existing partition with data and you do not want them to be erased - then set it to no. dest_partX_format_options Extra commandline arguments that will be passed to the proper make filesystem program (e.g. mke2fs). May be left blank. stride=X ext2 option for RAID drives is computed and added automagicaly, unless specified here. dest_partX_options Extra options that will be used to mount partition (/etc/fstab options). Leaving it blank means use defaults.

The next section of file is pkgs section. So far there is only two variables here: pkgs_installer Program used to install rpm packages. So far only poldek program is supported so you may choose from poldek, or poldek or maybe ... pkgs_install_docs Whatever to install documentation. (doesn't work yet). List of packages to install is flat text file stored in /etc/installer.pkgs. It can be easily created using UI and groups of packages.

The last section of file is boot section. So far there is only one variable here: boot_loader This determines whatever to install bootloader, and which one choose. It can be just lilo, which means to install lilo, or empty (don't install bootloader). Grub will be supported soon.

Pawel Gajda Wrote poldek Rafal Kleger-Rudomin Wrote batch installer, UI and this manual Pawel Kolodziej Wrote wuch Michal Moskal Wrote fine dml, one of batch-installer architects, contributed many parts of installer Sergiusz Pawlowicz Inspired me with batch installation idea, and helped testing bootdisk Sebastian Zagrodzki The author of the first working installer, called prowizorka. Also added support for console on serial port to bootdisk, and instruction how to use it (in this manual)