May 11,2001

README.1st

    lmw.sh - A bash script to generate an X capable initrd image.

                   !!!!DANGER, WILL ROBINSON!!!!

This script copies files to directories that are similarly named to
your operational directories. Sooner or later you will screw up and
overwrite your development system. Backup soon and often, and DO NOT
use on a critical path computer!

**********************************************************************
THERE IS NO WARRANTY FOR THIS PROGRAM, IT IS PROVIDED "AS IS" WITHOUT
WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT
LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR 
A PARTICULAR PURPOSE.  THE ENTIRE RISK AS TO THE QUALITY AND 
PERFORMANCE OF THE PROGRAM IS WITH YOU.  SHOULD THE PROGRAM PROVE 
DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR 
CORRECTION.

This program Copyright (C) April 2001, Terry Loveall and Mike McQuade. 
Released under GPL 2. A copy of the GPL should be included with this
package. If not, you can find a copy at: 
http://www.fsf.org/copyleft/gpl.html
**********************************************************************

OVERVIEW

The purpose of the lmw.sh script is to generate a minimal linux
directory tree from your operational linux installation. This tree is
capable of being booted and mounted either from an initrd image or
from a mass storage device. You too, can join the throng of
PDA/network appliance developers in the privacy of your own home.

See the file CONFIG for final initrd configuration details. 

See the file OPTIONS for explicit details about lmw.sh script options.


User Requirements:

This package assumes that you have built your own kernel, know what
a soft link is, know how to read man pages and are comfortable
performing routine edit/compile/boot functions purely as user root.
If any of the above does not make sense, I recommend starting your
education at http://www.newbie.org/. 

Program Necessities:

In addition to linux running pre 4.0 X (any 3.3.x will do), bash, the
gcc development package and the linux kernel source, you will need to
download, unpack and compile the following on your development system:

tinylogin: http://tinylogin.lineo.com/
busybox:   http://busybox.lineo.com/
uClibc:    http://cvs.uclinux.org/uClibc.html

I recommend using anonymous CVS access to get the above packages.

VNC:       http://www.uk.research.att.com/vnc/
 doc:      http://www.uk.research.att.com/vnc/docs.html
 You need the VNC package to use Xvnc on your initrd image. Also,
 an excellent all around remote client/server for linux/windows/Mac.

NASM 0.98: http://www.web-sites.co.uk/nasm/ 
 You need NASM to build the e3 editor.

e3:        http://www.sax.de/~adlibit/.
 If e3 is not installed, you have no console text editor, only xe, an
 X window editor. And you will probably need to edit files from the
 console to get X running. Catch-22. Alternatively, you can enable the
 'vi' function in busybox. See busybox doc for details.

Loadlin:   http://elserv.ffm.fgan.de/~lermen/
 You need loadlin.exe for booting the initrd during development
 (if  you think this is a turnkey package, you haven't been 
 paying  attention).

Getting it on:

Unpack the lmw-xxxx.tgz to a suitable directory. Anywhere in your file
tree will do. /usr/src is a valid option.

After you have all of the above installed and compiled, make softlinks
to the four directories uClibc, tinylogin, busybox and e3 in the
../lmw  directory. Edit lmw.sh to reflect any differences
between the script and the files/directories invoked. 

See the file CONFIG for final initrd configuration details. 

See the file OPTIONS for explicit details about lmw.sh script options.

For successful build and booting purposes you need to be logged in as
root user. Normal user priveleges are not sufficient to generate a
bootable initrd. 

Invoke the build script with './lmw.sh' from a command line in
the ../lmw directory.  Note any omissions/errors during execution
and edit the lmw.sh script for incorrect names, or copy missing
files to the specified location as indicated by error messages and
inspection.

Use the source, Luke! You will have to understand it to use it
effectively. When all else fails, read the screen.

After successful execution, lmw.sh writes a copy of itself back
to the init_scripts directory and to your '~/' directory (along with a
copy onto the initrd), with the name modified by the version number.
The version number is maintained in line 4 of lmw.sh. Change the
version number for a cheap and dirty form of RCS.

Booting:

To test your new initrd, you need a kernel to boot. Modules are not
supported at this time (nor by default, PCMCIA. For a start on
how to cope with PnP and PCMCIA, Read The Fine Documentation:
"/usr/src/linux/Documentation/initrd.txt" on how to double load/boot
an initrd). You need to build a monolithic kernel with an operational 
network driver built in. 

Included in this directory is the file conf243nm which is a copy of my
.config for the 2.4.3-pre6 linux i386 kernel. It is provided for
reference only! (The 2.4.x kernels are in a radical state of flux,
their .config files are different for every release and are _entirely_
different from 2.2.x). This config has no module support, networking
compiled in for non-PnP NE2000 and the 3com 3c905b, framebuffer
enabled and support for an opl3sa2 sound card.

Enable initrd and ramdisk. Set a size compatible with the initrd
unzipped size. If you initialize newfs to 16Mb then you need to set a
16,384 ramdisk size. See conf243nm for a reference config. The default
setting on every kernel I have ever seen is 4096, so check your 
kernel.

After building (and successfully booting your development system) with
your new monolithic kernel, you are now ready to boot the initrd. 
The safest way is to boot DOS and use loadin.exe (it is also the only
method supported at this time. LILO can be deadly!). Copy the initrd
image, newfs.gz and a copy of your monolithic kernel to an MSDOS 
partition, reboot to DOS (disable HIMEM.SYS) and invoke the following
command line with loadlin.exe (put it in a bat file, 'cause you will
use it quite often).

loadlin bzimnm initrd=newfs.gz root=/dev/rd/0 init=/linuxrc rw vga=0x315

The above line assumes loadlin.exe is in the path, the monolithic
image is named bzimnm (bzImage, No Modules) and that you want to boot
with the framebuffer video enabled in 800x600 24 bit color mode. Drop
the " vga=0x315" if you just want normal console video out.

Assuming everything works, your system should boot up and prompt for
a login name. Enter 'root'. Password is blank. If you are paranoid, 
you can invoke passwd to immediately set one. Recommended if you have
networking enabled. Then copy the resulting passwd and shadow files
back to the ../lmw/init_scripts/etc directory for inclusion in
the succeeding initrd images. 

Hint: use 'e' or 'vi' to edit /etc/fstab for the appropriate /dev/hdxx
device type to mount on directory /d, mkdir /d, mount -a and then
copy your files.  NOTE! If you are using the e3 editor, pay attention.
Invoking it as vi does not change the key bindings from the default
WordStar set. Use Alt-h to get a help screen.
 
Remote X:

At this point, you are ready to run Xvnc. Change to root directory
and execute 'vncserver' if you have enabled XVNC (default), or 'startx' 
if you have enabled either VGA16 or FBDEV which starts up a local X 
session.

The lmw.sh package comes configured without a password for Xvnc,
but Xvnc will not load until you enter a password. Copy the resulting
/root/.vnc/passwd file to your development directory, as per above.
Execute a bare 'vncviewer' (*nix) or 'vncviewer.exe' (windows) for
first time access after setting the Xvnc password. Then 'save 
connection info' to remember the new password. Old, even identical
passwords do not seem to work.

GTk+ and Dillo:

Copying a resident version of the GTk libs is now supported. This assumes
you have an operational GTk installation. If you do not, I recommend
downloading and installing the current stable GTk= package from the
distribution source of your resident linux. 

lmw.sh copies the run time dynamic link libraries only. Static libs, 
themes and theme engines are not supported. What is copied is adequate 
to run dillo and other complete applications. Your mileage may vary.

For Dillo sources see:
http://dillo.sourceforge.net/

Back to the Future:

Once remotely connected with vnc, you can run xc: eye candy directory
viewer, xfm: hacked xfilemanager with file editing, ycalc: a quasi
TI-59 emulator hacked for programmers or just wander around the 
directory structure kicking the tires and peering under the hood. 
Read The Fine Documentation in the root directory for how to play with 
the toys. Hopefully, at this point you have ideas of your own as to 
what to do next. Good luck and feel free to send feedback.

Terry Loveall,
loveall@qwest.net
May 11, 2001

CONFIG:

                   End Use Configuration

Binaries are supplied for the following apps:

ycalc        := modified X TI-59 emulator w/number conversion.
xe           := modified xenon X text editor.
xfilemanager := modified old X Explorer clone.
xcruise      := modified directory structure viewer.
lwm          := modified Light Window Manager.

Source for the above modified files can be found at:
http://www.users.qwest.net/~loveall/

thttpd       := micro web server.
Source and doc for thttpd can be found at:
http://www.acme.com/software/thttpd/

Xvnc         := remote X server, taken from the mulinux VNC package.
vncpasswd    := Xvnc password setting program from same.

Source for the VNC binaries can be found at the VNC web site:
http://www.uk.research.att.com/vnc/

The remaining supplied files are either scripts or fonts. Your
operational system is the source for the rest of the initrd image.

You can substitute more recent *.gz font files for more compact
storage, but you will need to update the fonts.dir and fonts.alias
files.


CONFIGURING UCLIBC, TINYLOGIN and BUSYBOX:
==========================================

As an aid to getting uClibc, tinylogin and busybox working, the 
appropriate Config, Config.h and Makefile files are included in
the following directories:

../lmw/init_scripts/uClibc/Config
../lmw/init_scripts/tinylogin/Makefile
../lmw/init_scripts/tinylogin/Config.h
../lmw/init_scripts/busybox/Makefile
../lmw/init_scripts/busybox/Config.h

These are provided for guidance, not as absolutes. Different systems 
will have different needs. But at least you will have some sense as
to something that did work, once :-)

Go to the URL:
http://opensource.lineo.com/cvs_anon.html
and follow the instructions for getting access to CVS.
After that, download all three projects with the following line:
"cvs -z3 -d:pserver:anonymous@opensource.lineo.com:/var/cvs co -P uClibc busybox tinylogin"

Copy the above Config, Config.h and Makefile files into the correspondig 
directories _after_ having renamed the originals. 

These files work with the builds of Busybox v0.51, tinylogin Makefile/1.31 
and uClibc Makeifle 1.63.

Be aware, these are dynamic projects and evolve. The included files may 
or may not work on future releases.


CONFIGURING LMW.SH:
===================

----------------------
Bash string variables:

REV is a bash string variable for internal housekeeping. Update here.
Changes propagate to backup filenames names.

These two variables determine the directory that the initrd image is
built in, BUILDIR, and the mount point, MOUNTP, for the finished
initrd image,

BUILDIR="embfiles"
MOUNTP="target"

The following variables specify which options are installed into the
final initrd image. Place a bash comment character, '#', in front of
undesired options. Loading both VGA16 and FBDEV options will leave the
default X set to FBDEV (as well as taking up lots of space).

#FIREWALL="1"
#THTTPD="1"
GPM="1"
#LDD="1"
REBOOT="1"
#SULOGIN="1"
#STRACE="1"

INSTALL_X="1"
LWM="1"
#GTK="1"
#DILLO="1"
#HELIWM="1"
XCRUISE="1"
#BROWSEX_SUP="1"
XENON="1"
XFILEMAN="1"
#VGA16="1"
#FBDEV="1"
XVNC="1"

See the file ../lmw/OPTIONS for a detailed explanation.

INITRD CONFIGURATION:
=====================

List of configuration files taken from the host development system:

group 
host.conf 
hosts 
shadow-
issue 
localtime 
protocols 
group 
gshadow
rpc 
securetty 
services 

The above should work as-is. However you may want/need to change them
to fit the target environment. See the appropriate man pages for 
further details.

----------------

The following files are copied from your host development system, but
then over-written with supplied defaults. If you prefer defaults from
your own system, then remove the supplied defaults from the
../lmw/init_scripts/etc directory.

passwd 
shadow 
profile 
inittab 
resolv.conf

HOSTNAME is a special case where the target HOSTNAME is generated by
running the command 'uname -n >HOSTNAME'. You can create your own
fixed HOSTNAME file using a text editor. Make sure the file
owner/group permissions match that of an appropriate HOSTNAME. Copy
the new HOSTNAME to the ../lmw/init_scripts/etc directory and
comment out the 'uname -n...' line in lmw.sh

-----------------------------
../lmw/init_scripts/xskel.sh:

Bash script file for creating the Xskel.tgz X window file tree skeleton from
the mulinux2 mu2-X11R6.tgz package. Xskel.tgz contains the added X directory 
structure, plus minimal ../fonts/misc and ../fonts/75dpi directories. No
binaries, just directories and fonts.

------------------------------
../lmw/init_scripts/etc/fstab:

The supplied fstab is a pretty little thing that is ignored until 
the appropriate mount point directories are created. It provides
a workable example of different mount points and file systems.

--------------------------------
../lmw/init_scripts/etc/inittab:

'inittab' is a custom file specifically for use with tinylogin and
busybox. tinylogin does NOT support run levels, so a conventional 
inittab is out of the question. inittab determines the major structure
of booting, startup, login and shutdown. See the appropriate man pages
and docs for tinylogin, busybox, init, halt and reboot for detailed
operation. Then see inittab for how it really works.

-------------------------------
../lmw/init_scripts/etc/passwd:
../lmw/init_scripts/etc/shadow:
../lmw/init_scripts/etc/nsswitch.conf:

These three files are provided so that the system starts up with a
blank password, otherwise I would have to tell you mine. See the
previous comments about passwords.

-----------------------------------
../lmw/init_scripts/etc/ld.so.conf:

Probably don't need this if you are NOT going to run X or add any 
other libs to the system.

------------------------------------
../lmw/init_scripts/etc/resolv.conf:

Added this so that external DNS servers are used. No security bug
laden DNS servers on this machine! Edit to change external DNS
servers.

--------------------------------
../lmw/init_scripts/etc/profile:
../lmw/init_scripts/.profile:

These two files constitute every geeks third religion behind 
programming language and text editor. Having exposed you to 2 out 3
of mine in this package was the least I could get away with. Can
you guess the third? And, no, it aint C.

----------------------------------------
../lmw/init_scripts/etc/rc.d/rc.sysinit:

This executes the system startup functions from when the kernel
finishes loading until login. Customize to suit your target.

------------------------------------------
../lmw/init_scripts/etc/rc.d/rc.functions:

A support subroutine that generates the purty green and red status
messages during startup.

------------------------------------
../lmw/init_scripts/etc/rc.d/rc.gpm:

A default gpm setup that gets overwritten by the GPM code in 
lmw.sh. Use whichever suits you. Default turned off. chmod =x to
change. Edit to match your mouse device. 

---------------------------------------
../lmw/init_scripts/etc/rc.d/rc.reboot:

What the system is supposed to execute in response to a three
fingered salute (Ctrl-Alt-Del) from the console or the
reboot/halt/shutdown commands.

--------------------------------------
../lmw/init_scripts/etc/firewall.conf:

How to communicate with the world (which network interface) and about
what (which protocols to support). Default interface is set to
'eth0'. Change if you add/change network interfaces.

-----------------------------------------------------
../lmw/init_scripts/etc/rc.d/rc.start/rc.00.firewall:

Sets the level of ipchains involvement. Tweak to suit your needs.
RTFM.

-----------------------------------
../lmw/init_scripts/etc/httpd.conf:

Set the http port and other configurables. Setup for thttpd.

--------------------------------------------------
../lmw/init_scripts/etc/rc.d/rc.start/rc.20.httpd:

Startup the thttpd and then report startup status. Default is to not
start. chmod +x to enable it.

-------------------------------------------------
../lmw/init_scripts/etc/network.d/interface.eth0:

Main _ethernet_ network configuration. For other interfaces, e.g. ppp,
add more interface.xxx files for each interface. Sets interface type,
static/dynamic IP, IP address, netmask, broadcast address and gateway.

----------------------------------------------------
../lmw/init_scripts/etc/rc.d/rc.start/rc.10.network:

This is the script that actually uses the info in interface.eth0. This
takes that data and sets up the system with ifconfig and route. 
Default is turned on.

-----------------------------------
../lmw/init_scripts/etc/inetd.conf:

Specifies the services that inetd supports. Tune, tweak or eliminate
as you see fit.

--------------------------------------------------
../lmw/init_scripts/etc/rc.d/rc.start/rc.30.inetd:

Starts inetd daemon. Default is to not start. chmod +x to enable.


X CONFIGURATION:
================

lmw uses the Xvnc server for a default X server. There are
unselected options for installing either an XF86_VGA16 server or an
XF86_FBDev server. By enabling the appropriate option and supplying a
matching X server, you can run X local on your target system. The
supplied XF86Config.3.3.6 is set up for a Sony VAIO 505G. The
XF86Config.FBDev is setup for a frame buffer enabled kernel running
at 800x600 resolution, 24 bit color. Change to suit/fit your need.
For further details refer to your specific X configuration docs.


The script 'vncserver' is used to start the Xvnc server. 'vncserver'
is dynamically generated by lmw.sh.

'vncserver' invokes the script:
/usr/X11R6/bin/vnc 
which in turn calls the script 
/root/.vnc/xstartup. 

----------------------------
../lmw/init_scripts/x11/vnc:

Starting at line# 124 the Xvnc parameters are set. Values set are:
connection timeout, 
rfb port, 
fontpath, 
geometry (sets X resolution) and
password file. 
See the Xvnc doc for further details. This config will get you up and
running with a modicum of security. File to form and bash to fit your
needs.

----------------------------------
../lmw/init_scripts/.vnc/xstartup:

This is similar to a conventional xinitrc. The difference is that it
is called by vnc which takes the place of xinit. This way, you do not
have to choose between a conventional X setup or Xvnc. Both can be
active and operational. 

Executes setroot for desktop color, fires up an rxvt terminal and
then invokes the window manager. Edit this file if you change window
managers or for other X startup functions you want performed.

OPTIONS:


                           LMW.SH OPTIONS

List of lmw.sh options:
=======================

REV

BUILDIR=
MOUNTP

BLOCKSIZE

FIREWALL
THTTPD
GPM
LDD
REBOOT
SULOGIN
STRACE

INSTALL_X
LWM
GTK
DILLO
HELIWM
XCRUISE
BROWSEX_SUP
XENON
XFILEMAN
VGA16
FBDEV
XVNC

---------------------
Detailed explanation:
---------------------

REV
---
A bash string variable for internal housekeeping. Update in lmw.sh, line# 4.
Changes reflected in backup script file names. Cheap and dirty RCS. Default
setting to current release REV.

BUILDIR="target"
----------------
BUILDIR holds the name of the directory which is created and contains the LMW 
tree under construction. Previous instance is deleted. Default "target".

MOUNTP="embfiles"
-----------------
MOUNTP holds the name of the mount point directory for the initrd image, 
"newfs". The final tarred and gzipped initrd image, ready for booting,
is named "newfs.gz". Copy/install on the medium of choice.

First the LMW tree is created and stocked in the BUILDIR directory. File
copying, creation, stripping and soft links are performed here. After 
successfully building the tree, it is then copied into the initrd image
which is loop mounted on MOUNTP directory. This minimizes file 
fragmentation for maximal tgz compression.

BLOCKSIZE
---------
Specifies the number of 1024 byte blocks to initialize in the initrd image
'newfs'. E.G. 8192 creates an image of 8192 x 1024 bytes for a total size
of 8Meg. Rescue disk size=4096, Xvnc size=12288, GTK/dillo=13312. 
Default is 12288.

!!!!Be sure to rebuild your kernel to a matching RAMDISK size!!!!

The following is an example from conf243nm, the example '.config'.

CONFIG_BLK_DEV_RAM=y
CONFIG_BLK_DEV_RAM_SIZE=12288
CONFIG_BLK_DEV_INITRD=y

======================
Option enable/disable:
======================

The following variables specify which options are installed into the
final initrd image. Place a bash comment character, '#', in front of
an undesired option to disable, remove to enable. 

=================================
Minimal kernel/Text mode options:

FIREWALL="1"
-------------
When enabled, turns on the x bit for etc/rc.d/rc.start/rc.00.firewall.
Default disabled

THTTPD="1"
-----------
When enabled, turns on the x bit for etc/rc.d/rc.start/rc.20.httpd and
copies the thttpd binary into usr/sbin.
Default disabled.

GPM="1"
-------
Enable GPM console mouse. Creates rc.gpm. Customize for mouse type, port
and usage. See code for specific options.
Default enabled.

LDD="1"
--------
When enabled, copies the ldd binary to usr/bin.
Default disabled.

REBOOT="1"
----------
When enabled, replaces busybox 'halt' and 'reboot' with standalone versions.
Added due to bugs in busybox with kernel 2.4.3 rebooting.
Default enabled.

SULOGIN="1"
------------
When enabled, appends an explicit 'sulogin' to the end of rc.sysinit and 
copies the standalone sulogin binary to sbin. Useful for debugging tinylogin
passwd configuration.
Default disabled.

STRACE="1"
-----------
When enabled, copies the strace binary to usr/bin and support libs to lib.
Default disabled.


==========
X OPTIONS:
==========

INSTALL_X="1"
-------------
When enabled, X install options are enabled.
Default enabled.

LWM="1"
-------
Install lwm, 'light-weight window manager'.
Default enabled.

GTK="1"
--------
Install resident GTk+ dynamic lib support. Does _not_ copy static libs.
Default disabled.

DILLO="1"
----------
Install the open source 'dillo' web browser (220k). Requires option GTK enabled.
Default disabled.

HELIWM="1"
-----------
Install keyboard driven 'Helix window manager'.
Default disabled

XCRUISE="1"
-----------
Install eye candy xcruise file directory viewer. Read the doc, see the galaxy.
Default enabled.

BROWSEX_SUP="1"
----------------
Install libgdbm to support tcl/tk BrowseX web browser. BrowseX is a compressed
binary that conflicts with the initrd compression (compressed files larger than
1k do _not_ survive initrd decompression). The compressed BrowseX must be loaded 
from a non-compressed storage medium or uncompressed prior to newfs.gz creation.
Default disabled.

XENON="1"
---------
Install xenon X text editor.
Default enabled.

XFILEMAN="1"
------------
Install xfilemanager.
Default enabled.

VGA16="1"
----------
Install XF86_VGA16 X server and supporting XF86Config.
Default disabled.

FBDEV="1"
----------
Install XF86_FBDev X server and supporting XF86Config.
Default disabled.

XVNC="1"
--------
Install Xvnc remote X virtual network console server and support.
Default enabled.

=================
Multiple Options:

Loading both VGA16 and FBDEV options will leave the default X set to 
FBDEV. The last option in the sequence takes precedence.

It is possible to install both an explicit X server _and_ Xvnc. But
since LMW is targeted at a low memory application, no effort has been
made to resolve any potential conflicts.

CHANGELOG:

May 11, 2001 lmw-0.23
Added BLOCKSIZE option to specify initrd size rather than being hard coded.
Added GTk+ dynamic lib support.
Added Dillo web browser option.
Added LDD option.
Added STRACE option to aid debugging.
Added OPTION text file to provide specific option details.
Corrected various grammar/spelling errors in documentation.

May 4, 2001 lmw-0.23
Added scientific ycalc option, with programmer friendly hex/dec/oct/bin 
number conversion.

May 4, 2001 lmw-0.22
NOTE: busybox halt/shutdown function segfaults on SMP 2.4.3-pre6
  configuration. Works ok on single CPU 2.4.3-pre6 config.
Restructured ../lmw/init_scripts/etc/rc.d/rc.sysinit so that
  gpm would effectively load on an SMP 2.4.3-pre6 kernel (seems
  to work ok on single CPU 2.4.3-pre6). Busybox init function 
  seems to terminate the last process before login.
Cleaned up requirements for uClibc/tinylogin configuration. uClibc
  requires 'make install' after 'make' but before running 'make'
  for tinylogin. Provided a set of defaults for all three packages.
Added REBOOT and SULOGIN options to lmw.sh.
Added 'hostname' to busybox, removed from copy list from /bin. 

May 1, 2001 lmw-0.21

Started this file CHANGELOG.
Split out CONFIG information file from README.1st.
Added the following reference files for uClibc, tinylogin and busybox:
  ../lmw/init_scripts/uClibc/Config
  ../lmw/init_scripts/tinylogin/Config.h
  ../lmw/init_scripts/busybox/Config.h

May 2, 2001
Changed/fixed location of the xinitrc soft-link to xinitrc.heliwm from
  /usr/X11R6/bin to /usr/X11R6/lib/X11/xinit.
Removed explicit copy of soft-link xedit.
Removed soft-link xedit->xe from tree, added dynamic creation of soft-link
  xedit->xe to lmw.sh.
Changed incorrectly named backup destination filenames from lwm$REV.sh 
  to lmw$REV.sh