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.
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.
15 Consider the following example:
17 sfatables -A INCOMING -- -m hrn --user-hrn plc.princeton -- -j RESTRICT_TO_NODES --blacklist plc.mit
19 The statement in this example has three parts: the command, the match
20 and the target, separated by the token '--'.
22 * The command is '-A', which means 'Add rule.'
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.
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.
33 sfatables comes with a default set of matches and targets, which can
34 be extended using a simple interface.
36 When you execute this command, you should see it in your current
37 configuration by running 'sfatables -L INCOMING'
39 # ./sfatables -L INCOMING
41 # Rule Match Arguments Target Arguments
42 # 1 hrn user-hrn=plc.princeton.* RESTRICT_TO_NODES blacklist=plc.mit
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.
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.
54 XPath crash course -- read this now, or deal with frustration in the
55 remainder of the document
56 -----------------------------------------------------
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.'
66 An XPath expression is like a directory path, with the following key
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:
74 child - e.g. site/node
78 descendant - e.g. user//node
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'.
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"
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
103 <context select="//sfa/current/user@hrn"/>
106 <name>user-hrn</name>
107 <help>HRN of the user requesting resouces</help>
108 <operand>HRN</operand>
111 <processor filename="hrn.xsl"/>
114 Now, when we run the command in the previous example:
116 sfatables -A INCOMING -- -m hrn --user-hrn plc.princeton -- -j RESTRICT_TO_NODES --blacklist plc.mit
118 ... this match specification is parameterized and dropped in the
119 sfatables configuration directory. The paramterized version of the
120 match is given below:
123 <!-- Empty context. We _always_ get the hrn of the current user -->
124 <context select="//sfa/current/user@hrn"/>
127 <name>user-hrn</name>
128 <help>HRN of the user requesting resouces</help>
129 <operand>HRN</operand>
130 <value>plc.princeton</value> <------------------
133 <processor filename="hrn.xsl"/>
136 Notice the additional 'value' tag. Let's list the entries in the
137 configuration directory.
139 # ls -l /etc/sfatables/INCOMING
141 sapan@joyce ~/Projects/planetlab/sfa/sfatables/targets $
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
146 As you can see, a configuration is simply a set of match-target pairs.
148 Finally, this is what the match processor looks like:
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">
156 <xsl:when test="starts-with($context-hrn, hrn)">
160 False <!-- No match -->
163 <xsl:value-of select="$result"/>
168 It is written in XSLT. If the syntax of XSLT were not XML-based, then
169 it might have looked as follows:
171 context-hrn = //sfa/user/hrn
172 request-hrn = //request/user/hrn
175 if (starts_with(context-hrn,request-hrn)) then
181 This is exactly what the previous fragment of code says, albeit in a
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:
190 <target name="RESTRICT_TO_NODES">
191 <!-- The context is empty, since this target does not require any input from SFA -->
195 <name>whitelist</name>
196 <help>Prefix of nodes to whitelist for this match.</help>
197 <operand>PREFIX</operand>
200 <name>blacklist</name>
201 <help>Prefix of nodes to blacklist for this match.</help>
202 <operand>PREFIX</operand>
205 <processor filename="restrict_to_nodes.xsl"/>
208 and the corresponding target processor:
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()">
216 <xsl:apply-templates select="@* | node()"/>
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"/>
223 <!-- Drop nodes that are not in the whitelist -->
224 <xsl:template match="node">
226 <xsl:when test="starts-with(@name,$whitelist_prefix) and not($blacklist_prefix and starts-with(@name,$blacklist_prefix))">
227 <xsl:copy-of select="."/>
233 <xsl:template match="sfatables-input"/>
236 [TODO: explain this target]
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'.
249 Here's a summary of the model:
250 -----------------------------
252 An AM can inherit from a set of elements (E).
254 Each element in E is associated with three things:
256 * A er... 'micro-rspec'
258 * an abstract database schema - S, which the AM is expected to be
259 able to generate on the fly.
261 * a set of matches and targets.
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