\documentclass{amsart}
\usepackage{amssymb}
\usepackage[pdftex]{graphicx}
\DeclareFontFamily{OMS}{cmsy}{%
\fontdimen16\font=3pt
\fontdimen17\font=3pt}
\setlength{\headheight}{1.5\baselineskip}
\def\dj{d\kern-.30em\raise1.25ex\vbox{\hrule width .3em height .03em}}
\def\Dj{D\rlap{\kern-.70em\raise0.75ex
\vbox{\hrule width .3em height .03em}}}
\newenvironment{pf}{\proof[\proofname]}{\endproof}
\makeatletter
\renewcommand{\subsection}{\@startsection{subsection}{2}{\z@}%
{\baselineskip}{0.5\baselineskip}{\bfseries}}
\def\l@section{\def\@tocpagenum##1{\hss{\bfseries ##1}}%
\@tocline{1}{8pt}{0pc}{}{\bfseries}}
\def\l@subsection{\def\@tocpagenum##1{}
\@tocline{2}{2pt}{2pc}{2pc}{}}
\makeatother
\textheight=1.015\textheight
\renewcommand{\thefootnote}{\fnsymbol{footnote}}
\renewcommand{\thepage}{\ifnum\value{page}=1 \else\arabic{page}\fi}

\parskip=2pt plus2pt minus1pt
\addtolength{\textheight}{0.8\baselineskip}

\begin{document} 

\title[Quetzal Presentation]{Quetzal--A Live DVD/CD System 
Based on OpenBSD} 

\author{micho {\Dj}UR{\Dj}EVICH}

\address{
Instituto de Matematicas, UNAM,
Area de la Investigacion Cientifica, 
Circuito Exterior, Ciudad Universitaria,
M\'exico DF, CP 04510, MEXICO / Q-Systems, MEXICO}

\email{ micho@matem.unam.mx\newline\indent\indent 
http://quetzal.matem.unam.mx\newline\indent\indent
http://www.matem.unam.mx/{\~\/}micho}

\begin{abstract}
This is the companion article to Quetzal--which is a live 
DVD/CD based on OpenBSD operating system. 
We explain basic features of the system, a DHCP/PXE remote-booting 
setup, and provide  
more detailed instructions for a manual hard disk install. We also discuss 
simple modifications to the OpenBSD kernel used in Quetzal, and 
some tricks, that might be interesting on their own.   
\end{abstract}

\maketitle
\tableofcontents

The word `Quetzal' is intertwined with roots of ancient Mexican and Central 
American civilizations. In N\'ahuatl {\it Quetzalli\/} means a `rich green 
feather'. Quetzal is a beautiful and extraordinary bird, with green 
and red feathers. 
The male has long green tail coverts, and the female is more `elliptic'. 
A fundamental god of ancient
Mexican and Central American cultures is {\it Quetzalcoatl\/} a creature 
unifying the bird and Serpent (\textit{Coatl\/}).  A quantum superposition of 
Heaven and Earth\dots

\section{Introduction}
Here we shall deal with another Quetzal--a live DVD/CD system, 
based on OpenBSD. 
This article\footnote{Version 3.6.2006} can be viewed as a user manual for 
Quetzal. The system  
contains a full OpenBSD installation, and a collection of 
selected applications. Our window manager of choice is WindowMaker. 
Its geometrical simplicity, modularity, performance, stability and
internal architecture, match nicely with the philosophy of OpenBSD
and UNIX in general. Desktop images, themes and icons come from various 
sources \cite{icons}.  A fine live CD called OliveBSD \cite{olive} was 
an initial inspiration for this work. We refer to \cite{aobsd}, for 
a general introduction to OpenBSD operating system. 

\noindent Here is a list of principal packages 
included with Quetzal: 

\begin{itemize}
\item Symbolic Mathematics Package Maxima + wxMaxima Frontend; 
\item GNU Image Manipulation Program--GIMP + Full Help/Docs;  
\item Scripting Language and Graphical Toolkit TCL/TK; 
\item Object Oriented Scripting Language Python;
\item Graphical Toolkit wxWidgets + wxPython;  
\item Common Unix Printing System--CUPS; 
\item Internet Messaging System Gaim;
\item Complete \TeX\ distribution;
\item Text Editor SciTE;
\item Remote Desktop; 
\item PDF Viewer Xpdf;
\item File Manager Rox; 
\item OpenOffice.org Suite; 
\item Thunderbird Mail Client; 
\item Firefox Internet Navigator; 
\item Audio Player XMMS + MP3 Plugin; 
\item GhostScript \& GV Postscript Viewer;  
\item Dockable Clock, Moon Clock, \& Audio Mixer. 
\end{itemize} 

\noindent This document focuses on DVD releases of Quetzal. Modulo simple 
modifications, almost everything applies to CD releases as well. 
\section{First Steps} 

The first step is to download the corresponding bz2-compressed image. The  
Quetzal DVD can be created by burning the image, with the help of 
virtually any DVD burning software. For this to work, of course, 
we need a good DVD-ROM burner :)  

On OpenBSD, the whole procedure would 
look something like this: 
\begin{verbatim}
       bzip2 -d quetzal-dd.mm.yyyy.iso.bz2
\end{verbatim}

\noindent At this point it would be wise to verify 
the checksum for the iso-file. For example

\begin{verbatim}
       md5/sha1 quetzal-dd.mm.yyyy.iso
\end{verbatim} 

\noindent To actually burn the image to a DVD-ROM, 

\begin{verbatim}
       growisofs -dvd-compat -Z /dev/rcd0c=quetzal-dd.mm.yyyy.iso 
\end{verbatim}

The system boots to text-mode interface. The only real user defined is
`root' and the password is `quetzal'.  The system requires some configuration
of virtually all OpenBSD components, including network and X windows. 
This is done intentionally. Quetzal is primarily intended as an 
educational tool, so all the major configuration options are left open.  
In such a way we also stay compatible with the spirit of UNIX. 

Quetzal is easily installable on a local hard disk. 
We do not provide any installation wizard---the installation 
is a collection of simple manually executable steps.  

In order to start the graphical interface using the X autoconfiguration,
we simply execute {\tt xinit}. This should work fine in most of the cases.
An alternative is to manually configure the X server, by 
invoking a standard sequence of commands: 

\begin{verbatim}
       X -configure
       cp /root/xorg.conf.new /etc/X11/xorg.conf
       vi /etc/X11/xorg.conf
\end{verbatim}

In this case, after editing {\tt xorg.conf} and 
before initializing X via {\tt xinit}, 
it is necessary to {\it delete} the file {\tt /tmp/.X11-unix/X0}. 

\section{About OpenOffice}

The OpenOffice suite included with Quetzal is a Linux application. Therefore,
we need to activate the Linux emulation:

\begin{verbatim}
       sysctl -w kern.emul.linux=1
       mount -o rw,linux -t procfs /proc /proc
\end{verbatim}

\enlargethispage{\baselineskip}        
Under `normal' circumstances, this should be sufficient to run most 
of Linux applications.\footnote{Preliminary releases of Quetzal included
Linux Opera \& Flash Plugin. They had to be removed from the final version 
due to inappropriate licensing conditions.} However, in order to run 
OpenOffice from a read-only medium as the Quetzal DVD, it is 
necessary to apply an extra trick. If we try
to run it directly from the disc, the program would crash with an error
message. The origin of the problem lies in an inappropriate handling of  
lock file requests by the filesystem driver. Some applications require the
locking functionality in order to work properly, and OpenOffice is one of
them.

A solution we present here is to simply mount via NFS, the local directory
{\tt opt} containing OpenOffice distribution. The NFS does handle lock
requests properly. A future version of Quetzal will include a modified
cd9660 filesystem driver, and the trick will be
unnecessary.  At first, we start the NFS server:
\begin{verbatim}
        portmap; nfsd -t -u -n 4
        mountd 
\end{verbatim}
        
\noindent And then we mount the NFS share defined in {\tt /etc/exports} file:
\begin{verbatim}
        mount localhost:/opt /oo2
\end{verbatim}

\section{Remote Booting}

In this section we shall present a simple DHCP/PXE remote-booting setup,
suitable for booting diskless clients over a local area network.
These clients would mount their root filesystem via NFS, and so it is
necessary to compile the appropriate custom kernel:
\begin{verbatim}
        config bsd root on nfs swap on nfs
\end{verbatim}
Such a kernel is included as {\tt /quetzal/bsd.nfs}. On the server (and
we assume it is an OpenBSD system) we have
to set up various daemons. At first, it is the TFTP service. The simplest
is to enable it in {\tt /etc/inetd.conf}. The default directory {\tt
/tftpboot} should contain at least the loader {\tt pxeboot} and
the above mentioned kernel renamed to {\tt bsd}. Second, we have to configure
the DHCP server, by editing {\tt /etc/dhcpd.conf}. Here is a simple
configuration:

\begin{verbatim}

        option domain-name "q-systems.mexico";
        option routers 192.168.1.1;
        option subnet-mask 255.255.255.0;
        option broadcast-address 192.168.1.255;
        option domain-name-servers 192.168.1.2;
        server-name "DHCPserver";
        server-identifier 192.168.1.2;

        default-lease-time 300;
        max-lease-time 300;

        subnet 192.168.1.0 netmask 255.255.255.0 {
               filename "pxeboot";
               range 192.168.1.7 192.168.1.117;
           }

\end{verbatim}
This ensures the initial client-server communication via PXE, which
would load via TFTP {/tt pxeboot} into the client memory and execute it. The
loader would, in its turn, get the kernel via TFTP into the client memory
and pass control to it. At the end of kernel processing, it tries to mount
the root filesystem via NFS. In order for this to work succesfully, besides
properly configured NFS server, we need to configure two more daemons: {\tt
rarpd} for reverse address resolution and {\tt rpc.bootparamd} for supplying
root filesystem and swap information to the client. The reverse address
resolution is controlled by {\tt /etc/ethers}. This file translates
network adapter MAC addresses into hostnames. A single client setup would
look like
\begin{verbatim}
        00:50:DA:1A:14:A3      qbird
\end{verbatim}
where {\tt qbird} is the diskless client name. The MAC address is taken
from the actual client we played with (IBM Network Station 2800, equipped
with a PCI 3Com 905C-TX-M adapter). The file {\tt /etc/bootparams}
controls the {\tt rpc.bootparamd} service. It is divided in sections, corresponding
to different remote-booting clients:

\begin{verbatim}
        qbird   root=xochitl:/opt/quetzal \
                swap=xochitl:/opt/qbird/swap
\end{verbatim}
Here {\tt xochitl} is the hostname of the server. Both client names
(as {\tt qbird}) and the server name ({\tt xochitl})
should be defined in {\tt /etc/hosts}. The above configuration tells us
where the root of the client NFS filesystem is, and the location of
the virtual memory file. Assuming we already have created {\tt /opt/quetzal}
on the server, we will have to copy over the contents of the Quetzal DVD,
say
\begin{verbatim}
        tar cf - -C /mnt . | tar xpf - -C /opt/quetzal
\end{verbatim}
as well as to create a nice initial collection of zeros for the swap
\begin{verbatim}
        dd if=/dev/zero of=/opt/qbird/swap bs=8192 count=8192
\end{verbatim}
The above would create a 64M swap file. 

The whole remote-boot system is orchestrated by the following sequence of 
commands:
\begin{verbatim}
        dhcpd; rarpd <ethn>
        portmap
        rpc.bootparamd
        nfsd -t -u -n 4
        mountd  
\end{verbatim}
A principal use of remote-booting is to create a simple yet efficient 
and highly manageable LAN consisting of thin clients (diskless machines). 
Another interesting use of remote-booting, is to facilitate local 
operating system installations. We can, for example, remote-boot Quetzal 
on a machine with a local hard disk, and install everything locally. 
Such a procedure is discussed in the next section. It is the same
for DVD and remote-booted versions of Quetzal.  
 
\section{Installing Quetzal on Hard Disk}

\subsection{Assumptions}
We shall assume here that Quetzal is being installed on the first IDE 
hard disk, corresponding to {\tt wd0} in OpenBSD nomenclature. 
We shall also assume that the whole hard disk is used for Quetzal. 
Other configurations are treatable in a similar spirit.

\subsection{Partitioning the Disk}

At first we create the appropriate MBR, using {\tt fdisk} in the interactive
mode: 

\begin{verbatim}
        fdisk -e wd0 
\end{verbatim}

Within the editor, we execute the following 4 instructions: 
\begin{verbatim}   
        reinit,update,write,quit
\end{verbatim} 
This would create a single {\tt 0xA6} partition covering the whole disk. 
The next step is to create the disk label. Fire up the OpenBSD label editor.    

\begin{verbatim}
        disklabel -E wd0 
\end{verbatim}

The OpenBSD partitions created will be \{{\tt wd0a,wd0b,wd0d,wd0e,wd0f}\} and 
correspond to \{{\tt /root,swap,/usr,/var,/opt}\} respectively.  

\subsection{Creating File Systems}

After creating the partitions, we need to create a fresh FFS on them: 
\begin{verbatim}
        newfs /dev/rwd0a; newfs /dev/rwd0d
        newfs /dev/rwd0e; newfs /dev/rwd0f
\end{verbatim}

The disk is now ready to hold Quetzal files. In order to be able to 
copy the optical disc contents, we first need to mount the 
relevant partitions:  

\begin{verbatim}
        mount /dev/wd0a /mnt
        mkdir /mnt/{usr,var,opt,dev,etc,proc,emul}
        mount /dev/wd0d /mnt/usr
        mount /dev/wd0e /mnt/var
        mount /dev/wd0f /mnt/opt
\end{verbatim}

\subsection{Copying Files}
This is a time-consuming step and runs a higher risk of failure, if the 
optical disc or DVD unit are low-quality. Here we shall use  
{\tt tar} to copy across filesystems. For example, 
\begin{verbatim}
        tar cf - -C / usr opt sbin bin | tar xpf - -C /mnt
        cd /etcq; tar cf - * | tar xpf - -C /mnt/etc
        cd /varq; tar cf - * | tar xpf - -C /mnt/var
\end{verbatim}
While the hdd-install {\tt /root} folder will be simply unpacked:

\begin{verbatim}
        tar xpf /quetzal/root.tar -C /mnt 
\end{verbatim}

Let us mention here that the {\tt /quetzal} directory
contains archived forms of {\tt /root,/etc,/var} folders, the files 
{\tt root.tar etc.tar} and {\tt var.tar} respectively. These 
archives are unpacked during the system boot, along the memory 
filesystems creations (from the {\tt rc} script). However 
directories {\tt /varq} and {\tt /etcq} are aimed for the hard
disk installations. In order to save memory, diverse files from {\tt /etc}
and {\tt /var} are simply symbolic links to the originals in {\tt /etcq}
and {\tt /varq} respectively. A handful of important files are
different between Quetzal and the hdd-install versions of these 
two directories. And many files need to be writable---hence the difference.  

\begin{verbatim}
        cp /quetzal/{bsd,boot}         /mnt
\end{verbatim}

The above step is necessary because the kernel for Quetzal is 
compiled with the root filesystem pointing to {\tt /dev/cd0a}. 
Such a kernel is not suitable for booting from a hard disk. The correct kernel 
is supplied in {\tt /quetzal} directory. Also, it is convenient to have the 
loader at the root of the filesystem.  
 
\subsection{Final Adjustments}

Let us proceed by making all the devices: 
\begin{verbatim}
        cp /quetzal/MAKEDEV  /mnt/dev
        cd /mnt/dev;   sh MAKEDEV all 
\end{verbatim} 

\noindent We have to create a number of links at the root of the filesystem:  
\begin{verbatim}
        ln -s /usr/local/emul/redhat /mnt/emul/linux
        ln -s /opt                   /mnt/oo2
        ln -s /var/tmp               /mnt/tmp 
        ln -s /opt/home              /mnt/home
\end{verbatim}

\noindent The {\tt oo2} link is to ensure that desktop objects 
for OpenOffice would work correctly `out of the box'.  
To complete our setup, let us install the first and the 
second stage boot loaders:  
\begin{verbatim}
        cd /usr/mdec; ./installboot -v /mnt/boot biosboot wd0 
\end{verbatim} 

We should now be ready to boot from the hard disk. Execute {\tt halt} 
remove the Quetzal disk from its unit, reboot and enjoy! 
 
\section{Concluding Remarks}

\subsection{Some Specific Changes to Code}

A kernel function {\tt inittodr} defined in 
{\tt /sys/arch/i386/isa/clock.c} was modified, in order to avoid
printing of a horrifying bogus error message about filesystem 
time discrepancy. The modified 
function, when called with {\tt base=0} skips all comparisions between
{\tt base} and the system time.  

Here is an example of a modified code: 
\begin{verbatim}
       if (base > 0 && base < zzzz) {
              printf("WARNING: blah blah"}
              base = xxxx
       }
\end{verbatim}

The kernel of OpenBSD was compiled with the appropriate  
root filesystem information 
\begin{verbatim}
       config bsd root on cd0a 
\end{verbatim}
\noindent The kernel messages are red on black. This is achieved by
putting
\begin{verbatim}
       WS_KERNEL_FG=WSCOL_RED
       WS_KERNEL_BG=WSCOL_BLACK
\end{verbatim} 
in the kernel configuration. 

The X server was modified, in order to remove CID folder from the default 
font folder search path. 

The filemanager ROX was modified, in order to remove annoying remainders about
running as root. The default folder 
icon was replaced by a more `NeXT-ish' one. When searching for 
mount points, the program will only look at actually 
mounted filesystems, without any {\tt fstab} involvement.   

The window manager was modified, in order to replace the GNUstep info dialog 
by a Quetzal dialog. Furthermore, WindowMaker comes with custom-prepared 
48-point icons and additional artwork \cite{icons}, as already mentioned.  

The package database {\tt /var/db/pkg} does not fully reflect the above 
modifications to the packages. 

\subsection{Constructing ISO}

Perhaps the most interesting question here is how to construct 
a bootable floppy used for the emulated boot. Let us assume 
we are at the root of the hdd-folder that holds all other Quetzal files. 

\begin{verbatim}
       dd if=/dev/zero of=bfloppy.fs bs=0x10000 count=45
\end{verbatim}
\noindent This would create the file for the 2.88M floppy type (64k*45).  
\begin{verbatim}
       vnconfig  -c -v svnd0 bfloppy.fs
       disklabel -w -r svnd0 floppy288
       newfs -m 0 -o space -i 524288 /dev/rsvnd0a
       mount /dev/svnd0a /mnt
\end{verbatim}
\noindent The above would format the image as a 2.88M floppy. The disk label is
taken from {\tt disktab} and the filesystem is optimized for space, 
with minimum-free set to zero, and the inode density set to a minimal 
value (0x80000=524288).  
\begin{verbatim}
       cp /usr/mdec/boot /mnt 
       gzip -c bsd > /mnt/bsd
\end{verbatim}
\noindent Here {\tt bsd} is our custom prepared Quetzal kernel. We put it on 
the floppy image, in the compressed form. We complete the construction by
installing the 1/2 boot loaders.  
\begin{verbatim}
       cd /usr/mdec; ./installboot -v /mnt/boot biosboot svnd0
       umount /mnt
       vnconfig -u svnd0 
\end{verbatim}

The bootable ISO image can be now created by {\tt mkisofs}. For example, 
from the Quetzal parent directory:  

\begin{verbatim}
       mkisofs -b bfloppy.fs -c boot.catalog -l -R -V Quetzal \
       -o dimages/quetzal.iso quetzal 
\end{verbatim}

\begin{thebibliography}{4}

\bibitem{icons} See {\tt /quetzal/ARTWORK} for a complete listing of 
artwork sources. In particular, the wallpapers collection contains
selected works
by Brad Cover ({\it http://americanpsycho.deviantart.com}\/) as well as
selected photographs by Stanko Kostic ({\it http://www.skostic.com}\/). 
In addition we included 3 iconsets from Barbara Kaemper collection:
{\it http://www.barbarakaemper.de}. And 4 complete themes from the same
website. All this artwork is included in Quetzal with kind permitions of 
the above mentioned authors.  For default desktop icons we used a 
custom-prepared set of `Gant' icons from Window Manager Icons collection:
{\it http://wm-icons.sourceforge.net/}.

\bibitem{olive} OliveBSD Project: {\it http://g.paderni.free.fr/olivebsd/}.  
\bibitem{boot} Kevin Lo: {\it Building an OpenBSD Live CD}, ONLamp.com
article\newline
{\it http://www.onlamp.com/pub/a/bsd/2005/07/14/openbsd\_live.html}.
\bibitem{aobsd} Michael W.\ Lucas: {\it Absolute OpenBSD: UNIX for
the Practical Paranoid}, No Starch Press, San Francisco (2003).
\end{thebibliography}

\end{document}