Stage 1 HOWTO
Stage1 is the program that will load second-stage install
Contents
Features
CD-ROM install
The stage1 will try the various CDROM drives to find the stage2. This step is fully automatic on most boxes.
Network install (ftp, http, nfs)
After choosing between ftp, http and nfs; you must enter the server (ip or name) and the path. Optionally you can enter username and password, or even proxy information.
In ftp installs, the installer displays a list of mirrors, fetched from
Mirrors_API (example: http://mirrors.mageia.org/api/mageia.3.i586.list).
Disk install (from mirror tree or ISO images)
Mageia Linux can be installed from a mirror tree or ISO images on disk. Supported partition types are ext2, vfat, ntfs and reiserfs.
The disk install can use multiple ISO images. Instead of specifying the whole path of the ISO image, you only need to specify the directory where the ISO images are located. If this directory contains multiple ISO images with a stage2 installer (typically the first CD of a CD set), the installer lets you choose one of those suitable images. Then it launches the stage2 installer from this ISO image, and the stage2 installer will automatically use other ISO images in this directory (relying on volume names of ISO images).
Stage1 architecture
Stage1 binaries
stage1 source code is available in git: viewvc
It is packaged in drakx-installer-binaries
. The most important binaries are:
init
: a simpleinit
-like program, which callsstage1
, then stage2.stage1
: it downloads the stage2 (http/ftp installs), then mounts it, then prepares some symlinks for stage2, then exits.
Stage1 initrd
The stage1 initrd is usually called all.rdz, it is built in package drakx-installer-images
using mostly two scripts:
update_kernel
: unpacks the kernel images + modules from a kernel rpmmake_boot_img
: creates stage1 initrd and all the boot images (boot.iso
,all.img
,isolinux/*
)
Automatic stage1
This feature is used to have a fully automated stage1. It uses the kernel parameter "automatic" with keywords separated with commas and colons, on the following genres:
automatic=method:nfs,network:static,ip:192.168.1.24,server:192.168.1.7,directory:/stable/i586 automatic=method:ftp,network:dhcp,server:ftp.ciril.fr,directory:/pub/linux/mandrake-devel/cooker automatic=method:ftp,network:dhcp,server:companyserver,directory:/mdkinst,user:XXX,pass:XXX automatic=method:ftp,interface:wired,network:dhcp,... automatic=method:ftp,network:adsl,adsluser:XXX,adslpass:XXX,... automatic=method:cdrom automatic=method:disk,disk:hdb,partition:hdb7,directory:/cooker |
All of these are explained in mdk-stage1 documentation.
You may use shorter versions of keywords (it helps reducing size of commandline), please find each keyword short-alias counterpart in file automatic.c under the identifier named "short_aliases".
This gives for example:
automatic=met:nfs,net:static,ip:192.168.1.24,ser:192.168.1.7,dir:/stable/i586 |
instead of
automatic=method:nfs,network:static,ip:192.168.1.24,server:192.168.1.7,directory:/stable/i586 |
Custom automatic stage1
Also one can just:
- retrieve drakx-installer-images SRPM (eg: from this mirror).
- unpack it:
rpm -i drakx-installer-images*.src.rpm
- enable debug in the spec file and add to the %%build step eg:
%build %if %debug # Example for building an automatic boot.iso: export BOOT_AUTOMATIC_METHOD="method:http,ser:192.168.0.10,dir:/mageia/unstable,netw:dhcp" export DEBUGSTAGE1=1 %endif |
Debugging and testing the stage1 on a test machine with tftp
Building stage1 initrd
First, grab the whole drakx git tree and prepare a kernel.
% cd ~ % git clone git://git.mageia.org/software/drakx % cd drakx/images/ % ./update_kernel /RPMS/kernel-desktop586-2.6.*.rpm |
Then make sure the stage1 isn't in testing mode (MODE_TESTING shouldn't be set) and build it.
% cd ~/drakx/mdk-stage1 % make |
Finally, build the initrd
containing modules and binaries.
% cd ~/drakx/images % DEBUGSTAGE1=yes ./make_boot_img isolinux |
isolinux/alt0/all.rdz
is now built (in ~/drakx/images
)
PXE
We will consider a PXE server already exists on the local network. Here is a way to have a flexible entry in the PXE server:
Have stage1 files available on a the tftp server
A flexible way is:
- to copy stage1 files locally:
rm -rf /export/isolinux cp -f ~/drakx/images/isolinux /export/isolinux |
- and to have the tftp server mount
/export
. Eg, add this to tftp server's fstab:
leia:/export /var/lib/tftpboot/X86PC/linux/images/leia nfs soft |
Configure special entries in the PXE server
label leia_nfs kernel images/leia/isolinux/alt0/vmlinuz append initrd=images/leia/isolinux/alt0/all.rdz vga=788 kickstart=install/auto_inst.cfg.pl automatic=method:nfs,network:dhcp,server:192.168.100.39,directory:/export,int:wired |
If you have a test box, you can also modify the PXE server to always boot a specific entry (eg: "leia_nfs") for a specific mac address.
Network grub
Here is an alternative to the PXE server.
Copy stage1 files on a tftp server
First, make the initrd and vmlinuz binary available in the tftp server root.
% sudo urpmi tftp-server % sudo cp -f ~/drakx/images/isolinux/alt0/* /var/lib/tftpboot/ |
Write a grub
menu that will allow a choice between multiple install methods, using vmlinuz
and all.rdz
from the tftp server. This grub
menu will be put in /var/lib/tftpboot/menu.lst
% sudo emacs /var/lib/tftpboot/menu.lst |
In this file, (nd)' represents the tftp server root.
Here's a sample file with multiple config and some automatic settings :
timeout 10 default 0 title nfs dhcp tftpserver 192.168.100.42 kernel (nd)/vmlinuz vga=788 kickstart=install/auto_inst.cfg.pl automatic=method:nfs,network:dhcp,server:192.168.100.42,directory:/export,user:a,pass:a initrd (nd)/all.rdz title ftp dhcp tftpserver 192.168.100.42 kernel (nd)/vmlinuz vga=788 kickstart=install/auto_inst.cfg.pl automatic=method:ftp,network:dhcp,server:192.168.100.42,directory:/export,user:a,pass:a initrd (nd)/all.rdz title rescue dhcp tftpserver 192.168.100.42 kernel (nd)/vmlinuz rescue vga=788 automatic=method:nfs,network:dhcp,server:192.168.100.42,directory:/export,user:a,pass:a initrd (nd)/all.rdz |
Create a grub boot disk
Now that the tftp server is ready and offers vmlinuz
, all.rdz
and menu.lst
files, a boot disk or a cdrom has to be created to fetch those files and start the stage1 on the test machine.
A grub
config file has to be created so that the boot disk uses the tftp server previously set up. This menu.lst
file will actually do nothing but reload the menu.lst
file from the tftp server.
Here's a sample menu.lst
file :
timeout 0 default 0 title loadmenu dhcp tftpserver 192.168.100.42 configfile (nd)/menu.lst |
The grub
boot disk is actually network card specific. You must compile your grub with --enable-CARDNAME. You must then install that specific grub on floppy or iso.
Booting the test machine
Insert the grub
boot disk in the floppy or cdrom drive of the test machine and boot on it.
grub
will read the menu.lst
file on this boot disk and then switch to the menu.lst
file on the tftp server to give the choice between boot entries defined in the /var/lib/tftpboot/menu.lst
file of your tftp server.
Debugging the stage1 using testing mode
Running stage1 on the workstation
First, the stage1 needs to be in testing mode. A good way to do this for now is to add set_param(MODE_TESTING) at the beginning of the main() function in ~/drakx/mdk-stage1/stage1.c
% cd ~/drakx/mdk-stage1 % make % sudo ./stage1-full |
Current ways to debug and test stage1
- global variable testing in init; if set, disables :
- screen blanking
/proc mount
/dev/console
open- hostname setting
- klog open
- unmount and reboot at end
- DEBUG macro in init
- if set, print a message and sleep(10), that's all folks ...
- name of the installer
- if the stage1 is named debugstage1, set MODE_DEBUGSTAGE1
- MODE_DEBUGSTAGE1 and IS_DEBUGSTAGE1 macros
- if set, hangs with a while(1) in
do_pivot_root()
, called fromfinish_preparing()
, probably to prevent stage2 from being launched
- if set, hangs with a while(1) in
- MODE_TESTING and IS_TESTING macros, if set:
- log in
debug.log
instead of SLASH_LOCATION/tmp/stage1.log
- do not spawn shell
- do not spawn interactive
- do not load modules
- do not configure network interfaces and routes
- stage1 returns 0 instead of 66
- log in
- SPAWN_SHELL macro
- defined in
Makefile
- if set, try to launch a shell
- defined in
- SPAWN_INTERACTIVE macro
- not defined
- if set, try to spawn interactive
- DEBUGSTAGE1 environment variable in
~/drakx/images/make_boot_img
- if set, add a shell in image
How to actually launch stage1 in debug/testing mode
MODE_TESTING
Possible evolutions
- drop DEBUG macro since the reboot code is debugged
- drop name of the installer (debugstage1) check
- merge MODE_DEBUGSTAGE1 macro with MODE_TESTING macro
- set testing variable in init and MODE_TESTING in stage1 if the DEBUGSTAGE1 environment variable is set
- run install2 in test mode if MODE_TESTING is set
- add a compile option to include debug symbols
- use another command line than
/proc/cmdline
if MODE_TESTING is set
Problems
- two ways to pass the stage2 method (
--method
option or METHOD environment variable) - no way in stage2 to distinguish between disk install from mirror tree or from ISO images