Gentoo Wiki


This article is part of the HOWTO series.
Installation Kernel & Hardware Networks Portage Software System X Server Gaming Non-x86 Emulators Misc



This HOWTO will show you how to make a diskless X terminal with splash and sound on a read-only root

It is intended for people who know a minimum about diskless boot and Gentoo

The steps will be as following :

  1. Install a few services on the server : dhcp, tftp, nfs and xdm
  2. Install the diskless in a directory of the server

Some notations :

The configurations given are just examples, you will have to modify them to fit your needs


Server configuration


First we install the dhcp server :

emerge dhcp

Then we configure it :

File: /etc/dhcp/dhcpd.conf
# Configuration file for ISCD dhcpd

ddns-update-style             none;
default-lease-time            86400;
max-lease-time                604800;
use-host-decl-names           on;

subnet netmask {
  option domain-name            "domain";
  option subnet-mask  ;
  option broadcast-address;
  option routers      ;
  option domain-name-servers;

group {
  next-server           server;
  option root-path      "server:/diskless_gentoo";
  filename              "/pxelinux.0";

  host diskless1 {
    hardware ethernet   00:01:02:03:04:05;
    fixed-address       diskless1.domain;

  host diskless2 {
    hardware ethernet   00:01:02:03:04:06;


Note: You set a permanent ip address for every diskless terminal in fixed-address field, so you actually do not need the range command. It may be necessary only if you have also another computers in your net.

Note2: Actually the fixed-address must be set to ip address (or resolvable dns name), which is outside the above defined range. This is because the range command defines dynamic address' pool, and fixed-address is... fixed (not dynamic). :-)

If you used dns names, they must be known for your server's resolver. I.e. you may add them to your /etc/hosts:

File: /etc/hosts diskless1.domain diskless1 diskless2.domain diskless2

And finally we start it :

rc-update add dhcp default
/etc/init.d/dhcp start


Installation :

emerge atftp

Configuration :

File: /etc/conf.d/atftp
# Config file for tftp server

TFTPD_OPTS="--daemon --user nobody --group nobody"

Start :

rc-update add atftp default
/etc/init.d/atftp start


Installation :

emerge nfs-utils

Configuration :

File: /etc/exports
/diskless_gentoo  diskless.domain(ro,sync,no_root_squash)

Start :

rc-update add nfs default
/etc/init.d/nfs start


Installation :

emerge xorg-x11
emerge xdm

(it is no longer included in xorg and must be emerged separately)

Configuration : Edit /etc/X11/xdm/Xaccess to add this line at the end to enable the diskless to login on xdm:

File: /etc/X11/xdm/Xaccess

# or ip address:

# wildcards are allowed:

Edit /etc/X11/xdm/Xservers to comment the last line (or xdm will start a X server on the server) :

File: /etc/X11/xdm/Xservers
#:0 local /usr/bin/X

Edit /etc/X11/xdm/Xsetup_0 to comment the last line (prevents xdm from adding a console to the xdm login screen)

File: /etc/X11/xdm/Xsetup_0
# xconsole -geometry 480x130-0-0 -daemon -notify -verbose -fn fixed -exitOnFail

Edit /etc/X11/xdm/xdm-config to comment the last line

File: /etc/X11/xdm/xdm-config
! SECURITY: do not listen for XDMCP or Chooser requests
! Comment out this line if you want to manage X terminals with xdm
!DisplayManager.requestPort:    0

Start xdm:

rc-update add xdm default
/etc/init.d/xdm start

If you use gdm as desktop manager start gdmsetup and go the tab "Security" Make sure 'Enable XDMCP' is checked.


If you want you may use xfs to provide fonts to the diskless teminal:

emerge xfs

Edit /etc/X11/fs/config and comment the following line:

File: /etc/X11/fs/config
 #no-listen  =  tcp

Edit /etc/conf.d/xfs:

File: /etc/conf.d/xfs

Start :

rc-update add xfs default
/etc/init.d/xfs start

The server is now ready

Diskless installation

Now we will install the diskless and prepare it to run on read only

It looks a lot like a normal installation , with a few skipped steps

Base System

Preparation of the directory

mkdir /diskless_gentoo
cd /diskless_gentoo

Stage3 tarball

tar -xjf stage3*.tar.bz2
rm stage3*.tar.bz2

Portage tree

We actually already have portage on our server in /usr/portage, so we need only to bind it to /diskless_gentoo/usr/portage.

emerge --sync
mkdir -p /diskless_gentoo/usr/portage
mount --bind /usr/portage /diskless_root/usr/portage

We edit /diskless_gentoo/etc/make.conf to change the usual stuffs

File: /diskless_gentoo/etc/make.conf
# These settings were set by the catalyst build script that automatically built this stage
# Please consult /etc/make.conf.example for a more detailed example
CFLAGS="-Os -march=pentium2 -pipe"
USE="-apm -arts -berkdb -curl -directfb -eds -fortran -gdbm -gif -gnome -gpm -gstreamer -gtk -gtk2 -ipv6 -java -kde -motif -mysql -nls -pam -perl -python -qt -samba -sdl -spell -tcltk -tcpd -usb -xml2"
USE="${USE} alsa font-server network nodrm nomotif nptl oggvorbis openal opengl oss threads"

If your /etc and /diskless_gentoo are within the same filesystem, you may consider invoking one or both of the following commands:

rm /diskless_gentoo/etc/hosts; ln /etc/hosts /diskless_gentoo/etc
ln /etc/resolv.conf /diskless_gentoo/etc

Note: Hard links are necessary - soft links will not work with nfs! This way you will always have the same resolver configuration on the server and on the diskless client. I.e. whenever you edit your server's /etc/hosts, your client's config will be also updated automagically. Later you may consider also similar "wrapping" of other configuration files. Please be careful!

And we continue with the usual

mount -t proc none proc
# if you omitted above mentioned hard linking:
cp /etc/resolv.conf etc

Then we chroot

chroot /diskless_gentoo /bin/bash

From here we are in the diskless

source /etc/profile
ln -sf /usr/portage/profiles/default-linux/x86/2005.1 /etc/make.profile
ln -sf /usr/share/zoneinfo/CET /etc/localtime


Now the kernel

emerge gentoo-sources
cd /usr/src/linux
make menuconfig

note that if the server system has a 64 bit arch, (x86_64) and the clients are x86, you must set a 32bit chroot environment; see the Offical 32-bit Chroot HOWTO.

You will need to activate :

Linux Kernel Configuration: DHCP
 Networking  --->
  Networking options  --->
   [*]   IP: kernel level autoconfiguration
   [*]     IP: DHCP support

Linux Kernel Configuration: NFS root
 File systems  --->
  Network File Systems  --->
   <*> NFS file system support
    [*]   Provide NFSv3 client support
   [*] Root file system on NFS

Linux Kernel Configuration: Initrd
 Device Drivers  --->
  Block devices  --->
   <*> RAM disk support
   [*]   Initial RAM disk (initrd) support

Linux Kernel Configuration: Splash
 Device Drivers  --->
  Graphics support  --->
   <*> Support for frame buffer devices
   <*>   VESA VGA graphics support
   [*] Support for the framebuffer splash

Compilation :

make bzImage
make modules modules_install
cp arch/i386/boot/bzImage /boot/linux-2.6.14-gentoo-r2-1diskless
cp /boot/
cp .config /boot/config-2.6.14-gentoo-r2-1diskless


Now we need to configure the system

/etc/mtab need to be writeable but the root is read only , a trick is to use /proc/mounts which contains the same things as mtab

ln -s /proc/mounts /etc/mtab

In /etc/fstab we will define a few directories to mount in tmpfs to be able to write in them

File: /etc/fstab
server:/diskless_gentoo /               nfs             noauto,ro               0 0
proc                    /proc           proc            defaults                0 0
shm                     /dev/shm        tmpfs           nodev,nosuid,noexec     0 0
tmpfs                   /var/lib/init.d tmpfs           rw                      0 0
tmpfs                   /var/run        tmpfs           rw                      0 0
tmpfs                   /var/log        tmpfs           rw                      0 0
tmpfs                   /var/lock       tmpfs           rw                      0 0
tmpfs                   /tmp            tmpfs           rw                      0 0
tmpfs                   /var/lib/xkb    tmpfs           rw                      0 0

Network :

In /etc/conf.d/hostname we set the hostname:

File: /etc/conf.d/hostname

Or you may try the hostname to be "dynamic" (so that every terminal had its own hostname).

File: /etc/conf.d/hostname
HOSTNAME="`dmesg|grep host=|sed -e 's/.*host=//' -e 's/,.*$//'`"
[ -n "$HOSTNAME" ] || HOSTNAME="diskless"

Note: The above script looks in dmesg, because the hostname was already sent to kernel by dhcp server. It is in my opinion extremely ugly. Does anyone have idea how to recognize the hostname? Maybe it is already somewhere in /proc or /sys and is waiting to be read by us? :-)

In /etc/conf.d/net we set the domain name

File: /etc/conf.d/domainname

We may not use /etc/init.d/net.eth0, because the kernel have to configure networking itself during boot up. Just in case you may remove it:

rm /etc/init.d/net.eth0


We need to create the sshd keys, normaly sshd creates them at the first start, as the root is read-only, we need to create them before

 ssh-keygen -t rsa1 -b 1024 -f /etc/ssh/ssh_host_key -N ''
 ssh-keygen -d -f /etc/ssh/ssh_host_dsa_key -N ''
 ssh-keygen -t rsa -f /etc/ssh/ssh_host_rsa_key -N ''

And we add it to the boot

rc-update add sshd default

Root password


Keymap (if needed)

nano /etc/conf.d/keymaps => KEYMAP="fr"


First we install the packages

emerge splash-themes-livecd

Then we create an initrd which will be used to display the splash image at the boot

splash_geninitramfs -v -g /boot/fbsplash-livecd -r 1280x1024 livecd-2005.1


To boot in pxe we will use pxelinux , part of the syslinux package

emerge syslinux
cp /usr/lib/syslinux/pxelinux.0 /boot
mkdir /boot/pxelinux.cfg

The file /boot/pxelinux.cfg/default contains the command line to pass to the kernel

File: /boot/pxelinux.cfg/default
DEFAULT /linux-2.6.14-gentoo-r2-1diskless
APPEND ip=dhcp root=/dev/nfs ro nfsroot=IP_SERVER:/diskless_gentoo video=nvidiafb:ywrap,mtrr,1280x1024-32@60 splash=silent,fadein,theme:livecd-2005.1 initrd=/boot/fbsplash-livecd quiet CONSOLE=/dev/tty1

Replace IP_SERVER by the ip of your server

nvidiafb is for the nvidia cards , the generic driver is vesafb (see your kernel)


We install it

emerge xorg-x11

Configure it

nano /etc/X11/xorg.conf 

(or any other way)

If you don't use xfs, configure static font paths:

File: /etc/X11/xorg.conf
Section "Files"
        RgbPath      "/usr/X11R6/lib/X11/rgb"
        ModulePath   "/usr/X11R6/lib/modules"
        FontPath     "/usr/X11R6/lib/X11/fonts/misc/"
        FontPath     "/usr/X11R6/lib/X11/fonts/TTF/"
        FontPath     "/usr/X11R6/lib/X11/fonts/Speedo/"
        FontPath     "/usr/X11R6/lib/X11/fonts/Type1/"
        FontPath     "/usr/X11R6/lib/X11/fonts/75dpi/"
        FontPath     "/usr/X11R6/lib/X11/fonts/100dpi/"
        FontPath     "/usr/X11R6/lib/X11/fonts/bitstream-vera/"

Or if you wish to use font server:

File: /etc/X11/xorg.conf
Section "Files"
        RgbPath      "/usr/X11R6/lib/X11/rgb"
        ModulePath   "/usr/X11R6/lib/modules"
        FontPath     "tcp/server:7100"

And to finish we need to launch X at the boot, but in query mode not via a local xdm

File: /etc/conf.d/local.start
X -query server&

Note: Above did not work for me! So I edited /etc/inittab instead, and everything works fine:

File: /etc/inittab
c7:2345:respawn:/usr/bin/X -query server


We will use esd as it is the most implemented , nas could also be used

emerge esound

The default configuration is fine

rc-update add esound default

We will also need to set the volume at the boot

emerge aumix
File: /etc/conf.d/local.start
aumix -v75 -w75&

Note : you might also want to add "export ESPEAKER=diskless" in the ~/.xsession of the user(s) who will use the diskless


If your terminal have parallel or serial port (or usb), you may want to connect a local printer. In order to use it, you need to:

- install your printer's drivers (foomatic?)
- install and configure print server (cups?)
- map terminal's printer to your server's printing deamon (cups?)
- every time you print, you will need to manually select the apriopriate printer (unless you make it default)

Above is a little bit of work, but it is possible. Anyone have better idea? Anyone will make howto? :-)

The diskless root is now ready, boot the diskless and enjoy

Retrieved from ""

Last modified: Fri, 05 Sep 2008 10:41:00 +0000 Hits: 18,037