HOWTO_Gentoo_Diskless_Install

Introduction

This HOWTO provides instructions for booting a Gentoo system over a network on a client computer. The described boot procedure requires a server computer with installed Gentoo and can be used to boot, for example, any diskless client supported by Gentoo. Both the client and the server require certain PXE functionality. Specifically, the client computer requires a network interface card that can boot an operating system using the PXE network boot procedure. Most networking interface hardware supports this functionality.

The client computer requires loading files and data from a server computer. The client computer can be a diskless machine. Certain usability aspects such as responsiveness of your client computer will depend on the quality of your network and the client server hardware. The client computer can utilize a disk or other mass storage media to gain extra computational power but it is not required on the client computer.

A computer set up according to these instructions is a fully-fledged Gentoo (Linux) machine that just happens to have no physical disc drive containing its root file system. The machine is capable of locally running a full suite of processes that may include network servers like Apache or Squid, X servers (XFree or XOrg), and X client applications (KDE or Gnome environments, browsers etc.). Contrast that with a thin client of the type that the Linux Terminal Server Project is aiming to provide: a bare minimum machine running an X server to provide display facilities to X client applications running on another machine. The LTSP client is just an X-terminal, which may be diskless but need not be.

The server computer must be able to provide initial services required at boot time such as DHCP and NFS functionality to the client computer.

In the following description the client is called "eta" and the server "sigma". Adapt this to your preferences. The "sigma" server has a static IP address that is 192.168.1.20.

The procedure is comprised of the following steps:

1. Server setup
2. Gentoo setup on the server
3. Booting the client
4. Enable XFree XDMCP
5. Enjoy ...

Server setup

Of course, I won't talk here about the complete setup of the server. For this follow the install guide provided in the Documentation area of the Gentoo website at http://www.gentoo.org/doc/en/diskless-howto.xml

Create directories

The first thing to do is to create the directories where your diskless system will be stored. Personally, I created a directory called /diskless on which I created a directory for each diskless host :

# mkdir -p /diskless/eta

Here eta is the name of one of my diskless desktop.

A good thing would be to directly create a "boot" directory for each host :

#  mkdir /diskless/eta/boot

Please be aware of the circumstance that the in.tftpd daemon may be configured to chroot to /diskless: in that case you should prevent using links pointing outside /diskless.

DHCP and TFTP setup

The client will get boot informations using DHCP and download all the required files using TFTP. Here's how to set this up. To get DHCP running, you can choose to install dhcp or dnsmasq. If you are running a small network, you might already have dnsmasq running for name resolution/dhcp. Below you can see the needed config change to make it PXE-capable.

Just run one of the following commands, depending on your choice:

1. USE="netboot" emerge -av dhcp tftp-hpa grub
2. USE="netboot" emerge -av dnsmasq tftp-hpa grub and configure it for your basic needs. Then, add the following in /etc/dhcp/dhcpd.conf :

option domain-name "domain";
default-lease-time 600;
max-lease-time 7200;
ddns-update-style interim; //ad-hoc is now depreciated

subnet 192.168.1.0 netmask 255.255.255.0 {
    range 192.168.1.1 192.168.1.30;
}
option option-150 code 150 = text ; 
host eta { 
    hardware ethernet 00:00:00:00:00:00; 
    next-server 192.168.1.20;
    fixed-address 192.168.1.10; 
    option option-150 "/eta/boot/grub.lst"; 
    filename "/eta/boot/pxegrub"; 
}

This provides a static IP adress for the client and the path of a PXE boot image, here pxegrub. You have to replace the MAC address of the Ethernet card of the client, server addres(next-server) where your tfpt server lived and the directory where you will put the client files with the one you use.

domain-needed
bogus-priv
local=/localdomain/
domain=localdomain
dhcp-range=192.168.1.10,192.168.1.100,255.255.255.0,6h
dhcp-host=00:00:00:00:00:00,192.168.1.10,eta,6h
dhcp-boot=/eta/boot/pxegrub,server-hostname,192.168.1.1
dhcp-option=150,/eta/boot/grub.lst

Same as above, static IP (and hostname) for the MAC address 00:00:00:00:00:00. Also Domainname ist provided (replace localdomain!). 'dhcp-range' limits the number of available IP's. The last line specifies the path to the PXE-config-file, the server-hostname, and the server-ip.

For TFTP, I emerged "net-ftp/tftp-hpa" that is really easy to use. In /etc/conf.d/in.tftpd, I put the following :

INTFTPD_PATH="/diskless" 
INTFTPD_USER="nobody" 
INTFTPD_OPTS="-u ${INTFTPD_USER} -l -vvvvvv -p -c -s ${INTFTPD_PATH}"

Another (possibly easier) option for a TFTP server if you use dnsmasq is to use the inbuilt tftp server capabilities.

enable-tftp
tftp-root=/diskless

If running without xinetd or similar, append the following to your hosts configuration. Adjust for your network.

in.tftpd: 192.168.1.0/255.255.255.0

Setup GRUB

To provide PXE booting I use GRUB. I've done this because I'm already using GRUB on several machines and I'm happy with.

As of grub 0.94-r1 (and later), it now builds pxegrub properly. It enables diskless booting, and compiles in all supported GRUB network drivers.

# cp /usr/lib/grub/pxegrub /diskless/eta/boot/pxegrub

Now edit the GRUB config file for the the diskless client :

# nano -w /diskless/eta/boot/grub.lst

And put the following inside (adapt the example for your needs) :

default 0
timeout 30
title=Diskless Gentoo 
root (nd)
kernel /eta/bzImage ip=dhcp root=/dev/nfs nfsroot=192.168.1.20:/diskless/eta

For the nfsroot option, the IP address is the one of the server and the directory is the one where your diskless client files are located (on the server).

Setup PXELinux

The alternative method of providing PXE is using pxelinux from sys-apps/syslinux.

default gentoo
prompt 1
timeout 10

label gentoo
  kernel /eta/bzImage
  append ip=dhcp root=/dev/nfs nfsroot=192.168.0.31:/diskless/eta

Setup NFS

NFS is quite easy to configure. The only thing you have to do is to add a line on the /etc/exports config file :

# /etc/exports: NFS file systems being exported. See exports(5).
/diskless/eta eta(rw,sync,no_root_squash)

If you are using NFSv4:

# /etc/exports: NFS file systems being exported. See exports(5).
/diskless/eta eta(rw,nohide,insecure,no_root_squash,no_subtree_check,sync)

Update your hosts

One important thing to do now is to modify your /etc/hosts file to fit your needs. In my configuration, I have the following on this file (I just replaced the domain name) :

127.0.0.1 localhost
192.168.1.10 eta.example.com eta
192.168.1.20 sigma.example.com sigma

Gentoo-client setup on the server

Stage tarballs and chroot

On the server (sigma), simply extract the stage3 tarball in the directory which will be mounted as root directory by the client (eta).

# cd /diskless/eta/
# tar -xvjpf  /mnt/cdrom/gentoo/stage3-*.tar.bz2 
# mount -t proc /proc /diskless/eta/proc 
# cp /etc/resolv.conf /diskless/eta/etc/resolv.conf 
# chroot /diskless/eta/ /bin/bash 
# env-update 
# source /etc/profile

Now follow the usual steps ... until the kernel configuration

Kernel configuration

Remember that the kernel will be executed on the client machine, so it should be tailored for the client's architecture: e.g., if your server is a Pentium4 and the client an Opteron, compile for Opteron. The same goes for all kernel components.

When you do the "make menuconfig" of your kernel configuration, don't forget to enable the following options with the others recommended into the install howto:

- Your network card driver. This needs to be built-in, not a module, because it is required for booting. Same for the following.

- Options

[*] TCP/IP networking
[*] IP: kernel level autoconfiguration (CONFIG_IP_PNP)
[*] IP: DHCP support (CONFIG_IP_PNP_DHCP)
[*] IP: BOOTP support (CONFIG_IP_PNP_BOOTP)

<*> NFS file system support 
[*] Provide NFSv3 client support (CONFIG_NFS_V3)
[*] Root file system on NFS (CONFIG_ROOT_NFS)

Changing fstab

Just let the following on the file :

192.168.1.20:/diskless/eta / nfs defaults,nolock 0 0
/dev/cdroms/cdrom0 /mnt/cdrom iso9660 noauto,ro 0 0
proc /proc proc defaults 0 0 
tmpfs /dev/shm tmpfs defaults 0 0

Changing conf.d/net

The bootscript net.lo starts all network cards on a gentoo system. At first it shuts down the network interface. After the bootscript starts the interface again with the right IP configuration. On a diskless system this attempt doesn't work. The network can't be stopped while the system is running! A config line like the following solves the problem:

 config_eth0=( "noop" "192.168.1.2 netmask 255.255.255.248" )

Because of the parameter "noop" the network interface gets only configured if it's not already configured.

Bootloader

Do not install any bootloader because we already have one on the server machine (pxegrub). If you set a MBR on the client's disk (assuming you have one at all), it will simply be ignored as the machine boots from the network, not the disk.

Of course you may want it as a local safety net in case things go wrong, in that case go ahead.

Restart the server

Finish the install and restart the server. It should boot like the others times (if not you have probably made a mistake ). Start DHCP, TFTPD and NFS.

Booting the client

Now, just boot the client. Configure the bios and the network card to use PXE in first to boot (before CD-ROM or floppy).

The network card should get an IP address using DHCP and download the GRUB PXE image using TFTP.

Then, you should see a nice black and white GRUB bootmenu where you will select the kernel to boot and press Enter.

If everything is ok the kernel should boot, mount the root filesystem using NFS and provide you the so waited login prompt.

If neither your network card nor your BIOS provide any PXE boot code, look at [1] for bootable CD / floppy images. If it didn't work, go to the trouble-shooting page.

Enjoy ...

Ok, now you have a nice diskless desktop that has all this stuff on a big server located somewhere else ... great, no?

If your client is too slow to run applications locally, you can use it only as X display and run the X applications on a server. For that, emerge XFree on the client's filesystem. To enable XDMCP on the server, follow the XDMCP-HOWTO. Then, on the client, do X -broadcast, and you should get the server display manager login prompt.

Also have a look at NX. The NX client and GPL version of the NX server are in portage. Details at http://nomachine.com

If you are happy with this tutorial, like me, post a message here to congratulate me.

If not, maybe because something gone wrong and my howto doesn't help, search on this nice forum before asking me ... There's a lot of other diskless experiments and you will maybe find your answer.

If you want me to add something to this howto just post here too ...