...
[nodemanager.git] / 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.