tentatively package unittests in rpm sfa-tests, for the nightlies
[sfa.git] / sfatables / README
1 sfatables is a tool for defining access and admission control policies
2 in an SFA network, in much the same way as iptables is for ip
3 networks. This file gives an overview of the tool and then describes
4 its design and implementation.
5
6 Example command
7 ---------------
8
9 An sfatables configuration consists of lists of rules that are applied
10 to incoming and outgoing rspecs. Each rule consists of a 'match', to
11 evaluate a given request against a certain set of criteria and a
12 'target', to perform a corresponding action. Rules are manipulated by
13 using the 'sfatables' command.
14
15 Consider the following example:
16
17 sfatables -A INCOMING -- -m hrn --user-hrn plc.princeton -- -j RESTRICT_TO_NODES --blacklist plc.mit
18
19 The statement in this example has three parts: the command, the match
20 and the target, separated by the token '--'.
21
22 * The command is '-A', which means 'Add rule.' 
23
24 * The match is defined in the segment '-m hrn --user-hrn
25   plc.princeton.' Here, '-m hrn' specifies the 'match type', and
26   '--user-hrn' provides an argument specific to the match type.
27
28 * The target is defined by the segment '-j RESTRICT_TO_NODES
29   --blacklist plc.princeton.' '-j RESTRICT_TO_NODES' defines the
30   target type (RESTRICT_TO_NODES) and '--blacklist' defines a
31   parameter specific to this type.
32
33 sfatables comes with a default set of matches and targets, which can
34 be extended using a simple interface.
35
36 When you execute this command, you should see it in your current
37 configuration by running 'sfatables -L INCOMING'
38
39 # ./sfatables -L INCOMING
40
41 # Rule  Match Arguments                Target            Arguments        
42 # 1     hrn   user-hrn=plc.princeton.* RESTRICT_TO_NODES blacklist=plc.mit
43
44 With this configuration, every time a request is received from
45 plc.princeton.*, nodes matching the blacklist prefix (plc.mit) are
46 dropped from the rspec.
47
48 The basis for deploying rules using sfatables is the library of
49 matches and targets. A set of such rules constitutes a 'policy', which
50 as we will see is a portable piece of information that can be
51 exchanged with users, peers, and policy makers to make resource
52 allocation and peering a more effective process.
53
54 XPath crash course -- read this now, or deal with frustration in the
55 remainder of the document
56 -----------------------------------------------------
57
58 XPath is used to select sets of nodes in an XML file. It is like the
59 'SELECT' command in SQL, but has the advantage of applying to tree
60 structures, which are more general than relations. That is, while a
61 relation (a table) has a depth = 2, a tree can have an arbitrary
62 depth. This property allows us to consicely refer to criteria such as 'the nodes in the
63 site corresponding to a user named Alice.' This particular command
64 might look like: '/user[name='Alice']/site/node.'
65
66 An XPath expression is like a directory path, with the following key
67 differences.
68
69 * In a directory path the relationship between X/Y is a parent-child
70   relationship. In XPath, this can be one of a large number of
71   relationships, including 'sibling', 'parent', 'ancestor',
72   'descendant' etc. The most frequently used relationships are:
73
74     child - e.g. site/node
75
76   and
77
78     descendant - e.g. user//node
79
80 * Each level can be filtered with a predicate; e.g.,
81   'site[startswith(@hrn,'plc')]/nodes' means all nodes in sites that
82   have the prefix 'plc'.
83
84 * Some terms have an '@' in them, meaning that they are attributes;
85   e.g., to retrieve the value of p in the following data, we would use
86   the expression "/x/y/@p"
87
88    <x>
89    <y p="q"/>
90    </x>
91
92 Example match
93 -------------
94
95 A match specification consists of a 'context', a set of arguments, and
96 a 'processor.' The context defines the information associated with a
97 request that this match operates on. Think of it as the input
98 parameters to the match. The arguments define values specific to the
99 rule. The processor refers to the program that actually evaluates the
100 match.
101
102 <match name="hrn">
103     <context select="//sfa/current/user@hrn"/>
104     <rule>
105         <argument>
106             <name>user-hrn</name>
107             <help>HRN of the user requesting resouces</help>
108             <operand>HRN</operand>
109         </argument>
110     </rule>
111     <processor filename="hrn.xsl"/>
112 </match>
113
114 Now, when we run the command in the previous example:
115
116 sfatables -A INCOMING -- -m hrn --user-hrn plc.princeton -- -j RESTRICT_TO_NODES --blacklist plc.mit
117
118 ... this match specification is parameterized and dropped in the
119 sfatables configuration directory. The paramterized version of the
120 match is given below:
121
122 <match name="hrn">
123     <!-- Empty context. We _always_ get the hrn of the current user -->
124     <context select="//sfa/current/user@hrn"/>
125     <rule>
126         <argument>
127             <name>user-hrn</name>
128             <help>HRN of the user requesting resouces</help>
129             <operand>HRN</operand>
130         <value>plc.princeton</value>   <------------------
131     </argument>
132     </rule>
133     <processor filename="hrn.xsl"/>
134 </match>
135
136 Notice the additional 'value' tag. Let's list the entries in the
137 configuration directory.
138
139 # ls -l /etc/sfatables/INCOMING
140
141 sapan@joyce ~/Projects/planetlab/sfa/sfatables/targets $ 
142 total 16
143 -rw-r--r-- 1 sapan sapan 671 Sep 11 12:13 sfatables-1-match
144 -rw-r--r-- 1 sapan sapan 646 Sep 11 12:13 sfatables-1-target
145
146 As you can see, a configuration is simply a set of match-target pairs.
147
148 Finally, this is what the match processor looks like:
149
150 <?xml version="1.0" encoding="ISO-8859-1"?>
151 <xsl:stylesheet version="1.0"
152     xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
153     <xsl:variable name="context-hrn" select="hrn"/>
154     <xsl:template match="user">
155                     <xsl:choose>
156                     <xsl:when test="starts-with($context-hrn, hrn)">
157                         True <!--Match -->
158                     </xsl:when>
159                     <xsl:otherwise>
160                         False <!-- No match -->
161                     </xsl:otherwise>
162                 </xsl:choose>
163         <xsl:value-of select="$result"/>
164     </xsl:template>
165         
166 </xsl:stylesheet>
167
168 It is written in XSLT. If the syntax of XSLT were not XML-based, then
169 it might have looked as follows:
170
171 context-hrn = //sfa/user/hrn 
172 request-hrn = //request/user/hrn
173
174 result = 
175   if (starts_with(context-hrn,request-hrn)) then
176     True
177   else
178     False
179   return result
180
181 This is exactly what the previous fragment of code says, albeit in a
182 different format.
183
184 Example target
185 --------------
186
187 Targets are specified just like matches. If you haven't read the match
188 example, then now is a good time to do that. Here's an example target:
189
190 <target name="RESTRICT_TO_NODES">
191     <!-- The context is empty, since this target does not require any input from SFA -->
192     <context select=""/>
193     <rule>
194         <argument>
195             <name>whitelist</name>
196             <help>Prefix of nodes to whitelist for this match.</help>
197             <operand>PREFIX</operand>
198         </argument>
199         <argument>
200             <name>blacklist</name>
201             <help>Prefix of nodes to blacklist for this match.</help>
202             <operand>PREFIX</operand>
203         </argument>
204     </rule>
205     <processor filename="restrict_to_nodes.xsl"/>
206 </target>
207
208 and the corresponding target processor:
209
210 <xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
211     <!-- Magic sauce copied from a manual. This fragment basically copies everything except for
212     stuff that explicitly matches with the templates defined below. In the case of such a match,
213     the matched node is treated differently.-->
214     <xsl:template match="@* | node()">
215         <xsl:copy>
216             <xsl:apply-templates select="@* | node()"/>
217         </xsl:copy>
218     </xsl:template>
219
220     <xsl:variable name="whitelist_prefix" select="//rspec//rule/argument[name='whitelist']/value"/>
221     <xsl:variable name="blacklist_prefix" select="//rspec//rule/argument[name='blacklist']/value"/>
222
223     <!-- Drop nodes that are not in the whitelist -->
224     <xsl:template match="node">
225             <xsl:choose>
226                 <xsl:when test="starts-with(@name,$whitelist_prefix) and not($blacklist_prefix and starts-with(@name,$blacklist_prefix))">
227                     <xsl:copy-of select="."/>
228                 </xsl:when>
229                 <xsl:otherwise/>
230             </xsl:choose>
231     </xsl:template>
232
233     <xsl:template match="sfatables-input"/>
234 </xsl:stylesheet>
235
236 [TODO: explain this target]
237
238
239 Contexts
240 --------
241
242 Matches and targets are associated with specific contexts. A target may use a
243 variety of criteria to process a request, and may need to look them up in the
244 SFA database. The 'context' contains an xpath expression that isolates the
245 items that a match or target may refer to. For example, if a match needs access
246 to the nodes corresponding to a slice's site, then the context may be '/sfa/slice[@name=/context/slice/@name]/nodes'.
247
248
249 Here's a summary of the model:
250 -----------------------------
251
252 An AM can inherit from a set of elements (E).
253
254 Each element in E is associated with three things:
255
256     * A er... 'micro-rspec'
257
258     * an abstract database schema - S, which the AM is expected to be
259       able to generate on the fly.
260
261     * a set of matches and targets. 
262
263 Matches and targets may use pieces of information from S by specifying
264 them in their context (see the 'context' part of matches and targets
265 above).