Wiki » Drakx-installer tips and tricks

Other languages English ;

this page is a draft.It requires improvements. If you want to improve it, simply log in and click on the Edit tab. Please remove this {{Draft}}template, when you're sure the page is complete and correct. View the other draft pages, or other pages to improve and maintain.

Basic architecture of the installer

The installer is divided in two parts: stage 1 (StageOne), written in C, to initialize the system, and stage 2.

There's two different stage2 available:

• the regular one, written in perl, exposed here.
• the rescue one.

The stage2 is provided in a squashfs image containing various files listed here. The result is install/stage2/mdkinst.sqfs, built by drakx-installer-stage2 src.rpm.

Keyboard shortcuts

In the Mageia Installer GUI, you can use the following keyboard shortcuts:

• F2: make a screenshot to place in /root/DrakX-screenshots after installation
• Ctrl-Alt-Home: go back to the first step of install. It is used to debug the "language selection" step, and must not be used for other purpose (especially, it will fail horribly if some partitions have been mounted).

Useful info

You can find the original documentation of AutoInstall here.

Or as one large raw HTML file (tarred): Media:auto_inst.tar.bz2

From DrakX README:

Making screenshots through network

On a test machine, make a network install, switch to console (ctrl-alt-F2), enter:

% xhost+

then, on another computer:

% DISPLAY=test_machine:0 xwd -root | convert - screenshot.png

Virtual consoles

During install, a lot of interesting stuff can be found in different places: in consoles and in files. To switch to console 2 for example, do Ctrl-Alt-F2 from the X install.

• alt-F1: the stdout of the install. Not very interesting stuff
• alt-F2: simple shell. Quite a lot of commands are available but as they are written in perl (for space), they do not handle the very same options as normally. After install, you can do chroot /mnt to see your system just like after rebooting. rpm -qa works for example.
• alt-F3: a lot of interesting things. Be careful, some ERROR messages are not interesting.
• alt-F4: kernel's place, i.e. the output of dmesg.
• alt-F7: the graphical install lives there

Log files

• /tmp/ddebug.log: same (or nearly the same) as alt-F3
• /tmp/syslog: same as alt-F4
• /mnt/root/ddebug.log: at the end of each step, DrakX tries to backup /tmp/ddebug.log to /mnt/root. Available only after mounting of /mnt.
• /mnt/root/install.log: the log of the installation (or upgrade) of the rpms
• /mnt/root/auto_inst.cfg.pl: a kickstart file generated at the end of each step. Can be used in 2 ways: kickstart install or defcfg install. Hopefully you know about kickstart. defcfg is a way to customize the default values in install. For example, French can be the default language with a qwerty keyboard, the auto-partitioning of partitions can be changed...

Command bug puts on usb key (or floppy) a lot of interesting stuff, including files above

Passing options to the installer

Various options

Drakx can use various options to change its behaviour (this list not complete, most of the code is in install2.pm:

• flang, lang: change the translation of the installer. flang will skip the question.
• patch, defcfg: used to patch the installer in live mode (see next chapter).
• display, askdisplay: export the installation on another X11

How to pass an option

The installer will take the options from the kernel command-line (/proc/cmdline), so either add it in isolinux.cfg or add it dynamically in gfxboot (ask for "Kernel Options" to display kernel command-line)

Special mode of installation

Using brltty

By passing the brltty parameter to the kernel you will activate the brltty software, allowing to install Mageia with a Braille display.

Using a serial cable for the installation

The installer should be able to use a serial link, as it is something standard on linux. All you have to do is to pass options to the kernel:

• console=ttyS0,1152008n
• text
• vga=text

And use minicom to do the installation. But this is untested by the author of this document. You can see the documentation of the kernel for the syntax of the console option.

Exporting the X11 display

You can run the graphical installation on another display. Either pass the option display=ip:0, or use askdisplay. You may need to lower the security ( using xhost + ) to make this work.

Debugging the stage2

rebuild the stage 2

One can now rebuild it and set debug to 1 in the spec file, then the generated rpm will contain a mdkinst.sqfs with gdb, bash, ...

Doc for packaging

For example, if you have a local mirror, you can overwrite install/stage2/mdkinst.sqfs with the one from the rpm you just generated, then boot your boot.iso. Once in the stage2, you can run: gdb -q --args perl /usr/lib/libDrakX/install/install2

Alternatively, you can just boot boot.iso in your favourite emulator and just set up a web server with /install/stage2/mdkinst.sqfs tree.

(take from https://bugs.mageia.org/show_bug.cgi?id=4724#c17)

write a test program

Many functions of the installer are used in standalone tools, so in some cases, you can simply run the associated configuration program (bootloader-config, XFdrake...).

Many other functions can be called from a small test program. Eg:

#!/usr/bin/perl use lib qw(/usr/lib/libDrakX); use standalone; #- warning, standalone must be loaded very first, for 'explanations' use common; use interactive; use security::level; use any; my $users = [ map { { name => $_, realname => $_ } } grep { ! /^-/ } @ARGV ]; my $in = 'interactive'->vnew('su'); any::ask_user_and_root($in, { password => "tot"}, $users, security::level::get(), needauser => 1);

(to be run in the perl-install/ directory)

When you have such a reproducer, it's easy to debug, using a combination of perl -d:Trace, perl -d...

Still, the behaviour can be somewhat different.

drakx-in-chroot

drakx-in-chroot is a special way to run the stage2 on a live system. Some steps are skipped completly (partitioning, formatting, bootloader). This means you can't debug those steps. Also note that the code used is sometimes a little different. Still, drakx-in-chroot is quite useful to reproduce some issues, especially since starting the stage2 that way is very fast, no need to reboot a test box.

You can find drakx-in-chroot in package drakx-installer-stage2. For example you can run as root:

/usr/lib/drakx-installer-stage2/misc/drakx-in-chroot /mnt/xxx/devel/cooker/i586 /tmp/foo

It will display the installer in a window using Xephyr or Xnest.

You can run drakx-in-chroot --help to list the command line options.

modifying the stage2

The following implies you have a /export directory containing /export/install/stage2/mdkinst.sqfs.

You can easily adapt to another directory by modifying variable ROOTDEST in drakx/trunk/perl-install/install/Makefile.

modifying the stage2

To uncompress the stage2, use mdkinst_stage2_tool:

% cd /export % misc/mdkinst_stage2_tool --uncompress install/stage2 Creating install/stage2/live from install/stage2/mdkinst.sqfs

You can then modify files in /export/install/stage2/live/.

Note that this command leaves /export/install/stage2/mdkinst.sqfs unmodified. live/ will be preferred to mdkinst.sqfs for nfs,cdrom,hd,drakx-in-chroot installs. But if you need to do http or ftp installs, you can't use live/ so must do misc/mdkinst_stage2_tool --compress install/stage2 after modifying live/.

testing a modification on a perl module

If you want to test a modification on a .pm file in drakx/trunk/perl-install/, do:

cd perl-install/install make install_pms

It's quite cheap, and allow cheap tests combined with drakx-in-chroot.

Note that this command leaves /export/install/stage2/mdkinst.sqfs unmodified but creates /export/install/stage2/live/ which can be modified by hand. But if you need to do http or ftp installs, you can't use live/ so must also do make install_pms compress instead of simply make install_pms.

building the stage2 from scratch

cd perl-install/install make stage2 # or DEBUG_INSTALL=1 make stage2

will build install/stage2/live/ from scratch. To directly build install/stage2/mdkinst.sqfs, use make stage2 compress.

With DEBUG_INSTALL=1, it will add interesting binaries to the stage2: gcc, strace, top...

Note that you must first install all the needed packages. You can do this with urpmi cooker/SRPMS/main/release/drakx-installer-*.src.rpm.

debug the stage2 when it crashes early

When the stage2 crashes, the init process prepares for reboot doing:

sending termination signals...done sending kill signals...done

One way to debug those issues is:

cd perl-install/install make dont_run_directly_stage2

The stage2 won't be run directly, and you will get a shell. You can then run install2 which starts the stage2. If the stage2 crashes, the shell should still be available to run stage2 once again. This is especially useful for nfs installs where /export/install/stage2/live/ can be modified, then install2 can be called again.

updating drakx-installer-stage2 RPM

Getting the source tar.xz

If the change you want in drakx-installer-stage2 has been commited upstream, you can use GIT. If you want to make and test a change, use GIT to checkout the sources.

• Checkout from GIT:

$ clone git://git.mageia.org/software/drakx

• Set/increment the version number in drakx/perl-install/Makefile.config

• Make any local changes, if using git.

• git commit them locally

• Build the tar.xz file, which is used when building an RPM.

cd drakx/perl-install/install make tar

(this will call make git or make dist)

The resulting tar.xz will be: drakx/drakx-installer-stage2-$VERSION.tar.xz and contain any local modifications you have commited to git, including changes not pushed.

Building

• get the source and spec for drakx-installer-stage2, either from the srpm, or from a git clone
• Copy the source generated from above into the SOURCES directory
• Update the spec file to use the new version of the sources
• Install the build deps, using urpmi drakx-installer-stage2.spec
• Rebuild using rpmbuild -ba drakx-installer-stage2.spec

Testing

The resulting RPM will contain /usr/lib(64)/drakx-installer-stage2/install/stage2/mdkinst.sqfs

This is the stage2 installer, and can either be added to a full installer image, or used by boot.iso (stage1) performing a network install.

@TODO (detail the above methods)

• For boot.iso to use it for an install from a local mirror or a correct file tree on a HD, first replace the existing mdkinst.sqfs with the new one in

$path_to_local_mirror/mageia/distrib/cauldron/<arch>/install/stage2/

• Alternatively, after installing new stage2 locally, it can be used in combination with drakx-in-chroot, (however, note that not all installer functionality is available then) e.g.:

cp -R /run/media/<user>/Mageia-5beta2-x86_64/x86_64/install/ /home/<user>/install cp /usr/lib64/drakx-installer-stage2/install/stage2/mdkinst.sqfs /home/<user>/install/stage2/mdkinst.sqfs #Replace the existing mdkinst.sqfs with the one to test su mount -o bind /home/<user>/install /run/media/<user>/Mageia-5beta2-x86_64/x86_64/install/ /usr/lib64/drakx-installer-stage2/misc/drakx-in-chroot /run/media/<user>/Mageia-5beta1-x86_64/x86_64/ /tmp/test

Customisation of the install by patching it

Drakx can be fully customised without recompilation or modification of the code, by using a perl script run in the context of the installer used to change variables or functions. This approach has many advantages over a real patch:

• this requires no modification of the source code, so the file can be changed and the patch still be valid.
• you have access to all the power of perl and the library used by install, allowing to add questions, and test them without running a full install
• it can be added on an iso very quickly, or on a network installation without changing anything in the layout

Examples: patches fixing bugs on mdv 2008.0 installer.

One typical use is to remove a step of the installer:

package install::install2; undef *selectLanguage; *selectLanguage = sub { 1 };

You can also use it to set some default variables. In fact, the auto_inst file is using the same mechanism.

The easiest way to use this is to place a file install/patch-oem.pl on the CD. This file will be read if it exists. You can also place a file named as you want, and use option defcfg=filename, to load this patch.

If you need to add some backgrounds, or change some files, you can also place an rpm in the file install/oem-theme.rpm, it will be installed with the command rpm -U (code in file installs_step.pm )

Testing the patch without burning a cd

Using OEM patch in the tree & drakx-in-chroot

Stage 2 of the installer can be run on a live system. First, you need to get a Mageia tree, the same you can find on cd or ftp mirror. You can use mount -o bind to not copy the whole tree on your disk:

mount /mnt/cdrom/ cp -R /mnt/cdrom/install/ ~/install sudo mount -o bind ~/install /mnt/cdrom/install/ emacs ~/install/patch-oem.pl

You can then run drakx-in-chroot from package drakx-installer-stage2 as root:

/usr/lib/drakx-installer-stage2/misc/drakx-in-chroot /mnt/cdrom /tmp/foo

It will display the installer in a window using Xephyr or Xnest.

If you get the following errors (can happen if you already tried the command before installing x11-server-xephyr, when rerunning it after installing that package):

umount: /tmp/drakx-in-chroot/dev: not mounted /tmp/drakx-in-chroot/dev is busy

then do:

rm -fvr /tmp/drakx-in-chroot/dev

and try again

Using a patch & regular ISO

Alternatively, the patch can be saved as patch.pl on some floppy or USB key that will be plugged to the machine that will be installed. Then you need to add the "patch" option to the command line when booting (eg: "linux patch" instead of just <enter> at the boot.iso prompt)

Patching existing mdkinst.sqfs

cp install/stage2/mdkinst.sqfs{,.bak} unsquashfs install/stage2/mdkinst.sqfs

do your changes into squashfs-root/usr/lib/libDrakX
eg:
cd squashfs-root/usr/lib/libDrakX; patch -p0 < /where/it/is/patch.diff
and then replace old mdkinst.sqfs with patched version:

rm -f install/stage2/mdkinst.sqfs mksquashfs squashfs-root/ install/stage2/mdkinst.sqfs