@(#)$Id: README,v 1.3 2005/03/09 22:48:39 huebsch Exp $ Copyright (c) 2004 Regents of the University of California. All rights reserved. This file is distributed under the terms in the attached BERKELEY-LICENSE file. If you do not find these files, copies can be found by writing to: Computer Science Division, Database Group, Universite of California, 617 Soda Hall #1776, Berkeley, CA 94720-1776. Attention: Berkeley License Copyright (c) 2004 Intel Corporation. All rights reserved. This file is distributed under the terms in the attached INTEL-LICENSE file. If you do not find these files, copies can be found by writing to: Intel Research Berkeley, 2150 Shattuck Avenue, Suite 1300, Berkeley, CA, 94704. Attention: Intel License Inquiry. PlanetLab Application Control Written by: Ryan Huebsch =============== Server Scripts =============== Sorry, but the documentation is terse. 1) You must have a PHP-enabled web server already configured. PHP should be compiled with CURL, PostgreSQL, OpenSSL, and XML support 2) You must have a PostgreSQL installation accessible by the webserver. It does not need to be on the same machine, as long as it can connect via TCP. 3) Place all the scripts (*.php and *.inc) in a directory on the webserver. 4) Create a new PostgreSQL database. 5) Create a new PostgreSQL user (perferably, plcontrol). The user needs no special privledges (such as create-user or create-db) 6) Load db.sql into the new database you created (as a database super-user). If you changed the username created in step 5, edit db.sql appropriately 7) Edit the first 5 lines of code in settings.php. These should match your database setup You should be able to test the installation at this point. If you get an error free index page, then everything is probably good. 8) Setup security. You may use the security provided by your webserver or you can use the builtin permissions-based system. This is separate from the security provided by postgres. The webserver and php code must be able to access postgres and all tables in the plcontrol database. This is done through the default 'plcontrol' user setup earlier. Once the scripts can talk to the database, application-level (rather than db-level) security takes over, which is described below. To setup the builtin system you must edit some tables directly via PostgreSQL. There is no web interface yet. Create users in the 'users' table. If the admin flag is set to true, the user can perform any action. Edit permissions in the 'permissions' table. Each non-admin user must be given permissions to the system and to each application. Each application require a separate tuple as well as one general system permissions tuple. Permissions Add the numbers up in each column for each application and set the 'readperm' and 'writeperm' columns to the sum. General (Appid = -1) | Read | Write ===================================== Display App List 2 --- Display Node Count 4 --- Add an application --- 2 Rebuild node listing --- 4 Remove expired nodes --- 8 View/Edit/Delete nodes 16 16 Application Specific | Read | Write ===================================== Application Info 32 32 Application Nodes 64 64 Interact with PLC --- 128 As a point of reference, consider using the following: for a new application, give 'public', 96 read, 0 write for a new user, give user, 22 read, 12 write for appid '-1' to give a user access to fully control an appid, give 96 read, 224 write for a particular appid 9) Now you need to setup the maintenance routines. These must be called from the command prompt, not through the webserver. This is done as a security precaution. You should add a cron job to run the maintenance periodically. The script, maintenance.php, is called with one parameter (the job name) and can perform 4 different jobs: vacuum - This will cause PostgreSQL to clean up the database and actually remove deleted rows. You MUST run this periodically. I suggest at least once a day. nodes - This will cause the system to update the list of nodes from PlanetLab central. This is optional, but I suggest running it at least once a week. fixbad - This will cause the system to force a re-install on nodes that are reported as in a state of error. The install will only occur if the intra-install time has elapsed. In prior versions of the server scripts, this was performed when any node for that application called-home. This is optional, but barely. I suggest running this once an hour. fixinstall - This will clear installs that have exceeded the maximum install time. This is mandatory or else you may have nodes that will never be installed again. (These install errors are caused by install scripts that never report back after they have been assigned a node to install). I suggest running this once an hour An example cron job may look like: 0 3 * * * cd /www/plcontrol; /usr/bin/php -f maintenance.php nodes