sfatables/README

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