Name                    Last modified       Size  Description

 Parent Directory        11-Aug-2010 07:31      -  
 cmds/                   11-Aug-2010 07:31      -  
 diet/                   11-Aug-2010 07:31      -  
 sirbed/                 11-Aug-2010 07:31      -  
 tino/                   11-Aug-2010 07:31      -  
 ANNOUNCE                15-Aug-2005 03:04     1k  
 COPYING                 24-May-2005 21:51    18k  
 ChangeLog               15-Aug-2005 02:46     1k  
 DESCRIPTION             25-Jul-2005 05:09     1k  
 Makefile                15-Aug-2005 03:04     4k  
 Makefile.tino           14-Aug-2005 04:44     1k  
 README                  15-Aug-2005 02:47     9k  
 VERSION                 15-Aug-2005 02:55     1k  
 debris.c                15-Aug-2005 02:47     3k  
 drisbuf.h               15-Aug-2005 03:04     2k  
 driscmds.h              25-Jul-2005 05:14     1k  
 driscurl.h              15-Aug-2005 03:04     3k  
 drisexec.h              15-Aug-2005 03:04     4k  
 drismd5.h               25-Jul-2005 05:16     1k  
 drisnext.h              15-Aug-2005 03:04     3k  
 dristool.h              15-Aug-2005 03:04     3k  

-*-text-*-
$Header: /CVSROOT/debris/README,v 1.5 2005/08/15 00:47:45 tino Exp $

DebRIS: DEBian Remote Install Scripter

In my ongoing effort to create a Debian Install Distribution named
HilbiX, this here is for Step 3 to install Debian on your server.

This may be copied according to the GNU GPL v2 or higher.


Build:
======
(This still is under CVS control, it will become GAT as soon as I
am ready with GAT.)

make

Note that this downloads diet and several libraries and automatically,
builds suitable statically versions of everything through diet.  This
is needed as on my system (RH9 and Debian sarge) I was unsuccessful to
use the static versions of the libs.


Quickstart:
===========

make
strip debris
ln -s `pwd`/sirbed/debris.php /var/www/path/debris.php
./sirbed.sh


Overview:
=========

How to install Debian onto a remote system:

Step 1: Prepare the new setup on the HilbiX install server.
Step 2: Download the install boot image from the HilbiX server.
Step 3: Boot the system into the boot image.  This runs DebRIS.
Step 4: Activate the install on the HilbiX install server.
Step 5: After install boot into the fresh Debian.
Step 6: Administer normally or via the HilbiX web pages.

However, HilbiX is not ready yet.  Today to install Debian do:

Step 1: Install SirbeD on another box running Linux.
Step 2: Boot the box into a rescue system.
Step 3: Download and run DebRIS.
Step 4: Start SirbeD with a suitable configuration file.
Step 5: After install boot into the fresh Debian.
Step 6: Administer the Debian box normally.

(SirbeD stands for Service to Install Remotely Booted Environment via
DebRIS, and well, yes, it's written debris backwards, of course.)


Prerequisites:
==============

Step 1:

You have a Server which is running Debian Sarge (probably needed).
The Server is running a web server.

A PHP script can be reached from the network to receive POST requests.

There are a couple of other crude scripts running on the Server to
provide the install environment.  These scripts communicate with the
PHP script over Unix Domain Sockets.

The server is able to access an Archive of DEB packages over http.

You probably can set up everything from a shell without root access.


Step 2: 

You have a Box which must be installed.  It is booted into your
favorite install system and is able to run HTTP/s requests to the
Server.

You can download and run a statically linked binary (DebRIS) on this
system.


Step 3:

As root run DebRIS on the Box.  It needs the URL and an install
password.  You probably have to set some environment variables to set
the correct Proxy.  DebRIS uses libcurl.

DebRIS now will start to run http requests to the Server and perform
the actions the server hands out.


Step 4:

You must be able to edit the install template on the Server and start
the SirbeD with the same password of step 3.  The password protects
both sides: It authorizes the requests to the Server and authenticates
the install commands to the box.  If the password is mismatched, the
digital signature (checksum) of the transmitted data will fail.  The
password itself is never transmitted over the network.


Step 5:

You must have some method to force a reboot of the Box if something
fails.  Probably you will need some "cycles" to install the remote
system until the install template is set up properly.

The good thing is, that, after you once have the install template, you
can keep it this way and re-install the Box easily again and again,
using the same template.  Also you can use the template to install
other boxes a similar way.


Step 6:

You need a way to administer the Box later on.  This currently cannot
be done over the Server.


Where to find the other parts:
==============================

Have a look at http://www.hilbix.com/ to find the state and the other
parts which you might be missing.  You can find some obfuscated bunch
of scripts for Step 1 there, however you are currently let alone to
set up everything.

If you can read C, Bash and PHP fluently, know how to compile things
yourself and don't need to ask me how to make it work, you are
welcome.

If you don't know anything about this and just want to install Debian,
this probably is nothing for you, until the nifty web install pages
are set up.  Please note that it may take ages until I manage to do
so.

The future will look as follows:

- Open a browser to point it at http://www.hilbix.com/
- Register at http://www.hilbix.com/
- Have a click feast to setup the configuration of the Box
- Download the HilbiX boot image.  It will fit on a 1.44 MB floppy.
- Boot this image from Floppy, USB, CD or Ethernet (PXE+TFTP)
- Wait until the Box shows up on the web pages.
- Enter the install password to authorize the install process.
- Wait until the Box has installed.
- Remote administer the Box via http://www.hilbix.com/

Note that for this complete process, you will never have to connect to
the Box.  It is assumed that the install service is running on some
server in the Internet and the Box is behind the highest grade
Internet Firewall you can ever buy for money.  The only thing
available at the Box are Remote Hands or a remote boot environment
without console access (the nice secretary who knows how to find the
power switch is enough).  This must be enough to get a complete root
shell on the Box.  The only precondition is, that the Box can somehow
reach the install service (not vice versa!).  The standard way will be
https, however there will show up some tunneling methods in case you
cannot do TCP connects directly, like: Direct access over the MAC
layer, UDP and DNS tunnels, serial line, memory stick over avian
carrier.


Running step 3:
===============

On the Box do:

URL=http://install.server.test/path/to/debris.php
wget $URL/debris; chmod +x debris; ./debris -v $URL password

Watch the output to the console if you like.


On the Server do:

cd /path/to/template/directory
vi whatever you want
path/to/sirbed /path/to/socket/of/php/script password

Watch the output to the console if you like.

If this does not help you, sorry, there is no more documentation yet.


Communication:
==============

DebRIS uses HTML POST to transfer data to SirbeD.  It reads the answer
and processes the commsnds in this answer.

The information is POSTed as a file attachment:

CHECKSUM<CR><LF>
ID PID PPID COUNT<CR><LF>
RESULT<CR><LF>
raw data

ID is a (unique) random string (without spaces) which never changes in
a run.  PID and PPID are the process IDs, respectively.  Count will be
incremented on each request to the HilbiX install server.  The install
server must not assume that an request has been transmitted, unless a
valid request with the next higher count has been seen.  Result is the
(shell) result code of the last action, 0 if success.

Note that with COUNT=0 the raw data contains the DebRIS version string
with the list of builtin commands.


The information received is:
CHECKSUM<CR><LF>
internal command with args<CR><LF>
raw data

CHECKSUM is the HEX encoded MD5 sum of:
DebRIS<CR><LF>
<Password from commandline>
line following the CHECKSUM up to the end of the request.

If the checksum is failing, the request is dropped and retried with
linear backoff and a maximum 1 minute delay.


Execution:
==========

DebRIS has some commands builtin.  If the command cannot be found
internally, it is executed externally with stdin connected to the "raw
data" received.  Stdout will be posted to the Server on the next
request (which will tell the result code as well) and stderr is
connected to the install console, as usual.

The list of internal commands can differ between versions of DebRIS.
Following commands are mandatory (<params> and {raw data}):

*exit <value>
	Exit DebRIS with a return <value>
*run <command> {stdin}
	Do not look for internal <command>s, just execute.
*chain <file> {data}
	Replace current DebRIS with the <file> executed.
	If {data} is present, write <file> first and set it executable.

Commands recommended:

*md5sum <file> ...
	Return length and MD5 sum of <file>.  Preset MD5 with {data}.
*put <offset> <file> {data}
	Write {data} to the <file> at <offset>
*get <offset> <length> <file>
	Read data from <file> at <offset> with <length> (0=4K).
*append <file> {data}
	Append {data} to <file>
*rm <file> ...
	Remove file.
*chmod <mode> <file> ...
	Set file <mode>, <mode> must be octal (start with 0).

Note that argument splitting is performed on whitespaces (like blanks
or TABs).  There is no such thing like escape codes or quotes.  That's
done to make it more easy.  Note that <file> names for internal
commands can contain blanks, as they are at the end of a line.
However they cannot contain the sequence <CR><LF> nor NUL bytes.  If
you need this (somehow) you have to prepare a wrapper first (how do
you access files with NUL bytes in them, anyways?).

-Tino
webmaster@scylla-charybdis.com
http://www.scylla-charybdis.com/
$Log: README,v $
Revision 1.5  2005/08/15 00:47:45  tino
updates for DebRIS improvements

Revision 1.4  2005/08/13 23:03:00  tino
new release 0.0.3

Revision 1.3  2005/07/25 03:39:07  tino
version 0.0.2 needs tinolib

Revision 1.2  2005/07/25 03:09:54  tino
new dist

Revision 1.1  2005/06/01 02:12:34  tino
first version.  As SirbeD is missing, this just does nothing yet.