[doc] Started setup_howto for openSLX - please comment / expand!

1 files changed, 140 insertions, 0 deletions

diff --git a/doc/setup_howto b/doc/setup_howto
new file mode 100644
index 00000000..2a051cac
--- /dev/null
+++ b/doc/setup_howto
@@ -0,0 +1,140 @@
+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