From Mageia wiki
Jump to: navigation, search

Stage 1 HOWTO

Stage1 is the program that will load second-stage install


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:

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 simple init-like program, which calls stage1, 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 rpm
  • make_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:


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:


instead of


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:
%if %debug
# Example for building an automatic boot.iso:
export BOOT_AUTOMATIC_METHOD="method:http,ser:,dir:/mageia/unstable,netw:dhcp"
export DEBUGSTAGE1=1

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://
% 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)


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/ automatic=method:nfs,network:dhcp,server:,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/

Configure menu.lst on the tftp server

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
kernel (nd)/vmlinuz vga=788 kickstart=install/ automatic=method:nfs,network:dhcp,server:,directory:/export,user:a,pass:a
initrd (nd)/all.rdz

title ftp
kernel (nd)/vmlinuz vga=788 kickstart=install/ automatic=method:ftp,network:dhcp,server:,directory:/export,user:a,pass:a
initrd (nd)/all.rdz

title rescue
kernel (nd)/vmlinuz rescue vga=788 automatic=method:nfs,network:dhcp,server:,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
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
    • if set, hangs with a while(1) in do_pivot_root(), called from finish_preparing(), probably to prevent stage2 from being launched
  • 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
  • SPAWN_SHELL macro
    • defined in Makefile
    • if set, try to launch a shell
    • 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


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


  • 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