======================================== How to get started with One_Penguin-pre2 ======================================== Installing Penguin ------------------ Before any code will be excuted, you will need the following: perl 5.002 safe 2.03 IO 1.02 PGP version something. Perl 5.002 will need to built and installed on the system, as well as the other two modules. You should ftp Safe and IO from the following location: coriolan.amicus.com/pub/PATCHED_MODULES These versions have been slightly modified from the originals in order to help Penguin along... This is not the only magic nessercary - Perl5 comes with Safe 1.0 installed, and you have to get rid of it before you can do anything useful. You will need to delete the following directories: ${PERL5LIB}/${ARCH}/5.002/auto/Safe/ and ${PERL5LIB}/auto/Safe/ as well as the file ${PERL5LIB}/Safe.pm in order for Safe-2.03 to work. This is a rather large hassle, but it is believed that it will be fixed in the next release of Perl (note: it wasn't) Configuring Penguin ------------------- Now you have the modules you need, installed in the correct places and all, you have to build Penguin. Go to the top of the Penguin source tree, and type 'perl Makefile.PL'. This will create a standard Makefile for your system. Once everything has finished, you can type 'make' to build Penguin, and then 'make install' (You probably need to be root to do this, as it installs it inside your ${PERL5LIB} directory). The next step along the way is creating a rightsfile. This is the file containing the Safe opcodes for each user. You can start your rightsfile by typeing 'touch ~/.rightsfile'. You must now edit the rightsfile, it looks intimidating, but really isn't that complicated. The format is: [User Name ] opcodes To decide what opcodes to give someone, please read Safe.pod this will tell you which each opcode means, and what functions they allow access to. If you're not sure, give the user the opcode :default. For instance, if you were adding Map Gallo (Felix Gallo's Cat) to your rightsfile, you could do it like this: [Map Gallo ] :default If you wish to comment your rightsfile, you can do so with a '#' preceding the commented line. Executing a Penguin Application ------------------------------- You should be now just about ready to run an application. To do so, enter the bin directory underneath the Penguin root. To try it out, you need a server to use and some working perl code (Write some, and save it in a file called 'test.pl'). Try coriolan.amicus.com (Felix Gallo's system). You can achive this by typing: client -h coriolan.amicus.com -f test.pl -v This basically says run the test.pl [-f test.pl] script on coriolan.amicus.com [-h coriolan.amicus.com], and display the results nicely [-v, for verbosity]. The client will disable the screen echo on your machine, and ask you to enter your PGP pass phrase. As soon as you do this, Penguin signs the code, and puts it in a frame. If Penguin can connect to coriolan.amicus.com, it will toss this frame across the network. The Penguin server unwraps the code and reads who sent the code (it uses the PGP signature to verify this). It then searches in the remote .rightsfile to see what rights your name has. Chances are, it won't find your name, so it will give you default rights. After unwrapping the code, it creates a compartment, where it can safely execute your script. If it finds unsafe operations (ie, those not specified in the rightsfile) then it will return an error message, otherwise it will simply return a 1 (True). If you want some specific information returned, you can always use the perl function 'return' in your scripts. If you got this far, congratulations, you just successfully ran a Penguin Application. Starting up your own Penguind ----------------------------- Penguind is the counterpart to 'client'. It receives the information across the network, and sets up the secure execution compartment for the remote code. To run penguind simply type 'penguind' from the command line. This will start the penguind server with the default options (No verbosity, port 8118, and Interactive). I suggest you start penguind with the following: penguind -v The -v switch turns verbosity on, and lets you see what exactly people are running on your machine. After you start penguind, the program asks you to type in your PGP pass phrase (You won't see what you are typing, the same as when you type your login password). Penguind will then appear to do nothing, until a client trys to attach. If and when a client attaches, penguind will print the hostname and port number that the client is coming from, and then also print the code it tries to execute. Notes ----- Most of this text was put together this evening (so the it may read a little strange in places), and much of it consists of long-winded ways of saying what has been said before. Hopefully this will help people run penguin properly, the first time through. I guess I'll have to completely revamp this text when One_Penguin-pre3 and finally One_Penguin come along, but it's a start. Regards, James. -- jduncan@hawk.igs.net