This is a little howto to get people started on openSLX. Please expand!


1. Prerequisites

Hard disk space: As the tm-scripts directory will expand considerably while
	building openSLX (to 5-6 GB), we recommend to allocate around 8-10 GB
	disk space. OpenSLX will install also some packages into the base
	system depending on chosen modules.

Currently supported distributions:
	Ubuntu 12.04 LTS, Ubuntu 13.04, openSuse 12.4.

Net access is vital as packages / source will be downloaded from the internet
while building. Please note that root privileges will be needed to run the
scripts, as e.g. needed packages will be installed automatically.


2. Source repositories

openSLX main repository: git://git.openslx.org/openslx-ng/tm-scripts.git
printerGUI repository: git://git.openslx.org/openslx-ng/printergui.git


3. Server prerequisites

Needed serices: dhcp, tftpd, httpd. ... (TODO: elaborate)


4. Getting the source

checkout openSLX git repository:
# git clone git://git.openslx.org/openslx-ng/tm-scripts.git


5. Getting started

Change into directory tm-scripts, and execute the mltk script ('mini linux
toolkit') without parameters (or use -h, --help) to see possible options
including some examples.

mltk will check for some needed basic development tools like gcc, make etc.
In case of missing development tools mltk will display an information:
| [info]     You appear to be missing following development tools.
along with some installing hints about needed package(s) and suggests
needed packet manager invocations to remedy.

mltk will write detailed log files to the directory 'logs' (stdout.log,
stderr.log). Detailed information can also be obtained using the '-d'
(debug) switch.

Please take note that mltk functions are divided in two parts, somewhat
misleadingly named: 'remote' and 'server' (second parameter choice). As
rule of thumb it may be said that 'remote' applies to building and 'server'
applies to packaging the built system in appropriate ways (initramfs, sqfs)
for delivery.


6. Building

Build Stage31:
# ./mltk remote stage31 -c -b (-d -> debug when appropriate)

Build Stage32:
# ./mltk remote stage32 -c -b

Build Stage32 for openSuse:
# ./mltk remote stage32-opensuse -c -b

...this will take some time, mostly caused by kernel compiling.

Build addons (vmware etc.)
# ./mltk remote vmware -c -b


7. 'Packaging'

When using the parameter 'server' either an IP adress or 'local' is expected.
If the building machine is also used to deliver the built boot images 'local'
should be used. If another machine is used to deliver built images (by http
etc.) the IP adress of the build machine shoud be used. In that case mltk
needs to be present on the server machine. Please take note that the 'remote'
machine (the machine on which the build process runs) needs to export the
build structure (option remote -n, see help).

So remember to execute
# ./mltk remote -n
on the build machine.

For now we presume the same machine is used for building and serving.

So, for 'packaging' the stages and an addon (vmware:
# ./mltk server local stage31 -e stage31
# ./mltk server local stage32 -e stage32
(Use this call for openSuse:)
# ./mltk server local stage32-opensuse -e stage32 (f. Target opensuse)

For packaging addons the parameter 'addons' should be used:
# ./mltk server local vmware -e addons (... other addons likewise)


8. Preparing for client boot

As example we suppose the packaged boot images are expected in
[webroot]/boot/clients; of course the dhcp boot chain needs to be pointed
to this directory also. The 'packaged' stages, addons and the kernel will
be found on the server machine at ../tm-scripts/server/boot/[IP or local]/.
It is recommended for convenience to link to these files, but they can also
be copied to [webroot]/boot/clients, of course.

So these links should be set:
initramfs-stage31
-> [path to tm-scripts]/server/boot/[IP or local]/initramfs-stage31
kernel
-> [path to tm-scripts]/server/boot/[IP or local]/kernel/kernel
stage32.sqfs
-> [path to tm-scripts]/server/boot/[IP or local]/stage32-opensuse.sqfs
vmware.sqfs
-> [path to tm-scripts]/server/boot/[IP or local]/vmware.sqfs
... other addons likewise.


9. Client configurations

Two configuration files will be needed in (following the example above)
[webroot]/boot/clients: config and config.tgz.

The file config will be used for client boot parameters, eg. which NFS share
will be used for storing VM images, proxy configurations, which addons are to
be used and the like. Please take note that the client machine root password
will be defined here. These parameters are documented in boot_config_vars.

The file config.tgz holds localization information for specific environments,
e.g. university specific authetification, home directories, shares and the
like. If there is no pre-formatted localization available it's perhaps a good
idea to just touch config.tgz or pack an empty archive of that name. These
localizations may be listed at [path to tm-scripts]/server/configs.


iPXE: TODO