path: root/docs/README

Well here is a little description of what DrakX needs to work in comparison
to the RH newt install.

********************************************************************************
* CVS **************************************************************************
********************************************************************************
Like all good free software, DrakX is in CVS :)

You can access it at http://www.mandrakelinux.com/cgi-bin/cvsweb.cgi/gi

or via

export CVS_RSH=ssh
export CVSROOT=:ext:anoncvs@cvs.mandrakesoft.com:/cooker
cvs checkout gi
 (enter password 'cvs')


This is only read-only access. If you want more, tell me (pixel@mandrakesoft.com)

Alas, all is not in CVS, a lot of things come from rpm packages which you must
install.

Please note that redoing *all* the stuff is not for the faint of heart. I myself
sometimes wonder what the whole make does :-%
Instead, changing some .pm files is quite easy (nice interpreted language)

********************************************************************************
* Making your custom install ***************************************************
********************************************************************************
If you have your own rpms you want to add, or make your own updated cdrom, you
just have to issue:

% gendistrib --noclean --distrib <DIRS>

Where <DIRS> is the root of all the media that the install will see, this first
one is the main one :

(1) network or 1-cdrom installs
	DIRS == the root directory of the Distribution

(2) multi-cdrom install
	DIRS == the root directories of all the media that the install will see

``gendistrib'' will scan the file media/media_info/hdlists in the main root
directory (the first one in DIRS) to search for all media used. Typically you
use media/main for RPM packages repository.
For multi-cd, please use media/main or media/foo, etc.
For one CD or a network/hd volume, please use media/main.

Optionnally, you can modify ``media/media_info/rpmsrate''; this file manages
the relative importance of the files, and thus their installation or not.

To modify the code of stage2, use "misc/mdkinst_stage2_tool install/stage2" to generate "install/stage2/live".
When you are done use "misc/mdkinst_stage2_tool install/stage2" again, the "rm -rf install/stage/live".
See below for information about these files.

********************************************************************************
* FILES ************************************************************************
********************************************************************************
First here are the different things needed :

media/media_info/hdlists
	description of the available install media.
	format is one line for one medium as
		<hdlist_name> <rpms_directory> <description>
	<hdlist_name> should be match regexp /hdlist\S*.cz2?/
	for example (two cd install) you get
		hdlist1.cz	Mandrake/RPMS1	Boot CD
		hdlist2.cz	Mandrake/RPMS2	Extension CD

media/media_info/hdlist*.cz
	table of rpm's headers, referred by ``hdlists''
	their contents can be listed using ``packdrake -l <hdlist_file>'' or
	or ``parsehdlist <hdlist_file>''.
	! Need to be remade when media/main changes (with ``gendistrib'') !

media/media_info/depslist.ordered
	for each packages, tell which package it depends on. Also contains the
	size for some (obscure) bloody reasons.
	! Need to be remade when media/main changes !
	(with ``gendistrib --noclean --distrib .'')

media/media_info/compssUsers

media/media_info/rpmsrate
	ranks and classify packages, so that the installer will know which
        ones to install. format is :
		<intern_group>
			<level> <packages>
	where <intern_group> is a symbolic name used in media/media_info/compssUsers* files,
	and <level> defines importance level as described below :
		5	must have
		4	important
		3	very nice
		2	nice
		1	maybe
	by default (for non expert), group selects packages for level 4 (important)
	and 5 (must have). export mode add 3 (very nice) level. other level (below 2)
	can only be selected using individual package selection.

install/stage2/live
	live system used on certain installs. See ``Ramdisk or not'' below for
	more.

install/stage2/mdkinst.clp
	for the compressed loopback of install.
	generated from install/stage2/live tree using misc/mdkinst_stage2_tool

install/stage2/rescue.clp
	rescue ramdisk. create_compressed_fs iso file
	this is the ramdisk loaded when typing rescue on boot prompt.

install/images/*.img
	floppy boot images to use with DrakX. Use:
	- cdrom.img for cdrom install
	- network.img + network_drivers.img for ftp/nfs install (non-pcmcia devices)
	- hd_grub.img for hard-disk install (see http://qa.mandrakesoft.com/hd_grub.cgi)
	- pcmcia.img for pcmcia install (see ``PCMCIA install'' below for more)

install/images/boot.iso
	iso image to burn enabling any install (cdrom/hd/nfs/ftp)

********************************************************************************
* logs *************************************************************************
********************************************************************************
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 normal.
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 carefull, some ``ERROR'' messages are
not interesting.
- alt-F4: kernel's place. aka the output of dmesg.
- alt-F7: the graphical install lives there

- command "bug" puts on floppy lots of interesting stuff.
- /tmp/stage1.log: same as alt-F3 part when stage1 run (e.g. actions
  before graphical install really begins)
- /tmp/ddebug.log: (nearly the) same as latter alt-F3 part
- /tmp/syslog: same as alt-F4
- /mnt/root/drakx/ddebug.log: at the end of each step, DrakX tries to backup
  /tmp/ddebug.log to /mnt/root/drakx. Available only after mounting of /.
- /mnt/root/drakx/install.log: the log of the installation (or upgrade) of the rpms
(just like rpm's /mnt/tmp/(install|upgrade).log)
- /mnt/root/drakx/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-partitionning partitions can be changed, the default user class can be
set to developer (!)...

********************************************************************************
* po translation files *********************************************************
********************************************************************************
DrakX uses .po files for its translation. A script takes the different
strings out of the .pm files. It generates the DrakX.pot file which contains
all the english strings to translate.

********************************************************************************
* PCMCIA install ***************************************************************
********************************************************************************
If the media you use to install is a pcmcia device, use the pcmcia boot disk.

********************************************************************************
* modules **********************************************************************
********************************************************************************
Modules can be found in at least 2 places:
- in /modules/modules.mar
- in /lib/modules.cz<KERNEL_VERSION_RELEASE>

/modules/modules.mar is used in mdk-stage1. It contains only modules
interesting for one kind of install. For example in an hd install, it
contains scsi modules. For a network install, it contains network card
modules. (To create, extract or view files in a ``mar'' archive, please
use gi/mdk-stage1/mar/mar; this is basically an archive format meant to
be minimalistic)

/lib/modules.cz<KERNEL_VERSION_RELEASE> contains all modules, it is used
in stage2.


To manually install a module during install, switch to console #2
and type "modprobe <modulename>". The modprobe program is a perl
wrapper around /usr/bin/insmod. It uses the dependencies found in
/modules/modules.dep (stage1).

/usr/bin/insmod is a wrapper around /usr/bin/insmod_. It just extracts the
module out of /lib/modules.cz in /tmp. Then it calls insmod_.

/usr/bin/insmod_ is the real prog (which you usually find in /sbin/). You need
to give it the complete path.

********************************************************************************
* Making screenshots ***********************************************************
********************************************************************************
1. easy solution: press "F2"!

2. 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

********************************************************************************
* Auto install *****************************************************************
********************************************************************************
A powerful auto-install system is available. It allows performing
an install without any human interaction.

To feed automatic parameters to the stage1 part (the textmode
part - might not be necessary for you if you plan to do
cdrom-based auto-installs, but mostly highly needed when doing
network installs), please refer to ../mdk-stage1/doc/TECH-INFOS.

About the stage2 part (the actual installer, at the time you're
(usually) running in graphical mode), please refer to the nice
documentation written by David Eastcott. Either install the
package "drakx-autoinstall-doc" from contrib, or browse:

http://members.shaw.ca/mandrake/drakx/9.0/HTML/

The previous document will explain you how to setup the contents
of the auto_inst.cfg file. Note that you have 3 alternatives for
providing this file:
- from a floppy disk; use "kickstart=floppy" as kernel parameter,
  as explained in the document
- from the installation volume itself; put the file in the
  "install" directory of the installation volume; use
  "kickstart" only, or "kickstart=filename" to specify another
  filename than auto_inst.cfg
- specified by the network; setup your DHCP server to provide the
  "bootfile" parameter, this file will be used as the
  "auto_inst.cfg" file; in this case you also need to provide the
  "netauto" boot parameter

In any case, if the specified file ends with -IP or -IP.pl, IP
will be substituted by the IP address of the machine, when doing
a network install. Might be useful so that you can control all
your auto installs from your server.

********************************************************************************
* Miscellaneous ****************************************************************
********************************************************************************
>  o Media access methods: nfs, ftp, http, hd, cdrom
>  o Stages: init, stage1, stage2
>    - What exactly each stage does

init loads stage1
stage1 loads stage2, from various medium type

stage2 is too big to fit on a floppy, that's why stage1 exists

>    - How each stage relates to the various media access methods

stage1 knows only how to access to the media is compiled for. It
contains only the kernel modules needed for that media. For eg,
the nfs/ftp/http stage1 (network.img floppy) doesn't contain scsi
modules nor ide.

>    - How one stage terminates and another begins. i.e., How does
>      stage1 find, mount, and launch stage2?

  /sbin/init just starts /sbin/stage1, and monitors its
execution; it's here to cleanly umount the partitions when stage1
or stage2 dies/finished

  /sbin/stage1 takes care of mounting stage2 (in ramdisk if
necessary) then it execs /usr/bin/runinstall2 (thus, stage2
replaces stage1, and init then monitors stage2)

>  o Text and Graphic mode installers
>    - Architectural overview of each

have a look at gi/docs/object_class.fig


********************************************************************************
* OEM **************************************************************************
********************************************************************************
> I am a system OEM in Bangalore,India selling systems bundled with
> Mandrakelinux. The problem is that with every system I sell, I need to
> install & configure the system which takes HOURS!. Can I do a diskcopy
> instead?
> 
> Please Help. This is a major bottleneck for  me.

many solutions:

- make an install on drive hdb, then :
      dd if=/dev/hdb of=/dev/hdc
  but you should make sure the hardware is *REALLY* identical.

- try the oem feature
   3. - burn a cd out of *latest* cooker or 8.0 and above.
      - boot on it telling "oem" to syslinux
      !! it will destroy every data on the harddrive or
         resize (or use free space) if *ONLY* one fat partition is defined !!
      - you now have a very automated install matrix 
      (duplicate it with "dd if=/dev/hdb of=/dev/hdc bs=1M count=730")

    put the harddrive in the oem box, the user will now have an *very* automated
    install, just asking the root password and user password, and some other
    question according its hardware.

   4. just like 3. but you may have to mount /cdrom after typing rescue on
      syslinux prompt (oem script do it automatically if a automatic boot nfs
      network has been done as server is known). under /cdrom may be anything
      as long as it provides an installation tree of Mandrakelinux.
      after that run oem script by typing "/etc/oem -f" for normal installation
      or "/etc/oem -f server" for server installation (normal with server installed).

   5. (just like 3. without burning a cd, doing the first part by hand)
      have a look at the /etc/oem script on the rescue and do it by hand...


cu Pixel, fpons.


comments:
1. maybe copy unnecessary things -> take too long
   solution -> use bs=8k count=xxxx 
2. kernel_reread can be found on the new rescue, source is also at end of this
mail. This solution works with one partition. Can be easily enhanced to many
primary partitions... For extended partitions, more complicated, but not much :)
3. has just been added in latest cooker. It may still have some pb. The main
current limitation is IDE only, though it can be fixed easily for special cases.

--------------------------------------------------------------------------------
#include <stdio.h>
#include <sys/mount.h>
#include <fcntl.h>

void die(char *msg)
{
  perror(msg);
  exit(1);
}

void kernel_read(char *dev)
{
  int fd;
  if ((fd = open(dev, O_RDONLY)) == -1) die("can't open device");
  ioctl(fd, BLKRRPART, 0);
  close(fd);
}

int main(int argc, char **argv) 
{
  if (argc != 2) {
    fprintf(stderr, "usage: kernel_read_part <hard drive device>\n");
    exit(1);
  }
  kernel_read(argv[1]);
}