README.txt

   1 THE NEW NODE MANAGER
   2 ====================
   3
   4 This is a very preliminary version of the new node manager.  Currently
   5 it is set up to download slices.xml; however, not all of the
   6 implemented functionality is accessible via slices.xml.
   7
   8 FILES
   9 =====
  10
  11 accounts.py - Account management functionality generic between
  12 delegate accounts and VServers.
  13
  14 api.py - XMLRPC interface to Node Manager functionality.  Runs on port
  15 812, supports a Help() call with more information.
  16
  17 bwcap.py - Sets the bandwidth cap via the bwlimit module.  The bwlimit
  18 calls are commented out because they've been giving me a bunch of
  19 errors.
  20
  21 config.py - Configuration parameters.  You'll probably want to change
  22 SA_HOSTNAME to the PLC address.
  23
  24 database.py - The dreaded NM database.  The main class defined is a
  25 dict subclass, which both indexes and stores various records.  These
  26 records include the sliver/delegate records, as well as the timestamp,
  27 node bw cap, and any other crap PLC wants to put there.
  28
  29 delegate.py - Create and delete delegate accounts.  These accounts
  30 have low space overhead (unlike a VServer) and serve to authenticate
  31 remote NM users.
  32
  33 forward_api_calls.c - The forward_api_calls program proxies stdin to
  34 the Unix domain socket /tmp/node_mgr_api, letting Node Manager take
  35 advantage of ssh authentication.  It is intended for use as a shell on
  36 a special delegate account.
  37
  38 logger.py - This is a very basic logger.
  39
  40 Makefile - For compiling forward_api_calls.
  41
  42 nm.py - The main program.
  43
  44 plc.py - Downloads and parses slices.xml, reads the node id file.
  45
  46 README.txt - Duh.
  47
  48 sliver.py - Handles all VServer functionality.
  49
  50 ticket.py - Not used at the moment; contains a demonstration of
  51 xmlsec1.
  52
  53 tools.py - Various convenience functions for functionality provided by
  54 Linux.
  55
  56 RUNNING
  57 =======
  58
  59 Change SA_HOSTNAME in config.py and run nm.py.  No bootstrapping
  60 required.
  61
  62 INTERNALS
  63 =========
  64
  65 At the moment, the main thread loops forever, fetching slices.xml and
  66 updating the database.  Other threads handle incoming API connections
  67 (each connection is handled by a separate thread) and the database
  68 dumper.  There is also one thread per account, which supervises
  69 creation/deletion/resource initialization for that account.  The other
  70 threads request operations by means of a queue.
  71
  72 Other than the queues, the threads synchronize by acquiring a global
  73 database lock before reading/writing the database.  The database
  74 itself is a collection of records, which are just Python dicts with
  75 certain required fields.  The most important of these fields are
  76 'timestamp', 'expiry', and 'record_key'.  'record_key' serves to
  77 uniquely identify a particular record; the only naming conventions
  78 followed are that account records have record_key <account
  79 type>_<account name>; thus sliver princeton_sirius has record_key
  80 'sliver_princeton_sirius'.
  81
  82 The two main features that will not be familiar from the old node
  83 manager are delegates and loans.  Delegates, as described above, are
  84 lightweight accounts whose sole purpose is to proxy NM API calls from
  85 outside.  The current code makes a delegate account 'del_snoop' that's
  86 allowed to spy on everyone's RSpec; you'll need to change the key in
  87 plc.py order to use it.  Loans are resource transfers from one sliver
  88 to another; the format for loans is a list of triples: recipient
  89 sliver, resource type, amount.  Thus for princeton_sirius to give 20%
  90 guaranteed CPU to princeton_eisentest, it would call
  91
  92 api.SetLoans(['princeton_eisentest', 'nm_cpu_guaranteed_share', 200])
  93
  94 provided, of course, that it has 200 guaranteed shares :)
  95
  96 POSTSCRIPT
  97 ==========
  98
  99 The log file will come in a great deal of use when attempting to
 100 use/debug node manager; it lives at /var/log/pl_node_mgr.log.  If you
 101 break the DB, you should kill the pickled copy, which lives at
 102 <config.py:DB_FILE>.
 103
 104 I have been refactoring the code constantly in an attempt to keep the
 105 amount of glue to a minimum; unfortunately comments quickly grow stale
 106 in such an environment, and I have not yet made any attempt to comment
 107 reasonably.  Until such time as I do, I'm on the hook for limited
 108 support of this thing.  Please feel free to contact me at
 109 deisenst@cs.princeton.edu.