-*-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 ID PID PPID COUNT RESULT 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 internal command with args raw data CHECKSUM is the HEX encoded MD5 sum of: DebRIS 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 ( and {raw data}): *exit Exit DebRIS with a return *run {stdin} Do not look for internal s, just execute. *chain {data} Replace current DebRIS with the executed. If {data} is present, write first and set it executable. Commands recommended: *md5sum ... Return length and MD5 sum of . Preset MD5 with {data}. *put {data} Write {data} to the at *get Read data from at with (0=4K). *append {data} Append {data} to *rm ... Remove file. *chmod ... Set file , 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 names for internal commands can contain blanks, as they are at the end of a line. However they cannot contain the sequence 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.